@mauroandre/velojs 0.0.37 → 0.0.38

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

@@ -0,0 +1,472 @@
+---
+name: velojs-testing
+description: "Writing tests with `createTestApp` from `@mauroandre/velojs/testing`: HTTP requests, actions, loaders, auth, SSE subscriptions, sockets. Use when writing or fixing a test for a VeloJS app."
+---
+
+# Testing
+
+VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. It spins up your app in memory, fires HTTP requests against the registered handlers, subscribes to event streams, and asserts on the result. No socket. No browser. No fragile mocks of the framework internals.
+
+You test the whole stack — middleware, auth, routing, conventions, serialization — through the API your real users hit.
+
+## Why a built-in toolkit?
+
+Writing integration tests for a VeloJS app without this toolkit means one of:
+- Spinning up a real HTTP server, opening sockets, racing on ports
+- Calling `loader`/`action_*`/`stream_*` functions directly and mocking the Hono `Context` by hand
+- Reaching into the database to assert state, bypassing services
+
+All three pull tests away from the API your code actually exposes. The toolkit closes that gap.
+
+## Prerequisite — Vitest must load the VeloJS Vite plugin
+
+The toolkit relies on metadata that the VeloJS Vite plugin injects at build time (`metadata.moduleId`, `metadata.fullPath`, stream `__path`). For tests to see this metadata, your `vitest.config.ts` must include `veloPlugin()`:
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { veloPlugin } from "@mauroandre/velojs/vite";
+
+export default defineConfig({
+    plugins: [veloPlugin()],
+    test: {
+        // your test config
+    },
+});
+```
+
+If you have a `vite.config.ts` with the plugin already, you can extend it with `mergeConfig`. Without this step, `.action(fn)`, `.loader(fn)`, and `.subscribe(stream)` won't be able to resolve URLs.
+
+## Quick start
+
+```typescript
+import { createTestApp } from "@mauroandre/velojs/testing";
+import routes from "../app/routes.js";
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+
+describe("API", () => {
+    let app: Awaited<ReturnType<typeof createTestApp>>;
+
+    beforeAll(async () => {
+        app = await createTestApp({
+            routes,
+            bootstrap: async () => {
+                await connect(process.env.MONGO_URI!);
+            },
+            getSessionCookie: async ({ user }) => ({
+                session: await createToken(user),
+            }),
+        });
+    });
+
+    afterAll(async () => await app.close());
+
+    it("returns 200 for health check", async () => {
+        const res = await app.get("/api/health");
+        expect(res.status).toBe(200);
+    });
+});
+```
+
+That's the whole shape. Below is each piece in detail.
+
+## createTestApp
+
+```typescript
+const app = await createTestApp({
+    routes,
+    bootstrap?: async () => { ... },
+    getSessionCookie?: async ({ user }) => ({ ... }),
+});
+```
+
+| Option | Purpose |
+|--------|---------|
+| `routes` | Required. Your app's `routes` array — typically `import routes from "./app/routes.js"` (it is the **default** export of `routes.tsx`) |
+| `bootstrap` | Runs once before the app is created. Use for DB connections, index creation, anything `app/server.tsx` does at startup. `addRoutes()` and `onServer()` calls here are **scoped to this app only** |
+| `getSessionCookie` | Maps a user object to cookies the test client will attach. Required for `app.as(user)` and `app.sessionCookies(user)` |
+
+### app.close()
+
+Tears down everything: heartbeats, retention timers, listeners, callbacks. After `close()`, Vitest must report **zero open handles**. Always call it in `afterAll`.
+
+### app.reset()
+
+Zeros transient state without re-importing routes or re-running `bootstrap`:
+- All event stream buffers (`{ snapshot: true }` accumulator)
+- All listeners (residual subscribers)
+- All closed-channel sets
+- All `perChannelSource` AbortControllers
+
+Call it in `beforeEach` to keep tests isolated:
+
+```typescript
+beforeEach(async () => {
+    await app.reset();
+    await cleanTestDb(); // your responsibility
+});
+```
+
+## HTTP client
+
+```typescript
+const res = await app.get("/api/repos", {
+    cookies: { session: "jwt" },
+    headers: { "X-Trace": "abc" },
+    query: { filter: "active" },
+});
+
+await app.post("/api/payments/webhook", {
+    body: { txid: "abc" }, // auto JSON-serialized + Content-Type set
+});
+
+await app.post("/api/upload", {
+    body: formData, // FormData passed as-is
+});
+```
+
+Methods: `.get`, `.post`, `.put`, `.patch`, `.delete`.
+
+These methods hit everything registered under your `routes` — **pages, actions, streams, and endpoints**. A webhook declared as `{ path: "/api/github/webhook", method: "POST", handler: githubWebhook }` in `routes.tsx` is exercised exactly like any other POST route:
+
+```typescript
+const res = await app.post("/api/github/webhook", {
+    headers: { "x-hub-signature-256": sig },
+    body: { action: "push" },
+});
+```
+
+See [06-endpoints.md](/docs/endpoints) for declaring endpoints.
+
+`TestResponse` mirrors the Fetch `Response`:
+
+| Field | Description |
+|-------|-------------|
+| `status` | HTTP status |
+| `headers` | Plain object. **Keys are lowercased** (Fetch `Headers` normalization) — use `res.headers["x-trace"]`, not `res.headers["X-Trace"]` |
+| `cookies` | Set-Cookie headers parsed into a record |
+| `json<T>()` | Parse body as JSON |
+| `text()` | Body as text |
+| `blob()` | Body as Blob |
+| `raw` | The underlying Response |
+
+### Cookies and query strings
+
+Pass `cookies: { name: value }` and the toolkit serializes them into the `Cookie` header. Query strings accept arrays:
+
+```typescript
+await app.get("/api/posts", { query: { tag: ["preact", "ssr"] } });
+// → /api/posts?tag=preact&tag=ssr
+```
+
+## Auth — getSessionCookie and .as
+
+Most authenticated tests look like:
+
+```typescript
+const cookies = await app.sessionCookies({ user: alice });
+const res = await app.get("/api/me", { cookies });
+```
+
+But that gets repetitive. Use `app.as({ user })` to scope a sub-client:
+
+```typescript
+const asAlice = app.as({ user: alice });
+await asAlice.get("/api/me");
+await asAlice.action(action_save, { body: {...} });
+await asAlice.subscribe(stream_progress, { channel: appId });
+```
+
+Every method of the sub-client carries Alice's cookies automatically.
+
+If `getSessionCookie` was not provided, `.as()` throws a clear error. The framework doesn't know your app's session format — you provide it.
+
+## Conventions — .action(fn) and .loader(fn)
+
+For VeloJS conventions, you don't need to know the URL. Pass the imported function:
+
+```typescript
+import { action_setBackup } from "../app/stacks/Backup.js";
+
+const res = await app.action(action_setBackup, {
+    body: { appId, schedule: "daily" },
+    cookies: { session: jwt },
+});
+expect(res.status).toBe(200);
+```
+
+```typescript
+import { loader as homeLoader } from "../app/Home.js";
+
+const data = await app.loader(homeLoader, {
+    cookies: { session: jwt },
+    params: { id: "abc" },
+});
+// `data` is the loader's return value, unwrapped from the HTTP response
+expect(data.user.name).toBe("Alice");
+```
+
+### .loader unwrapping rules
+
+| Loader behavior | Returned by `.loader()` |
+|-----------------|------------------------|
+| Returned a value | The value directly (unwrapped) |
+| Redirected (`c.redirect(...)`) | `TestResponse` for status inspection |
+| Set a non-2xx status (`c.status(403)`) | `TestResponse` for status inspection |
+| Threw an exception | `TestResponse` with status 500 — **not** re-thrown |
+
+A loader runs inside a Hono handler, and Hono catches a throw and turns it into a 500 response — so `.loader()` resolves either way. Assert on `res.status`; `await expect(app.loader(fn)).rejects.toThrow()` can never pass.
+
+If the function isn't found in the route tree, `.action`/`.loader` throws a clear error pointing at the most likely cause (Vitest config missing the VeloJS plugin).
+
+### Fallback — string URL
+
+If you need to bypass resolution, pass a URL string:
+
+```typescript
+await app.action("/_action/Login/login", { body: {...} });
+```
+
+## Streams — .subscribe(stream)
+
+Subscribing to a stream returns a `TestSubscription`:
+
+```typescript
+const sub = await app.as({ user: alice }).subscribe(stream_progress, {
+    channel: deployId,
+});
+```
+
+| Field/method | Description |
+|--------------|-------------|
+| `sub.status` | HTTP status of the initial response (200, 403, etc) |
+| `sub.snapshot` | Snapshot from the server (buffer or callback). `null` if none |
+| `sub.events` | All events received since connect, in order |
+| `sub.closed` | `true` after server signals deliberate close |
+| `sub.next({ timeoutMs })` | Wait for next event. **Rejects on timeout** (no silent undefined) |
+| `sub.nextN(n, { timeoutMs })` | Wait for N events. Total timeout is shared across them |
+| `sub.close()` | Force disconnect — triggers `perChannelSource` `abortSignal` server-side |
+
+### Asserting cross-user isolation
+
+```typescript
+it("user B cannot subscribe to user A's app", async () => {
+    const sub = await app.as({ user: userB }).subscribe(stream_appLogs, {
+        channel: userAsAppId,
+    });
+    expect(sub.status).toBe(403);
+    expect(sub.events).toEqual([]);
+});
+```
+
+### Asserting snapshot replay on reconnect
+
+```typescript
+it("F5 mid-deploy shows current state immediately", async () => {
+    const subA = await app.subscribe(stream_progress, { channel: appId });
+    await app.action(action_startDeploy, { body: { appId } });
+    await subA.next({ timeoutMs: 2000 });
+    await subA.close();
+
+    // Reconnect — buffer/snapshot still available within retainMs
+    const subB = await app.subscribe(stream_progress, { channel: appId });
+    expect(subB.snapshot?.[0]).toMatchObject({ status: "running" });
+});
+```
+
+### Asserting perChannelSource lifecycle
+
+```typescript
+it("perChannelSource aborts when the last subscriber leaves", async () => {
+    const a = await app.subscribe(stream_logs, { channel: "session" });
+    const b = await app.subscribe(stream_logs, { channel: "session" });
+
+    await a.close();
+    // Source still running — b is still subscribed
+    expect(activeSshConnections.get("session")).toBeDefined();
+
+    await b.close();
+    // Source aborted
+    expect(activeSshConnections.get("session")).toBeUndefined();
+});
+```
+
+## Sockets — `.socket(handler)`
+
+`app.socket(handlerOrStubOrPath, opts)` opens an **in-memory** WebSocket session against a `socket_*` handler — no real TCP, no upgrade handshake. The handler runs directly with a mock Context.
+
+```typescript
+import { socket_terminal } from "../app/workers/WorkerTerminal.js";
+
+const ws = await app.socket(socket_terminal, {
+    user: { id: "alice" },
+    params: { workerId: "w42" },
+    channel: "w42",
+});
+
+// Send frames client → server
+ws.send({ type: "data", data: "ls\n" });
+
+// Receive frames server → client
+const reply = await ws.next({ timeoutMs: 500 });
+expect(JSON.parse(reply as string)).toMatchObject({ type: "data" });
+
+// Consume a batch
+const batch = await ws.nextN(3, { timeoutMs: 1000 });
+
+// Close from the client — fires abortSignal inside the handler
+await ws.close();
+```
+
+| Field / method | Description |
+|---|---|
+| `ws.send(msg)` | Send a frame. `string` / `Uint8Array` pass through; objects → `JSON.stringify`. |
+| `ws.next({ timeoutMs })` | Wait for the next server-sent frame (cursor advances). |
+| `ws.nextN(n, { timeoutMs })` | Collect `n` consecutive frames (total timeout, not per-frame). |
+| `ws.messages` | All frames received so far. |
+| `ws.closed` | `true` when the handler finished or `close()` was called. |
+| `ws.done` | Promise that resolves when the handler finishes. |
+| `ws.close(code?, reason?)` | Client-initiated close. Aborts `abortSignal` inside the handler. |
+
+### What `app.socket()` does NOT do
+
+- **Middleware does not run.** If your socket handler reads `c.get("user")`, pass `user` via the option:
+  ```typescript
+  const ws = await app.socket(handler, { user: await buildUserForTest(...) });
+  ```
+  Test middleware correctness separately through a regular endpoint or page that exercises the same middleware.
+- **No real HTTP upgrade.** Binary frames (`Uint8Array`) pass through the queue, but the adapter is a buffered channel, not a socket.
+
+### Accepting multiple input shapes
+
+- **Function**: the server-imported `socket_*` handler.
+  `app.socket(socket_terminal, ...)`
+- **Path string**: resolve by route path.
+  `app.socket("/_socket/workers/WorkerTerminal/terminal", ...)`
+- **Stub**: the client stub `{ __path }` produced by the Vite plugin.
+  `app.socket(terminalStub, ...)`
+
+`app.close()` aborts every open socket session on the app — no leaked handlers between tests.
+
+## mockContext — escape hatch
+
+Last resort. Build a partial Hono `Context` for direct invocation of background jobs or internal helpers that aren't routes:
+
+```typescript
+const c = app.mockContext({
+    user: { id, email, role },
+    params: { id: "abc" },
+    query: { filter: "active" },
+    body: { foo: "bar" },
+});
+
+await someJob({ c });
+```
+
+Middlewares **don't run** with `mockContext`. That's the trade-off — direct invocation skips the stack. Use `.action`/`.loader`/`.subscribe` whenever possible; reach for `mockContext` only for code that isn't behind a route.
+
+## Putting it together — full example
+
+```typescript
+import { createTestApp } from "@mauroandre/velojs/testing";
+import routes from "../app/routes.js";
+import { stream_backup } from "../app/layouts/AdminLayout.js";
+import { action_setBackup, action_backupNow } from "../app/stacks/apps/AppEdit.js";
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+
+describe("Backup — stream + auth + ownership", () => {
+    let app: Awaited<ReturnType<typeof createTestApp>>;
+    let userA: any, userB: any, appId: string;
+
+    beforeAll(async () => {
+        app = await createTestApp({
+            routes,
+            bootstrap: async () => {
+                const { connect } = await import("@mauroandre/zodmongo");
+                await connect(process.env.MONGO_URI!, "podcubo_test");
+            },
+            getSessionCookie: async ({ user }) => {
+                const { createToken } = await import("../app/modules/user/user.service.js");
+                return { session: await createToken({ user }) };
+            },
+        });
+    });
+
+    afterAll(async () => await app.close());
+
+    beforeEach(async () => {
+        await app.reset();
+        await cleanTestDb();
+        userA = await factory.user({ email: "a@x.com" });
+        userB = await factory.user({ email: "b@x.com" });
+        appId = await factory.dbApp(userA, "postgresql");
+    });
+
+    it("backup events reach the app owner", async () => {
+        const sub = await app.as({ user: userA }).subscribe(stream_backup, {
+            channel: appId,
+        });
+        expect(sub.status).toBe(200);
+
+        await app.as({ user: userA }).action(action_setBackup, {
+            body: { appId, schedule: "daily" },
+        });
+        await app.as({ user: userA }).action(action_backupNow, { body: { appId } });
+
+        const event = await sub.next({ timeoutMs: 2000 });
+        expect(event).toMatchObject({ kind: "backup", status: "running" });
+        await sub.close();
+    });
+
+    it("user B cannot subscribe to user A's app stream", async () => {
+        const sub = await app.as({ user: userB }).subscribe(stream_backup, {
+            channel: appId,
+        });
+        expect(sub.status).toBe(403);
+        expect(sub.events).toEqual([]);
+    });
+});
+```
+
+A single test exercises: channel resolver with auth, middleware chain, cookie parsing, action invocation, service → stream emit, snapshot persistence, reconnection. **No mocks of framework internals.** Real DB. Stack complete.
+
+## Patterns that are NOT in scope
+
+The toolkit covers backend testing (HTTP, streams, server-side functions). It **does not** cover:
+
+- **Driver / service mocking** — use `vi.mock(path, factory)` from Vitest. The toolkit doesn't try to abstract this since Vitest already does it well.
+- **Frontend testing** — use Preact Testing Library or Playwright. These are well-served by external tools; VeloJS doesn't duplicate them.
+- **End-to-end with browser** — use Playwright with `velojs start`.
+
+## FAQ
+
+### Can I run tests in parallel?
+
+Yes. Each test file runs in its own Vitest worker, and the toolkit isolates state per `createTestApp` instance. Within a file, `it.concurrent` works as long as each test has its own app or you avoid shared streams across concurrent tests.
+
+### Does `app.close()` really clean up everything?
+
+Yes — that's an invariant, not a feature. Heartbeats, retention timers, source AbortControllers, listeners — all go away. If Vitest reports open handles after `close()`, that's a bug in the toolkit.
+
+### What about `addRoutes` and `onServer` called at top-level import?
+
+If your `app/server.tsx` calls `addRoutes(...)` at the top level, those calls happen at import time, before any `createTestApp`. The toolkit captures a snapshot of the default context when each `createTestApp` is created, so top-level registrations are included.
+
+If your test needs **additional** route registration scoped to that test, do it inside `bootstrap`:
+
+```typescript
+const app = await createTestApp({
+    routes,
+    bootstrap: async () => {
+        addRoutes((a) => a.get("/test-only", (c) => c.json({ ok: true })));
+    },
+});
+```
+
+### How do I test a stream without a real perChannelSource resource?
+
+Mock the resource (e.g., the SSH client) with `vi.mock`, then subscribe normally. The framework's lifecycle (subscribe → start → unsubscribe → abort) runs as in production; only the underlying resource is mocked.
+
+### Why no top-level await on createTestApp?
+
+Top-level await works in Vitest, but the explicit `beforeAll` is clearer and lets you call `app.close()` symmetrically in `afterAll`.

package/agent/skills/velojs-type-reference/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: velojs-type-reference
+description: "Exact TypeScript signatures for route and config types: `AppRoutes`, `RouteNode`, `RouteModule`, `LoaderArgs`, `ActionArgs`, `Metadata`, `EndpointHandler`, `VeloConfig`, plus the package subpath exports. Use when you need a precise type or aren't sure which subpath exports a symbol."
+---
+
+# Type Reference
+
+This page lists all the TypeScript types and interfaces exported by VeloJS, organized by import path.
+
+## Subpath exports
+
+| Import | What you get |
+|--------|-------------|
+| `@mauroandre/velojs` | Types (`AppRoutes`, `RouteNode`, `RouteModule`, `ActionArgs`, `LoaderArgs`, `Metadata`, `HTTPMethod`, `EndpointHandler`, `EndpointHandlerArgs`, `VeloConfig`), `Scripts`, `Link`, `defineConfig`, `createEventStream`, `poll` |
+| `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage` |
+| `@mauroandre/velojs/client` | `startClient` |
+| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch`, `useEventStream`, `useSocket` |
+| `@mauroandre/velojs/events` | `createEventStream`, `poll` |
+| `@mauroandre/velojs/sockets` | `parseJson` |
+| `@mauroandre/velojs/testing` | `createTestApp`, `TestApp`, `TestResponse`, `TestSubscription`, `TestSocketSession` |
+| `@mauroandre/velojs/cookie` | `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie` |
+| `@mauroandre/velojs/factory` | `createMiddleware`, `createFactory` |
+| `@mauroandre/velojs/vite` | `veloPlugin` |
+| `@mauroandre/velojs/config` | `defineConfig`, `VeloConfig` |
+
+## Interfaces
+
+### LoaderArgs
+
+Passed to every `loader` function. Contains the URL parameters, query string, and Hono context:
+
+```typescript
+interface LoaderArgs {
+    params: Record<string, string>;  // URL params like :id
+    query: Record<string, string>;   // Query string like ?page=2
+    c: Context;                      // Hono request context
+}
+```
+
+### ActionArgs
+
+Passed to every `action_*` function. The generic type `TBody` defines the shape of the data sent from the client:
+
+```typescript
+interface ActionArgs<TBody = unknown> {
+    body: TBody;                          // Data from the client
+    params?: Record<string, string>;      // URL params (server only)
+    query?: Record<string, string>;       // Query string (server only)
+    c?: Context;                          // Hono context (server only)
+}
+```
+
+### Metadata
+
+Automatically injected into each module by the Vite plugin. Contains the module identifier and resolved paths:
+
+```typescript
+interface Metadata {
+    moduleId: string;         // e.g., "admin/Users"
+    fullPath?: string;        // e.g., "/admin/users"
+    path?: string;            // e.g., "/users"
+    [key: string]: unknown;   // your own metadata (title, etc)
+}
+```
+
+### RouteModule
+
+The shape of a route module (what `import * as Module` gives you):
+
+```typescript
+interface RouteModule {
+    Component: ComponentType<any>;
+    loader?: (args: LoaderArgs) => Promise<any>;
+    /** Dynamic routes to prerender with `velojs build --static`. */
+    staticPaths?: () => Promise<Record<string, string>[]>;
+    metadata?: Metadata;
+    [key: `action_${string}`]: (args: ActionArgs<any>) => Promise<any>;
+}
+```
+
+### RouteNode
+
+A single node in the route tree defined in `routes.tsx`:
+
+```typescript
+interface RouteNode {
+    path?: string;
+    /** Optional: endpoint-only and grouping nodes have no module. */
+    module?: RouteModule;
+    /** Endpoint nodes — see the Endpoints doc. */
+    method?: HTTPMethod;
+    handler?: EndpointHandler;
+    children?: RouteNode[];
+    middlewares?: MiddlewareHandler[];
+    isRoot?: boolean;
+    /** HTTP status for the page (default 200). A bare `path: "*"` catch-all
+     *  defaults to 404 and is served via Hono's notFound hook. */
+    statusCode?: number;
+}
+```
+
+### HTTPMethod
+
+```typescript
+type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+```
+
+### EndpointHandlerArgs / EndpointHandler
+
+Passed to an endpoint node's `handler`. Unlike a loader, it returns a `Response`:
+
+```typescript
+interface EndpointHandlerArgs {
+    c: Context;
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+
+type EndpointHandler = (args: EndpointHandlerArgs) => Response | Promise<Response>;
+```
+
+### AppRoutes
+
+The type of the default export from `routes.tsx`:
+
+```typescript
+type AppRoutes = RouteNode[];
+```
+
+### VeloConfig
+
+Configuration options for `veloPlugin()`:
+
+```typescript
+interface VeloConfig {
+    appDirectory?: string;   // default: "./app"
+    routesFile?: string;     // default: "routes.tsx"
+    serverInit?: string;     // default: "server.tsx"
+    clientInit?: string;     // default: "client.tsx"
+    port?: number;           // default: 3000 (the PORT env always wins)
+}
+```

package/agent/skills/velojs-vite-plugin/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: velojs-vite-plugin
+description: "The `veloPlugin` build pipeline: the 9 AST transforms that inject metadata, stub actions, strip loaders/middlewares and prune imports; plugin options and virtual entries. Use when configuring `vite.config.ts` or debugging why transformed code behaves unexpectedly."
+---
+
+# Vite Plugin
+
+The `veloPlugin()` is the core of VeloJS. It's a single function that returns 6 Vite plugins working together to handle routing, SSR, code transforms, and more.
+
+## The 6 plugins
+
+| Plugin | What it does |
+|--------|-------------|
+| `velo:config` | Sets up build config for client/server modes, Preact aliases, and environment defines |
+| `velo:transform` | Performs AST transforms on your code (the most important plugin) |
+| `velo:static-url` | Rewrites CSS `url(/path)` to use `STATIC_BASE_URL` in production builds |
+| `@preact/preset-vite` | Adds Preact JSX support |
+| `@hono/vite-dev-server` | Runs the SSR dev server |
+| `velo:ws-bridge` | Exposes Vite's HTTP server for WebSocket handlers during development |
+
+## AST Transformations
+
+The `velo:transform` plugin uses Babel to modify your code at build time. It applies 9 transformations to `.ts`/`.tsx` files inside your `appDirectory` (a file elsewhere, or a `.js`/`.jsx` one, is not transformed at all):
+
+| # | Transform | When | What it does |
+|---|-----------|------|-------------|
+| 1 | Remove middlewares | Client only | Strips the `middlewares` property and any import only it referenced |
+| 2 | Remove endpoint routes | Client only | Strips `{ method, handler }` nodes from `routes.tsx`, and their imports |
+| 3 | Inject metadata | Server + Client | Adds `export const metadata = { moduleId, fullPath, path }` to each module |
+| 4 | Transform loader functions | Server + Client | Injects moduleId into `useLoader()` and `Loader()` calls so they know which data to read |
+| 5 | Transform actions for client | Client only | Replaces `action_*` bodies with `fetch()` stubs (the RPC mechanism) |
+| 6 | Transform streams for client | Client only | Replaces `stream_*` with a `{ __path }` stub |
+| 7 | Transform sockets for client | Client only | Replaces `socket_*` with a `{ __path }` stub |
+| 8 | Remove loaders | Client only | Strips `export const loader` entirely from the client bundle |
+| 9 | Prune orphaned imports | Client only | Removes imports left unreferenced by 1–8, so server-only code doesn't reach the browser |
+
+These transforms are why VeloJS can provide such a seamless developer experience — you write one file, and the framework generates the right code for server and client automatically.
+
+## Build process
+
+When you run `velojs build`, two Vite builds happen in sequence:
+
+```bash
+velojs build
+# 1. vite build              → dist/client/ (client.[hash].js, client.[hash].css + .vite/manifest.json)
+# 2. vite build --mode server → dist/server.js
+```
+
+The first build creates the client bundle (JavaScript, CSS, and assets). The second build creates the server entry point that handles SSR and API routes.
+
+## Virtual modules
+
+VeloJS uses Vite virtual modules to generate the server and client entry points automatically:
+
+| Module | Purpose |
+|--------|---------|
+| `virtual:velo/server-entry` | Imports your `server.tsx` + routes, calls `startServer()` |
+| `virtual:velo/client-entry` | Imports your `client.tsx` + routes, calls `startClient()` |
+| `/__velo_client.js` | Alias for the client entry (used in dev mode) |
+
+You never import these directly — they're generated by the plugin.
+
+## Hot reload
+
+When you edit `routes.tsx`, the plugin detects the change, rebuilds the path map, and triggers a full page reload. Other file changes use Vite's standard HMR (hot module replacement).
+
+## Request isolation
+
+VeloJS uses Node's `AsyncLocalStorage` to isolate data per request. Each SSR render runs in its own storage context, so concurrent requests never leak data between each other.
+
+This is why hooks like `useParams()`, `useQuery()`, and `Loader()` work correctly on the server — they read from the current request's storage, not from a global variable.