@mauroandre/velojs 0.0.37 → 0.0.39

package/agent/skills/velojs-production-deploy/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: velojs-production-deploy
+description: "Deploying to production: `velojs build`/`start`, Docker, env vars (`PORT`, `NODE_ENV`, `STATIC_BASE_URL`), serving assets from a CDN. Use when writing a Dockerfile, configuring a host, or shipping to production."
+---
+
+# Production Deploy
+
+VeloJS apps compile to a simple structure: a `dist/` folder with a server entry and static assets. This makes deployment straightforward on any Node.js hosting.
+
+## Build your app
+
+```bash
+npx velojs build
+```
+
+This runs two Vite builds:
+1. **Client build** → `dist/client/` (JavaScript, CSS, and other static assets)
+2. **Server build** → `dist/server.js` (the SSR server entry point)
+
+## Start in production
+
+```bash
+npx velojs start
+```
+
+This automatically sets `NODE_ENV=production` and starts the server. In production mode, VeloJS serves static files from `dist/client/` and handles SSR for all page routes.
+
+## Dockerfile
+
+Here's a production-ready Dockerfile with multi-stage build:
+
+```dockerfile
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY app ./app
+COPY tsconfig.json vite.config.ts ./
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY --from=builder /app/dist ./dist
+
+ENV PORT=3000
+EXPOSE 3000
+CMD ["npx", "velojs", "start"]
+```
+
+The multi-stage build keeps the final image small — it only includes production dependencies and the compiled output, not your source code or dev dependencies.
+
+## Setting the port
+
+The server reads the port from, in order of precedence:
+
+1. The `PORT` environment variable — the convention most hosts (Railway, Render, Fly, Heroku) inject automatically.
+2. The `port` field in `defineConfig` (`vite.config.ts`) — applies to both `velojs dev` and `velojs start`.
+3. The default, `3000`.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { veloPlugin } from "@mauroandre/velojs/vite";
+
+export default defineConfig({
+    plugins: [veloPlugin({ port: 4000 })],
+});
+```
+
+In dev, `velojs dev --port 5000` still overrides everything (it's passed straight to Vite).
+
+## Static assets on CDN
+
+If you want to serve static assets (JS, CSS, images) from a CDN or S3 bucket instead of the Node.js server, set the `STATIC_BASE_URL` environment variable:
+
+```bash
+STATIC_BASE_URL=https://cdn.example.com/assets npx velojs start
+```
+
+The `<Scripts />` component and CSS `url()` references will automatically use this prefix. The server will skip serving static files when `STATIC_BASE_URL` points to an external URL.
+
+## Included dependencies
+
+VeloJS is an opinionated framework — a single `npm install @mauroandre/velojs` brings everything you need:
+
+- **Hono** — HTTP server and routing
+- **Preact** — UI rendering (SSR + client hydration)
+- **@preact/signals** — Reactive state management
+- **wouter-preact** — Client-side routing
+- **Vite** — Build tool and dev server
+- **@preact/preset-vite** — Preact JSX support
+- **@hono/vite-dev-server** — SSR dev server
+
+You don't need to install or configure any of these separately. VeloJS controls the versions to ensure everything works together.

package/agent/skills/velojs-project-graph/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: velojs-project-graph
+description: "Use `.velojs/graph.json` to understand the project's route tree and module dependency graph before reading any source files. Always consult the graph first when exploring a VeloJS codebase. Generate it with `velojs graph` if missing."
+---
+
+# Project Graph
+
+VeloJS can generate a structural snapshot of your project — the route tree hierarchy, module dependency graph, and convention exports — as a single JSON file at `.velojs/graph.json`. This file gives an AI agent (or any tool) a complete map of the codebase in a few KB, replacing dozens of exploratory file reads.
+
+## When to use
+
+Always. Before reading any source file in a VeloJS project, check `.velojs/graph.json` first. It tells you:
+
+- **Route tree** — full hierarchy of layouts, pages, paths, `isRoot`, and middlewares
+- **Module dependencies** — for every module: what it imports (`imports`) and who imports it (`importedBy`)
+- **Convention exports** — which modules export `loader`, `action_*`, `stream_*`, `socket_*`
+
+## Generating the graph
+
+If `.velojs/graph.json` does not exist, generate it:
+
+```bash
+velojs graph
+```
+
+This runs a fast Babel-based crawl of `app/routes.tsx` and its transitive imports. No build. No Vite. Sub-second. Works even if the project does not compile.
+
+The graph is also regenerated automatically on every `velojs build` (via the `velo:graph` plugin) and on every file change during `velojs dev`.
+
+## Graph structure
+
+```typescript
+interface GraphJson {
+    routes: RouteTreeNode[];
+    modules: Record<string, ModuleInfo>;
+}
+
+interface RouteTreeNode {
+    moduleId: string | null;   // e.g. "pages/Home", null if no module
+    fullPath: string | null;   // e.g. "/admin/users/:id"
+    path: string | null;       // e.g. "/users/:id"
+    isRoot: boolean;           // root layout (renders <html>)
+    middlewares: string[];     // middleware identifiers
+    children: RouteTreeNode[];
+}
+
+interface ModuleInfo {
+    file: string;              // relative path from project root
+    kind: "root" | "layout" | "page" | "unknown";
+    exports: {
+        hasComponent: boolean;
+        hasLoader: boolean;
+        actions: string[];     // e.g. ["save", "delete"]
+        streams: string[];     // e.g. ["progress", "logs"]
+        sockets: string[];     // e.g. ["terminal"]
+    };
+    imports: string[];         // moduleIds this module depends on
+    importedBy: string[];      // moduleIds that depend on this module
+}
+```
+
+## Common queries
+
+### "Which routes use this loader?"
+
+1. Find the loader's module in `modules` → note its `moduleId`
+2. Search `routes` recursively for nodes where `moduleId` matches
+3. The matching node's ancestors are the layouts wrapping it
+
+### "What breaks if I change this file?"
+
+1. Find the module in `modules[moduleId]`
+2. Follow `importedBy` — these modules import it
+3. Transitively follow `importedBy` on those modules
+4. Filter to modules where `kind` is `"page"` to see which pages are affected
+
+### "What actions does this page expose?"
+
+1. Find the page in `modules[moduleId]`
+2. Read `exports.actions` — e.g. `["save", "delete"]`
+3. These are the `action_*` exports callable from the client
+
+### "Where is the auth middleware applied?"
+
+1. Search `routes` recursively for nodes where `middlewares` includes the auth middleware name
+2. The matching nodes and their children are protected
+
+### "Which modules have no tests?"
+
+Compare `modules` keys against the `tests/` directory. Modules with no corresponding test file are candidates for new tests.
+
+## Notes
+
+- External imports (`@mauroandre/velojs`, `preact`, `wouter-preact`) are recorded in `imports` but not crawled
+- `export function action_*` is NOT detected — only `export const action_*` (matches framework behavior)
+- Path-less layouts (no `path` property) have `fullPath: ""` and `path: ""`
+- The graph is regenerated on every build and on file changes during dev — never stale

package/agent/skills/velojs-routes/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: velojs-routes
+description: "The route tree in `app/routes.tsx`: nesting, layouts, path-less wrappers, URL params, index routes, the catch-all 404, per-route status codes. Use when adding/moving/removing a page or URL, building a layout, or asked why a route 404s."
+---
+
+# Routes
+
+In VeloJS, all routes are defined in a single file: `app/routes.tsx`. Instead of filesystem-based routing, you define your routes as a **tree structure**. This gives you full control over layouts, nesting, and middleware inheritance.
+
+## The route tree
+
+Each node in the tree represents either a **page** (leaf node) or a **layout** (node with children). Here's an example with authentication:
+
+```typescript
+import type { AppRoutes } from "@mauroandre/velojs";
+import * as Root from "./client-root.js";
+import * as AuthLayout from "./auth/Layout.js";
+import * as Login from "./auth/Login.js";
+import * as AdminLayout from "./admin/Layout.js";
+import * as Dashboard from "./admin/Dashboard.js";
+import * as Users from "./admin/Users.js";
+import * as UserDetail from "./admin/UserDetail.js";
+import { authMiddleware } from "./modules/auth/auth.middleware.js";
+
+export default [
+    {
+        module: Root,
+        isRoot: true,
+        children: [
+            // Public routes — no authentication required
+            {
+                module: AuthLayout,
+                children: [
+                    { path: "/login", module: Login },
+                ],
+            },
+            // Protected routes — authMiddleware runs first
+            {
+                module: AdminLayout,
+                middlewares: [authMiddleware],
+                children: [
+                    { path: "/", module: Dashboard },
+                    { path: "/users", module: Users },
+                    { path: "/users/:id", module: UserDetail },
+                ],
+            },
+        ],
+    },
+] satisfies AppRoutes;
+```
+
+## How nesting works
+
+Routes with `children` act as **layouts**. Their `Component` receives `children` and wraps the nested routes. VeloJS renders the full hierarchy from root to leaf.
+
+For example, when a user visits `/users/123`, VeloJS renders:
+
+```
+Root (isRoot — the <html>, <head>, <body> shell)
+  └─ AdminLayout (sidebar, navigation bar)
+       └─ UserDetail (the actual page content)
+```
+
+Here's what the layout components look like:
+
+```typescript
+// app/admin/Layout.tsx — Layout wraps its children
+export const Component = ({ children }: { children: any }) => (
+    <div class="layout">
+        <nav class="sidebar">...</nav>
+        <main class="content">{children}</main>
+    </div>
+);
+
+// app/admin/UserDetail.tsx — Page is the leaf (no children)
+export const Component = () => {
+    const { data } = useLoader<User>();
+    return <div>{data.value?.name}</div>;
+};
+```
+
+Every layout and page can have its own `loader`. When a page is requested, **all loaders in the hierarchy run in parallel** — the Root loader, AdminLayout loader, and UserDetail loader all execute at the same time. This makes data loading fast.
+
+On the client, a layout **stays mounted** while you navigate between its child routes — only the inner content swaps. This follows the tree automatically: navigating between sibling routes never re-mounts anything above them, so a sidebar or nav bar (and its loader, scroll, and state) is preserved instead of flickering. It works the same whether the layout has a `path` (a section like `/admin`) or is a path-less wrapper (an app shell grouping several top-level routes) — no configuration needed.
+
+## Route node properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` | URL path segment. Supports `:params` (e.g., `/users/:id`). |
+| `module` | `RouteModule` | The module with `Component`, `loader`, and `action_*` exports. |
+| `children` | `RouteNode[]` | Nested routes. When present, the module acts as a layout. |
+| `middlewares` | `MiddlewareHandler[]` | Server-side middlewares. Inherited by all children. |
+| `isRoot` | `boolean` | Marks the root node (the HTML shell). |
+| `statusCode` | `number` | HTTP status code for the rendered page. Defaults to `200`. See [Status codes](#status-codes) and [The 404 page](#the-404-page). |
+
+## Status codes
+
+By default every page responds with HTTP `200`. Set `statusCode` on a route to override it — useful for pages like _gone_ (`410`) or _service unavailable_ (`503`):
+
+```typescript
+{ path: "/old-page", module: Gone, statusCode: 410 }
+```
+
+The status is applied to both the SSR HTML response and the JSON returned for SPA navigation, so it stays consistent however the page is reached.
+
+For a **conditional** status — a route that exists but whose resource may be missing (e.g. `/users/:id` for an unknown id) — don't use a static `statusCode`. Set it from the loader instead, via the Hono context:
+
+```typescript
+export const loader = async ({ params, c }: LoaderArgs) => {
+    const user = await getUser(params.id);
+    if (!user) c.status(404);
+    return { user };
+};
+```
+
+## The 404 page
+
+To render your own _not found_ page, add a **catch-all** route with `path: "*"` as the **last child of the root**:
+
+```typescript
+import * as NotFound from "./pages/NotFound.js";
+
+export default [
+    {
+        module: Root,
+        isRoot: true,
+        children: [
+            { path: "/", module: Home },
+            // Keep the catch-all last — it matches only when nothing else does.
+            { path: "*", module: NotFound, statusCode: 404 },
+        ],
+    },
+] satisfies AppRoutes;
+```
+
+The `NotFound` page is a normal page component, rendered inside the root layout like any other route:
+
+```typescript
+// app/pages/NotFound.tsx
+export const Component = () => (
+    <main>
+        <h1>404</h1>
+        <p>Page not found.</p>
+        <a href="/">Go home</a>
+    </main>
+);
+```
+
+VeloJS handles the catch-all specially across all modes:
+
+- **SSR** — it's wired to Hono's `notFound` hook, so it runs only after no route matched and no static asset was found. It never shadows your assets, actions, streams, or sockets. The response carries the `statusCode` (default `404`).
+- **SPA navigation** — the client router renders it when no route matches, with no round-trip. A top-level unknown URL renders standalone; an unknown sub-route of a section that has a layout (e.g. `/admin/nope`) renders the 404 **inside that section's layout**, so the layout stays mounted (no flicker).
+- **Static generation** (`velojs build --static`) — it's emitted as `dist/404.html` at the output root, following the universal `/404.html` convention that static hosts (nginx, GitHub Pages, Netlify, S3/CloudFront…) serve automatically.
+
+The catch-all is **optional**. Without it, an unmatched path still responds `404`, just with a plain-text body instead of your styled page.
+
+> On the server the 404 always renders standalone (inside the root shell only) and its route middlewares don't run — there was no route to match. On the client, a section layout stays mounted when you navigate to a bad sub-route of that section.
+
+## Path resolution
+
+Paths are **segments** that build up from parent to child:
+
+```
+Root (no path)
+  └─ AdminLayout (no path)
+       ├─ Dashboard    → path: "/"           → fullPath: "/"
+       ├─ Users        → path: "/users"      → fullPath: "/users"
+       └─ UserDetail   → path: "/users/:id"  → fullPath: "/users/:id"
+```
+
+Nodes without a `path` don't add a segment to the URL — they are **pure layout wrappers**. This is useful when you want to wrap a group of pages in a shared layout without changing their URLs.
+
+The Vite plugin automatically parses your `routes.tsx` at build time and calculates both `fullPath` (the complete URL) and `path` (the relative segment) for each module.
+
+## Shared layouts, different paths
+
+You can reuse the same layout for different route groups:
+
+```typescript
+export default [
+    {
+        module: Root,
+        isRoot: true,
+        children: [
+            // Public pages — PublicLayout, no auth
+            {
+                module: PublicLayout,
+                children: [
+                    { path: "/", module: Home },
+                    { path: "/about", module: About },
+                ],
+            },
+            // Dashboard — DashboardLayout + auth middleware
+            {
+                path: "/dashboard",
+                module: DashboardLayout,
+                middlewares: [authMiddleware],
+                children: [
+                    { path: "/", module: Overview },
+                    { path: "/settings", module: Settings },
+                ],
+            },
+        ],
+    },
+] satisfies AppRoutes;
+```
+
+Here, `PublicLayout` and `DashboardLayout` are completely separate layouts. Public pages live at `/` and `/about`, while dashboard pages live at `/dashboard` and `/dashboard/settings`.

package/agent/skills/velojs-scripts-component/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: velojs-scripts-component
+description: "The `<Scripts />` component in the root HTML shell: injecting the client bundle and CSS, favicon, CDN/static asset base paths. Use when setting up the root layout, changing the favicon, or serving assets from a CDN."
+---
+
+# Scripts Component
+
+The `Scripts` component injects the CSS and JavaScript files that your app needs. It must be placed inside `<head>` in your `client-root.tsx`.
+
+## Usage
+
+```tsx
+import { Scripts } from "@mauroandre/velojs";
+
+export const Component = ({ children }) => (
+    <html>
+        <head>
+            <Scripts />
+        </head>
+        <body>{children}</body>
+    </html>
+);
+```
+
+## What it outputs
+
+`Scripts` automatically detects whether you're in development or production mode and outputs the appropriate tags.
+
+**In development:**
+```html
+<link rel="icon" href="/favicon.ico" type="image/x-icon" />
+<script type="module" src="/@vite/client"></script>
+<script type="module" src="/__velo_client.js"></script>
+```
+
+**In production:**
+```html
+<link rel="icon" href="/favicon.ico" type="image/x-icon" />
+<link rel="stylesheet" href="/client.C3f9Ax_1.css" />
+<script type="module" src="/client.C3f9Ax_1.js"></script>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `basePath` | `string` | `""` | Base path prefix for all asset URLs. Uses `STATIC_BASE_URL` env var if set. |
+| `favicon` | `string \| false` | `"/favicon.ico"` | Path to the favicon. Set to `false` to disable. |
+
+## Using with a CDN
+
+If you serve static assets from a CDN or S3 bucket, set the `STATIC_BASE_URL` environment variable. The `Scripts` component will automatically prefix all asset URLs:
+
+```bash
+STATIC_BASE_URL=https://cdn.example.com/assets velojs start
+```
+
+This makes the output become:
+```html
+<link rel="stylesheet" href="https://cdn.example.com/assets/client.C3f9Ax_1.css" />
+<script type="module" src="https://cdn.example.com/assets/client.C3f9Ax_1.js"></script>
+```

package/agent/skills/velojs-server-api/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: velojs-server-api
+description: "Server lifecycle and escape hatches: `addRoutes` for custom Hono routes, `onServer` for the raw HTTP server, port config, env vars. Use when mounting a custom Hono route, attaching a library to the HTTP server, or configuring the port."
+---
+
+# Server API
+
+VeloJS gives you direct access to the underlying Hono server. This lets you add custom API endpoints, SSE streams, WebSocket handlers, and anything else that goes beyond page routes.
+
+## addRoutes
+
+Register custom Hono routes in `app/server.tsx`. These routes are added **before** page and action routes, so they take priority:
+
+```typescript
+import { addRoutes } from "@mauroandre/velojs/server";
+import type { Hono } from "hono";
+
+addRoutes((app: Hono) => {
+    // Simple API endpoint
+    app.get("/api/health", (c) => c.json({ ok: true }));
+
+    // File upload
+    app.post("/api/upload", async (c) => {
+        const body = await c.req.parseBody();
+        const file = body.file;
+        return c.json({ ok: true });
+    });
+
+    // Middleware for a group of API routes
+    app.use("/api/admin/*", async (c, next) => {
+        const token = c.req.header("Authorization");
+        if (!token) return c.json({ error: "Unauthorized" }, 401);
+        await next();
+    });
+});
+```
+
+## Server-Sent Events (SSE)
+
+> **Recommended:** For most real-time use cases, use [Event Streams](/docs/event-streams) (`createEventStream`). They handle channels, snapshots, auto-close, heartbeat, middleware inheritance, and type safety automatically. Drop down to raw `streamSSE` only when you need fine-grained control over the protocol.
+
+SSE is a simple way to push real-time updates from server to client. If you need raw control, use Hono's `streamSSE` directly:
+
+```typescript
+import { addRoutes } from "@mauroandre/velojs/server";
+
+addRoutes((app) => {
+    app.get("/api/events", async (c) => {
+        const { streamSSE } = await import("hono/streaming");
+
+        return streamSSE(c, async (stream) => {
+            // Send initial data when client connects
+            await stream.writeSSE({
+                event: "snapshot",
+                data: JSON.stringify({ count: 0 }),
+            });
+
+            // Subscribe to updates
+            const unsubscribe = subscribe((data) => {
+                stream.writeSSE({
+                    event: "update",
+                    data: JSON.stringify(data),
+                });
+            });
+
+            // Clean up when client disconnects
+            stream.onAbort(() => { unsubscribe(); });
+
+            // Keep the stream open
+            await new Promise<void>(() => {});
+        });
+    });
+});
+```
+
+On the client, use the standard `EventSource` API:
+
+```typescript
+useEffect(() => {
+    const es = new EventSource("/api/events");
+
+    es.addEventListener("snapshot", (e) => {
+        state.value = JSON.parse(e.data);
+    });
+
+    es.addEventListener("update", (e) => {
+        state.value = JSON.parse(e.data);
+    });
+
+    return () => es.close();
+}, []);
+```
+
+### SSE with polling
+
+For live metrics or periodic updates, use a polling loop inside the stream:
+
+```typescript
+addRoutes((app) => {
+    app.get("/api/metrics/live", async (c) => {
+        const { streamSSE } = await import("hono/streaming");
+
+        return streamSSE(c, async (stream) => {
+            let running = true;
+            stream.onAbort(() => { running = false; });
+
+            while (running) {
+                const metrics = await collectMetrics();
+                await stream.writeSSE({ data: JSON.stringify(metrics) });
+                await new Promise((r) => setTimeout(r, 3000));
+            }
+        });
+    });
+});
+```
+
+## onServer — WebSocket support
+
+`onServer` gives you access to the underlying Node.js HTTP server. This is mainly used for WebSocket upgrade handlers:
+
+```typescript
+import { onServer } from "@mauroandre/velojs/server";
+
+onServer(async (httpServer) => {
+    const { WebSocketServer } = await import("ws");
+    const wss = new WebSocketServer({ noServer: true });
+
+    httpServer.on("upgrade", (req, socket, head) => {
+        const url = new URL(req.url!, `http://${req.headers.host}`);
+
+        if (url.pathname === "/ws") {
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                ws.on("message", (raw) => {
+                    const msg = JSON.parse(raw.toString());
+                    // Handle message
+                });
+
+                ws.on("close", () => {
+                    // Clean up
+                });
+            });
+        }
+    });
+});
+```
+
+Callbacks registered with `onServer` queue until the server starts. If called after the server is already running, the callback executes immediately.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | The port the server listens on. Overrides `defineConfig`'s `port`. |
+| `NODE_ENV` | — | Set automatically by `velojs start` to `production` |
+| `STATIC_BASE_URL` | `""` | CDN/bucket prefix for static assets |