@apex-stack/core 0.5.0 → 0.6.0

package/dist/{build-VHS6KZBK.js → build-XUDXRQ4W.js}

@@ -7,8 +7,8 @@ import {
   renderPage,
   resolveApexConfig,
   scanPages
-} from "./chunk-XDKJO6ZC.js";
-import "./chunk-JLIAISWM.js";
+} from "./chunk-DVNFDYEO.js";
+import "./chunk-PMLGY6Z3.js";
 
 // src/commands/build.ts
 import { cpSync, existsSync as existsSync3, mkdirSync, readdirSync as readdirSync3, rmSync, writeFileSync } from "fs";
@@ -18,7 +18,7 @@ import { defineCommand } from "citty";
 import { createServer as createViteServer } from "vite";
 
 // src/build/buildClient.ts
-import { existsSync, readFileSync, readdirSync } from "fs";
+import { existsSync, readdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { apex } from "@apex-stack/vite";
 import { build } from "vite";

package/dist/{chunk-XDKJO6ZC.js → chunk-DVNFDYEO.js}

@@ -2,7 +2,7 @@ import {
   clientConfigScript,
   isApexStore,
   setRuntimeConfig
-} from "./chunk-JLIAISWM.js";
+} from "./chunk-PMLGY6Z3.js";
 
 // src/config/resolve.ts
 import { existsSync, readFileSync } from "fs";

package/dist/{chunk-JLIAISWM.js → chunk-PMLGY6Z3.js}

@@ -1,14 +1,3 @@
-// src/store.ts
-function defineStore(name, factory) {
-  if (!name || /[^a-zA-Z0-9_$]/.test(name)) {
-    throw new Error(`defineStore: invalid store name "${name}" \u2014 use letters, digits, _ or $.`);
-  }
-  return { __apexStore: true, name, factory };
-}
-function isApexStore(x) {
-  return typeof x === "object" && x !== null && x.__apexStore === true;
-}
-
 // src/config/runtime.ts
 function defineConfig(config) {
   return config;
@@ -37,12 +26,23 @@ function env(key, fallback) {
   return fallback;
 }
 
+// src/store.ts
+function defineStore(name, factory) {
+  if (!name || /[^a-zA-Z0-9_$]/.test(name)) {
+    throw new Error(`defineStore: invalid store name "${name}" \u2014 use letters, digits, _ or $.`);
+  }
+  return { __apexStore: true, name, factory };
+}
+function isApexStore(x) {
+  return typeof x === "object" && x !== null && x.__apexStore === true;
+}
+
 export {
-  defineStore,
-  isApexStore,
   defineConfig,
   setRuntimeConfig,
   clientConfigScript,
   useRuntimeConfig,
-  env
+  env,
+  defineStore,
+  isApexStore
 };

package/dist/cli.js

@@ -14,7 +14,7 @@ import { defineCommand as defineCommand2, runMain } from "citty";
 
 // src/commands/new.ts
 import { spawn, spawnSync } from "child_process";
-import { cpSync, existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from "fs";
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { basename, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { defineCommand } from "citty";
@@ -147,13 +147,13 @@ var main = defineCommand2({
   },
   subCommands: {
     new: newCommand,
-    dev: () => import("./dev-G7HPP6KW.js").then((m) => m.devCommand),
-    build: () => import("./build-VHS6KZBK.js").then((m) => m.buildCommand),
-    start: () => import("./start-3O3E43PT.js").then((m) => m.startCommand),
+    dev: () => import("./dev-74CABXDP.js").then((m) => m.devCommand),
+    build: () => import("./build-XUDXRQ4W.js").then((m) => m.buildCommand),
+    start: () => import("./start-TBG2TEOE.js").then((m) => m.startCommand),
     make: () => import("./make-VAYO5GWA.js").then((m) => m.makeCommand),
     add: () => import("./add-M3YLIFF5.js").then((m) => m.addCommand),
     theme: () => import("./theme-UUOIV44V.js").then((m) => m.themeCommand),
-    upgrade: () => import("./upgrade-WC5F5FKY.js").then((m) => m.upgradeCommand),
+    upgrade: () => import("./upgrade-GCRSV4IE.js").then((m) => m.upgradeCommand),
     migrate: () => import("./migrate-X6LIHMIE.js").then((m) => m.migrateCommand),
     mcp: () => import("./mcp-CH7L4GF3.js").then((m) => m.mcpCommand)
   },

package/dist/client.js

@@ -1,5 +1,5 @@
 // src/client.ts
-import { registerApexComponent, createAction } from "@apex-stack/kit/client";
+import { createAction, registerApexComponent } from "@apex-stack/kit/client";
 export {
   createAction,
   registerApexComponent

package/dist/{dev-G7HPP6KW.js → dev-74CABXDP.js}

@@ -24,7 +24,7 @@ var devCommand = defineCommand({
     process.stdout.write(banner());
     const sp = spinner(`Starting dev server${args.islands ? " (islands mode)" : ""}\u2026`);
     try {
-      const { startDevServer } = await import("./server-PTHGOE42.js");
+      const { startDevServer } = await import("./server-VQSL2KPO.js");
       const { port: actual } = await startDevServer({ root, port, islands: Boolean(args.islands) });
       sp.succeed("Dev server ready");
       ready([

package/dist/index.d.ts

@@ -124,31 +124,6 @@ interface ApexResource {
 }
 declare function isApexResource(x: unknown): x is ApexResource;
 
-type StoreState = Record<string, unknown>;
-interface ApexStore {
-    readonly __apexStore: true;
-    readonly name: string;
-    readonly factory: () => StoreState;
-}
-/**
- * Define a global, SSR-safe store shared across every page, component, and island.
- *
- * ```ts
- * // stores/cart.ts
- * import { defineStore } from '@apex-stack/core'
- * export default defineStore('cart', () => ({
- *   items: [] as string[],
- *   get count() { return this.items.length },
- *   add(x: string) { this.items.push(x) },
- * }))
- * ```
- *
- * Access it anywhere as `$store.cart` — `$store.cart.count` renders on the server
- * and stays reactive after hydration.
- */
-declare function defineStore(name: string, factory: () => StoreState): ApexStore;
-declare function isApexStore(x: unknown): x is ApexStore;
-
 /** The short-circuit value returned by `ctx.redirect(...)`. */
 interface MiddlewareResult {
     readonly __apexRedirect: true;
@@ -178,4 +153,29 @@ type Middleware = (ctx: MiddlewareContext) => MiddlewareReturn | Promise<Middlew
 /** Author a middleware. Identity function — for types + discoverability. */
 declare function defineMiddleware(fn: Middleware): Middleware;
 
+type StoreState = Record<string, unknown>;
+interface ApexStore {
+    readonly __apexStore: true;
+    readonly name: string;
+    readonly factory: () => StoreState;
+}
+/**
+ * Define a global, SSR-safe store shared across every page, component, and island.
+ *
+ * ```ts
+ * // stores/cart.ts
+ * import { defineStore } from '@apex-stack/core'
+ * export default defineStore('cart', () => ({
+ *   items: [] as string[],
+ *   get count() { return this.items.length },
+ *   add(x: string) { this.items.push(x) },
+ * }))
+ * ```
+ *
+ * Access it anywhere as `$store.cart` — `$store.cart.count` renders on the server
+ * and stays reactive after hydration.
+ */
+declare function defineStore(name: string, factory: () => StoreState): ApexStore;
+declare function isApexStore(x: unknown): x is ApexStore;
+
 export { type ApexConfig, type ApexResource, type ApexRoute, type ApexRouteConfig, type ApexRouteHandlerContext, type ApexStore, type HttpMethod, type InferInput, type InferOutput, type Middleware, type MiddlewareContext, type MiddlewareResult, type ResourceRoute, type RuntimeConfig, type StoreState, type TypedApexRoute, defineApexRoute, defineConfig, defineMiddleware, defineStore, env, isApexResource, isApexStore, useRuntimeConfig };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   env,
   isApexStore,
   useRuntimeConfig
-} from "./chunk-JLIAISWM.js";
+} from "./chunk-PMLGY6Z3.js";
 
 // src/api/defineRoute.ts
 function defineApexRoute(config) {

package/dist/{server-PTHGOE42.js → server-VQSL2KPO.js}

@@ -16,11 +16,11 @@ import {
   renderPage,
   resolveApexConfig,
   scanPages
-} from "./chunk-XDKJO6ZC.js";
-import "./chunk-JLIAISWM.js";
+} from "./chunk-DVNFDYEO.js";
+import "./chunk-PMLGY6Z3.js";
 
 // src/dev/server.ts
-import { existsSync as existsSync2, readdirSync } from "fs";
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "fs";
 import { createServer as createHttpServer } from "http";
 import { createRequire } from "module";
 import { join } from "path";
@@ -175,17 +175,31 @@ async function startDevServer(options) {
   if (alpine) alias.alpinejs = alpine;
   if (kit) alias["@apex-stack/kit"] = kit;
   const plugins = [apex({ clientRuntime: "@apex-stack/core/client" })];
+  let hasTailwind = false;
   try {
     const reqProj = createRequire(join(options.root, "package.json"));
     const twMod = await import(pathToFileURL(reqProj.resolve("@tailwindcss/vite")).href);
     const tw = twMod.default ?? twMod;
     plugins.unshift(tw());
+    hasTailwind = true;
   } catch {
   }
   const appCssRel = ["app.css", "styles/app.css", "src/app.css"].find(
     (p) => existsSync2(join(options.root, p))
   );
-  const appCss = appCssRel ? `/${appCssRel}` : void 0;
+  let appCss = appCssRel ? `/${appCssRel}` : void 0;
+  if (appCssRel && !hasTailwind) {
+    const css = readFileSync2(join(options.root, appCssRel), "utf8");
+    if (/@import\s+['"]tailwindcss['"]|@tailwind\b/.test(css)) {
+      console.warn(
+        `
+  \u26A0 ${appCssRel} imports Tailwind, but it isn't installed \u2014 skipping it (styles won't apply).
+    Fix: npm i -D tailwindcss @tailwindcss/vite
+`
+      );
+      appCss = void 0;
+    }
+  }
   const vite = await createViteServer({
     root: options.root,
     appType: "custom",

package/dist/{start-3O3E43PT.js → start-TBG2TEOE.js}

@@ -11,8 +11,8 @@ import {
   matchRoute,
   renderIslandsPage,
   renderPage
-} from "./chunk-XDKJO6ZC.js";
-import "./chunk-JLIAISWM.js";
+} from "./chunk-DVNFDYEO.js";
+import "./chunk-PMLGY6Z3.js";
 
 // src/commands/start.ts
 import { existsSync as existsSync2 } from "fs";

package/dist/{upgrade-WC5F5FKY.js → upgrade-GCRSV4IE.js}

@@ -9,7 +9,7 @@ import {
 
 // src/commands/upgrade.ts
 import { spawnSync } from "child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
 import { basename, dirname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import { defineCommand } from "citty";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-stack/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The full-stack meta-framework for Alpine.js — CLI and runtime",
   "type": "module",
   "license": "MIT",
@@ -47,8 +47,8 @@
     "h3": "^1.13.0",
     "vite": "^6.0.7",
     "zod": "^4.4.3",
-    "@apex-stack/kit": "0.2.0",
-    "@apex-stack/vite": "0.1.6",
+    "@apex-stack/kit": "0.3.0",
+    "@apex-stack/vite": "0.1.7",
     "@apex-stack/theme": "0.3.0"
   },
   "peerDependencies": {

package/templates/default/README.md

@@ -2,15 +2,20 @@
 
 An [Apex JS](https://apexjs.site) app — HTML-first, server-rendered, AI-native.
 
+This starter is a small, themed demo: a landing page, a blog (list + dynamic
+`[slug]` detail) served from a sample-data service, an About page with SEO, a
+dark-mode toggle, themeable components, and an API route that's also an MCP tool.
+
 ## Commands
 
 ```bash
-npm run dev          # dev server → http://localhost:3000
-npm run dev:islands  # static-first islands mode (ship ~zero JS)
-npm run build        # production build
-npm start            # run the production server build
-npm test             # run tests (Vitest)
-npm run typecheck    # strict type-check
+npm run dev           # dev server → http://localhost:3000
+npm run dev:islands   # static-first islands mode (ship ~zero JS)
+npm run build         # production build (server target: SSR + dynamic routes + API/MCP)
+npm start             # run the production server build
+npm run build:static  # static build — prerenders static pages (dynamic routes need the server target)
+npm test              # run tests (Vitest)
+npm run typecheck     # strict type-check
 ```
 
 > `apex` is a project command — run it via `npm run dev`, or install it globally
@@ -21,7 +26,7 @@ npm run typecheck    # strict type-check
 ```
 pages/         File-based routes (.alpine) — server-rendered, then hydrated.
 layouts/       Shared page shells; default.alpine wraps every page (<slot/>).
-components/    Reusable <PascalCase/> components with scoped styles.
+components/    Reusable <PascalCase/> components, themed with Apex tokens (Button, Card, Badge, Counter).
 server/api/    Typed routes (defineApexRoute) — each is a REST endpoint AND an MCP tool.
 services/      Business logic as plain OO classes. Keep routes thin; delegate here.
 shared/        Types/interfaces shared by the backend and the frontend.
@@ -38,7 +43,7 @@ public/        Static assets served as-is.
   class in `services/`. Business logic stays testable in isolation and reusable everywhere.
 - **Types live in `shared/`.** One source of truth; strict TypeScript enforces them across
   backend and frontend — no drift.
-- **Tests by default.** `npm test` runs Vitest (see `tests/greeting.test.ts`).
+- **Tests by default.** `npm test` runs Vitest (see `tests/posts.test.ts`).
 
 ## Generators
 
@@ -53,13 +58,16 @@ apex make middleware auth      # → middleware/auth.ts (runs on every request)
 apex make test billing         # → tests/billing.test.ts
 ```
 
-## Styling
+## Styling & theming
 
-- **Scoped by default.** A `<style scoped>` block in an `.alpine` file is scoped to that component.
-- **Global / shared styles.** Create `app.css` (also `styles/app.css` or `src/app.css`) in the
-  project root — Apex auto-loads and processes it (Vite HMR in dev, bundled in build).
-- **Tailwind.** `npm i tailwindcss @tailwindcss/vite`, then `@import "tailwindcss";` at the top of
-  `app.css`. Apex auto-detects `@tailwindcss/vite` — no extra config.
+- **Tailwind + theme, preinstalled.** `app.css` already imports Tailwind and defines the Apex
+  theme tokens (`--color-primary`, `--radius-radius`, fonts, and a `dark` variant). Components use
+  token classes like `bg-primary` / `text-on-surface` / `rounded-radius`, so they all restyle at once.
+- **Restyle everything:** `apex theme --primary "#4f46e5" --radius 0.5rem` rewrites the managed
+  `/* apex-theme */` block in `app.css`. Or design it visually at https://apexjs.site/theme.html.
+- **Add components:** `apex add <name>` copies a themed component into `components/`. Browse them at
+  https://apexjs.site/ui.html.
+- **Scoped styles** still work too: a `<style scoped>` block in an `.alpine` file is scoped to it.
 
 ## Config & environment
 

package/templates/default/components/Badge.alpine

@@ -0,0 +1,6 @@
+<!-- Apex component adapted from Penguin UI (MIT). -->
+<template x-data>
+  <span class="inline-flex items-center gap-1 rounded-radius border border-outline bg-surface-alt px-2 py-0.5 text-xs font-medium text-on-surface dark:border-outline-dark dark:bg-surface-dark-alt dark:text-on-surface-dark">
+    <slot>Badge</slot>
+  </span>
+</template>

package/templates/default/components/Button.alpine

@@ -0,0 +1,10 @@
+<!-- Apex component adapted from Penguin UI (MIT). Styles via theme tokens
+     (bg-primary / rounded-radius / …) — needs Tailwind + @apex-stack/theme. -->
+<template x-data>
+  <button
+    type="button"
+    class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-radius bg-primary border border-primary px-4 py-2 text-sm font-medium tracking-wide text-on-primary transition hover:opacity-75 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary active:opacity-100 active:outline-offset-0 disabled:opacity-75 disabled:cursor-not-allowed dark:bg-primary-dark dark:border-primary-dark dark:text-on-primary-dark dark:focus-visible:outline-primary-dark"
+  >
+    <slot>Button</slot>
+  </button>
+</template>

package/templates/default/components/Card.alpine

@@ -0,0 +1,6 @@
+<!-- Apex component adapted from Penguin UI (MIT). -->
+<template>
+  <div class="flex flex-col gap-4 rounded-radius border border-outline bg-surface-alt p-6 text-on-surface dark:border-outline-dark dark:bg-surface-dark-alt dark:text-on-surface-dark">
+    <slot></slot>
+  </div>
+</template>

package/templates/default/components/Counter.alpine

@@ -1,15 +1,10 @@
+<!-- A small interactive component, themed with Apex tokens. `start`/`label` are
+     props; the count lives in client state and updates on click (hydrated). -->
 <template x-data="{ count: Number(start) }">
-  <button class="counter" @click="count++" x-text="label + ': ' + count"></button>
+  <button
+    type="button"
+    class="inline-flex items-center gap-2 rounded-radius border border-outline bg-surface-alt px-4 py-2 text-sm font-medium text-on-surface transition hover:opacity-75 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary dark:border-outline-dark dark:bg-surface-dark-alt dark:text-on-surface-dark dark:focus-visible:outline-primary-dark"
+    @click="count++"
+    x-text="label + ': ' + count"
+  ></button>
 </template>
-
-<style scoped>
-  .counter {
-    padding: 0.45rem 0.9rem;
-    border: 1px solid #6366f1;
-    border-radius: 0.5rem;
-    background: #eef2ff;
-    color: #3730a3;
-    cursor: pointer;
-    font: inherit;
-  }
-</style>

package/templates/default/layouts/default.alpine

@@ -1,16 +1,39 @@
+<!-- The default layout wraps every page. It's themed entirely with Apex tokens
+     (bg-surface / text-on-surface / dark:*), so restyling the whole app is one
+     `apex theme` command away. <slot></slot> is where the page renders. -->
 <template>
-  <header class="site-header">
-    <a class="brand" href="/">{{name}}</a>
-  </header>
-  <main>
-    <slot></slot>
-  </main>
-  <footer class="site-footer">Built with Apex JS</footer>
-</template>
+  <div class="flex min-h-svh flex-col bg-surface text-on-surface dark:bg-surface-dark dark:text-on-surface-dark">
+    <header class="border-b border-outline dark:border-outline-dark">
+      <nav
+        class="mx-auto flex max-w-5xl items-center gap-2 px-6 py-4"
+        x-data="{ dark: false }"
+        x-init="dark = localStorage.getItem('theme') === 'dark'; document.documentElement.classList.toggle('dark', dark)"
+      >
+        <a href="/" class="mr-auto font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">
+          {{name}}
+        </a>
+        <a href="/" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Home</a>
+        <a href="/blog" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Blog</a>
+        <a href="/about" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">About</a>
+        <button
+          type="button"
+          aria-label="Toggle dark mode"
+          class="ml-1 rounded-radius border border-outline p-2 text-on-surface hover:bg-surface-alt dark:border-outline-dark dark:text-on-surface-dark dark:hover:bg-surface-dark-alt"
+          @click="dark = !dark; document.documentElement.classList.toggle('dark', dark); localStorage.setItem('theme', dark ? 'dark' : 'light')"
+        >
+          <svg x-show="!dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
+          <svg x-cloak x-show="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="size-4" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        </button>
+      </nav>
+    </header>
+
+    <main class="mx-auto w-full max-w-5xl flex-1 px-6 py-10">
+      <slot></slot>
+    </main>
 
-<style scoped>
-  .site-header { padding: 1rem 1.5rem; border-bottom: 1px solid #e2e8f0; }
-  .brand { font-weight: 700; color: #2563eb; text-decoration: none; }
-  main { max-width: 44rem; margin: 0 auto; padding: 2.5rem 1.5rem; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.6; color: #1e293b; }
-  .site-footer { padding: 1.5rem; text-align: center; color: #64748b; font-size: 0.9rem; border-top: 1px solid #e2e8f0; }
-</style>
+    <footer class="border-t border-outline px-6 py-6 text-center text-sm text-on-surface/70 dark:border-outline-dark dark:text-on-surface-dark/70">
+      Built with
+      <a href="https://apexjs.site" class="font-medium text-primary dark:text-primary-dark">Apex JS</a>
+    </footer>
+  </div>
+</template>

package/templates/default/package.json

@@ -5,7 +5,8 @@
   "scripts": {
     "dev": "apex dev",
     "dev:islands": "apex dev --islands",
-    "build": "apex build",
+    "build": "apex build --server",
+    "build:static": "apex build",
     "start": "apex start",
     "test": "vitest run",
     "test:watch": "vitest",

package/templates/default/pages/about.alpine

@@ -0,0 +1,29 @@
+<script server lang="ts">
+  export function loader() {
+    return {}
+  }
+
+  // SEO for this page — server-rendered <title> + meta description.
+  export function head() {
+    return {
+      title: 'About · {{name}}',
+      meta: [{ name: 'description', content: 'What this Apex JS starter demonstrates.' }],
+    }
+  }
+</script>
+
+<template x-data>
+  <h1 class="font-title text-3xl font-extrabold text-on-surface-strong dark:text-on-surface-dark-strong">About this starter</h1>
+  <p class="mt-3 max-w-2xl">This app was scaffolded with <code>create-apexjs</code>. It's a small tour of what Apex gives you out of the box:</p>
+
+  <ul class="mt-6 grid gap-3 sm:grid-cols-2">
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">File routing</b><span class="text-sm">Pages, dynamic <code>[slug]</code>, and a shared layout — see <code>pages/</code>.</span></Card></li>
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">SSR + hydration</b><span class="text-sm">Loaders render real HTML; Alpine hydrates it with no flash.</span></Card></li>
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">Themed components</b><span class="text-sm">Add more with <code>apex add &lt;name&gt;</code>; restyle with <code>apex theme</code>.</span></Card></li>
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">AI-native API</b><span class="text-sm">Routes double as MCP tools at <code>/mcp</code>.</span></Card></li>
+  </ul>
+
+  <p class="mt-8 text-sm text-on-surface/80 dark:text-on-surface-dark/80">
+    Edit any file under <code>pages/</code>, <code>components/</code>, or <code>app.css</code> and save — the dev server updates instantly.
+  </p>
+</template>

package/templates/default/pages/blog/[slug].alpine

@@ -0,0 +1,38 @@
+<script server lang="ts">
+  import { PostService } from '../../services/PostService'
+
+  const posts = new PostService()
+
+  // Dynamic route: pages/blog/[slug].alpine → /blog/:slug. The matched param
+  // arrives in loader({ params }).
+  export function loader({ params }: { params: Record<string, string> }) {
+    const post = posts.bySlug(params.slug)
+    return { post: post ?? null }
+  }
+
+  export function head({ data }: { data: { post: { title: string } | null } }) {
+    return { title: `${data.post ? data.post.title : 'Not found'} · {{name}}` }
+  }
+</script>
+
+<template x-data>
+  <a href="/blog" class="text-sm text-primary hover:opacity-75 dark:text-primary-dark">← Back to blog</a>
+
+  <template x-if="post">
+    <article class="mt-4">
+      <div class="flex items-center gap-2 text-sm text-on-surface/70 dark:text-on-surface-dark/70">
+        <Badge><span x-text="post.author"></span></Badge>
+        <span x-text="post.date"></span>
+      </div>
+      <h1 class="mt-3 font-title text-3xl font-extrabold text-on-surface-strong dark:text-on-surface-dark-strong" x-text="post.title"></h1>
+      <p class="mt-4 text-lg leading-relaxed" x-text="post.body"></p>
+    </article>
+  </template>
+
+  <template x-if="!post">
+    <div class="mt-8">
+      <h1 class="font-title text-2xl font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Post not found</h1>
+      <p class="mt-2 text-on-surface/80 dark:text-on-surface-dark/80">That post doesn't exist. Try the <a href="/blog" class="text-primary dark:text-primary-dark">blog index</a>.</p>
+    </div>
+  </template>
+</template>

package/templates/default/pages/blog/index.alpine

@@ -0,0 +1,37 @@
+<script server lang="ts">
+  import { PostService } from '../../services/PostService'
+
+  const posts = new PostService()
+
+  export function loader() {
+    return { posts: posts.all() }
+  }
+
+  // head() drives <title> and meta tags — SEO, rendered on the server.
+  export function head() {
+    return { title: 'Blog · {{name}}' }
+  }
+</script>
+
+<template x-data>
+  <h1 class="font-title text-3xl font-extrabold text-on-surface-strong dark:text-on-surface-dark-strong">Blog</h1>
+  <p class="mt-2 text-on-surface/80 dark:text-on-surface-dark/80">Sample posts served from a service — no database required.</p>
+
+  <!-- Apex components work inside x-for/x-if — <Card> here is re-created per item
+       on the client, fully styled. That's the "Alpine Extreme" bit. -->
+  <div class="mt-8 grid gap-4 sm:grid-cols-2">
+    <template x-for="p in posts" :key="p.slug">
+      <a :href="'/blog/' + p.slug" class="block transition hover:opacity-75">
+        <Card>
+          <div class="flex items-center gap-2 text-xs text-on-surface/70 dark:text-on-surface-dark/70">
+            <span x-text="p.author"></span>
+            <span>·</span>
+            <span x-text="p.date"></span>
+          </div>
+          <h2 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong" x-text="p.title"></h2>
+          <p class="text-sm" x-text="p.excerpt"></p>
+        </Card>
+      </a>
+    </template>
+  </div>
+</template>

package/templates/default/pages/index.alpine

@@ -1,38 +1,67 @@
 <script server lang="ts">
+  import { PostService } from '../services/PostService'
+
+  const posts = new PostService()
+
+  // Runs on the server. Its return value becomes the page's x-data — so the
+  // HTML is rendered from real data before a single byte of JS runs.
   export function loader() {
     return {
       title: 'Welcome to {{name}}',
-      tagline: 'The meta-framework for Alpine.js — server-rendered, then hydrated.',
+      tagline: 'A full-stack, server-rendered app built on Alpine.js — themed, typed, and AI-native.',
+      recent: posts.recent(3),
     }
   }
 </script>
 
-<template x-data="{ open: false }">
-  <h1 x-text="title"></h1>
-  <p class="tagline" x-text="tagline"></p>
-
-  <section class="card">
-    <p>
-      This was rendered on the server from <code>pages/index.alpine</code>, wrapped in
-      <code>layouts/default.alpine</code>, then hydrated by Alpine. Edit and save to see it live.
-    </p>
-    <button type="button" @click="open = !open" x-text="open ? 'Hide' : 'Show me how'"></button>
-    <div x-show="open" x-transition class="details">
-      <p>The <code>loader()</code> runs on the server and hands its data to Alpine's <code>x-data</code>.</p>
-      <p>Open <code>server/api/hello.ts</code>: a thin route → <code>GreetingService</code>, exposed as REST <em>and</em> an MCP tool.</p>
+<template x-data="{ show: false }">
+  <!-- Hero -->
+  <section class="py-8 text-center">
+    <h1 class="font-title text-4xl font-extrabold tracking-tight text-on-surface-strong sm:text-5xl dark:text-on-surface-dark-strong" x-text="title"></h1>
+    <p class="mx-auto mt-4 max-w-2xl text-lg" x-text="tagline"></p>
+    <div class="mt-6 flex flex-wrap justify-center gap-3">
+      <a href="/blog"><Button>Read the blog</Button></a>
+      <a href="https://apexjs.site" class="inline-flex items-center justify-center rounded-radius border border-outline px-4 py-2 text-sm font-medium text-on-surface transition hover:opacity-75 dark:border-outline-dark dark:text-on-surface-dark">Docs</a>
     </div>
   </section>
 
-  <p class="hint">A reusable component that hydrates in the browser:</p>
-  <Counter start="0" label="Clicks" />
-</template>
+  <!-- Feature cards -->
+  <section class="mt-6 grid gap-4 sm:grid-cols-3">
+    <Card>
+      <h3 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Server-rendered</h3>
+      <p class="text-sm">Every page is real HTML from a <code>loader()</code>, then hydrated by Alpine — fast and indexable.</p>
+    </Card>
+    <Card>
+      <h3 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Themed</h3>
+      <p class="text-sm">All components use theme tokens. Restyle the whole app with one <code>apex theme</code> command.</p>
+    </Card>
+    <Card>
+      <h3 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">AI-native</h3>
+      <p class="text-sm">Every typed API route is also an MCP tool your AI can call. See <code>server/api/posts.ts</code>.</p>
+    </Card>
+  </section>
 
-<style scoped>
-  h1 { color: #2563eb; font-size: 2.25rem; margin-bottom: 0.25rem; }
-  .tagline { font-size: 1.1rem; color: #475569; margin-top: 0; }
-  .card { margin-top: 1.5rem; padding: 1.25rem; border: 1px solid #e2e8f0; border-radius: 0.75rem; background: #f8fafc; }
-  .card button { margin-top: 0.5rem; padding: 0.55rem 1rem; font-weight: 600; color: #fff; background: #2563eb; border: none; border-radius: 0.5rem; cursor: pointer; }
-  .details { margin-top: 1rem; }
-  code { padding: 0.1rem 0.35rem; background: #e2e8f0; border-radius: 0.35rem; font-size: 0.9em; }
-  .hint { margin-top: 1.5rem; color: #64748b; font-size: 0.95rem; }
-</style>
+  <!-- Recent posts, from the loader -->
+  <section class="mt-10">
+    <h2 class="font-title text-xl font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Recent posts</h2>
+    <ul class="mt-3 divide-y divide-outline dark:divide-outline-dark">
+      <template x-for="p in recent" :key="p.slug">
+        <li class="py-3">
+          <a :href="'/blog/' + p.slug" class="font-medium text-primary hover:opacity-75 dark:text-primary-dark" x-text="p.title"></a>
+          <p class="text-sm text-on-surface/80 dark:text-on-surface-dark/80" x-text="p.excerpt"></p>
+        </li>
+      </template>
+    </ul>
+  </section>
+
+  <!-- A hydrated, interactive component -->
+  <section class="mt-10 flex flex-col items-start gap-3">
+    <p class="text-sm text-on-surface/80 dark:text-on-surface-dark/80">Hydrated in the browser — click it:</p>
+    <Counter start="0" label="Clicks" />
+    <button type="button" class="text-sm text-primary hover:opacity-75 dark:text-primary-dark" @click="show = !show" x-text="show ? 'Hide details' : 'How does this work?'"></button>
+    <p x-show="show" x-transition class="max-w-2xl text-sm text-on-surface/80 dark:text-on-surface-dark/80">
+      This page is <code>pages/index.alpine</code>, wrapped in <code>layouts/default.alpine</code>.
+      The server ran <code>loader()</code>, rendered the HTML, and Alpine took over in the browser — the counter and this toggle are proof.
+    </p>
+  </section>
+</template>

package/templates/default/server/api/posts.ts

@@ -0,0 +1,20 @@
+import { defineApexRoute } from '@apex-stack/core'
+import { z } from 'zod'
+import { PostService } from '../../services/PostService'
+
+const posts = new PostService()
+
+/**
+ * A route is a thin adapter: validate input, delegate to a service, return the
+ * result. Because `mcp: true`, this is ALSO an MCP tool named "posts" at /mcp —
+ * one definition, REST + AI-callable. Try:
+ *   curl "http://localhost:3000/api/posts"
+ *   curl "http://localhost:3000/api/posts?slug=hello-apex"
+ */
+export default defineApexRoute({
+  method: 'GET',
+  description: 'List blog posts, or fetch one by slug',
+  input: { slug: z.string().optional() },
+  mcp: true,
+  handler: ({ input }) => (input.slug ? (posts.bySlug(input.slug) ?? null) : posts.all()),
+})

package/templates/default/services/PostService.ts

@@ -0,0 +1,51 @@
+import type { Post } from '../shared/types'
+
+/**
+ * A service holds business logic as a plain class — testable in isolation and
+ * reusable from routes, page loaders, and jobs. Here it stands in for a database
+ * with in-memory sample data; swap the array for a real query (see the `db/`
+ * folder and `defineResource`) and nothing else in the app changes.
+ */
+const POSTS: Post[] = [
+  {
+    slug: 'hello-apex',
+    title: 'Hello, Apex',
+    excerpt: 'Why Alpine deserved a full-stack meta-framework.',
+    author: 'Ada Lovelace',
+    date: '2026-02-01',
+    body: 'Apex renders your pages on the server as real, indexable HTML, then Alpine hydrates them in the browser — no client-side framework tax, no flash. This whole app is server-rendered from .alpine files and made interactive by Alpine.',
+  },
+  {
+    slug: 'ssr-then-hydrate',
+    title: 'SSR first, hydrate second',
+    excerpt: 'Real HTML on the first byte. Interactivity right after.',
+    author: 'Grace Hopper',
+    date: '2026-02-08',
+    body: 'Each page has a loader() that runs on the server. Its return value is handed to Alpine as x-data, so the markup you see is the markup search engines and users get instantly — then the same state powers client interactivity.',
+  },
+  {
+    slug: 'routes-are-tools',
+    title: 'Every route is also an MCP tool',
+    excerpt: 'Ship an API your AI can call — from one definition.',
+    author: 'Alan Turing',
+    date: '2026-02-15',
+    body: 'Open server/api/posts.ts: one defineApexRoute is a validated REST endpoint AND an MCP tool at /mcp. Point an AI client at it and it can list your posts with no extra glue.',
+  },
+]
+
+export class PostService {
+  /** All posts, newest first. */
+  all(): Post[] {
+    return [...POSTS].sort((a, b) => b.date.localeCompare(a.date))
+  }
+
+  /** The N most recent posts. */
+  recent(n: number): Post[] {
+    return this.all().slice(0, n)
+  }
+
+  /** A single post by its slug, or undefined. */
+  bySlug(slug: string): Post | undefined {
+    return POSTS.find((p) => p.slug === slug)
+  }
+}

package/templates/default/shared/types.ts

@@ -1,11 +1,16 @@
 /**
  * Shared types — the single source of truth for shapes used across the app,
- * on the BACKEND (routes, services) and the FRONTEND. Import from '../shared/types'.
+ * on the BACKEND (routes, services) and the FRONTEND (pages, components).
+ * Import from '../shared/types'.
  *
  * Defining types here (instead of inline) is what keeps a growing codebase clean:
  * one place to change a shape, and the compiler enforces it everywhere it's used.
  */
-export interface Greeting {
-  message: string
-  at: string
+export interface Post {
+  slug: string
+  title: string
+  excerpt: string
+  author: string
+  date: string
+  body: string
 }

package/templates/default/tests/posts.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { PostService } from '../services/PostService'
+
+// Services are plain classes → unit-test them in isolation, no server needed.
+describe('PostService', () => {
+  const posts = new PostService()
+
+  it('lists posts newest first', () => {
+    const dates = posts.all().map((p) => p.date)
+    expect(dates.length).toBeGreaterThan(0)
+    expect(dates).toEqual([...dates].sort((a, b) => b.localeCompare(a)))
+  })
+
+  it('limits recent()', () => {
+    expect(posts.recent(2)).toHaveLength(2)
+  })
+
+  it('finds a post by slug', () => {
+    expect(posts.bySlug('hello-apex')?.title).toBe('Hello, Apex')
+    expect(posts.bySlug('nope')).toBeUndefined()
+  })
+})

package/templates/default/server/api/hello.ts

@@ -1,18 +0,0 @@
-import { defineApexRoute } from '@apex-stack/core'
-import { z } from 'zod'
-import { GreetingService } from '../../services/GreetingService'
-
-const greetings = new GreetingService()
-
-/**
- * A route is a thin adapter: validate input, delegate to a service, return the
- * result. Because `mcp: true`, this is ALSO an MCP tool named "hello" at /mcp —
- * one definition, REST + AI-callable.
- */
-export default defineApexRoute({
-  method: 'GET',
-  description: 'Greet someone by name',
-  input: { name: z.string() },
-  mcp: true,
-  handler: ({ input }) => greetings.greet(input.name),
-})

package/templates/default/services/GreetingService.ts

@@ -1,12 +0,0 @@
-import type { Greeting } from '../shared/types'
-
-/**
- * A service holds business logic as a plain class — testable in isolation and
- * reusable from routes, page loaders, and jobs. Keep routes/loaders thin: they
- * validate input and delegate to a service. This is the clean-code backbone.
- */
-export class GreetingService {
-  greet(name: string): Greeting {
-    return { message: `Hello, ${name}!`, at: new Date().toISOString() }
-  }
-}

package/templates/default/tests/greeting.test.ts

@@ -1,12 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { GreetingService } from '../services/GreetingService'
-
-// Services are plain classes, so they test in isolation — no server needed.
-// Generate more with:  apex make test <name>
-describe('GreetingService', () => {
-  it('greets by name', () => {
-    const g = new GreetingService().greet('Apex')
-    expect(g.message).toBe('Hello, Apex!')
-    expect(typeof g.at).toBe('string')
-  })
-})