@warlock.js/web 5.0.0

package/llms.txt

@@ -0,0 +1,21 @@
+# Warlock Web
+
+> 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.
+
+## 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.
+- [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.
+- [write-the-root](@warlock.js/web/write-the-root/SKILL.md): Author `src/web/root.tsx`, the full-document application root that owns `<html>`, `<head>`, and `<body>`, places page metadata with `<Head />`, renders the hydrated subtree inside `#root`, and emits the payload with `<Scripts />`. Triggers: `root.tsx`, `AppProps`, `AppLoader`, `Head`, `Scripts`, `id="root"`; "customize the root document", "add html lang", "add an app provider", "where do Head and Scripts go"; typical import `import { Head, Scripts, type AppProps } from "@warlock.js/web"`. Skip: page component contract — `@warlock.js/web/create-a-page/SKILL.md`; layout wrappers — `@warlock.js/web/use-layouts/SKILL.md`; CSS delivery — `@warlock.js/web/serve-styles/SKILL.md`; competing roots `next/layout`, Remix `root`, React `createRoot`.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@warlock.js/web",
+  "description": "Warlock.js web layer for the SSR page pipeline and client runtime.",
+  "warlock": {
+    "environment": "universal"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.7",
+    "@babel/types": "^7.29.7",
+    "magic-string": "^0.30.21"
+  },
+  "peerDependencies": {
+    "@vitejs/plugin-react": "^5.2.0",
+    "@warlock.js/core": "5.0.0",
+    "@warlock.js/seal": "5.0.0",
+    "react": "*",
+    "react-dom": "*",
+    "vite": ">=7.3.5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "@vitejs/plugin-react": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/web"
+  },
+  "keywords": [
+    "warlock",
+    "ssr",
+    "react",
+    "web"
+  ],
+  "author": "hassanzohdy",
+  "license": "MIT",
+  "version": "5.0.0",
+  "type": "module",
+  "main": "./esm/index.mjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      }
+    },
+    "./hydration": {
+      "import": {
+        "types": "./esm/hydration/index.d.mts",
+        "default": "./esm/hydration/index.mjs"
+      }
+    },
+    "./client/runtime": {
+      "import": {
+        "types": "./esm/client/runtime/index.d.mts",
+        "default": "./esm/client/runtime/index.mjs"
+      }
+    },
+    "./connector": {
+      "import": {
+        "types": "./esm/connector/index.d.mts",
+        "default": "./esm/connector/index.mjs"
+      }
+    },
+    "./vite": {
+      "import": {
+        "types": "./esm/vite/index.d.mts",
+        "default": "./esm/vite/index.mjs"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,103 @@
+---
+name: add-web-to-an-app
+description: '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`.'
+---
+
+# Warlock — add web to an app
+
+`warlock add web` turns an existing Warlock API application into an application that can also serve SSR React pages. It installs the web and React packages, adds the Vite development peers, scaffolds the smallest page layer, and registers the late-phase web connector.
+
+## The shape
+
+```bash
+yarn warlock add web
+```
+
+On the ordinary path it leaves this application-owned shape:
+
+```text
+src/
+  web/
+    root.tsx
+    home.page.tsx
+warlock.config.ts
+```
+
+The generated home page declares `route = "/"`. The generated root owns the document, renders `<Head />`, keeps `{children}` inside `#root`, and renders `<Scripts />`.
+
+## Connector registration
+
+The command adds `webConnector()` to `warlock.config.ts`. If the config cannot be patched safely, add the same wiring yourself:
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+import { webConnector } from "@warlock.js/web/connector";
+
+export default defineConfig({
+  connectors: [webConnector()],
+});
+```
+
+Keep the connector in `warlock.config.ts`. The build reads this same array to collect web's build contribution, while dev/start use it to boot the runtime. Registering it again from `src/app/main.ts` boots it twice and duplicates page routes.
+
+## What happens to an existing `GET "/"`
+
+The stock project template already owns `/` with a JSON welcome route. The page stub also owns `/`, and two `GET` handlers for one path fail at request time. The installer preserves both surfaces by changing the existing JSON route to `/welcome` before it writes the page.
+
+The automatic move is intentionally narrow. It only inspects:
+
+```text
+src/app/shared/routes.ts
+```
+
+and only rewrites exactly one top-level declaration shaped like this:
+
+```ts
+router.get("/", homePageController);
+```
+
+After the move:
+
+```ts
+router.get("/welcome", homePageController);
+```
+
+Indented `router.get("/", ...)` declarations inside a prefixed group are not root collisions and are not touched.
+
+## Collision outcomes
+
+- No `src/app/shared/routes.ts`, or no top-level `GET "/"`: create the root page normally.
+- Exactly one recognized top-level `GET "/"` and no top-level `GET "/welcome"`: move it to `/welcome`, then create the home page.
+- More than one top-level `GET "/"`, an existing top-level `GET "/welcome"`, an unreadable/unwritable routes file, or an unrecognized rewrite: create `root.tsx`, do not create `home.page.tsx`, set a failing exit code, and still register the connector.
+
+On the refusal path, free `/` yourself and create a page with either `route = "/"` or another literal route.
+
+## Re-running the command
+
+`src/web/root.tsx` is the scaffold sentinel. If it already exists, the command skips the `src/web` scaffold rather than overwriting a human-owned root. Connector registration is independently idempotent: if the config already mentions `webConnector`, it is left alone.
+
+## Verify the result
+
+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
+```
+
+The desired result is one page route at `/` and, when the stock JSON route existed, one API route at `/welcome`.
+
+## Gotchas
+
+- **The collision scan is not codebase-wide.** A root route declared outside `src/app/shared/routes.ts` is not moved. Check `warlock routes` after installation.
+- **`/welcome` must be free before relocation.** The installer refuses to trade one duplicate route for another.
+- **A partial scaffold exits non-zero.** `root.tsx` and connector registration may still have been written; complete only the missing home page after resolving the collision.
+- **Do not register the connector twice.** Use `warlock.config.ts`, not an additional `connectorsManager.register(...)` call.
+- **Do not import the hydration entry.** The connector and build contribution own it.
+
+## See also
+
+- [`create-a-page/SKILL.md`](../create-a-page/SKILL.md) — write the page after installation.
+- [`write-the-root/SKILL.md`](../write-the-root/SKILL.md) — customize the generated document shell.
+- [`serve-styles/SKILL.md`](../serve-styles/SKILL.md) — add global CSS from the root.
+- [`@warlock.js/core/run-app/SKILL.md`](@warlock.js/core/run-app/SKILL.md) — run dev, build, and production.

package/skills/create-a-page/SKILL.md

@@ -0,0 +1,141 @@
+---
+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.'
+---
+
+# 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.
+
+## The shape
+
+```tsx title="src/app/products/web/product-details.page.tsx"
+import type { PageLoader, PageMetadata, PageProps } from "@warlock.js/web";
+
+export const route = {
+  path: "/products/:id",
+  name: "products.details",
+} as const;
+
+export const loader = (async ({ request, response }) => {
+  const id = request.input("id");
+
+  response.header("cache-control", "private, max-age=60");
+
+  return {
+    product: {
+      id,
+      name: `Product ${id}`,
+    },
+  };
+}) satisfies PageLoader<undefined, typeof route>;
+
+export const metadata: PageMetadata<typeof loader> = ({ data }) => ({
+  title: data.product.name,
+  description: `Details for ${data.product.name}`,
+});
+
+export default function ProductDetailsPage({ data }: PageProps<typeof loader>) {
+  return (
+    <main>
+      <h1>{data.product.name}</h1>
+      <p>Product id: {data.product.id}</p>
+    </main>
+  );
+}
+```
+
+Use `satisfies PageLoader`, not `: PageLoader`. `satisfies` checks the context contract while retaining the loader's concrete return type, which is how `PageProps<typeof loader>` knows the shape of `data`.
+
+## The minimum page
+
+```tsx title="src/web/contact.page.tsx"
+export const route = "/contact";
+
+export default function ContactPage() {
+  return (
+    <main>
+      <h1>Contact</h1>
+      <a href="mailto:support@example.com">support@example.com</a>
+    </main>
+  );
+}
+```
+
+The `route` export is required. Development skips a page without it; the production discovery pass refuses to build it.
+
+## Route declarations
+
+Use either a bare path or a literal object:
+
+```ts
+export const route = "/products";
+```
+
+```ts
+export const route = {
+  path: "/products/:id",
+  name: "products.details",
+} 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.
+
+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.
+
+## 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.
+
+Write two pages for an optional segment. Validate a constrained parameter in the page instead of putting a regex in its path.
+
+## Metadata
+
+`metadata` may be a static object or a function of the resolved loader data and readonly `shared` payload:
+
+```tsx
+import type { PageMetadata } from "@warlock.js/web";
+
+export const metadata: PageMetadata = {
+  title: "Products",
+  description: "Browse the product catalogue",
+  robots: "index,follow",
+  openGraph: {
+    type: "website",
+    image: "/images/catalogue-card.png",
+  },
+};
+```
+
+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 client boundary
+
+The browser boundary is decided by the import graph, not by the file's location. A `*.page.tsx` is universal:
+
+- `route`, `middleware`, `validation`, `loader`, and `metadata` are stripped from the client projection.
+- The default component and any other surviving exports form the client graph.
+- An import used only by a stripped server export is removed with it.
+- An import also used by the component survives and therefore must be browser-safe.
+
+Keep server-only repository and service reads inside `loader`. Do not read them from module-scope initializers or the default component.
+
+## Gotchas
+
+- **Do not derive URLs from filenames.** The file chooses discovery; `route` chooses the public URL.
+- **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.
+- **A default component is synchronous.** Fetch in the loader, then render its result.
+- **There are no server actions.** Mutations remain ordinary API requests; call `refresh()` after a successful mutation.
+- **Do not import the hydration entry.** `esm/hydration/index.mjs` is a framework build input, not a consumer API. The public low-level runtime subpath is `@warlock.js/web/client/runtime`.
+
+## See also
+
+- [`load-page-data/SKILL.md`](../load-page-data/SKILL.md) — validation, loader context, response short-circuits, and `shared`.
+- [`use-layouts/SKILL.md`](../use-layouts/SKILL.md) — positional layouts, prefixes, and persistence.
+- [`navigate-on-the-client/SKILL.md`](../navigate-on-the-client/SKILL.md) — `Link`, `href`, navigation, and `refresh()`.
+- [`serve-styles/SKILL.md`](../serve-styles/SKILL.md) — CSS imports in page and root modules.

package/skills/load-page-data/SKILL.md

@@ -0,0 +1,183 @@
+---
+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.'
+---
+
+# 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.
+
+## The shape
+
+```tsx title="src/app/products/web/product-details.page.tsx"
+import { v } from "@warlock.js/seal";
+import type { PageLoader, PageProps } from "@warlock.js/web";
+
+export const route = {
+  path: "/products/:id",
+  name: "products.details",
+} as const;
+
+export const validation = {
+  schema: v.object({
+    id: v.string().minLength(2),
+  }),
+  validating: ["params"],
+} as const;
+
+export const loader = (async ({ request, response, shared }) => {
+  const { id } = request.validated();
+
+  if (id === "missing") {
+    return response.notFound();
+  }
+
+  response.header("cache-control", "private, max-age=60");
+
+  return {
+    product: {
+      id,
+      name: `Product ${id}`,
+    },
+    locale: (shared as { locale?: string }).locale ?? "en",
+  };
+}) satisfies PageLoader<typeof validation, typeof route>;
+
+export default function ProductDetailsPage({ data }: PageProps<typeof loader>) {
+  return (
+    <article lang={data.locale}>
+      <h1>{data.product.name}</h1>
+    </article>
+  );
+}
+```
+
+`LoaderShortCircuit` values from `notFound()` and redirects are excluded from `PageProps["data"]`, so the component sees only the successful loader return.
+
+## Three loader levels
+
+| 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>` |
+
+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()`.
+
+## Validation
+
+A page's `validation` export has:
+
+- `schema`: a Seal validator.
+- `validating`: any ordered subset of `"body"`, `"query"`, `"params"`, and `"headers"`.
+
+When `validating` is absent or empty, pages validate query + params, with params winning a duplicate key. Validation runs before loaders and a failure short-circuits with 422.
+
+`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`.
+
+## Loader response surface
+
+Each loader gets its own buffered response because App, Layout, and Page loaders execute in parallel. The public loader methods are:
+
+```ts
+response.header("cache-control", "private, max-age=60");
+response.setStatusCode(201);
+return response.redirect("/login");
+return response.permanentRedirect("/products");
+return response.notFound();
+```
+
+Do not continue after a redirect or `notFound`; return the result. Surviving buffers are committed root to leaf. For the same header key, the leafward write wins. A loader that throws or a lower level discarded by a short-circuit does not leak its buffered writes.
+
+## Declare the shared payload
+
+`SharedContext` ships empty and has no index signature. Augment it once with everything the browser is allowed to receive:
+
+```ts title="src/web/types.ts"
+declare module "@warlock.js/web" {
+  interface SharedContext {
+    locale: string;
+    user?: {
+      name: string;
+    };
+  }
+}
+
+export {};
+```
+
+Required keys need an unconditional middleware writer. Optional keys may be written conditionally:
+
+```tsx title="src/web/root.tsx"
+import { Head, Scripts, shared as writableShared } from "@warlock.js/web";
+import type { AppProps } from "@warlock.js/web";
+import "./types";
+
+const publishLocale = async () => {
+  writableShared.locale = "en";
+};
+
+export const middleware = [publishLocale];
+
+export default function App({ children, shared }: AppProps) {
+  return (
+    <html lang={shared.locale}>
+      <head>
+        <Head />
+      </head>
+      <body>
+        <div id="root">{children}</div>
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+
+## Shared lifecycle
+
+`shared` looks global but resolves through the current request's store on every access. Two requests never share its target.
+
+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.
+4. Components receive a readonly snapshot through props or `useShared()`.
+
+Use `useShared()` in a deep component that is not already receiving level props:
+
+```tsx title="src/web/components/locale-label.tsx"
+import { useShared } from "@warlock.js/web";
+
+export function LocaleLabel() {
+  const shared = useShared();
+
+  return <span>Locale: {shared.locale}</span>;
+}
+```
+
+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
+
+- App, Layout, and Page loaders cannot read each other's return values.
+- 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.
+
+## Gotchas
+
+- **Use `satisfies`, not a type annotation.** Preserve the return type for component props.
+- **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.
+- **Server actions are not supported.** POST to an ordinary Warlock API route and call `refresh()` after success.
+
+## See also
+
+- [`create-a-page/SKILL.md`](../create-a-page/SKILL.md) — the complete page module.
+- [`write-the-root/SKILL.md`](../write-the-root/SKILL.md) — `AppLoader`, `<Head />`, and `<Scripts />`.
+- [`use-layouts/SKILL.md`](../use-layouts/SKILL.md) — `LayoutLoader` and persistent wrappers.
+- [`navigate-on-the-client/SKILL.md`](../navigate-on-the-client/SKILL.md) — re-fetch loaders with `refresh()`.