@warlock.js/web 5.0.2 → 5.2.0

package/llms-full.txt

@@ -2,14 +2,6 @@
 
 > Package: `@warlock.js/web`
 
-> SSR React pages served by the same Warlock HTTP server that serves the API — a backend framework that renders React, not a React framework.
-
-> First published release: 5.0.0. `@warlock.js/web` had never been published to npm before this release.
-
-> Consumer entry points: `@warlock.js/web`, `@warlock.js/web/client/runtime`, `@warlock.js/web/connector`, and `@warlock.js/web/vite`. The published `@warlock.js/web/hydration` subpath is a framework build input; application code never imports it.
-
-> Deliberate non-goals: server actions are a v2 design decision rather than a missing v1 feature; page routes reject regex parameters, optional parameters, and multiple parameters in one segment.
-
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/web/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
 ## add-web-to-an-app  `@warlock.js/web/add-web-to-an-app/SKILL.md`
@@ -26,7 +18,7 @@ description: 'Install the SSR page layer with `warlock add web`: add React/Vite
 ## The shape
 
 ```bash
-yarn warlock add web
+pnpm warlock add web
 ```
 
 On the ordinary path it leaves this application-owned shape:
@@ -97,8 +89,8 @@ On the refusal path, free `/` yourself and create a page with either `route = "/
 Read the files rather than assuming the command could patch every application shape:
 
 ```bash
-yarn warlock routes --method GET --path /
-yarn warlock routes --method GET --path /welcome
+pnpm warlock routes --method GET --path /
+pnpm warlock routes --method GET --path /welcome
 ```
 
 The desired result is one page route at `/` and, when the stock JSON route existed, one API route at `/welcome`.
@@ -122,16 +114,16 @@ The desired result is one page route at `/` and, when the stock JSON route exist
 
 ---
 name: create-a-page
-description: 'Create an SSR React page under `src/web/**` or `src/app/<module>/web/**` with a literal `route`, a default component, an optional typed `loader`, and page `metadata`. Triggers: `*.page.tsx`, `route`, `PageLoader`, `PageProps`, `PageMetadata`; "create a page", "add an SSR route", "make a React page", "type page loader data"; typical import `import type { PageLoader, PageProps } from "@warlock.js/web"`. Skip: root document shell — `@warlock.js/web/write-the-root/SKILL.md`; layout wrappers and prefixes — `@warlock.js/web/use-layouts/SKILL.md`; loader lifecycle and `shared` — `@warlock.js/web/load-page-data/SKILL.md`; competing frameworks `next`, `remix`, `react-router` file routes.'
+description: 'Create an SSR React page under `src/web/**`, with either a literal `route` or a filesystem-derived one, a default component, an optional typed `loader`, page `metadata`, the `error.page.tsx` boundary, and the universal `register()` hook. Triggers: `*.page.tsx`, `route`, `PageLoader`, `PageProps`, `PageMetadata`, `error.page.tsx`, `register`, `[...slug]`; "create a page", "add an SSR route", "make a React page", "type page loader data", "add an error boundary", "catch-all route", "page renders blank 200", "page has no default export"; typical import `import type { PageLoader, PageProps } from "@warlock.js/web"`. Skip: root document shell — `@warlock.js/web/write-the-root/SKILL.md`; layout wrappers and prefixes — `@warlock.js/web/use-layouts/SKILL.md`; loader lifecycle and `shared` — `@warlock.js/web/load-page-data/SKILL.md`; competing frameworks `next`, `remix`, `react-router` file routes.'
 ---
 
 # Warlock — create a page
 
-A page is any `*.page.tsx` beneath the global `src/web/` tree or a module's `src/app/<module>/web/` tree. Its URL is declared by `route`; its default export renders React.
+A page is any `*.page.tsx` beneath `src/web/` — the only page root. (A per-module `src/app/<module>/web/` tree is not scanned; move any page that lived there into `src/web/`, a subdirectory if you like.) Its URL is either a declared `route` or one derived from its own location; its default export renders React.
 
 ## The shape
 
-```tsx title="src/app/products/web/product-details.page.tsx"
+```tsx title="src/web/products/product-details.page.tsx"
 import type { PageLoader, PageMetadata, PageProps } from "@warlock.js/web";
 
 export const route = {
@@ -184,7 +176,28 @@ export default function ContactPage() {
 }
 ```
 
-The `route` export is required. Development skips a page without it; the production discovery pass refuses to build it.
+`route` is optional. A page that omits it derives both its path and its name from where the file sits beneath `src/web` ([filesystem routing](#filesystem-routing), below). A page that declares `route` uses that instead — an explicit `route` always wins over the derived one, for both the path and (when it sets `name`) the name.
+
+Changed in 5.2: through 5.1 an omitted `route` was refused — `warlock dev` and the production discovery pass threw `MissingRouteExportError`, naming the file. That error class is gone; the same file now resolves to a real, browsable URL.
+
+### The default export is required
+
+`route` is optional; the default export is not. A `*.page.tsx` that exports only named bindings is a **hard discovery/build failure naming the file**:
+
+```
+The page "src/web/contact.page.tsx" has no runtime default export. Every `*.page.tsx`
+file must default-export the React component it renders. For example:
+`export default function Page() { return <main />; }`
+```
+
+Changed in 5.2: such a file used to be discovered and registered anyway, then serve a blank `200` at its URL — a page that looked deployed and rendered nothing, with no error anywhere. It now stops the build.
+
+Two details worth knowing:
+
+- **`export { Page as default }` satisfies the rule** — the check is for a runtime default binding, not for the `export default` keyword form specifically.
+- **`export default interface Page {}` does not.** A type-only default is erased at compile time, so there is no component at runtime; it is treated as missing.
+
+A file that cannot be parsed reports separately — `Cannot inspect the default export of "<file>": the file could not be parsed (…). Fix the syntax error and discovery will continue.` — so a syntax error never masquerades as a missing export.
 
 ## Route declarations
 
@@ -201,16 +214,44 @@ export const route = {
 } as const;
 ```
 
-Prefer an explicit stable `name` for links. Without one, Warlock derives a name from the module and declared path: a module page gets `<module>.<path-as-dots>`, a global root page gets `index`, and another global page gets its dotted path.
+Prefer an explicit stable `name` for links. Without one, Warlock derives a name from the declared path — a global root page gets `index`, another global page gets its dotted path — the same derivation [filesystem routing](#filesystem-routing) uses when there is no `route` at all.
+
+Every segment of a page's URL is written down somewhere: `route.path` (or the derived filesystem path), prefixed by the literal `prefix` exports of the positional layouts above it ([use-layouts](../use-layouts/SKILL.md)). Where the file sits always decides which layouts are above it, and — only when `route` is absent — the path segments too.
 
 The build reads `route` without executing application code. Declare it directly with `export const` and literal strings. Variables, function calls, computed object keys, spreads, and `export { route }` are refused.
 
+## Filesystem routing
+
+Omit `route` and the URL comes from the page's own path beneath `src/web`:
+
+- Every directory contributes a segment, in order — `src/web/products/featured.page.tsx` derives `/products/featured`.
+- A `(group)` directory — parentheses, not braces — contributes nothing to the URL, only to organization: `src/web/(marketing)/pricing.page.tsx` derives `/pricing`.
+- `index.page.tsx` claims its own directory rather than adding a segment: `src/web/products/index.page.tsx` derives `/products`. This is the ONLY filename with special meaning — `home.page.tsx` is not magic and derives `/home`.
+- `[id]` becomes `:id`: `src/web/products/[id].page.tsx` derives `/products/:id`.
+- A layout `prefix` on the page's ancestry composes in front of the derived path exactly as it does for an explicit `route.path` ([use-layouts](../use-layouts/SKILL.md)).
+
+Two pages that derive (or declare) the same effective path is a build error naming both files.
+
+### Catch-all segments are NOT supported
+
+**`[...slug].page.tsx` does not do what it looks like.** There is no catch-all / rest-parameter form in filesystem routing. Only `[name]` — a plain identifier in square brackets — is recognized as a dynamic segment; `[...slug]` fails that pattern and is taken as an ordinary **literal** segment.
+
+So `src/web/docs/[...slug].page.tsx` derives the route path `/docs/[...slug]` and the route name `docs.[...slug]`. It registers, it builds, and it serves — at the literal URL `/docs/%5B...slug%5D` and nowhere else. `/docs/a/b` does not match it.
+
+⚠ **Nothing warns you.** There is no build error, no dev warning, and no refusal; the page simply answers a URL nobody will ever request. If you came from Next.js or Remix expecting `[...slug]` to work, this is the failure mode to recognize.
+
+Until a catch-all exists, use the terminal wildcard with an explicit `route`:
+
+```tsx
+export const route = { path: "/docs/*", name: "docs.catchAll" } as const;
+```
+
 ## Page-route grammar
 
 Page routes deliberately accept less than API routes:
 
 - Supported: `/`, static segments, whole-segment params such as `/products/:id`, the exact wildcard `*`, and a terminal wildcard such as `/docs/*`.
-- Not supported: regex params, optional params, multiple params in one segment, params mixed with text, doubled or trailing slashes, and non-terminal wildcards.
+- Not supported: regex params, optional params, multiple params in one segment, params mixed with text, doubled or trailing slashes, non-terminal wildcards, and catch-all/rest segments (`[...slug]`).
 
 Write two pages for an optional segment. Validate a constrained parameter in the page instead of putting a regex in its path.
 
@@ -234,6 +275,39 @@ export const metadata: PageMetadata = {
 
 Supported fields are `title`, `description`, `keywords`, `canonical`, `robots`, `openGraph`, and `twitter`. Function metadata runs after a successful loader. If a loader fails, Warlock uses error metadata instead of calling the page function with missing data.
 
+## The error boundary — `error.page.tsx`
+
+`error.page.tsx` anywhere beneath `src/web` is the application's one error boundary — exactly two page filenames are special in Warlock, this and `404.page.tsx`. A second `error.page.tsx` is a build error naming both files. Like `404.page.tsx`, it declares no `route` — it has no URL of its own and is reached only when something throws.
+
+```tsx title="src/web/error.page.tsx"
+import type { ErrorPageProps } from "@warlock.js/web";
+
+export default function ErrorPage({ error, status }: ErrorPageProps) {
+  return (
+    <main>
+      <h1>Something went wrong</h1>
+      <p>Status: {status}</p>
+    </main>
+  );
+}
+```
+
+During SSR the component receives the real thrown value in `error`. After hydration it receives the JSON-safe `{ name, message, stack? }` shape instead — the original value does not survive the wire. `robots: noindex` is a framework default on this path that an app-supplied `metadata` cannot remove.
+
+If the failure happens before any page module could even load — a module-load or `register()` throw — there is no trustworthy server composition left to hydrate against, so Warlock renders a plain framework fallback (your `error.page.tsx` if it can still be loaded, otherwise a minimal built-in boundary) with no hydration script at all rather than risk hydrating client code against markup nothing can vouch for.
+
+## The `register()` hook
+
+`root.tsx`, `layout.tsx`, and `*.page.tsx` may each export `register`: a synchronous, no-argument, side-effect hook that runs once per module namespace instance, on both the server and the browser, before that module's middleware or loader. Unlike `route`/`middleware`/`validation`/`loader`/`metadata`, it is not stripped from the client — it is meant to run on both sides.
+
+```tsx
+export function register() {
+  // one-time setup for this module namespace; must not return a Promise
+}
+```
+
+Returning a Promise (or anything thenable) throws — `register()` must finish before the module is usable.
+
 ## The client boundary
 
 The browser boundary is decided by the import graph, not by the file's location. A `*.page.tsx` is universal:
@@ -245,9 +319,30 @@ The browser boundary is decided by the import graph, not by the file's location.
 
 Keep server-only repository and service reads inside `loader`. Do not read them from module-scope initializers or the default component.
 
+## Editing a page in development
+
+`warlock dev` decides Fast Refresh vs. a full reload by comparing the module's *skeleton* — its source with every component body masked out — across the edit. Everything outside a component body is part of the skeleton: imports, module-level declarations, and all server exports (`route`, `middleware`, `validation`, `loader`, `metadata`). The skeleton moving, with or without a simultaneous JSX change, forces a full reload; the skeleton holding still defers to Fast Refresh.
+
+- **A JSX-only edit hot-updates.** The skeleton is unchanged, so Vite's Fast Refresh applies the projected client code with no reload and no lost component state.
+- **A `metadata`-only edit reloads the document.** `metadata` sits outside the skeleton's masked region, so the edit moves it. Warlock sends a full reload, which re-runs SSR and rebuilds `<head>`. Component state is lost — that is the price of seeing the new `<title>` without touching the browser.
+- **Any module-level change reloads, not just `metadata`.** An edited import, a module-level declaration, or an edit confined to `route`, `middleware`, `validation`, or `loader` all move the skeleton the same way and take the same full-reload path.
+- **A helper function used only by the JSX still reloads if it is declared at module level.** The rule does not try to prove which half of a shared declaration the edit was "really" for — it over-approximates deliberately, because a false reload only costs component state, while a missed one ships a stale `<head>` and calls it a hot update.
+- Creating, deleting, or renaming a page file, or editing its `route` export, is page-GRAPH churn, not a skeleton edit — see below, not Fast Refresh.
+
+Changed in 5.1: a metadata-only edit previously left a stale `<head>` until you refreshed the browser by hand. The current skeleton-comparison rule replaces that earlier, narrower "metadata-only" special case.
+
+## Route-table changes in development
+
+Creating a page, deleting one, or editing its `route` export's path is a different kind of dev edit from the skeleton comparison above — it changes which URLs exist, not just how one already-registered URL renders. `warlock dev` re-registers the affected route(s) in the live route table, atomically and with no dev-server restart, so the new file (or new path) is reachable on the very next request with no manual restart.
+
+Changed in 5.2: through 5.1 the route table was built once at boot and never again. Creating a page 404'd forever; deleting one kept it reachable at its old URL; editing `route` served the OLD path from the old file and 404'd the new one — the running server silently disagreed with the source on disk. All three are now live.
+
 ## Gotchas
 
-- **Do not derive URLs from filenames.** The file chooses discovery; `route` chooses the public URL.
+- **A page with no `route` is not unreachable.** It derives a real URL from its file location — see [Filesystem routing](#filesystem-routing). Nothing about a route-less page is refused anymore.
+- **A page with no default export IS refused.** Named exports alone fail the build naming the file, instead of serving a blank 200.
+- **`[...slug]` is not a catch-all.** It is read as a literal path segment and silently produces an unreachable route — see [Catch-all segments are NOT supported](#catch-all-segments-are-not-supported).
+- **`process.env` is refused in the client/universal graph, `PUBLIC_` prefix included.** Read env values in a loader and return them as page data; see [`load-page-data/SKILL.md`](../load-page-data/SKILL.md).
 - **Keep `route` literal.** A computed route cannot be discovered without executing app code and is refused.
 - **Do not annotate the loader with `: PageLoader`.** That erases the return type `PageProps` needs.
 - **Components receive data, not HTTP objects.** `request` and `response` belong to loaders; the component also renders in the browser.
@@ -266,16 +361,86 @@ Keep server-only repository and service reads inside `loader`. Do not read them
 
 ---
 name: load-page-data
-description: 'Load App, Layout, and Page data with `AppLoader`, `LayoutLoader`, and `PageLoader`; type component `data`, validate page input, short-circuit with the buffered response, and publish request-scoped browser-safe values through `shared`. Triggers: `PageLoader`, `LayoutLoader`, `AppLoader`, `PageProps`, `shared`, `useShared`, `validation`, `request.validated`; "load page data", "pass server data to React", "share request data", "redirect from a loader". Skip: page module basics — `@warlock.js/web/create-a-page/SKILL.md`; layouts — `@warlock.js/web/use-layouts/SKILL.md`; mutation follow-up — `@warlock.js/web/navigate-on-the-client/SKILL.md`; competing loaders Next data functions, Remix loaders, React Server Components.'
+description: 'Load App, Layout, and Page data with `AppLoader`, `LayoutLoader`, and `PageLoader`; type component `data`, validate page input, short-circuit with the buffered response, and publish request-scoped browser-safe values through `shared`. Triggers: `PageLoader`, `LayoutLoader`, `AppLoader`, `PageProps`, `shared`, `useShared`, `validation`, `request.validated`, `process.env`, `env("PUBLIC_...")`, `import.meta.env.PUBLIC_`; "load page data", "pass server data to React", "share request data", "redirect from a loader", "read an environment variable in a page", "process.env refused in the client build", "loader execution order", "return a Response from a loader". Skip: page module basics — `@warlock.js/web/create-a-page/SKILL.md`; layouts — `@warlock.js/web/use-layouts/SKILL.md`; mutation follow-up — `@warlock.js/web/navigate-on-the-client/SKILL.md`; competing loaders Next data functions, Remix loaders, React Server Components.'
 ---
 
 # Warlock — load page data
 
 Loaders run on the server and return serializable data to their own component level. Use the level-specific loader type with `satisfies`, then pass `typeof loader` to the matching props type.
 
+## Pass environment values through loader data
+
+**`process.env` is refused outright in the client/universal graph, and there is
+no `PUBLIC_` exception to it — static or computed.** `env("PUBLIC_X")` does not
+work client-side either. **The supported pattern is: read the value in a loader,
+which is server code, and return it as page data.**
+
+```tsx
+import { env } from "@warlock.js/core";
+import type { PageLoader, PageProps } from "@warlock.js/web";
+
+export const loader = (async () => ({
+  siteName: env("PUBLIC_SITE_NAME"),
+})) satisfies PageLoader;
+
+export default function HomePage({ data }: PageProps<typeof loader>) {
+  return <h1>{data.siteName}</h1>;
+}
+```
+
+Loaders are server-only and may read configuration normally. Their return is
+serialized to the browser, so include only values that are safe to expose.
+
+### What is refused, and where
+
+Every one of these fails the build when it is reachable from a default page or
+layout component, `register()`, or any helper they import:
+
+```tsx
+process.env.API_URL; // static key — refused
+process.env.PUBLIC_API_URL; // a PUBLIC_ prefix changes nothing — refused
+process.env[key]; // computed key — refused
+const { API_URL } = process.env; // bare value-read — refused
+const all = { ...process.env }; // bare value-read — refused
+Object.keys(process.env); // bare value-read — refused
+JSON.stringify(process.env); // bare value-read — refused
+env("PUBLIC_API_URL"); // pulls in @warlock.js/core, a server package — refused
+```
+
+Bare value-reads matter as much as keyed ones: `process` does not exist in a
+browser, so referencing the object at all — assigned, destructured, spread, or
+passed as an argument — is already broken, and passing the whole object to a
+component is how a server secret reaches a page in one line.
+
+**Enforcement covers dev SSR as well as the client bundle, and a violation
+fails the build.** It is not a production-only check you can discover late: the
+same refusal fires under `warlock dev`.
+
+Reads inside `loader`, `route`, `middleware`, `validation`, and `metadata` are
+never affected — those exports are stripped before the client graph is formed.
+Server-side code is unrestricted.
+
+### The one client-side escape hatch
+
+If a value genuinely has to be inlined into browser code rather than passed
+through loader data, the supported spelling is `import.meta.env.PUBLIC_*` with a
+**static** key:
+
+```tsx
+export default function HomePage() {
+  return <h1>{import.meta.env.PUBLIC_SITE_NAME}</h1>;
+}
+```
+
+`import.meta.env` is the Vite surface, not Node's, and only the `PUBLIC_` prefix
+(plus Vite's own `MODE`, `DEV`, `PROD`, `BASE_URL`, `SSR`) is allowed through. It
+is inlined at build time, so it cannot vary per request or per deployment of the
+same bundle — which is why loader data remains the default answer, and the only
+one for anything request-scoped.
+
 ## The shape
 
-```tsx title="src/app/products/web/product-details.page.tsx"
+```tsx title="src/web/products/product-details.page.tsx"
 import { v } from "@warlock.js/seal";
 import type { PageLoader, PageProps } from "@warlock.js/web";
 
@@ -322,11 +487,11 @@ export default function ProductDetailsPage({ data }: PageProps<typeof loader>) {
 
 ## Three loader levels
 
-| Module | Contract | Component props |
-| --- | --- | --- |
-| `src/web/root.tsx` | `AppLoader` | `AppProps<typeof loader>` |
+| Module                  | Contract       | Component props              |
+| ----------------------- | -------------- | ---------------------------- |
+| `src/web/root.tsx`      | `AppLoader`    | `AppProps<typeof loader>`    |
 | positional `layout.tsx` | `LayoutLoader` | `LayoutProps<typeof loader>` |
-| `*.page.tsx` | `PageLoader` | `PageProps<typeof loader>` |
+| `*.page.tsx`            | `PageLoader`   | `PageProps<typeof loader>`   |
 
 All receive one context object with `request`, `response`, and `shared`. Page loaders add generics that connect their sibling `validation` and `route` exports to `request.validated()` and `request.input()`.
 
@@ -341,9 +506,17 @@ When `validating` is absent or empty, pages validate query + params, with params
 
 `request.validated()` uses the schema's output type, so fields with `.default(...)` are present. `request.input("id")` is narrowed from a literal route path when the loader uses `typeof route`.
 
+## Execution order
+
+Loaders run **sequentially, root to leaf, each one awaited before the next starts**: `root.tsx`'s `AppLoader`, then the layout's `LayoutLoader`, then the page's `PageLoader`. There are exactly three levels — a page has at most one _rendering_ layout (nested rendering layouts are a build error), so there is no outer-layout/inner-layout loader chain to reason about. Layout _middleware_ still composes across the whole ancestry; only the loader levels are capped at three.
+
+**The first core `Response` a loader returns is terminal.** Returning a `Response` object stops the pipeline immediately: no lower loader starts, `metadata` is not resolved, and that response is sent as-is. It is more terminal than a short-circuit — because the response is returned whole, the buffered header/cookie writes made at that same level are discarded along with everything below it. Use `response.redirect()` / `response.notFound()` (which produce a `LoaderShortCircuit`, committing that level's buffer inclusively) when you want your buffered writes to survive; return a raw `Response` only when you mean "this exact response, nothing else."
+
+A loader that **throws** is also terminal: it stops lower loaders, discards its own level's buffer, and commits only the levels above it.
+
 ## Loader response surface
 
-Each loader gets its own buffered response because App, Layout, and Page loaders execute in parallel. The public loader methods are:
+Each loader gets its own buffered response — never the live one — so that a level discarded by a short-circuit or a throw cannot leak half-written headers onto a response it no longer owns. The public loader methods are:
 
 ```ts
 response.header("cache-control", "private, max-age=60");
@@ -408,7 +581,7 @@ The request pipeline is:
 
 1. App, layout, and page middleware run outermost first and write `shared`.
 2. `shared` is normalized, checked, and sealed.
-3. App, layout, and page loaders run in parallel and may only read it.
+3. App, layout, and page loaders run in order, root to leaf, and may only read it.
 4. Components receive a readonly snapshot through props or `useShared()`.
 
 Use `useShared()` in a deep component that is not already receiving level props:
@@ -425,12 +598,12 @@ export function LocaleLabel() {
 
 Only put browser-safe data in `shared`: scalars, arrays, plain objects, or values with a valid `toJSON()` contract. Functions, `Date`, `Map`, `Set`, and arbitrary class instances are rejected. Prefer a narrow Resource output over a model.
 
-## Parallelism rules
+## Level isolation rules
 
-- App, Layout, and Page loaders cannot read each other's return values.
+- App, Layout, and Page loaders cannot read each other's return values. They run in order, but no channel is provided between them — a lower loader is not handed what an upper one returned. Put anything a lower level needs into `shared` from middleware instead.
 - A loader may read `shared` because middleware completed and it was sealed first.
 - A loader must not write `shared`; a post-seal write throws.
-- Loader response mutations are buffered per level and settled deterministically.
+- Loader response mutations are buffered per level and settled deterministically, root to leaf.
 
 ## Gotchas
 
@@ -438,7 +611,9 @@ Only put browser-safe data in `shared`: scalars, arrays, plain objects, or value
 - **Return client-safe data.** Components render again in the browser; models and server handles do not survive the wire.
 - **Write `shared` in middleware only.** Loaders run after the seal.
 - **Required shared keys need unconditional writers.** The type is a promise for every request.
-- **Do not use loader return values as cross-level communication.** The loaders run in parallel.
+- **Do not use loader return values as cross-level communication.** Levels run in order but are not wired to each other; use `shared`, written in middleware.
+- **`404.page.tsx` never runs its own loader.** The not-found page's module is registered and rendered for real — `register()` and its middleware still run — but the page loader is omitted from the request in both dev and production, so a missing URL cannot trigger application data work or fail a second time. Its ancestry contributes nothing either: the 404 page renders with an empty layout chain by construction. **The root `AppLoader` in `root.tsx` still runs** for a 404 request, so keep it cheap and make sure it tolerates a request that matched nothing.
+- **`process.env` is refused in the client/universal graph, with no `PUBLIC_` exception.** Read it in a loader and return it as page data.
 - **Server actions are not supported.** POST to an ordinary Warlock API route and call `refresh()` after success.
 
 ## See also
@@ -459,6 +634,8 @@ description: 'Navigate hydrated pages with `<Link>`, resolve named URLs with `hr
 
 `<Link>` renders a real anchor for progressive enhancement and intercepts a plain in-app click after hydration. The server remains the only route matcher; client navigation fetches the page-data representation of the URL and swaps the Layout + Page tree.
 
+Every behaviour on this page requires 5.1 in an installed app. In 5.0.0–5.0.2 no client JavaScript executed at all — `react-dom/client` was served as raw CommonJS and hydration never mounted — so `<Link>` degraded to its underlying anchor and every click was a full page load. See [write-the-root](../write-the-root/SKILL.md#root-is-the-hydration-boundary).
+
 ## The shape
 
 ```tsx title="src/web/components/product-link.tsx"
@@ -556,7 +733,7 @@ export function CheckoutButtons() {
 
 The public primitive is `refresh()`. There is no `revalidate()` export.
 
-```tsx title="src/app/products/web/delete-product-button.tsx"
+```tsx title="src/web/products/delete-product-button.tsx"
 import { refresh } from "@warlock.js/web";
 
 export function DeleteProductButton({ id }: { id: string }) {
@@ -701,7 +878,7 @@ Root imports ending in `.css`, `.scss`, `.sass`, `.less`, or `.styl` are recogni
 
 A page may import CSS directly:
 
-```tsx title="src/app/products/web/products.page.tsx"
+```tsx title="src/web/products/products.page.tsx"
 import "./products.css";
 
 export const route = {
@@ -718,7 +895,7 @@ export default function ProductsPage() {
 }
 ```
 
-```css title="src/app/products/web/products.css"
+```css title="src/web/products/products.css"
 .products-page {
   display: grid;
   gap: 1rem;
@@ -727,7 +904,7 @@ export default function ProductsPage() {
 
 Recognized asset imports survive the page's client projection. The client boundary is determined by the import graph, not by the file living under `web/`.
 
-In development, only root stylesheet imports are converted into render-blocking document links. A page-local import is loaded by Vite's client module graph around hydration, so it still applies but is not guaranteed before first paint. Move above-the-fold or site-wide rules into a stylesheet imported by `root.tsx` when avoiding a flash matters.
+For each matched handler, Warlock builds one ordered CSS chain: `[root, ...matched layouts, page]`. A stylesheet imported directly by any member of that chain becomes a render-blocking link in the initial document in both development and production. Unrelated pages and layouts do not contribute CSS to this response.
 
 ## Production delivery
 
@@ -737,9 +914,9 @@ The production client build enables Vite's manifest. Vite records emitted CSS ag
 <build.outdir>/client/.vite/manifest.json
 ```
 
-It collects every valid `css` asset across all manifest entries, deduplicates them in manifest order, and emits each as a render-blocking link before `</head>`.
+For each source in the matched handler chain, Warlock finds that source's manifest entry, collects its own CSS plus CSS from statically imported chunks, and emits the ordered, deduplicated result as render-blocking links before `</head>`. It does not follow `dynamicImports`, because doing so would pull unrelated lazy pages into the response.
 
-That means both root-imported and page-imported CSS are linked in the initial production document. The current implementation collects across the whole client manifest rather than selecting only the matched route's CSS, so every page receives the emitted stylesheet set.
+That means root-, matched-layout-, and page-imported CSS are linked in the initial production document without shipping another page's stylesheet set.
 
 Only manifest URLs under the one client asset prefix are emitted; a stylesheet outside the mounted asset directory is dropped instead of producing a dead link.
 
@@ -760,17 +937,16 @@ The hydration entry is built from the projected client graph. CSS imports are kn
 
 ## Diagnose missing or late CSS
 
-1. For global CSS in development, confirm `root.tsx` uses a bare import such as `import "./app.css";`.
+1. In development, confirm the root, matched layout, or page imports the stylesheet directly with a bare import such as `import "./app.css";`.
 2. Confirm the rendered document contains a closing `</head>` and a stylesheet URL ending in `?direct`.
-3. For page-local CSS in development, expect Vite's client graph to apply it after hydration; move critical rules to the root import if first paint matters.
-4. In production, confirm `.vite/manifest.json` has `css` arrays and the referenced files live under the client asset prefix.
+3. If CSS is imported indirectly through another JavaScript module in development, Vite's client graph still applies it, but Warlock's source scan cannot promote it to a render-blocking link; import critical CSS directly from a chain member.
+4. In production, confirm `.vite/manifest.json` has a source entry for the matched root/layout/page and that its `css` arrays reference files under the client asset prefix.
 5. Do not hand-author a link to a hashed production asset; its name belongs to the Vite manifest.
 
 ## Gotchas
 
-- **Root CSS and page CSS differ in dev.** Root imports are render-blocking; page imports are client-injected.
-- **Production currently links all emitted CSS on every page.** It is safe for first paint but not route-minimal.
-- **Use a bare root import.** `devStylesheetUrls` scans `import "./app.css"`, not a bound CSS-module import.
+- **CSS is scoped to the matched handler chain.** Root CSS is shared; only the current route's matched layouts and page add their direct imports.
+- **Use a bare direct import.** `devStylesheetUrls` scans `import "./app.css"` in each chain member, not a bound CSS-module import or an import hidden behind another JavaScript module.
 - **Keep a closing `</head>`.** Automatic link installation has nowhere safe to write without it.
 - **Do not remove `?direct` from a dev stylesheet link.** Vite otherwise responds with JavaScript.
 - **Do not import the hydration entry yourself.** The connector owns dev serving and production asset URLs.
@@ -794,7 +970,7 @@ A positional `layout.tsx` applies to pages in its directory and descendant direc
 
 ## The shape
 
-```tsx title="src/app/products/web/layout.tsx"
+```tsx title="src/web/products/layout.tsx"
 import type { LayoutLoader, LayoutProps } from "@warlock.js/web";
 
 export const prefix = "/products";
@@ -829,7 +1005,7 @@ export default function ProductsLayout({
 
 A page beside it can declare its path relative to the prefix:
 
-```tsx title="src/app/products/web/index.page.tsx"
+```tsx title="src/web/products/index.page.tsx"
 export const route = {
   path: "/",
   name: "products.index",
@@ -844,17 +1020,17 @@ The effective URL is `/products`. A page with `route.path = "/:id"` under the sa
 
 ## Prefix composition
 
-Every positional layout on the page's directory ancestry may export a literal `prefix`. Prefixes compose outermost first, then the page's own route path.
+Every positional layout on the page's directory ancestry may export a literal `prefix`. Prefixes compose outermost first, then the page's own route path — never appended to the directory's own name, so a layout `prefix` OVERRIDES its directory's segment rather than adding to it.
 
-```tsx title="src/app/users/web/layout.tsx"
+```tsx title="src/web/users/layout.tsx"
 export const prefix = "/users";
 ```
 
-```tsx title="src/app/users/web/account/layout.tsx"
+```tsx title="src/web/users/account/layout.tsx"
 export const prefix = "/account";
 ```
 
-```tsx title="src/app/users/web/account/settings.page.tsx"
+```tsx title="src/web/users/account/settings.page.tsx"
 export const route = {
   path: "/settings",
   name: "users.account.settings",
@@ -877,6 +1053,14 @@ The two prefix-only layouts above are legal because neither renders. Add a defau
 
 Non-rendering layouts may carry prefixes and middleware and may nest freely. Do not delete a middleware-only authorization boundary to satisfy the rendering limit; consolidate only the default-export wrappers.
 
+## `404.page.tsx` never gets a layout
+
+A `404.page.tsx` renders with no layouts, even when it sits in a directory with a rendering `layout.tsx` above it. Discovery reports an empty layout chain for the not-found page only, and both the client hydration registry and the production route table read from that same chain — the server has always rendered it with no layout wrapper, so the client no longer hydrates one either. A page that exists to handle failure must not depend on app chrome that can itself throw or need data.
+
+This is scoped to the not-found page: an ordinary page in the same directory still gets its full layout chain, and nested-layout refusal on the 404's own path is still enforced exactly as it is for any other page.
+
+`error.page.tsx` — the application's other special page, its one error boundary ([create-a-page](../create-a-page/SKILL.md)) — is excluded from discovery's layout-chain analysis the same way: neither special page has a layout chain of its own.
+
 ## Why layout state persists
 
 Client navigation rebuilds the Layout + Page element tree at the same `#root` position. When the next page uses the same layout component type in the same position, React reconciles it instead of remounting it. Layout state such as open menus, scroll containers, and media survives.
@@ -889,11 +1073,15 @@ Client navigation rebuilds the Layout + Page element tree at the same `#root` po
 
 Use `shared` when multiple levels need one request-derived value, and write it in middleware before loaders run. See [load-page-data](../load-page-data/SKILL.md).
 
+## The client boundary
+
+A layout is projected for the browser the same way a page is: `prefix`, `middleware`, `loader`, and (page-only) `validation`/`route` never reach the client bundle — `prefix` joins that stripped set for a layout the way `route` does for a page. The default export and any other surviving exports form the client graph. `register()` is the one export that is NOT stripped — it runs once per module namespace on both the server and the browser; see [create-a-page](../create-a-page/SKILL.md).
+
 ## Gotchas
 
 - **`layout.tsx` is positional.** It applies by directory ancestry; moving a page can change its layout and URL prefix together.
 - **Only one layout on a path may render.** Multiple prefix/middleware-only layouts are fine; multiple default exports are not.
-- **A layout prefix changes the registered URL.** Check the composed path, not only the page's `route.path`.
+- **A layout prefix changes the registered URL, and overrides its directory's segment rather than adding to it.** Check the composed path, not only the page's `route.path`.
 - **Keep `prefix` literal.** The build parses it without executing the module.
 - **Use `LayoutProps<typeof loader>`.** Bare `LayoutProps` is for a layout with no loader and gives `data` as `undefined`.
 - **Layout persistence is type-and-position based.** Changing to another layout component remounts it, as normal React reconciliation requires.
@@ -955,6 +1143,10 @@ The browser hydrates `#root`, not the whole document. The client tree deliberate
 
 Because App is outside the hydrated subtree, put client state that must survive navigation in a layout or component beneath `#root`, not in the document root.
 
+**Requires 5.1 in an installed app.** In 5.0.0–5.0.2 the dev server handed the browser `react-dom/client` as raw CommonJS, so `hydrateRoot` was not there as a named export and the hydration entry died on import — no client JavaScript ran at all. The symptoms were a page that server-rendered correctly but had dead `useState`, no HMR, and `<Link>` doing full page loads. The fix pre-bundles React through Vite's `optimizeDeps`. If you are debugging this against a checkout of the framework itself, note that the defect never reproduced there: inside the monorepo the hydration entry resolves outside `node_modules` and React was always optimized normally.
+
+If `root.tsx` (or any module it needs) fails to load or its `register()` throws, there is no trustworthy Layout+Page composition left to hydrate — Warlock falls back to a plain document with no hydration script at all rather than hydrate the browser against markup nothing can vouch for. See [create-a-page](../create-a-page/SKILL.md) for the app's own `error.page.tsx` boundary, which is tried first.
+
 ## `<Head />`
 
 `<Head />` renders the resolved page metadata at that position. It takes no props and emits:

package/llms.txt

@@ -2,10 +2,14 @@
 
 > Package: `@warlock.js/web`
 
+> Warlock.js web layer for the SSR page pipeline and client runtime.
+
 > SSR React pages served by the same Warlock HTTP server that serves the API — a backend framework that renders React, not a React framework.
 
 > First published release: 5.0.0. `@warlock.js/web` had never been published to npm before this release.
 
+> Use 5.1 or newer. In an installed 5.0.0–5.0.2 app no client JavaScript ran at all: the dev server served `react-dom/client` as raw CommonJS, so `hydrateRoot` was missing and hydration failed on import — dead `useState`, no HMR, `<Link>` falling back to full page loads. Pages still server-rendered, which is why it looked like a React problem.
+
 > Consumer entry points: `@warlock.js/web`, `@warlock.js/web/client/runtime`, `@warlock.js/web/connector`, and `@warlock.js/web/vite`. The published `@warlock.js/web/hydration` subpath is a framework build input; application code never imports it.
 
 > Deliberate non-goals: server actions are a v2 design decision rather than a missing v1 feature; page routes reject regex parameters, optional parameters, and multiple parameters in one segment.
@@ -13,8 +17,8 @@
 ## Skills
 
 - [add-web-to-an-app](@warlock.js/web/add-web-to-an-app/SKILL.md): Install the SSR page layer with `warlock add web`: add React/Vite peers, scaffold `src/web/root.tsx` and `src/web/home.page.tsx`, register `webConnector()`, and safely relocate the stock top-level `GET "/"` JSON route to `/welcome`. Triggers: `warlock add web`, `webConnector`, `src/web/root.tsx`, `src/web/home.page.tsx`, `GET "/welcome"`; "add web to an app", "install Warlock web", "scaffold SSR", "homepage route collision". Skip: author a page — `@warlock.js/web/create-a-page/SKILL.md`; customize the document — `@warlock.js/web/write-the-root/SKILL.md`; dev/build/start commands — `@warlock.js/core/run-app/SKILL.md`; competing installers `create-next-app`, `vite create`, `remix init`.
-- [create-a-page](@warlock.js/web/create-a-page/SKILL.md): Create an SSR React page under `src/web/**` or `src/app/<module>/web/**` with a literal `route`, a default component, an optional typed `loader`, and page `metadata`. Triggers: `*.page.tsx`, `route`, `PageLoader`, `PageProps`, `PageMetadata`; "create a page", "add an SSR route", "make a React page", "type page loader data"; typical import `import type { PageLoader, PageProps } from "@warlock.js/web"`. Skip: root document shell — `@warlock.js/web/write-the-root/SKILL.md`; layout wrappers and prefixes — `@warlock.js/web/use-layouts/SKILL.md`; loader lifecycle and `shared` — `@warlock.js/web/load-page-data/SKILL.md`; competing frameworks `next`, `remix`, `react-router` file routes.
-- [load-page-data](@warlock.js/web/load-page-data/SKILL.md): Load App, Layout, and Page data with `AppLoader`, `LayoutLoader`, and `PageLoader`; type component `data`, validate page input, short-circuit with the buffered response, and publish request-scoped browser-safe values through `shared`. Triggers: `PageLoader`, `LayoutLoader`, `AppLoader`, `PageProps`, `shared`, `useShared`, `validation`, `request.validated`; "load page data", "pass server data to React", "share request data", "redirect from a loader". Skip: page module basics — `@warlock.js/web/create-a-page/SKILL.md`; layouts — `@warlock.js/web/use-layouts/SKILL.md`; mutation follow-up — `@warlock.js/web/navigate-on-the-client/SKILL.md`; competing loaders Next data functions, Remix loaders, React Server Components.
+- [create-a-page](@warlock.js/web/create-a-page/SKILL.md): Create an SSR React page under `src/web/**`, with either a literal `route` or a filesystem-derived one, a default component, an optional typed `loader`, page `metadata`, the `error.page.tsx` boundary, and the universal `register()` hook. Triggers: `*.page.tsx`, `route`, `PageLoader`, `PageProps`, `PageMetadata`, `error.page.tsx`, `register`, `[...slug]`; "create a page", "add an SSR route", "make a React page", "type page loader data", "add an error boundary", "catch-all route", "page renders blank 200", "page has no default export"; typical import `import type { PageLoader, PageProps } from "@warlock.js/web"`. Skip: root document shell — `@warlock.js/web/write-the-root/SKILL.md`; layout wrappers and prefixes — `@warlock.js/web/use-layouts/SKILL.md`; loader lifecycle and `shared` — `@warlock.js/web/load-page-data/SKILL.md`; competing frameworks `next`, `remix`, `react-router` file routes.
+- [load-page-data](@warlock.js/web/load-page-data/SKILL.md): Load App, Layout, and Page data with `AppLoader`, `LayoutLoader`, and `PageLoader`; type component `data`, validate page input, short-circuit with the buffered response, and publish request-scoped browser-safe values through `shared`. Triggers: `PageLoader`, `LayoutLoader`, `AppLoader`, `PageProps`, `shared`, `useShared`, `validation`, `request.validated`, `process.env`, `env("PUBLIC_...")`, `import.meta.env.PUBLIC_`; "load page data", "pass server data to React", "share request data", "redirect from a loader", "read an environment variable in a page", "process.env refused in the client build", "loader execution order", "return a Response from a loader". Skip: page module basics — `@warlock.js/web/create-a-page/SKILL.md`; layouts — `@warlock.js/web/use-layouts/SKILL.md`; mutation follow-up — `@warlock.js/web/navigate-on-the-client/SKILL.md`; competing loaders Next data functions, Remix loaders, React Server Components.
 - [navigate-on-the-client](@warlock.js/web/navigate-on-the-client/SKILL.md): Navigate hydrated pages with `<Link>`, resolve named URLs with `href()`, use `navigateTo` / `navigateBack`, prefetch on interaction, inspect the server match with `currentRoute()`, and re-fetch loaders after a mutation with `refresh()`. Triggers: `Link`, `href`, `navigateTo`, `navigateBack`, `refresh`, `currentRoute`, `previousRoute`; "navigate without a reload", "link to a named route", "refresh page data", "revalidate loaders", "client-side back"; typical import `import { Link, refresh } from "@warlock.js/web"`. Skip: define a page route — `@warlock.js/web/create-a-page/SKILL.md`; loader mechanics — `@warlock.js/web/load-page-data/SKILL.md`; root hydration boundary — `@warlock.js/web/write-the-root/SKILL.md`; competing routers `@mongez/react-router`, `react-router-dom`, Next navigation.
 - [serve-styles](@warlock.js/web/serve-styles/SKILL.md): Serve CSS imported by `root.tsx` or `*.page.tsx`, with render-blocking `<link rel="stylesheet">` delivery from Vite source URLs in development and Vite manifest assets in production. Triggers: `import "./app.css"`, page CSS, `?direct`, `manifest.json`, stylesheet flash, FOUC, `<head>`; "add global styles", "style a page", "CSS missing in SSR", "page flashes unstyled", "serve CSS in production". Skip: root document markup — `@warlock.js/web/write-the-root/SKILL.md`; page authoring — `@warlock.js/web/create-a-page/SKILL.md`; client navigation — `@warlock.js/web/navigate-on-the-client/SKILL.md`; competing styling systems CSS-in-JS, Next CSS, styled-components.
 - [use-layouts](@warlock.js/web/use-layouts/SKILL.md): Wrap pages with positional `layout.tsx` modules, compose literal `prefix` exports, load typed layout data with `LayoutLoader` / `LayoutProps`, and preserve layout state during client navigation. Triggers: `layout.tsx`, `prefix`, `LayoutLoader`, `LayoutProps`, `children`; "add a page layout", "share navigation between pages", "prefix page routes", "keep a layout mounted". Skip: full-document root — `@warlock.js/web/write-the-root/SKILL.md`; page route export — `@warlock.js/web/create-a-page/SKILL.md`; loader and shared lifecycle — `@warlock.js/web/load-page-data/SKILL.md`; competing layout systems `next/layout`, React Router outlets, Remix nested routes.

package/package.json

@@ -11,8 +11,8 @@
   },
   "peerDependencies": {
     "@vitejs/plugin-react": "^5.2.0",
-    "@warlock.js/core": "5.0.2",
-    "@warlock.js/seal": "5.0.2",
+    "@warlock.js/core": "5.2.0",
+    "@warlock.js/seal": "5.2.0",
     "react": "*",
     "react-dom": "*",
     "vite": ">=7.3.5 <8"
@@ -37,7 +37,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.0.2",
+  "version": "5.2.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/add-web-to-an-app/SKILL.md

@@ -10,7 +10,7 @@ description: 'Install the SSR page layer with `warlock add web`: add React/Vite
 ## The shape
 
 ```bash
-yarn warlock add web
+pnpm warlock add web
 ```
 
 On the ordinary path it leaves this application-owned shape:
@@ -81,8 +81,8 @@ On the refusal path, free `/` yourself and create a page with either `route = "/
 Read the files rather than assuming the command could patch every application shape:
 
 ```bash
-yarn warlock routes --method GET --path /
-yarn warlock routes --method GET --path /welcome
+pnpm warlock routes --method GET --path /
+pnpm warlock routes --method GET --path /welcome
 ```
 
 The desired result is one page route at `/` and, when the stock JSON route existed, one API route at `/welcome`.