@inglorious/ssx 0.4.1 → 1.1.0

package/README.md

@@ -1,882 +1,664 @@
-# Inglorious Store
+# @inglorious/ssx
 
-[![NPM version](https://img.shields.io/npm/v/@inglorious/store.svg)](https://www.npmjs.com/package/@inglorious/store)
+[![NPM version](https://img.shields.io/npm/v/@inglorious/ssx.svg)](https://www.npmjs.com/package/@inglorious/ssx)  
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Redux-compatible, ECS-inspired state library that makes state management as elegant as game logic.
+**Static Site Xecution** - Build blazing-fast static sites with [@inglorious/web](https://www.npmjs.com/package/@inglorious/web), complete with server-side rendering, client-side hydration, and zero-config routing.
 
-**Drop-in replacement for Redux.** Works with `react-redux` and Redux DevTools. Borrows concepts from Entity-Component-System architectures and Functional Programming to provide an environment where you can write simple, predictable, and testable code.
-
-```javascript
-// from redux
-import { createStore } from "redux"
-// to
-import { createStore } from "@inglorious/store"
-```
+SSX takes your entity-based web apps and generates optimized static HTML with full hydration support. Think Next.js SSG or Astro, but with the simplicity and predictability of Inglorious Web's entity architecture.
 
 ---
 
-## Why Inglorious Store?
+## Why SSX?
 
-Redux is powerful but verbose. You need action creators, reducers, middleware for async operations, and a bunch of decisions about where logic should live. Redux Toolkit cuts the boilerplate, but you're still writing a lot of ceremony.
+### ⚡️ Fast by Default
 
-Inglorious Store eliminates the boilerplate entirely with an **entity-based architecture** inspired by game engines. Some of the patterns that power AAA games now power your state management.
+- **Pre-rendered HTML** - Every page is built at compile time
+- **Instant load times** - No waiting for server responses
+- **CDN-ready** - Deploy anywhere static files are served
+- **Perfect Lighthouse scores** - SEO and performance out of the box
 
-Game engines solved state complexity years ago — Inglorious Store brings those lessons to web development.
+### 🎯 Simple Architecture
 
-**Key benefits:**
+- **No server required** - Pure static files
+- **No complex build configs** - Convention over configuration
+- **File-based routing** - Pages are just files in `src/pages/`
+- **Entity-based state** - Same familiar patterns from @inglorious/web
 
-- ✅ Drop-in Redux replacement (same API with `react-redux`)
-- ✅ Entity-based state (manage multiple instances effortlessly)
-- ✅ No action creators, thunks, or slices
-- ✅ Predictable, testable, purely functional code
-- ✅ Built-in lifecycle events (`add`, `remove`)
-- ✅ 10x faster immutability than Redux Toolkit (Mutative vs Immer)
+### 🔥 Modern DX
 
----
+- **Hot reload dev server** - See changes instantly
+- **Lazy-loaded routes** - Code splitting automatically
+- **lit-html hydration** - Interactive UI without the bloat
+- **TypeScript ready** - Full type support (coming soon)
 
-## Quick Comparison: Redux vs RTK vs Inglorious Store
+### 🚀 Production Ready
 
-### Redux
+- **Automatic code splitting** - Per-page bundles
+- **Optimized builds** - Minified, tree-shaken output
+- **Source maps** - Debug production like development
+- **Error boundaries** - Graceful failure handling
 
-```javascript
-// Action creators
-const addTodo = (text) => ({ type: "ADD_TODO", payload: text })
+---
 
-// Reducer
-const todosReducer = (state = [], action) => {
-  switch (action.type) {
-    case "ADD_TODO":
-      return [...state, { id: Date.now(), text: action.payload }]
+## Quick Start
 
-    case "OTHER_ACTION":
-    // Handle other action
+### Installation
 
-    default:
-      return state
-  }
-}
+```bash
+npm install @inglorious/ssx @inglorious/web
+```
 
-// Store setup
-const store = configureStore({
-  reducer: {
-    work: todosReducer,
-    personal: todosReducer,
-  },
-})
+### Create Your First Site
 
-store.dispatch({ type: "ADD_TODO", payload: "Buy groceries" })
-store.dispatch({ type: "OTHER_ACTION" })
+<!-- ```bash
+npx @inglorious/create-app my-site --template ssx
+cd my-site
+npm run dev
 ```
 
-### Redux Toolkit
+Or manually: -->
 
 ```javascript
-const otherAction = createAction("app:otherAction")
-
-const todosSlice = createSlice({
-  name: "todos",
-  initialState: [],
-  reducers: {
-    addTodo: (state, action) => {
-      state.push({ id: Date.now(), text: action.payload })
-    },
+// src/pages/index.js
+import { html } from "@inglorious/web"
+
+export const index = {
+  render() {
+    return html`
+      <div>
+        <h1>Welcome to SSX!</h1>
+        <p>This page was pre-rendered at build time.</p>
+        <nav>
+          <a href="/about">About</a>
+        </nav>
+      </div>
+    `
   },
-  extraReducers: (builder) => {
-    builder.addCase(otherAction, (state, action) => {
-      // Handle external action
-    })
-  },
-})
+}
 
-const store = configureStore({
-  reducer: {
-    work: todosSlice.reducer,
-    personal: todosSlice.reducer,
+export const metadata = {
+  title: "Home",
+  meta: {
+    description: "Welcome to our site",
+    "og:image": "/og-image.png",
   },
-})
-
-store.dispatch(slice.actions.addTodo("Buy groceries"))
-store.dispatch(otherAction())
+}
 ```
 
-### Inglorious Store
-
-```javascript
-// Define entity types and their behavior
-const types = {
-  todoList: {
-    addTodo(entity, text) {
-      entity.todos.push({ id: Date.now(), text })
-    },
-
-    otherAction(entity) {
-      // Handle other action
-    },
-  },
-}
+### Development
 
-// Define initial entities
-const entities = {
-  work: { type: "todoList", todos: [] },
-  personal: { type: "todoList", todos: [] },
-}
+```bash
+npm run dev
+# → Dev server at http://localhost:3000
+```
 
-// Create store
-const store = createStore({ types, entities })
+### Build
 
-store.dispatch({ type: "addTodo", payload: "Buy groceries" })
-store.dispatch({ type: "otherAction" })
+```bash
+npm run build
+# → Static site in dist/
+```
 
-// or, even better:
-store.notify("addTodo", "Buy groceries")
-store.notify("otherAction")
+### Deploy
 
-// same result, 10x simpler
+```bash
+npm run preview
+# → Preview production build
 ```
 
-**Key differences:**
+Deploy `dist/` to:
 
-- ❌ No action creators
-- ❌ No switch statements or cases
-- ❌ No slice definitions with extraReducers
-- ✅ Define what each entity type can do
-- ✅ Add multiple instances by adding entities, not code
+- **Vercel** - Zero config
+- **Netlify** - Drop folder
+- **GitHub Pages** - Push and done
+- **Cloudflare Pages** - Instant edge
+- **Any CDN** - It's just files!
 
 ---
 
-## Core Concepts
+## Features
 
-### 🎮 Entities and Types
+### �️ Sitemap & RSS Generation
 
-State consists of **entities** (instances) that have a **type** (behavior definition). Think of a type as a class and entities as instances:
+SSX automatically generates `sitemap.xml` and `rss.xml` based on your pages. Configure them in `src/site.config.js`:
 
 ```javascript
-const types = {
-  todoList: {
-    addTodo(entity, text) {
-      entity.todos.push({ id: Date.now(), text })
-    },
-    toggle(entity, id) {
-      const todo = entity.todos.find((t) => t.id === id)
-      if (todo) todo.completed = !todo.completed
-    },
+export default {
+  // Basic metadata
+  title: "My Awesome Site",
+  meta: {
+    description: "A site built with SSX",
+    "og:type": "website",
+    "og:site_name": "My Site",
   },
 
-  settings: {
-    setTheme(entity, theme) {
-      entity.theme = theme
+  // Sitemap configuration
+  sitemap: {
+    hostname: "https://myblog.com",
+    filter: (page) => !["/admin", "/draft-*", "/test"].includes(page.pattern),
+    defaults: {
+      changefreq: "weekly",
+      priority: 0.5,
     },
   },
-}
 
-const entities = {
-  workTodos: { type: "todoList", todos: [], priority: "high" },
-  personalTodos: { type: "todoList", todos: [], priority: "low" },
-  settings: { type: "settings", theme: "dark", language: "en" },
+  // RSS configuration
+  rss: {
+    title: "My Blog",
+    description: "Latest posts from my blog",
+    link: "https://myblog.com",
+    feedPath: "/feed.xml",
+    language: "en",
+    copyright: "© 2026 My Blog",
+    maxItems: 10,
+    filter: (page) => page.path.startsWith("/posts/"),
+  },
 }
 ```
 
-**Why this matters:**
+Pages with a `published` date in metadata are included in RSS feeds.
+
+### �📁 File-Based Routing
 
-- Same behavior applies to all instances of that type
-- No need to write separate code for each instance
-- Your mental model matches your code structure
+Your file structure defines your routes:
 
-### 🔄 Event Handlers (Not Methods)
+```
+src/pages/
+├── index.js          → /
+├── about.js          → /about
+├── blog.js          → /blog
+└── posts/
+    └── _slug.js        → /posts/:slug
+```
 
-Even though it looks like types expose methods, they are actually **event handlers**, very similar to Redux reducers. There are a few differences though:
+Dynamic routes use underscore prefix: `_id.js`, `_slug.js`, etc.
 
-1. Just like RTK reducers, you can mutate the entity directly since event handlers are using an immutability library under the hood. Not Immer, but Mutative — which claims to be 10x faster than Immer.
+### ⚛️ Entity-Based State And Behavior
 
 ```javascript
-const types = {
-  counter: {
-    increment(counter) {
-      counter.value++ // Looks like mutation, immutable in reality
-    },
+// src/pages/about.js
+import { html } from "@inglorious/web"
+
+export const about = {
+  click(entity) {
+    entity.name += "!"
+  },
+
+  render(entity, api) {
+    return html`<h1>
+      About
+      <span @click=${() => api.notify(`#${entity.id}:click`)}
+        >${entity.name}</span
+      >
+    </h1>`
   },
 }
 ```
 
-2. Event handlers accept as arguments the current entity, the event payload, and an API object that exposes a few convenient methods:
-
 ```javascript
-const types = {
-  counter: {
-    increment(counter, value, api) {
-      api.getEntities() // access the whole state in read-only mode
-      api.getEntity(id) // access some other entity in read-only mode
-      api.notify(type, payload) // similar to dispatch. Yes, you can dispatch inside of a reducer!
-      api.dispatch(action) // optional, if you prefer Redux-style dispatching
-    },
+// src/entities.js
+export const entities = {
+  about: {
+    type: "about",
+    name: "Us",
   },
 }
 ```
 
----
-
-## Installation & Setup
-
-The Inglorious store, just like Redux, can be used standalone. However, it's commonly used together with component libraries such as React.
+### 🔄 Data Loading
 
-### Basic Setup with `react-redux`
+Load data at build time with the `load` export:
 
 ```javascript
-import { createStore } from "@inglorious/store"
-import { Provider, useSelector, useDispatch } from "react-redux"
-
-// 1. Define entity types
-const types = {
-  counter: {
-    increment(counter) {
-      counter.value++
-    },
-    decrement(counter) {
-      counter.value--
-    },
+// src/pages/blog.js
+import { html } from "@inglorious/web"
+
+export const blog = {
+  render(entity) {
+    return html`
+      <h1>Blog Posts</h1>
+      <ul>
+        ${entity.posts?.map(
+          (post) => html`
+            <li>
+              <a href="/posts/${post.id}">${post.title}</a>
+            </li>
+          `,
+        )}
+      </ul>
+    `
   },
 }
 
-// 2. Define initial entities
-const entities = {
-  counter1: { type: "counter", value: 0 },
-}
-
-// 3. Create the store
-const store = createStore({ types, entities })
-
-// 4. Provide the store with react-redux
-function App() {
-  return (
-    <Provider store={store}>
-      <Counter />
-    </Provider>
-  )
+// SSR: Load data during build
+export async function load(entity) {
+  const response = await fetch("https://api.example.com/posts")
+  entity.posts = await response.json()
 }
 
-// 5. Wire components to the store
-function Counter() {
-  const dispatch = useDispatch()
-  const count = useSelector((state) => state.counter1.value)
-
-  return (
-    <div>
-      <p>{count}</p>
-      <button onClick={() => dispatch({ type: "increment" })}>+</button>
-      <button onClick={() => dispatch({ type: "decrement" })}>-</button>
-    </div>
-  )
-}
+export const title = "Blog"
 ```
 
-### With `@inglorious/react-store` (Recommended)
-
-For React applications, `@inglorious/react-store` provides a set of hooks and a Provider that are tightly integrated with the store. It's a lightweight wrapper around `react-redux` that offers a more ergonomic API.
-
-```javascript
-import { createStore } from "@inglorious/store"
-import { createReactStore } from "@inglorious/react-store"
+The `load` function runs on the server during build. Data is serialized into the HTML and available immediately on the client.
 
-const store = createStore({ types, entities })
+### 🎨 Dynamic Routes with `staticPaths`
 
-export const { Provider, useSelector, useNotify } = createReactStore(store)
+Generate multiple pages from data:
 
-function App() {
-  return (
-    // No store prop needed!
-    <Provider>
-      <Counter />
-    </Provider>
-  )
+```javascript
+// src/pages/posts/_slug.js
+import { html } from "@inglorious/web"
+
+export const post = {
+  render(entity) {
+    return html`
+      <article>
+        <h1>${entity.post.title}</h1>
+        <div>${entity.post.body}</div>
+      </article>
+    `
+  },
 }
 
-function Counter() {
-  const notify = useNotify() // less verbose than dispatch
-  const count = useSelector((state) => state.counter1.value)
-
-  return (
-    <div>
-      <p>{count}</p>
-      <button onClick={() => notify("increment")}>+</button> // simplified
-      syntax
-      <button onClick={() => notify("decrement")}>-</button>
-    </div>
+// Load data for a specific post
+export async function load(entity, page) {
+  const response = await fetch(
+    `https://api.example.com/posts/${page.params.slug}`,
   )
+  entity.post = await response.json()
 }
-```
-
-The package is fully typed, providing a great developer experience with TypeScript.
 
----
-
-## Core Features
-
-### 🎮 Entity-Based State
+// Tell SSX which pages to generate
+export async function staticPaths() {
+  const response = await fetch(`https://api.example.com/posts`)
+  const posts = await response.json()
 
-The real power: add entities dynamically without code changes.
-
-**Redux/RTK:** To manage three counters, you can reuse a reducer. But what if you want to add a new counter at runtime? Your best option is probably to reshape the whole state.
-
-```javascript
-// The original list of counters:
-const store = configureStore({
-  reducer: {
-    counter1: counterReducer,
-    counter2: counterReducer,
-    counter3: counterReducer,
-  },
-})
+  return posts.map((post) => ({
+    params: { slug: post.slug },
+    path: `/posts/${post.slug}`,
+  }))
+}
 
-// becomes:
-const store = configureStore({
-  reducer: {
-    counters: countersReducer,
+export const metadata = (entity) => ({
+  title: entity.post.title ?? "Post",
+  meta: {
+    description: entity.post.excerpt,
   },
 })
-
-// with extra actions to manage adding/removing counters:
-store.dispatch({ type: "addCounter", payload: "counter4" })
 ```
 
-**Inglorious Store** makes it trivial:
+### 📄 Page Metadata
+
+Export metadata for HTML `<head>`. The `metadata` export can be a plain object or a function:
 
 ```javascript
-const types = {
-  counter: {
-    increment(entity) {
-      entity.value++
-    },
+export const index = {
+  render() {
+    return html`<h1>Home</h1>`
   },
 }
 
-const entities = {
-  counter1: { type: "counter", value: 0 },
-  counter2: { type: "counter", value: 0 },
-  counter3: { type: "counter", value: 0 },
+// Static metadata
+export const metadata = {
+  title: "My Site",
+  meta: {
+    description: "An awesome static site",
+    "og:image": "/og-image.png",
+  },
 }
 
-store.notify("add", { id: "counter4", type: "counter", value: 0 })
-```
-
-Inglorious Store has a few built-in events that you can use:
-
-- `add`: adds a new entity to the state. Triggers a `create` lifecycle event.
-- `remove`: removes an entity from the state. Triggers a `destroy` lifecycle event.
-
-The lifecycle events can be used to define event handlers similar to constructor and destructor methods in OOP:
-
-> Remember: events are broadcast to all entities, just like with reducers! Each handler decides if it should respond. More on that in the section below.
-
-```javascript
-const types = {
-  counter: {
-    create(entity, id) {
-      if (entity.id !== id) return // "are you talking to me?"
-      entity.createdAt = Date.now()
-    },
-
-    destroy(entity, id) {
-      if (entity.id !== id) return // "are you talking to me?"
-      entity.destroyedAt = Date.now()
-    },
+// Or dynamic metadata (uses entity data)
+export const metadata = (entity) => ({
+  title: `${entity.user.name}'s Profile`,
+  meta: {
+    description: entity.user.bio,
+    "og:image": entity.user.avatar,
   },
-}
+})
 ```
 
-### 🔊 Event Broadcasting
+### 🔥 Client-Side Hydration
 
-Events are broadcast to all entities via pub/sub. Every entity handler receives every event of that type, just like it does in Redux.
+Pages hydrate automatically with lit-html. Interactivity works immediately:
 
 ```javascript
-const types = {
-  todoList: {
-    taskCompleted(entity, taskId) {
-      const task = entity.tasks.find((t) => t.id === taskId)
-      if (task) task.completed = true
-    },
-  },
-  stats: {
-    taskCompleted(entity, taskId) {
-      entity.completedCount++
-    },
-  },
-  notifications: {
-    taskCompleted(entity, taskId) {
-      entity.messages.push("Nice! Task completed.")
-    },
+export const counter = {
+  click(entity) {
+    entity.count++
   },
-}
-
-// One notify call, all three entity types respond
-store.notify("taskCompleted", "task123")
-```
 
-In RTK, such action would have be to be defined outside of the slice with `createAction` and then processed with the builder callback notation inside of the `extraReducers` section.
-
-- What if you want to notify the event only to entities of one specific type? Define an event handler for that event only on that type.
-- What if you want to notify the event only on one entity of that type? Add an if that checks if the entity should be bothered or not by it.
-
-```javascript
-const types = {
-  todoList: {
-    toggle(entity, id) {
-      // This runs for EVERY todoList entity, but only acts if it's the right one
-      if (entity.id !== id) return
-
-      const todo = entity.todos.find((t) => t.id === id)
-      if (todo) todo.completed = !todo.completed
-    },
+  render(entity, api) {
+    return html`
+      <div>
+        <p>Count: ${entity.count}</p>
+        <button @click=${() => api.notify(`#${entity.id}:click`)}>
+          Increment
+        </button>
+      </div>
+    `
   },
 }
-
-// Broadcast to all todo lists
-store.notify("toggle", "todo1")
-// Each list's toggle handler runs; only the one with todo1 actually updates
 ```
 
-### ⚡ Async Operations
+The HTML is pre-rendered on the server. When JavaScript loads, lit-html hydrates the existing DOM and wires up event handlers. No flash of unstyled content, no duplicate rendering.
 
-In **Redux/RTK**, logic should be written inside pure functions as much as possible — specifically in reducers, not action creators. But what if I need to access some other part of the state that is not visible to the reducer? What if I need to combine async behavior with sync behavior? This is where the choice of "where does my logic live?" matters.
+### 🧭 Client-Side Navigation
 
-In **Inglorious Store:** your event handlers can be async, and you get deterministic behavior automatically. Inside an async handler, you can access other parts of state (read-only), and you can trigger other events via `api.notify()`. Even if we give up on some purity, everything still maintains predictability because of the underlying **event queue**:
+After hydration, navigation is instant:
 
 ```javascript
-const types = {
-  todoList: {
-    async loadTodos(entity, payload, api) {
-      try {
-        entity.loading = true
-        const { name } = api.getEntity("user")
-        const response = await fetch(`/api/todos/${name}`)
-        const data = await response.json()
-        api.notify("todosLoaded", todos)
-      } catch (error) {
-        api.notify("loadFailed", error.message)
-      }
-    },
+// Links navigate without page reload
+;<a href="/about">About</a> // Client-side routing
 
-    todosLoaded(entity, todos) {
-      entity.todos = todos
-      entity.loading = false
-    },
+// Programmatic navigation
+api.notify("navigate", "/posts")
 
-    loadFailed(entity, error) {
-      entity.error = error
-      entity.loading = false
-    },
-  },
-}
+// With options
+api.notify("navigate", {
+  to: "/posts/123",
+  replace: true,
+})
 ```
 
-Notice: you don't need pending/fulfilled/rejected actions. You stay in control of the flow — no hidden action chains. The `api` object passed to handlers provides:
-
-- **`api.getEntities()`** - read entire state
-- **`api.getEntity(id)`** - read one entity
-- **`api.notify(type, payload)`** - trigger other events (queued, not immediate)
-- **`api.dispatch(action)`** - optional, if you prefer Redux-style dispatching
-- **`api.getTypes()`** - access type definitions (mainly for middleware/plugins)
-- **`api.getType(typeName)`** - access type definition (mainly for overrides)
+Routes are lazy-loaded on demand, keeping initial bundle size small.
 
-All events triggered via `api.notify()` enter the queue and process together, maintaining predictability and testability.
-
-### 🧪 Testing
-
-Event handlers are pure functions (or can be treated as such), making them easy to test in isolation, much like Redux reducers. The `@inglorious/store/test` module provides utility functions to make this even simpler.
+---
 
-#### `trigger(entity, handler, payload, api?)`
+## CLI
 
-The `trigger` function executes an event handler on a single entity and returns the new state and any events that were dispatched.
+SSX provides a simple CLI for building and developing:
 
-```javascript
-import { trigger } from "@inglorious/store/test"
+### `ssx build`
 
-// Define your entity handler
-function increment(entity, payload, api) {
-  entity.value += payload.amount
-  if (entity.value > 100) {
-    api.notify("overflow", { id: entity.id })
-  }
-}
+Builds your static site:
 
-// Test it
-const { entity, events } = trigger(
-  { type: "counter", id: "counter1", value: 99 },
-  increment,
-  { amount: 5 },
-)
+```bash
+ssx build [options]
 
-expect(entity.value).toBe(104)
-expect(events).toEqual([{ type: "overflow", payload: { id: "counter1" } }])
+Options:
+  -c, --config <file>  Config file (default: "site.config.js")
+  -r, --root <dir>     Source root directory (default: "src")
+  -o, --out <dir>      Output directory (default: "dist")
+  -i, --incremental    Enable incremental builds (default: true)
+  -f, --force          Force clean build, ignore cache
 ```
 
-#### `createMockApi(entities)`
+### `ssx dev`
 
-If your handler needs to interact with other entities via the `api`, you can create a mock API. This is useful for testing handlers that read from other parts of the state.
+Starts development server with hot reload:
 
-```javascript
-import { createMockApi, trigger } from "@inglorious/store/test"
+```bash
+ssx dev [options]
 
-// Create a mock API with some initial entities
-const api = createMockApi({
-  counter1: { type: "counter", value: 10 },
-  counter2: { type: "counter", value: 20 },
-})
+Options:
+  -c, --config <file>  Config file (default: "site.config.js")
+  -r, --root <dir>     Source root directory (default: "src")
+  -p, --port <port>    Dev server port (default: 3000)
+```
 
-// A handler that copies a value from another entity
-function copyValue(entity, payload, api) {
-  const source = api.getEntity(payload.sourceId)
-  entity.value = source.value
+### Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "ssx dev",
+    "build": "ssx build",
+    "preview": "pnpm dlx serve dist"
+  }
 }
+```
 
-// Trigger the handler with the custom mock API
-const { entity } = trigger(
-  { type: "counter", id: "counter2", value: 20 },
-  copyValue,
-  { sourceId: "counter1" },
-  api,
-)
+---
+
+## Project Structure
 
-expect(entity.value).toBe(10)
+```
+my-site/
+├── src/
+│   ├── pages/          # File-based routes
+│   │   ├── index.js    # Home page
+│   │   ├── about.js    # About page
+│   │   └── posts/
+│   │       ├── index.js    # /posts
+│   │       └── _id.js      # /posts/:id
+│   ├── entities.js     # Entity definitions
+│   └── types/          # Custom entity types (optional)
+├── dist/               # Build output
+├── package.json
+└── site.config.js      # Site configuration
 ```
 
-The mock API provides:
+---
 
-- `getEntities()`: Returns all entities (frozen).
-- `getEntity(id)`: Returns a specific entity by ID (frozen).
-- `dispatch(event)`: Records an event for later assertions.
-- `notify(type, payload)`: A convenience wrapper around `dispatch`.
-- `getEvents()`: Returns all events that were dispatched.
+## Comparison to Other Tools
 
-### 🌍 Systems for Global Logic
+| Feature                 | SSX         | Next.js (SSG) | Astro  | Eleventy |
+| ----------------------- | ----------- | ------------- | ------ | -------- |
+| Pre-rendered HTML       | ✅          | ✅            | ✅     | ✅       |
+| Client hydration        | ✅ lit-html | ✅ React      | ✅ Any | ❌       |
+| Client routing          | ✅          | ✅            | ✅     | ❌       |
+| Lazy loading            | ✅          | ✅            | ✅     | ❌       |
+| Entity-based state      | ✅          | ❌            | ❌     | ❌       |
+| No compilation required | ✅          | ❌            | ❌     | ✅       |
+| Zero config             | ✅          | ❌            | ❌     | ❌       |
+| Framework agnostic      | ❌          | ❌            | ✅     | ✅       |
 
-When you need to coordinate updates across multiple entities (not just respond to individual events), use systems. Systems run after all entity handlers for the same event, ensuring global consistency, and have write access to the entire state. This concept is the 'S' in the ECS Architecture (Entity-Component-System)!
+SSX is perfect if you:
 
-```javascript
-const systems = [
-  {
-    taskCompleted(state, taskId) {
-      // Read from multiple todo lists
-      const allTodos = Object.values(state)
-        .filter((e) => e.type === "todoList")
-        .flatMap((e) => e.todos)
-
-      // Update global stats
-      state.stats.total = allTodos.length
-      state.stats.completed = allTodos.filter((t) => t.completed).length
-    },
-  },
-]
+- Want static site performance
+- Love entity-based architecture
+- Prefer convention over configuration
+- Need full client-side interactivity
+- Don't want React/Vue lock-in
 
-const store = createStore({ types, entities, systems })
-```
+---
 
-Systems receive the entire state and can modify any entity. They're useful for cross-cutting concerns, maintaining derived state, or coordinating complex state updates that can't be expressed as individual entity handlers.
+## Advanced Usage
 
-### 🔗 Behavior Composition
+### Site Configuration
 
-A type can be a single behavior object, or an array of behaviors.
+Customize SSX behavior in `src/site.config.js`:
 
 ```javascript
-// single-behavior type
-const counter = {
-  increment(entity) {
-    entity.value++
+export default {
+  // Basic metadata
+  lang: "en",
+  charset: "UTF-8",
+  title: "My Awesome Site",
+  meta: {
+    description: "A site built with SSX",
+    "og:type": "website",
   },
 
-  decrement(entity) {
-    entity.value--
+  // Global assets
+  styles: ["./styles/reset.css", "./styles/theme.css"],
+  scripts: ["./scripts/analytics.js"],
+
+  // Build options
+  basePath: "/",
+  rootDir: "src",
+  outDir: "dist",
+  publicDir: "public",
+  favicon: "/favicon.ico",
+
+  // Router config
+  router: {
+    trailingSlash: false,
+    scrollBehavior: "smooth",
   },
-}
 
-// multiple behavior type
-const resettableCounter = [
-  counter,
-  {
-    reset(entity) {
-      entity.value = 0
+  // Vite config passthrough
+  vite: {
+    server: {
+      port: 3000,
+      open: true,
     },
   },
-]
-```
-
-A behavior is defined as either an object with event handlers, or a function that takes a type and returns an enhanced behavior (decorator pattern):
 
-```javascript
-// Base behavior
-const resettable = {
-  submit(entity, value) {
-    entity.value = ""
+  // Build hooks
+  hooks: {
+    beforeBuild: async (config) => console.log("Starting build..."),
+    afterBuild: async (result) => console.log(`Built ${result.pages} pages`),
   },
 }
-
-// Function that wraps and enhances a behavior
-const validated = (type) => ({
-  submit(entity, value, api) {
-    if (!value.trim()) return
-    type.submit?.(entity, value, api) // remember to always pass all args!
-  },
-})
-
-// Another wrapper
-const withLoading = (type) => ({
-  submit(entity, value, api) {
-    entity.loading = true
-    type.submit?.(entity, value, api)
-    entity.loading = false
-  },
-})
-
-// Compose them together to form a type
-const form = [resettable, validated, withLoading]
 ```
 
-When multiple behaviors define the same event, they all run in order. This allows you to build middleware-like patterns: validation, logging, error handling, loading states, etc.
-
-### ⏱️ Batched Mode
+### Environment Variables
 
-The Inglorious Store features an **event queue**. In the default `auto` update mode, each notified event will trigger and update of the state (same as Redux). But in `manual` update mode, you can process multiple events together before re-rendering:
+Use Vite's environment variables:
 
 ```javascript
-const store = createStore({ types, entities, updateMode: "manual" })
+// Access in your code
+const apiUrl = import.meta.env.VITE_API_URL
 
-// add events to the event queue
-store.notify("playerMoved", { x: 100, y: 50 })
-store.notify("enemyAttacked", { damage: 10 })
-store.notify("particleCreated", { type: "explosion" })
-
-// process them all in batch
-store.update()
+// .env file
+VITE_API_URL=https://api.example.com
 ```
 
-Instead of re-rendering after each event, you can batch them and re-render once. This is what powers high-performance game engines and smooth animations.
-
----
-
-## Comparison with Other State Libraries
-
-| Feature                   | Redux        | RTK          | Zustand    | Jotai      | Pinia      | MobX       | Inglorious Store |
-| ------------------------- | ------------ | ------------ | ---------- | ---------- | ---------- | ---------- | ---------------- |
-| **Boilerplate**           | 🔴 High      | 🟡 Medium    | 🟢 Low     | 🟢 Low     | 🟡 Medium  | 🟢 Low     | 🟢 Low           |
-| **Multiple instances**    | 🔴 Manual    | 🔴 Manual    | 🔴 Manual  | 🔴 Manual  | 🟡 Medium  | 🟡 Medium  | 🟢 Built-in      |
-| **Lifecycle events**      | 🔴 No        | 🔴 No        | 🔴 No      | 🔴 No      | 🔴 No      | 🔴 No      | 🟢 Yes           |
-| **Async logic placement** | 🟡 Thunks    | 🟡 Complex   | 🟢 Free    | 🟢 Free    | 🟢 Free    | 🟢 Free    | 🟢 In handlers   |
-| **Redux DevTools**        | 🟢 Yes       | 🟢 Yes       | 🟡 Partial | 🟡 Partial | 🟡 Partial | 🟢 Yes     | 🟢 Yes           |
-| **Time-travel debugging** | 🟢 Yes       | 🟢 Yes       | 🔴 No      | 🔴 No      | 🔴 No      | 🟡 Limited | 🟢 Yes           |
-| **Testability**           | 🟢 Excellent | 🟢 Excellent | 🟡 Good    | 🟡 Good    | 🟡 Good    | 🟡 Medium  | 🟢 Excellent     |
-| **Immutability**          | 🔴 Manual    | 🟢 Immer     | 🔴 Manual  | 🔴 Manual  | 🔴 Manual  | 🔴 Manual  | 🟢 Mutative      |
-
----
-
-## API Reference
+### Custom 404 Page
 
-### `createStore(options)`
+Create a fallback route:
 
 ```javascript
-const store = createStore({
-  types, // Object: entity type definitions
-  entities, // Object: initial entities
-  systems, // Array (optional): global state handlers
-  updateMode, // String (optional): 'auto' (default) or 'manual'
-})
-```
-
-**Returns:** A Redux-compatible store
-
-### Types Definition
+// src/pages/404.js
+export const notFound = {
+  render() {
+    return html`
+      <div>
+        <h1>404 - Page Not Found</h1>
+        <a href="/">Go Home</a>
+      </div>
+    `
+  },
+}
 
-```javascript
-const types = {
-  entityType: [
-    // Behavior objects
-    {
-      eventName(entity, payload, api) {
-        entity.value = payload
-        api.notify("otherEvent", data)
-      },
-    },
-    // Behavior functions (decorators)
-    (behavior) => ({
-      eventName(entity, payload, api) {
-        // Wrap the behavior
-        behavior.eventName?.(entity, payload, api)
-      },
-    }),
-  ],
+export const metadata = {
+  title: "404",
 }
 ```
 
-### Event Handler API
-
-Each handler receives three arguments:
-
-- **`entity`** - the entity instance (mutate freely, immutability guaranteed)
-- **`payload`** - data passed with the event
-- **`api`** - access to store methods:
-  - `getEntities()` - entire state (read-only)
-  - `getEntity(id)` - single entity (read-only)
-  - `notify(type, payload)` - trigger other events
-  - `dispatch(action)` - optional, if you prefer Redux-style dispatching
-  - `getTypes()` - type definitions (for middleware)
-  - `getType(typeName)` - type definition (for overriding)
-  - `setType(typeName, type)` - change the behavior of a type
-
-### Built-in Events
-
-- **`create(entity)`** - triggered when entity added via `add` event, visible only to that entity
-- **`destroy(entity)`** - triggered when entity removed via `remove` event, visible only to that entity
-
-### Notify vs Dispatch
-
-Both work (`dispatch` is provided just for Redux compatibility), but `notify` is cleaner (and uses `dispatch` internally):
+Register it in your router:
 
 ```javascript
-store.notify("eventName", payload)
-store.dispatch({ type: "eventName", payload }) // Redux-compatible alternative
+// src/entities.js
+import { setRoutes } from "@inglorious/web/router"
+
+setRoutes({
+  // ... other routes
+  "*": "notFound", // Fallback
+})
 ```
 
-### 🧩 Type Safety
+### Incremental Builds
 
-Inglorious Store is written in JavaScript but comes with powerful TypeScript support out of the box, allowing for a fully type-safe experience similar to Redux Toolkit, but with less boilerplate.
+SSX enables incremental builds by default. Only changed pages are rebuilt, dramatically speeding up your build process:
 
-You can achieve strong type safety by defining an interface for your `types` configuration. This allows you to statically define the shape of your entity handlers, ensuring that all required handlers are present and correctly typed.
+```bash
+ssx build
+# Only changed pages are rebuilt
 
-Here’s how you can set it up for a TodoMVC-style application:
+ssx build --force
+# Force a clean rebuild of all pages
+```
 
-**1. Define Your Types**
+Incremental builds respect your page dependencies and invalidate cache when dependencies change.
 
-First, create an interface that describes your entire `types` configuration. This interface will enforce the structure of your event handlers.
+---
 
-```typescript
-// src/store/types.ts
-import type {
-  FormEntity,
-  ListEntity,
-  FooterEntity,
-  // ... other payload types
-} from "../../types"
+## API Reference
 
-// Define the static shape of the types configuration
-interface TodoListTypes {
-  form: {
-    inputChange: (entity: FormEntity, value: string) => void
-    formSubmit: (entity: FormEntity) => void
-  }
-  list: {
-    formSubmit: (entity: ListEntity, value: string) => void
-    toggleClick: (entity: ListEntity, id: number) => void
-    // ... other handlers
-  }
-  footer: {
-    filterClick: (entity: FooterEntity, id: string) => void
-  }
-}
+### Build API
 
-export const types: TodoListTypes = {
-  form: {
-    inputChange(entity, value) {
-      entity.value = value
-    },
-    formSubmit(entity) {
-      entity.value = ""
-    },
-  },
-  // ... other type implementations
-}
+```javascript
+import { build } from "@inglorious/ssx/build"
+
+await build({
+  rootDir: "src",
+  outDir: "dist",
+  configFile: "site.config.js",
+  incremental: true,
+  clean: false,
+})
 ```
 
-With `TodoListTypes`, TypeScript will throw an error if you forget a handler (e.g., `formSubmit`) or if its signature is incorrect.
-
-**2. Create the Store**
+### Dev Server API
 
-When creating your store, you'll pass the `types` object. To satisfy the store's generic `TypesConfig`, you may need to use a double cast (`as unknown as`). This is a safe and intentional way to bridge your specific, statically-checked configuration with the store's more generic type.
-
-```typescript
-// src/store/index.ts
-import { createStore, type TypesConfig } from "@inglorious/store"
-import { types } from "./types"
-import type { TodoListEntity, TodoListState } from "../../types"
+```javascript
+import { dev } from "@inglorious/ssx/dev"
 
-export const store = createStore<TodoListEntity, TodoListState>({
-  types: types as unknown as TypesConfig<TodoListEntity>,
-  // ... other store config
+await dev({
+  rootDir: "src",
+  port: 3000,
+  configFile: "site.config.js",
 })
 ```
 
-**3. Enjoy Full Type Safety**
-
-Now, your store is fully type-safe. The hooks provided by `@inglorious/react-store` will also be correctly typed.
-
 ---
 
-## Use Cases
+<!-- ## Examples
 
-### Perfect For
+Check out these example projects:
 
-- 🎮 Apps with multiple instances of the same entity type
-- 🎯 Real-time collaborative features
-- ⚡ Complex state coordination and async operations
-- 📊 High-frequency updates (animations, games)
-- 🔄 Undo/redo, time-travel debugging
+- **[Basic Blog](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/ssx-blog)** - Simple blog with posts
+- **[Documentation Site](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/ssx-docs)** - Multi-page docs
+- **[E-commerce](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/ssx-shop)** - Product catalog
+- **[Portfolio](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/ssx-portfolio)** - Personal portfolio
 
-### Still Great For
+--- -->
 
-- Any Redux use case (true drop-in replacement)
-- Migration path from Redux (keep using react-redux)
+## Roadmap
 
----
+- [ ] TypeScript support
+- [ ] Image optimization
+- [ ] API routes (serverless functions)
+- [ ] MDX support
+- [ ] i18n helpers
 
-### Demos
+---
 
-Check out the following demos to see the Inglorious Store in action on real-case scenarios:
+## Philosophy
 
-**React Examples:**
+SSX embraces the philosophy of [@inglorious/web](https://www.npmjs.com/package/@inglorious/web):
 
-- **[React TodoMVC](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/apps/react-todomvc)** - An (ugly) clone of Kent Dodds' [TodoMVC](https://todomvc.com/) experiments, showing the full compatibility with react-redux and The Redux DevTools.
-- **[React TodoMVC-CS](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/apps/react-todomvc-cs)** - A client-server version of the TodoMVC, which showcases the use of `notify` as a cleaner alternative to `dispatch` and async event handlers.
-- **[React TodoMVC-RT](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/apps/react-todomvc-rt)** - A "multiplayer" version, in which multiple clients are able to synchronize through a real-time server.
-- **[React TodoMVC-TS](https://github.com/IngloriousCoderz/inglorious-forge/tree/main/examples/apps/react-todomvc-ts)** - A typesafe version of the base TodoMVC.
+- **Simplicity over cleverness** - Obvious beats clever
+- **Convention over configuration** - Sensible defaults
+- **Predictability over magic** - Explicit is better than implicit
+- **Standards over abstractions** - Use the platform
 
-For more demos and examples with `@inglorious/web`, see the [`@inglorious/web` README](../web/README.md).
+Static site generation should be simple. SSX makes it simple.
 
 ---
 
-## Frequently Unsolicited Complaints (FUCs)
-
-It's hard to accept the new, especially on Reddit. Here are the main objections to the Inglorious Store.
+## Contributing
 
-**"This is not ECS."**
+Contributions are welcome! Please read our [Contributing Guidelines](../../CONTRIBUTING.md) first.
 
-It's not. The Inglorious Store is _inspired_ by ECS, but doesn't strictly follow ECS. Heck, not even the major game engines out there follow ECS by the book!
+---
 
-Let's compare the two:
+## License
 
-| ECS Architecture                      | Inglorious Store                       |
-| ------------------------------------- | -------------------------------------- |
-| Entities are ids                      | Entities have an id                    |
-| Components are pure, consecutive data | Entities are pure bags of related data |
-| Data and behavior are separated       | Data and behavior are separated        |
-| Systems operate on the whole state    | Systems operate on the whole state     |
-| Usually written in an OOP environment | Written in an FP environment           |
+**MIT License** - Free and open source
 
-**"This is not FP."**
+Created by [Matteo Antony Mistretta](https://github.com/IngloriousCoderz)
 
-It looks like it's not, and that's a feature. If you're used to classes and instances, the Inglorious Store will feel natural to you. Even behavior composition looks like inheritance, but it's actually function composition. The same [Three Principles](https://redux.js.org/understanding/thinking-in-redux/three-principles) that describe Redux are applied here (with some degree of freedom on function purity).
+---
 
-**"This is not Data-Oriented Design."**
+## Related Packages
 
-It's not. Please grep this README and count how many occurrences of DoD you can find. This is not [Data-Oriented Design](https://en.wikipedia.org/wiki/Data-oriented_design), which is related to low-level CPU cache optimization. It's more similar to [Data-Driven Programming](https://en.wikipedia.org/wiki/Data-driven_programming), which is related to separating data and behavior. The Inglorious Store separates behavior in... behaviors (grouped into so-called types), while the data is stored in plain objects called entities.
+- [@inglorious/web](https://www.npmjs.com/package/@inglorious/web) - Entity-based web framework
+- [@inglorious/store](https://www.npmjs.com/package/@inglorious/store) - State management
+- [@inglorious/engine](https://www.npmjs.com/package/@inglorious/engine) - Game engine
 
 ---
 
-## License
-
-MIT © [Matteo Antony Mistretta](https://github.com/IngloriousCoderz)
+## Support
 
-Free to use, modify, and distribute.
+- 📖 [Documentation](https://inglorious-engine.vercel.app)
+- 💬 [Discord Community](https://discord.gg/Byx85t2eFp)
+- 🐛 [Issue Tracker](https://github.com/IngloriousCoderz/inglorious-forge/issues)
+- 📧 [Email Support](mailto:antony.mistretta@gmail.com)
 
 ---
 
-## Contributing
-
-Contributions welcome! Please read our [Contributing Guidelines](../../CONTRIBUTING.md) first.
+**Build static sites the Inglorious way. Simple. Predictable. Fast.** 🚀