netjes 0.0.2 → 0.0.4

package/skills/netjes/references/data-and-actions.md

@@ -19,6 +19,7 @@ app.MapPageLoader("/projects/[id]", async (string id, ClaimsPrincipal user, AppD
 - It binds like a minimal API: route values by name, services, `ClaimsPrincipal`, `HttpContext`, `CancellationToken`, `[FromQuery]`.
 - It reads no request body, so a complex type that is not a registered service needs `[AsParameters]` or a static `BindAsync`. A loader or action whose parameters minimal APIs cannot bind stops the app at startup, saying which and why. So does a loader parameter that reads the body (`[FromBody]`, `[FromForm]`, `IFormFile`): posted data belongs in a page action or a server action. A page loader stops the app too for a type that adds accepts metadata (`IAcceptsMetadata`) for itself, and must not get `.Accepts<T>()`: routing would match the page only for requests with that Content-Type, and navigations would get the not-found page. Repeated query values bind to an array (`int[] ids`); `List<int>` and `IEnumerable<int>` stop the app at startup, the latter because minimal APIs would bind it from services.
 - `Page.Props(record)` names the props type for `pages['/projects/[id]']`. `Page.NotFound()`, `Page.Forbidden()`, `Page.Unauthorized()` render the nearest boundary file; `Page.Redirect(url)` and `Page.LocalRedirect(returnUrl)` (for URLs from the request) redirect, and the client router follows them. `.WithStatus(422)` changes the status.
+- A link to one of the app's pages is a `Href` in the props record (`public sealed record NavLink(Href Href, string Label)`, `new Href($"/projects/{Uri.EscapeDataString(id)}")`, with each value encoded), root-relative, in the page file's spelling (the props parse compares literal segments with their case, so `/About` fails for `app/about/page.tsx`) and without the base path. It is generated as the `Href` schema, so the props parse checks it against the pages and the component passes it to `<Link href>` as it is. `new Href(url)` throws `ArgumentException` unless the URL starts with `/` (and not `//` or `/\`), `?`, `#`, `http:`, `https:`, `mailto:` or `tel:`, and also for a control character anywhere in it or a space at either end; `Href.TryCreate` returns false instead. C# checks only that shape: a root-relative `Href` that no page serves fails the whole props parse and the page shows its error boundary (a 500 from the server only when no Suspense boundary, such as a `loading.tsx`, is above the component that parses; otherwise the server sends that boundary's fallback with the loader's status), so a link to an endpoint or a file, such as `/llms.txt`, stays a `string`, rendered with `useHref`, and so does a link from a CMS, checked with `isHref` where it is rendered. No query or route value binds to an `Href`: a `returnUrl` stays a `string` for `Page.LocalRedirect`, and a `[FromForm]` input takes a `string`, since form binding reads no `Href` from the field of its name. `LinkGenerator`'s `HttpContext` overloads add the base path, so pass `pathBase: PathString.Empty`.
 - It returns a `RouteHandlerBuilder`: `.RequireAuthorization()`, `.CachePage(...)` and filters apply.
 - A page's loader runs before its layouts' loaders, so a page under a layout that checks access checks it too.
 
@@ -67,14 +68,18 @@ const nameError = state?.ok === false ? state.errors.name?.[0] : undefined;
 
 - Results: `ServerAction.Ok(result)` or `Ok()`, `Invalid(field, message)` or `Invalid(errors)` (422), `Redirect(url)`, `Forbidden()`, `NotFound()`. Chain `.Revalidate(tags)` and `.RevalidatePath(paths)` (evict output-cached pages and refresh the page), `.Refresh()`, `.Invalidate(queryKey)` and `.WithQuery(queryKey, data)` (TanStack Query on the client).
 - `[FromForm]` inputs make the form work without JavaScript: the browser posts, a success redirects back, a failure renders the page again with the errors and the typed values. Keep that working.
-- An input without `[FromForm]` binds JSON: `await serverActions['posts.like']({ slug })` resolves to `{ ok: true, result }` or `{ ok: false, errors }`; server failures throw to the nearest error boundary.
+- An input without `[FromForm]` binds JSON: `await serverActions['posts.like']({ slug })` resolves to `{ ok: true, result }` or `{ ok: false, errors }`; server failures throw a `ServerActionError` (`status`, and `withheld` when the server sent no message, as for a 5xx with error details off) to the nearest error boundary.
 - Validation: DataAnnotations (`[Required]`, `[StringLength]`, `[Range]`, `[EmailAddress]`) and `IValidatableObject` on an action's input are checked before the action runs (for a polymorphic JSON input, those of the `[JsonDerivedType]` the call sends). Failures come back as field errors (422, `state.errors`), also without JavaScript, and the action is not called. This needs no setup: `builder.Services.AddValidation()` is for your other minimal API endpoints, not for `MapAction` or `MapPageAction`. An attribute that cannot be read, such as a `[Display]` whose resource type has no such name, stops the app at startup, also on a derived type a JSON input lists with `[JsonDerivedType]`. A `[FromForm]` input is never `null` (unless declared nullable): a post with none of its fields, such as a form of unchecked checkboxes, gets an empty input, checked like any other. Give form inputs `init` properties, as above, not constructor parameters: a field the post leaves out (an unchecked checkbox, a list with nothing chosen) keeps its default, while form binding refuses such a post (400) for a positional record. A form input, and each type its properties and lists hold, needs exactly one public constructor: form binding never builds a type with several or none, or an abstract class or an interface, so that stops the app at startup. Bind a checkbox group or a list as a property of the input type (`public string[] Tags { get; init; } = [];`), not as a top-level `[FromForm]` parameter: a top-level list or dictionary reads fields named `[0]` or `[key]`, not its own name, and is `null` when none is posted.
 - Optimistic UI: `useAction(action, { onSubmit(formData) { setOptimistic(...) } })` with React's `useOptimistic`.
 - Every action needs `app.UseAntiforgery()` (after authentication) and checks the origin; `<Form>` and `serverActions` send the token. `MapAction` bodies are limited to 1 MB (`ActionBodySizeLimit`); an upload action sets `[RequestSizeLimit(bytes)]`. Page actions keep the server's limit.
-- Name actions `feature.verb`. Check authorization inside the action, or with `.RequireAuthorization()`, as for any endpoint.
+- Name actions `feature.verb`. Names are compared ignoring case, and a second `MapAction` of a name, the app's or a page package's, stops the app at startup. Every action answers at `/_netjes/actions/{name}`, so `MapAction` in a `MapGroup` with a prefix throws; map it on the app, or on `MapGroup("")` for shared conventions. Check authorization inside the action, or with `.RequireAuthorization()`, as for any endpoint.
 - `app.MapPageAction("/guestbook", ...)` is the other kind: a POST to the page's own URL from `<Form method="post">`, fields typed in `forms['/guestbook']`. Its input's DataAnnotations and `IValidatableObject` are checked as for `MapAction`: on a failure the delegate does not run, the page renders again from its loader (422), and `const failed = usePageActionState()` gives `failed.errors` and `failed.values` (null otherwise). Checks that need data stay in the delegate: return `Page.Props(...)` with your own errors and the typed values (`.WithStatus(422)`), or `Page.Redirect(...)` after a change.
 - An action or post that sets or deletes a cookie (signing in or out) makes the client router forget the pages it keeps for back and forward, reload the page on screen and clear the query cache, in every tab of the app in that browser. Nothing to do in the action; a proxy must pass `X-Netjes-Cookies` through.
 
+## Page packages
+
+A mounted page package's loaders, layout loaders, actions and endpoints are mapped by the package's extension, through its mount, and typed in the package's own generated file, not in the app's. The app's `generated/netjes.ts` routes the package's pages (`route('/help/contact')`) and holds only what the app maps itself; run `npx netjes generate` after updating a package. The app's `MapPageLoader`, `MapPageAction` and `MapLayoutLoader` refuse a package's page or layout, naming the mount. A page the app replaces with `.Override` renders with the package's loader, so it reads its props from the package's file: `definePage(pages['/contact'], ...)` with `pages` from `'@acme/help-center/generated'`. The app's own pages under the prefix, and their loaders, are the app's as before. Schemas both sides read by key, such as an export a package adds with `AddTypeScriptExport`, are in both files.
+
 ## JSON endpoints and TanStack Query
 
 ```csharp
@@ -83,16 +88,19 @@ app.MapGet("/api/projects/{slug}/stats", async Task<Results<Ok<ProjectStats>, No
 ```
 
 ```ts
-async function fetchStats(slug: string) {
-  const response = await fetch(`/api/projects/${encodeURIComponent(slug)}/stats`);
+async function fetchStats(url: string) {
+  const response = await fetch(url);
   if (!response.ok) throw new Error(`Stats request failed with ${response.status}`);
   return api['GET /api/projects/{slug}/stats'].response.parse(await response.json());
 }
-const stats = useQuery({ queryKey: ['projects', slug, 'stats'], queryFn: () => fetchStats(slug) });
+const url = useHref(endpointUrl('GET /api/projects/{slug}/stats', { slug }));
+const stats = useQuery({ queryKey: ['projects', slug, 'stats'], queryFn: () => fetchStats(url) });
 ```
 
-Typed results (`TypedResults`, `Results<...>`) give the endpoint its `api` schemas, keyed by method and route template. Seed the same query key from the loader with `.WithQuery(key, data)` and the query renders on the server with no fetch; keep the key in one place on each side. Seeded data is fresh for the default `staleTime` (one minute).
+Typed results (`TypedResults`, `Results<...>`) give the endpoint its `api` schemas, keyed by method and route template. `endpointUrl(key, params, search)` builds the URL of the app's endpoints that are not pages, JSON or not (a JSON endpoint has a key per method except `HEAD`, any other endpoint one for `GET`, if it answers `GET`), by the same key: the route values and the query values its handler binds are typed from C#, an enum as its C# names and values, and `search` adds others. It has no base path: `useHref` adds it, for a `fetch` or an `<a href>`. Its result is a `string`, which the type of `<Link href>` does not accept, as an endpoint is not a page: link it with `<a href={useHref(endpointUrl(...))}>`. Seed the same query key from the loader with `.WithQuery(key, data)` and the query renders on the server with no fetch; keep the key in one place on each side. Seeded data is fresh for the default `staleTime` (one minute).
+
+`MapGet` answers `GET` only: a `HEAD` to its URL goes to whatever else matches it, often the not-found page. For an endpoint that crawlers, link checkers or monitors ask with `HEAD`, map `app.MapMethods(pattern, [HttpMethods.Get, HttpMethods.Head], handler)`; its `api` key stays `GET` and the route. Pages, `/sitemap.xml`, `/robots.txt`, `/_netjes/image` and the locale redirect answer `HEAD` already.
 
 ## More
 
-[Data loading](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/data-loading.md) and [Actions and forms](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/actions-and-forms.md) in the guides.
+[Data loading](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/data-loading.md), [Actions and forms](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/actions-and-forms.md) and [Page packages](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/page-packages.md) in the guides.

package/skills/netjes/references/deployment.md

@@ -7,13 +7,14 @@ A Netjes app is an ASP.NET Core app that also needs Node at runtime: the .NET pr
 ```bash
 npx netjes generate --check   # in CI: the generated types match the C# types
 npm test && npm run typecheck && dotnet build
+dotnet test tests/MyApp.Tests -c Release   # the C# tests, where the app has them; a plain dotnet test runs none
 dotnet publish -c Release -o bin/publish   # runs `npm run build`, ships dist/ (client, server bundle, sidecar)
 cd bin/publish && ASPNETCORE_ENVIRONMENT=Production dotnet MyApp.dll
 ```
 
 `npx netjes start` runs the app in Production from the source tree (or `--dll bin/publish/MyApp.dll`, which runs from the publish folder). In production the routes come from the built client manifest, so a page file that was not built does not exist.
 
-For these startup failures the app logs one critical entry, saying what is wrong and what to do, and exits with code 1: no build in Production (`npm run build`), a `node` it cannot start (`Netjes:NodeExecutable`), a sidecar script that is not installed or built (`npm install` in development, `npm run build` in production), or in development the Vite dev server's port taken, an error in `vite.config.ts` (with Vite's code frame) or a package it imports that is not installed (`npm install`). Under `WebApplicationFactory` the start throws that message instead. Other exceptions at startup, such as a route conflict, keep their stack.
+For these startup failures the app logs one critical entry, saying what is wrong and what to do, and exits with code 1: no build in Production (`npm run build`), a `node` it cannot start (`Netjes:NodeExecutable`), a sidecar script that is not installed or built (`npm install` in development, `npm run build` in production), or in development the Vite dev server's port taken, an error in `vite.config.ts` (with Vite's code frame) or a package it imports that is not installed (`npm install`). Under `WebApplicationFactory` the start throws that message instead. Other exceptions at startup, such as a route conflict, keep their stack. An exception that nothing catches, at startup or on a thread of the app's own, ends it as a .NET crash does: an abort, exit code 134 on Linux and macOS. ASP.NET Core catches a request's exceptions (a page's renders its `error.tsx`), and the host catches one from a `BackgroundService` and stops the app with exit code 0.
 
 ## Docker
 
@@ -21,6 +22,8 @@ For these startup failures the app logs one critical entry, saying what is wrong
 
 - `docker compose up`: development, with `dotnet watch` and Vite HMR, ports bound to localhost.
 - `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d`: the production image, a non-root user on a read-only filesystem, with a health check on `/healthz` and Data Protection keys in a named volume.
+- Both publish the app on host port 8080; `APP_PORT` (in the shell or a `.env` file) moves it. Vite's 5173 stays.
+- The production image runs `tini -s -- dotnet MyApp.dll`: tini is PID 1, passes `docker stop`'s SIGTERM on, and exits with the app's code, so a crash ends the container (134) and `restart: always` acts. When .NET itself is a container's PID 1, its abort does not end it. On arm64 it spins at 100% CPU and never exits; after a crash later than startup the rest of the app keeps serving and `/healthz` still passes. On x86-64 under emulation it has been seen to exit after a few seconds, with 139 instead of 134. An image of the app's own, or one from an older template, needs an init too: the template's `tini` stage, its `COPY` and the `ENTRYPOINT`, or the host's (`docker run --init`, Compose `init: true`, ECS `initProcessEnabled`).
 
 The image restores Netjes from NuGet and npm, so the app must reference the packages, as an app made with `npx netjes new` does (from a Netjes checkout, pass `--packages`).
 
@@ -31,9 +34,10 @@ The image restores Netjes from NuGet and npm, so the app must reference the pack
 - Data Protection keys sign antiforgery tokens and draft-mode cookies: keep them across restarts (the production compose file mounts a volume) and share them between instances.
 - Several instances behind a load balancer also share the output-cache store and need the same `Netjes:SegmentKeySecret` (32 bytes or more).
 - `Netjes:SidecarProcesses`: Node processes rendering in production (default 1; about one per core for CPU-heavy pages).
-- If no sidecar is ready (they crashed and are restarting), documents are sent for the browser to render instead of failing (`ClientRenderFallback`, on by default), and `/healthz` reports Unhealthy. Register the check with `builder.Services.AddHealthChecks().AddNetjes()` and `app.MapHealthChecks("/healthz")`.
+- If no sidecar is ready (they crashed or stopped answering, and are restarting), documents are sent for the browser to render instead of failing (`ClientRenderFallback`, on by default), and `/healthz` reports Unhealthy. Register the check with `builder.Services.AddHealthChecks().AddNetjes()` and `app.MapHealthChecks("/healthz")`.
+- The app restarts its Node processes itself: one that exits, and in production one that answers no health ping within `RenderTimeout` (at least 5 s). A restart policy on the container's exit (`restart: always`) is all the host needs. A custom `Netjes:SidecarScript` must answer `GET /health`, with any status, without reading a request body.
 - Output caching: set `SizeLimit`, and see [caching-and-streaming.md](caching-and-streaming.md).
-- Security headers: every document gets `X-Content-Type-Options`, `Referrer-Policy` and a same-origin framing policy unless the app sets them (`Netjes:SecurityHeaders`). A Content-Security-Policy is off until you set `NetjesOptions.ContentSecurityPolicy`, with `{nonce}` for a nonce-based policy.
+- Security headers: every response through `UseNetjes()` gets `X-Content-Type-Options: nosniff`, so every response needs its real `Content-Type`: a script or stylesheet with a wrong one or none is refused, and a page that an endpoint writes with `Response.WriteAsync` shows as plain text unless the endpoint sets `Response.ContentType = "text/html; charset=utf-8"` first. Every document also gets `Referrer-Policy` and a same-origin framing policy, or the `X-Frame-Options` that the policy's `frame-ancestors` implies, unless the app sets them (`Netjes:SecurityHeaders`). A Content-Security-Policy is off until you set `NetjesOptions.ContentSecurityPolicy`: with `{nonce}` for a nonce-based policy, or without it, with `NetjesContentSecurityPolicy.ScriptHashes` in its `script-src`, for a hash-based one, which output-cached pages need ([caching-and-streaming.md](caching-and-streaming.md)).
 - `Netjes:PublicConfig` is sent to the browser as is; secrets go in other configuration.
 - Telemetry: add the `Netjes` ActivitySource and Meter (`NetjesTelemetry.Name`) to OpenTelemetry for loader, action and render spans and render durations.
 

package/skills/netjes/references/routing.md

@@ -7,11 +7,11 @@ ASP.NET Core does the routing: every page file becomes an endpoint with an ordin
 | File | Role |
 |---|---|
 | `page.tsx` | The page for its folder's URL. |
-| `layout.tsx` | Wraps every page below it and stays mounted across navigations (its state survives). The root `app/layout.tsx` imports the global stylesheet. |
+| `layout.tsx` | Wraps every page below it and stays mounted across navigations (its state survives). The root `app/layout.tsx` imports the global stylesheet. Netjes renders `<html>`, `<head>` and `<body>` around the root layout, with `suppressHydrationWarning` on `<html>` and `<body>`, so no layout renders them: the root one returns what goes inside `<body>`. |
 | `template.tsx` | Like a layout, but remounted on every navigation. |
 | `loading.tsx` | Suspense fallback, streamed first while the page below waits on deferred values or lazy code. |
-| `error.tsx` | Error boundary below its layout; props `{ error, reset }` (`ErrorPageProps`), status in `error.status`. In development `error.message` can take several lines (a syntax error's code frame): render it with `whitespace-pre-wrap`. |
-| `not-found.tsx` | Rendered for `Page.NotFound()` from a loader below it, and the root one for unknown URLs. |
+| `error.tsx` | Error boundary below its layout; props `{ error, reset }` (`ErrorPageProps`). `error.status` is the HTTP status of a server answer behind the error and is undefined for an error thrown in the browser, so show `error.status ?? 500`. Render `error.message` only when `!error.withheld`: `withheld` marks a stand-in for a message Netjes does not show (an exception's or a failed `Page.Defer` value's with error details off, a server action answer with no message, a thrown value that is neither an Error nor a string). `reset()` renders the segment again, or on an error page the server rendered loads the page again; on the page the router's own boundary shows it does nothing, so offer a link there too. In development `error.message` can take several lines (a syntax error's code frame): render it with `whitespace-pre-wrap`. |
+| `not-found.tsx` | Rendered for `Page.NotFound()` from a loader below it, and the root one for unknown URLs, except below a page package's mount, where the package's renders. |
 | `forbidden.tsx`, `unauthorized.tsx` | Rendered for `Page.Forbidden()` / `Page.Unauthorized()` and for empty 403/401 responses from authorization; without one, the error page renders. |
 | `global-error.tsx` | In `app/` only: rendered without any layout when even the error page fails. |
 
@@ -31,14 +31,25 @@ Built-in pages stand in for missing boundary files.
 
 A literal segment beats a dynamic one (`blog/new` over `blog/[slug]`), as in Next.js. Two page files of the same shape (`[lang]/about` and `[slug]/about`) stop the app at startup. There is no pages router: Next.js pages router files in `pages/` stop the app at startup, and the message says where each goes (`pages/about.js` to `app/about/page.jsx`, `pages/404.tsx` to `app/not-found.tsx`, `pages/_app.tsx` and `pages/_document.tsx` to the root `app/layout.tsx`, `pages/api/` routes to minimal API endpoints). There are no route handlers either: a `route.ts` in `app/` stops the app in development and fails `vite build`, and an API is a minimal API endpoint in C# (`app.MapGet`, `app.MapPost`).
 
+## One URL per page
+
+A page answers its file's spelling: a `GET` or `HEAD` for `/About` for `app/about/page.tsx` gets a 308 to `/about`, and a client navigation a redirect payload, so links and crawlers see one URL, and the output cache stores no other case that a browser sends (`RedirectLiteralCase`, on by default; `options.RedirectLiteralCase = false`, or `Netjes:RedirectLiteralCase=false`, answers every case). Other methods are answered as sent: a `POST` to `/About` is not redirected. Only literal segments change; route values (`/Blog/Hello` goes to `/blog/Hello`), the query and the base path stay as sent, so a loader that redirected to its own spelling of a literal can drop that check, while one that checks a slug's case keeps it. A trailing slash is answered as it is (`TrailingSlash.Ignore`); `options.TrailingSlash = TrailingSlash.Never` (`Netjes:TrailingSlash=Never`) sends `/about/` to `/about` and drops a catch-all's last slash. The `/robots.txt` and `/sitemap.xml` that `MapRobotsTxt` and `MapSitemap` serve follow both. `WebApplicationFactory` tests run on TestServer, which passes on no request target, so they see no redirect: check it end to end with Playwright, or set `IHttpRequestFeature.RawTarget` in a startup filter, as the testing guide shows.
+
 ## Loader parameters and route warnings
 
-Loaders bind like minimal APIs: a string or `TryParse` parameter takes the route value of the same name (any case), and otherwise the query string. `(string id)` on `/blog/[slug]` therefore reads `?id=`, never the slug, and `string[] path` on `[...path]` reads `?path=`. Netjes logs a warning for that at startup, and `npm run routes` prints it. Name parameters after the route segment, or mark query parameters `[FromQuery]`. The other warning is two pages that match the same URLs (`[id]` next to `[...rest]`); rename one, or accept it if the overlap is wanted.
+Loaders bind like minimal APIs: a string or `TryParse` parameter takes the route value of the same name (any case), and otherwise the query string. `(string id)` on `/blog/[slug]` therefore reads `?id=`, never the slug, and `string[] path` on `[...path]` reads `?path=`. Netjes logs a warning for that at startup, and `npm run routes` prints it. Name parameters after the route segment, or mark query parameters `[FromQuery]`. Another warning is two pages that match the same URLs (`[id]` next to `[...rest]`); rename one, or accept it if the overlap is wanted. Others are an endpoint of the app that ties with a page (below), and a `[FromForm]` positional record with a `bool`, `bool?` or list field, which form binding refuses (400) when the post leaves that field out, as for an unchecked box: give the input `init` properties instead.
+
+## Endpoints next to pages
+
+ASP.NET Core ranks the endpoints a URL matches by order (pages and `MapGet` endpoints have 0), then route precedence (a literal, a constrained parameter, a parameter, a constrained catch-all, then a catch-all), then HTTP methods, hosts and accepted content types, in that order. When two rank first together and both fit a request, it answers 500 (`AmbiguousMatchException`); Netjes warns about such an endpoint next to a page or a page action at startup and in `npm run routes`. A file next to a catch-all page, such as a Markdown copy of each docs page next to `app/docs/[...path]/page.tsx`, ranks the same as the page, so map it ahead of it and for HEAD as well: `app.MapMethods("/docs/{**path:regex(\\.md$)}", [HttpMethods.Get, HttpMethods.Head], ...).WithOrder(-1)`. Link it with `<a href={useHref(endpointUrl('GET /docs/{**path:regex(\\.md$)}', { path: 'routing.md' }))}>`, where `path` is the file's path as one string (on the docs page, `` `${path.join('/')}.md` `` from the catch-all's array); a bare `<a href>` misses the base path.
 
 ## Links and navigation
 
-- `<Link href={route('/blog/[slug]', { slug })}>`: client navigation with prefetch on hover and focus, `aria-current` on the active link. `route()` and the `Href` type come from `generated/netjes.ts`, so a wrong path or a missing parameter is a type error.
-- `useRouter()`: `push`, `replace`, `prefetch`, `refresh`, `back`, `forward`.
+- `<Link href={route('/blog/[slug]', { slug })}>`: client navigation with prefetch on hover and focus; takes a `ref`, as `<Form>`, `<SubmitButton>` and `<Image>` do. `route()` and the `Href` type come from `generated/netjes.ts`, so a wrong path or a missing parameter is a type error.
+- `route(pattern, params, search, { hash })` builds the query from `search` and a `#fragment` from `hash`, the id of an element on the page: `route('/docs/[...path]', { path }, undefined, { hash: 'keys' })`. Pass `undefined` as `search` for a link with a fragment and no query.
+- `aria-current="page"` goes on a link to the page on screen: the same path (`/x` and `/x/` are one) and the page's values for every query parameter the link names. Parameters it leaves out do not count, and a `#` link is never marked. Pass `aria-current` to decide yourself: `undefined` on an "All" filter (`/blog`) while a filter is on, `"true"` on a section link (Docs) below the section's page, from `useSelectedLayoutSegments()` or `usePathname()`.
+- `useRouter()`: `push`, `replace`, `prefetch`, `refresh`, `back`, `forward`. The promises of `push`, `replace` and `refresh` resolve once the router has handed the page to React, when the old page can still be on screen; code that needs the new page runs in an effect of that page, or in one that depends on `usePathname()` and `useSearchParams()`.
+- After a navigation to another page the router announces it in a polite live region (its title, else its first `h1`, else its path) and starts the focus over at the top of the document. A link to a `#fragment`, on the page on screen or on another, moves the focus to that element instead, which is how the skip link works; Back and Forward restore the scroll position and give a fragment no focus. The region speaks only when the name differs from the previous page's, so give each page its own title, and keep the skip link the first thing in the root layout that takes the focus: `<Link href="#content" prefetch="none" className="sr-only focus:not-sr-only">Skip to content</Link>` and `<main id="content">`. The focus stays on the same page (query changes, refreshes, a post that stays, a modal), on an `autoFocus` element or wherever the app's code moved it during the navigation (a link's `onClick` and a form's `onSubmit` included), on a `scroll={false}` link that still has it, and in a field the user types into. To put it elsewhere on the new page, do it in that page's `useEffect`, which runs after the router's. If a menu closes in an effect after the navigation, give the focus back to its button only while the focus is still inside the menu. In end-to-end tests, focus a field before typing after a navigation (`locator.fill()` does), and read the element you mean rather than a container's whole text.
 - `usePathname()`, `useSearchParams(schema?)`, `useParams(schema?)`: with a schema the values are parsed; catch-all params are arrays. Search values a schema rejects are dropped so its defaults apply; a rejected route param goes to the error page, so constrain route params in C#.
 - `useSelectedLayoutSegment()`, `useSelectedLayoutSegments()`: the active child segment in a layout (tabs).
 - `useNavigation()`: `idle`, `loading` or `submitting`, for progress indicators.
@@ -46,20 +57,32 @@ Loaders bind like minimal APIs: a string or `TryParse` parameter takes the route
 
 ## Metadata
 
-- `export const metadata: Metadata = { title: 'About' }` on pages and layouts; a layout's `title: { default, template: '%s · Site' }` applies to the pages below it.
+- `export const metadata: Metadata = { title: 'About' }` on pages and layouts; a layout's `title: { default, template: '%s · Site' }` applies to the pages below it. A `default` below the root goes through the nearest template above it, like a string (`'Docs'` under `'%s · Site'` is `Docs · Site`), never through the one beside it; `{ absolute: 'Docs' }` skips every template.
 - From C#: `.WithMetadata(new PageMetadata { Title = post.Title, Description = ... })` on the loader's result, merged over the files' metadata.
 - Below a layout that sets a title, use `metadata`, not a `<title>` element (that makes a second title).
+- Code the first paint needs, such as a theme set on `<html>`, goes in `<Script id="theme" strategy="beforeInteractive">{code}</Script>` first in the root layout (a script takes no focus, so the skip link after it stays first): the server writes inline code where it stands and the parser runs it there. An external `beforeInteractive` script runs once the shell is parsed, in order, before the page's code; hydration waits for it, and inline code runs before it. That holds in a server-rendered document: a component that mounts in the browser, after a client navigation or when no sidecar was ready, adds its script after mounting, as `afterInteractive` does. Keep them outside Suspense boundaries. Under a hash-based policy, list the hash of the code as the document carries it, which `inlineScriptHashes` from `netjes/testing` gives, and an external script's origin in `script-src`.
 
 ## Protecting sections
 
-`app.MapLayoutLoader("/dashboard", ...).RequireAuthorization()` protects every page below `app/dashboard/`; `app.MapPages().RequireAuthorization()` protects every page that has no loader of its own; a page loader takes `.RequireAuthorization()` itself. With cookie authentication, answer 401/403 instead of redirecting (`OnRedirectToLogin`, `OnRedirectToAccessDenied`) so `unauthorized.tsx` and `forbidden.tsx` render.
+`app.MapLayoutLoader("/dashboard", ...).RequireAuthorization()` protects every page below `app/dashboard/`; `app.MapPages().RequireAuthorization()` protects every page that has no loader of its own; a page loader takes `.RequireAuthorization()` itself. With cookie authentication, answer 401/403 instead of redirecting (`OnRedirectToLogin`, `OnRedirectToAccessDenied`) so `unauthorized.tsx` and `forbidden.tsx` render. `MapPages()`'s conventions never challenge an unknown URL, which stays a 404; a fallback policy covers the not-found fallback too, and challenges a visitor it refuses there. The not-found page, like the status and error pages of server actions and minimal APIs and a page's 401, 403 and pre-authorization status pages (a rate limiter's 429), runs a layout loader only for a visitor the pages in its folder would let in (its conventions and those above it, which pages with a loader carry too, and for file pages `MapPages()`'s or the fallback policy), and renders inside the layouts above it for the rest. So under `MapPages().RequireAuthorization()` the root `unauthorized.tsx` renders without the root layout when that has a loader: make it stand on its own, and never put `.AllowAnonymous()` on a layout loader to keep it, since that opens every page below. `Page.Render(pattern)` from a minimal API runs the page's layout loaders under that endpoint's authorization: protect it as the page is.
 
 A check that depends on data (is this user a member of this project?) goes in the page loader as well as in the layout loader: a page's loader runs before its layouts' loaders, and a layout loader is skipped on client navigations within its section while its own route values, the user and the roles stay the same. A layout loader also binds only the route values of its own URL, so it cannot check a deeper one.
 
+## Page packages
+
+A page package is an npm package and a NuGet package of one version that bring pages, layouts, boundaries, loaders and actions. The app mounts it with the package's extension, before `app.MapPages()`, and lists the npm half in `netjes({ packages: ['@acme/help-center'] })`; both halves are installed at one version, or the app stops at startup in one line that says what to install.
+
+- The prefix is in folder syntax: `/help`, `/(marketing)/help` (the same URL, inside `app/(marketing)/layout.tsx`), `/[tenant]/help` (`tenant` is a route value). The package's folder of pages merges into `app/` under it, folder by folder: its `layout.tsx` at the mount wraps the app's own pages in `app/help/`, and its `(center)` group wraps an app page in `app/help/(center)/`. Link to its pages with the app's `route('/help/articles/[slug]', { slug })`.
+- An app page of the same shape as a package's page stops the app. To replace the package's page, put the app's in the same folder and add `.Override("/help/contact")` to the mount: it renders with the package's loader, so it reads `pages['/contact']` from the package's generated file (`import { pages } from '@acme/help-center/generated'`), and the app maps no loader for it. Layouts and boundaries cannot be replaced.
+- Conventions on the mount (`.RequireAuthorization()`, `.ExcludeFromExport()`, `.ExcludeFromSitemap()`) cover the package's pages and endpoints, not the app's pages under the prefix; protect those with a layout loader above them, as before. An app layout loader above the mount protects the package's pages too.
+- An unknown URL below the mount renders the package's `not-found.tsx`, after the layout loaders on the way, and `MapPages()`'s authorization, have authorized the visitor.
+- A package that draws its own shell (a back-office package) should not render inside the site's header: keep `app/layout.tsx` to providers and the skip link, and move the site's header and footer into `app/(site)/layout.tsx` with the site's pages. URLs do not change. The `package-shell` route warning names an app that has not.
+- Route warnings for packages: `package-shell`, `package-unmounted` (in the build but not mounted), `package-nonce` (a package whose pages stream, under a Content-Security-Policy without a nonce), and `overlap` for a literal page of one source next to a parameter page of the other (`/help/settings` from the package next to the app's `app/help/[section]`).
+
 ## Base path and locales
 
 `app.UsePathBase("/docs")` with `netjes({ basePath: '/docs' })`; links, forms and redirects add it, and app code is written as if at the root (`useHref(path)` for a plain `<a>`). Locale routing is a `[lang]` folder with `AddNetjesLocalization`, `UseNetjesLocalization` and `MapLocaleRedirect`; `useLocale()` reads it.
 
 ## More
 
-[Routing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/routing.md) and [Metadata](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/metadata.md) in the guides, and the [React API](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/react-api.md) for every component and hook.
+[Routing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/routing.md), [Page packages](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/page-packages.md) and [Metadata](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/metadata.md) in the guides, and the [React API](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/react-api.md) for every component and hook.

package/skills/netjes/references/testing.md

@@ -4,7 +4,7 @@ Test first: write the test, watch it fail for the reason you expect, then change
 
 ## Components and pages: Vitest
 
-`netjes()` in `vite.config.ts` sets up Vitest: jsdom, Testing Library cleanup, and `e2e/`, `dist/`, `bin/` and `obj/` excluded. Tests sit next to the code as `*.test.tsx` and run with `npm test`.
+`netjes()` in `vite.config.ts` sets up Vitest: jsdom, Testing Library cleanup (a config with `setupFiles` of its own lists `netjes/testing/setup` in them), `e2e/`, `dist/`, `bin/` and `obj/` excluded, and in every app a setup file of Netjes's own, which lets Testing Library work with fake timers and hands `createTestApp` the app's query defaults. Inline `test.projects` that share the root's Vite server, Vitest 5's default, get none of this: set `sharedViteServer: false` in the root's `test` options. Tests sit next to the code as `*.test.tsx` and run with `npm test`.
 
 ```tsx
 import { render, screen } from '@testing-library/react';
@@ -25,24 +25,40 @@ it('shows the validation error from C# next to the field', async () => {
 });
 ```
 
-`createTestApp({ url, params, shared, queries, navigation, antiforgery, actions })` returns `{ Wrapper, navigations, queryClient }`:
+`createTestApp({ url, params, shared, queries, defaultOptions, navigation, antiforgery, actions })` returns `{ Wrapper, navigations, queryClient }`:
 
 - `url` and `params` set what `usePathname`, `useSearchParams` and `useParams` see; `shared` is what `useSharedProps` returns; `queries: [{ key, data }]` seeds TanStack Query as a loader's `.WithQuery` would.
-- `actions` answers server action calls by name: `{ ok: true, result }` or `{ ok: false, status: 422, errors }` (add `fields: ['email']` to name the fields a failed state's `values` keep, as the server does). A component that calls an action, even from an effect as it mounts, must render inside `app.Wrapper`: outside it the call fails with "called before the page was ready".
+- The `QueryClient` starts from the app's `netjes({ query: { defaultOptions } })`: a failed query or mutation is tried as often as in the app, with no wait between the tries, so the test sees the error the app shows after its last try. `defaultOptions` goes over them: `{ queries: { retry: false } }` shows the error after the first request. Seeded data is fresh for the app's `staleTime` from when `createTestApp()` is called: with a `staleTime` of 0, or in a component rendered after a fake clock moved past it, a seeded query is fetched again as it mounts; answer that request (MSW) or pass `{ queries: { staleTime: 60_000 } }`.
+- `actions` answers server action calls by name: `{ ok: true, result }` or `{ ok: false, status: 422, errors }` (add `fields: ['email']` to name the fields a failed state's `values` keep, as the server does). A failure other than a 422 throws a `ServerActionError`, withheld unless the answer has the `message` the server would send: `{ ok: false, status: 403, errors: {}, message: 'Forbidden' }`. A component that calls an action, even from an effect as it mounts, must render inside `app.Wrapper`: outside it the call fails with "called before the page was ready".
 - `navigations` records what happened: `{ type: 'push' | 'replace', href }`, `{ type: 'refresh' | 'back' | 'forward' }`, `{ type: 'submit', action, data }` for form posts, `{ type: 'action', name, input }` for action calls.
 
 Render a page component directly with the props its loader would send: `render(<Post title="Hello" body="..." />, { wrapper: createTestApp({ url: '/blog/hello' }).Wrapper })`. A page made with `definePage` parses them with its schema, so props the loader could not send fail the test with `Invalid props: ...`.
 
+For the whole document, as the server sends it (the layouts, the head, Netjes's inline scripts), `renderDocument('app/blog/[slug]/page.tsx', { props, params: { slug: 'hello' }, url: '/blog/hello', layouts: { 'app/blog/layout.tsx': { categories } }, shared })` from `netjes/testing` resolves with the HTML. The test file starts with `// @vitest-environment node`: in a DOM environment it rejects, since the server renders without one. No C# runs, so pass what the loaders would send; a layout that `layouts` does not name gets no props. Nothing else the server adds is there: query entries seeded with `.WithQuery` (a `useQuery` renders without its data), metadata from C#, the antiforgery token, the locale, draft mode, the base path and the image optimiser's settings. A boundary file renders inside the layouts down to its own folder, and `global-error` without any layout, with no route. A Promise in the props is a `Page.Defer` value; pass `signal: AbortSignal.timeout(1000)` when one may never settle. `inlineScriptHashes(html)` is async: `await inlineScriptHashes(html)` resolves to the `'sha256-…'` hashes of the inline scripts in the document that a browser runs, for a Content-Security-Policy without a nonce. With no inline scripts of the app's own they equal `CSP_SCRIPT_HASHES.split(' ')` from `netjes`, as `app/document.test.ts` in a new app checks for the home page: `expect(await inlineScriptHashes(html)).toEqual(CSP_SCRIPT_HASHES.split(' '))`. The document is a crawler's, so React's scripts that reveal a Suspense boundary for a visitor are not in it, nor the inline code of an `afterInteractive` or `lazyOnload` `<Script>`, which the browser adds: its hash goes in the policy only. A `beforeInteractive` `<Script>`'s inline code is in the document, so its hash goes in the policy and in the list a test expects from `inlineScriptHashes`.
+
+Fake timers work with Testing Library: after `vi.useFakeTimers()`, create the user with `userEvent.setup({ advanceTimers: vi.advanceTimersByTime })`, and let `findBy…` or `waitFor` wait, which moves the fake clock on (their timeout counts fake time). Run a timer that `fireEvent` started with `await act(() => vi.advanceTimersByTimeAsync(ms))`, and call `vi.useRealTimers()` in an `afterEach`.
+
 ## Loaders and actions: C#
 
+An app made with `netjes new` has a test project in `tests/<App>.Tests`, with an `AppFactory` set up as below and tests of the home page: `dotnet test tests/<App>.Tests` runs them. In another app, copy that setup from the [testing guide](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/testing.md#c-tests-of-loaders-and-actions); the app's project needs `<DefaultItemExcludes>$(DefaultItemExcludes);tests/**;e2e/**</DefaultItemExcludes>` first, since the Web SDK compiles everything below it.
+
 - Loader logic: call the loader or the method it uses and read `PageResult<T>.Props` in an xUnit test.
-- Endpoints: test the real app with `WebApplicationFactory<Program>` from `Microsoft.AspNetCore.Mvc.Testing` (ASP.NET Core 10 makes the `Program` class of top-level statements public, so the test project sees it). No Node is needed when the test sets `Netjes:Mode` to `Development` (routes come from `app/` on disk) and registers an `ISsrRenderer` (`Netjes.Rendering`) of its own that returns fixed HTML, in `ConfigureServices`. Request a page as the client router does, with the header `X-Netjes-Data: 1` (`NetjesHeaders.Data`): the answer is the page payload as JSON, with `props`, `status` and `antiforgery`; a page with `Page.Defer` values answers NDJSON, the payload first. When the app cannot start (no build in Production, `node` not found), `CreateClient()` throws an `InvalidOperationException` that says why.
+- Endpoints: test the real app with `WebApplicationFactory<Program>` from `Microsoft.AspNetCore.Mvc.Testing` (ASP.NET Core 10 makes the `Program` class of top-level statements public, so the test project sees it). No Node is needed when the test sets `Netjes:Mode` to `Development` (routes come from `app/` on disk) and registers an `ISsrRenderer` (`Netjes.Rendering`) of its own that returns fixed HTML, in `ConfigureServices`. Set `NetjesOptions.TypesFile` to `null` there too (`services.Configure<NetjesOptions>(o => o.TypesFile = null)`): in development mode the app rewrites `generated/netjes.ts` at startup, and a test run that did would let a later `netjes generate --check` pass on a stale committed file. Run it in the `Testing` environment (`builder.UseEnvironment("Testing")`), as the testing guide's factory does: `WebApplicationFactory` uses `Development` unless told otherwise, and there Netjes output-caches no page, so a test of `CachePage` would see every request render. Request a page as the client router does, with the header `X-Netjes-Data: 1` (`NetjesHeaders.Data`): the answer is the page payload as JSON, with `props`, `status` and `antiforgery`; a page with `Page.Defer` values answers NDJSON, the payload first. When the app cannot start (no build in Production, `node` not found), `CreateClient()` throws an `InvalidOperationException` that says why.
 - Server actions are `POST /_netjes/actions/{name}`. Call one as the client router does: the fields form-encoded, `X-Netjes-Data: 1`, and the payload's `antiforgery.requestToken` in the header named by `antiforgery.headerName` (a client that keeps cookies, so the antiforgery cookie goes along; `GET /_netjes/antiforgery` returns a token too). A plain form post, as without JavaScript, sends the token as the `antiforgery.formFieldName` field instead.
 - Use a real database for data access tests (Testcontainers), not an in-memory fake.
 
 ## End to end: Playwright
 
-Put Playwright tests in `e2e/` (Vitest skips it). Run them against the app in Development (`dotnet run --no-launch-profile` with `ASPNETCORE_ENVIRONMENT=Development`) and in Production (`npm run build`, then `dotnet run --no-launch-profile` with `ASPNETCORE_ENVIRONMENT=Production`), waiting on `/healthz`. Test the forms with JavaScript turned off too (`test.use({ javaScriptEnabled: false })`): they must post, show errors and keep what was typed.
+An app made with `netjes new` has this set up: `playwright.config.ts`, `e2e/home.spec.ts` and `npm run test:e2e`, after `npx playwright install chromium` once. Put Playwright tests in `e2e/` (Vitest skips it). Build the app once (`dotnet build`, as `npm run test:e2e` does), then run them against it in Development (`dotnet run --no-build --no-launch-profile` with `ASPNETCORE_ENVIRONMENT=Development` and a `Netjes__ViteDevPort` of its own) and in Production (`npm run build`, then `dotnet run --no-build --no-launch-profile` with `ASPNETCORE_ENVIRONMENT=Production`), each waiting on `/healthz`. Playwright starts its servers at once, and two `dotnet run` without `--no-build` would build the same project at the same time. Test the forms with JavaScript turned off too (`test.use({ javaScriptEnabled: false })`): they must post, show errors and keep what was typed.
+
+With JavaScript on, wait for hydration after each full page load, before the first click or keystroke; until then links load pages in full and forms post natively, so the test can pass without the client. Netjes puts `data-netjes-hydrated` on `<html>` once the client router runs in the document:
+
+```ts
+await page.goto('/');
+await expect(page.locator('html')).toHaveAttribute('data-netjes-hydrated', '');
+```
+
+`page.locator('html[data-netjes-hydrated]').waitFor({ state: 'attached' })` waits for the same thing without `expect`'s 5-second limit. Never wait on `history.state`: a reload keeps it, so it is there before the page's scripts have run. Content inside a Suspense boundary can hydrate after the mark; React hydrates it first when a click lands on it.
 
 ## Before calling a change done
 
@@ -50,8 +66,8 @@ Put Playwright tests in `e2e/` (Vitest skips it). Run them against the app in De
 npm test && npm run typecheck && dotnet build && npx netjes generate --check
 ```
 
-and `npm run routes` without new warnings.
+and `npm run routes` without new warnings. Where the app has them: `dotnet test tests/<App>.Tests`, and `npm run test:e2e` for a change to a page or a form.
 
 ## More
 
-[Testing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/testing.md) in the guides, and `createTestApp` in the [React API](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/react-api.md#createtestapp).
+[Testing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/testing.md) in the guides, and [`createTestApp`](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/react-api.md#createtestapp) and [`renderDocument`](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/react-api.md#renderdocument) in the React API.

package/src/actions.tsx

@@ -23,13 +23,19 @@ export interface ServerAction<TInput, TResult> {
   readonly url: string;
 }
 
-/** Thrown into the nearest error boundary when the server could not run the action (not for validation errors). */
+/**
+ * Thrown into the nearest error boundary when the server could not run the action (not for validation errors).
+ * `status` is the status of the server's answer. `withheld` is true when the server sent no message, as for a 5xx
+ * with error details off: the message is then Netjes's own, which names the action and the status.
+ */
 export class ServerActionError extends Error {
   override name = 'ServerActionError';
   readonly status: number;
-  constructor(message: string, status: number) {
+  readonly withheld: boolean;
+  constructor(message: string, status: number, withheld = false) {
     super(message);
     this.status = status;
+    this.withheld = withheld;
   }
 }
 
@@ -170,7 +176,7 @@ export function serverAction<TInput = FormData, TResult = unknown>(
     const active = client ?? (await readyClient(name));
     const answer = await active.invoke(name, url, input);
     if (!answer.ok && answer.status !== 422) {
-      throw new ServerActionError(answer.message ?? `Server action ${name} failed with status ${answer.status}`, answer.status);
+      throw new ServerActionError(answer.message ?? `Server action ${name} failed with status ${answer.status}`, answer.status, answer.message === undefined);
     }
     if (!answer.ok) {
       const values = submittedValues(input, active.tokenField?.(), answer.fields);

package/src/client-entry.tsx

@@ -1,4 +1,6 @@
-// Must come first: installs the React Fast Refresh runtime before any component module runs (empty in builds).
+// Must come first, ahead of anything that could make a zod schema: turns zod's compiled parsers off (ADR 0036).
+import './zod-jitless.ts';
+// Must come before any component module: installs the React Fast Refresh runtime before one runs (empty in builds).
 import '@vitejs/plugin-react/preamble';
 import { createRoot, hydrateRoot } from 'react-dom/client';
 import { pages } from 'virtual:netjes/pages';
@@ -7,6 +9,7 @@ import { type RouteModules, createModuleLoader } from './modules.ts';
 import { DATA_ELEMENT_ID, SHELL_END_ID, parseInitialPayload } from './payload.ts';
 import { Root } from './root.tsx';
 import { withClockOffset } from './router.tsx';
+import { BEFORE_INTERACTIVE_MARKER, adoptServerScripts } from './script.tsx';
 
 /**
  * The payload is the body's first element, so it is normally parsed by the time this async script runs. If the
@@ -112,6 +115,18 @@ async function firstPageModules(): Promise<RouteModules | null> {
   }
 }
 
+/**
+ * A `<Script strategy="beforeInteractive">` in the server's document puts a marker in the head, which is complete by
+ * the time the payload is read. Such a page waits for the end of the shell, where the parser has run the inline ones,
+ * then runs the external ones in order and waits for them, before the page's modules run and hydrate (ADR 0044). A
+ * page without one loads its modules while the rest of the shell arrives (ADR 0022).
+ */
+const beforeInteractive = document.head.querySelector(`meta[name="${BEFORE_INTERACTIVE_MARKER}"]`) !== null;
+if (beforeInteractive) {
+  await shellParsed();
+  await adoptServerScripts(payload.document.nonce);
+}
+
 const modules = await firstPageModules();
 if (modules) {
   const root = <Root payload={payload} modules={modules} loader={loader} dataJson={dataJson} />;
@@ -120,7 +135,10 @@ if (modules) {
     // the scripts and stylesheets already in it and replaces the rest.
     createRoot(document).render(root);
   } else {
-    await shellParsed();
+    if (!beforeInteractive) {
+      await shellParsed();
+      await adoptServerScripts(payload.document.nonce);
+    }
     hydrateRoot(document, root);
   }
 }

package/src/deferred.ts

@@ -1,5 +1,6 @@
 // Deferred loader values (Page.Defer in C#): placeholders in the payload that become promises the page reads with
 // React's use() inside a Suspense boundary.
+import { withheldError } from './errors.ts';
 import type { PagePayload, SegmentRef } from './payload.ts';
 
 /** A promise that records its outcome the way React's `use()` reads it, so a settled one renders without suspending. */
@@ -94,8 +95,9 @@ export function deferredRegistry() {
     resolve(id: string, value: unknown) {
       entry(id).resolve(value);
     },
+    /** Fails a value with the server's message; an empty one is a message the server withheld (no error details). */
     reject(id: string, message: string) {
-      entry(id).reject(new Error(message));
+      entry(id).reject(message === '' ? withheldError() : new Error(message));
     },
     /** Rejects every value still pending, e.g. when the stream that was to deliver them ended. */
     rejectPending(message: (id: string) => string) {
@@ -115,6 +117,17 @@ export function deferredRegistry() {
 export const DEFERRED_BOOTSTRAP =
   "self.__netjes_d=self.__netjes_d||function(i,v,e){self.__netjes_v[i]=[v,e]};Object.prototype.hasOwnProperty.call(self,'__netjes_v')||(self.__netjes_v={})";
 
+/**
+ * The `script-src` sources that allow Netjes's fixed inline scripts by their hashes, for a policy without a nonce: each
+ * `'sha256-…'` in its quotes, separated by spaces, as in `` `script-src 'self' ${CSP_SCRIPT_HASHES}` ``. A fixed script
+ * has the same text in every document. In this version there is one, the bootstrap that collects streamed `Page.Defer`
+ * values, and a Netjes version that changes it or adds another changes the value. The scripts that deliver those
+ * values, and React's scripts that reveal Suspense boundaries, differ from render to render, so no hash covers them.
+ * React's script for form actions that are functions is left out too, since its text follows the React version. The
+ * same value as `NetjesContentSecurityPolicy.ScriptHashes` in C#.
+ */
+export const CSP_SCRIPT_HASHES: string = "'sha256-FSjVV+FzmXP8KKrLKLdvst/5N/bEWSkde01XzpGKRgs='";
+
 const UNSAFE = /[<>&\u2028\u2029]/g;
 
 /** JSON that can sit inside a <script> element. */

package/src/document.tsx

@@ -15,8 +15,17 @@ type DocumentProps = { info: DocumentInfo; dataJson: string; children: ReactNode
  */
 export function Document({ info, dataJson, children }: DocumentProps) {
   const { nonce } = info;
+  // Netjes owns <html> and <body>: the app's layout renders inside the body, so its markup cannot give either one an
+  // attribute. A script that runs before hydration can (a theme, a browser extension, a translator), and in development
+  // React logs a mismatch for each attribute on an element that its props do not have. suppressHydrationWarning ends
+  // that check for the element's own attributes. It also makes React accept any text that is the element's own child,
+  // in production too: text that a layout or a page renders outside any element or Suspense boundary sits directly in
+  // the body, and a mismatch there is neither reported nor repaired. The elements in the body are checked as before,
+  // their attributes and their text. React does not write the prop into the markup, and production does not check
+  // attributes at all. The check is off for `lang` too: the server and the client read it from the same payload, so it
+  // differs only when a script changed it, or when Netjes has a bug.
   return (
-    <html lang={info.lang}>
+    <html lang={info.lang} suppressHydrationWarning>
       <head>
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -28,8 +37,18 @@ export function Document({ info, dataJson, children }: DocumentProps) {
         {info.assets.stylesheets.map((href) => (
           <link key={href} rel="stylesheet" href={href} nonce={nonce} />
         ))}
+        {/* In development, the CSS the page imports, so that it is styled before its scripts run. Vite's client owns
+            each element's text once it runs: the CSS module with that id sets it as it loads, before hydration, and
+            again after every edit. The sidecar inlines the build that module carries, but a file edited between the
+            render and the import differs, so React leaves the text unchecked. */}
         {info.devStyles?.map((style) => (
-          <style key={style.id} data-vite-dev-id={style.id} nonce={nonce} dangerouslySetInnerHTML={{ __html: style.css }} />
+          <style
+            key={style.id}
+            data-vite-dev-id={style.id}
+            nonce={nonce}
+            suppressHydrationWarning
+            dangerouslySetInnerHTML={{ __html: style.css }}
+          />
         ))}
         {info.assets.modulePreloads.map((href) => (
           <link key={href} rel="modulepreload" href={href} nonce={nonce} />
@@ -38,7 +57,7 @@ export function Document({ info, dataJson, children }: DocumentProps) {
           <script key={src} type="module" src={src} async nonce={nonce} />
         ))}
       </head>
-      <body>
+      <body suppressHydrationWarning>
         {/* Already escaped for HTML by the server; the client reads it back verbatim to hydrate. */}
         <script id={DATA_ELEMENT_ID} type="application/json" nonce={nonce} dangerouslySetInnerHTML={{ __html: dataJson }} />
         {children}

package/src/errors.ts

@@ -0,0 +1,12 @@
+// The mark on errors whose message Netjes withheld: `withheld` is true when the message is Netjes's stand-in for one it
+// does not show (error details are off, or the thrown value had none), so `!error.withheld` means it is worth showing.
+
+/** Netjes's stand-in for a message it does not show, marked as one. */
+export function withheldError(): Error & { withheld: true } {
+  return Object.assign(new Error('Something went wrong'), { withheld: true as const });
+}
+
+/** Whether `error` is marked as one whose message was withheld. */
+export function isWithheld(error: unknown): boolean {
+  return error instanceof Error && (error as { withheld?: unknown }).withheld === true;
+}

package/src/form.tsx

@@ -1,4 +1,4 @@
-import type { ButtonHTMLAttributes, FormHTMLAttributes, SubmitEvent } from 'react';
+import type { ComponentPropsWithRef, SubmitEvent } from 'react';
 import { RETURN_FIELD, actionMetaOf } from './actions.tsx';
 import { encodeForm } from './form-data.ts';
 import type { Href } from './href.ts';
@@ -7,8 +7,8 @@ import { useBasePath, useInternalRouter, usePagePayload, withBasePath } from './
 /** A React form action, e.g. the `formAction` from `useAction(serverAction('name'))`. */
 export type FormAction = (formData: FormData) => void | Promise<void>;
 
-/** The props of `<Form>`: a form's own, with client navigation and server action support. */
-export type FormProps = Omit<FormHTMLAttributes<HTMLFormElement>, 'method' | 'action'> & {
+/** The props of `<Form>`: a form's own and its ref, with client navigation and server action support. */
+export type FormProps = Omit<ComponentPropsWithRef<'form'>, 'method' | 'action'> & {
   method?: 'get' | 'post';
   /**
    * Where to submit. Default: the current URL, which is where `MapPageAction` handlers for this page listen. Or a
@@ -74,6 +74,9 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
   }
 
   function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
+    // Read before the app's own onSubmit, which runs as the form is submitted: where it moves the focus, the router
+    // leaves it, as after a link's onClick.
+    const focusedAtStart = document.activeElement;
     onSubmit?.(event);
     if (event.defaultPrevented || reloadDocument) return;
     const form = event.currentTarget;
@@ -88,7 +91,7 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
     const data = formDataOf(form, submitter);
     const submitMethod = (submitter?.getAttribute('formmethod') ?? method).toLowerCase();
     if (submitMethod === 'post') {
-      void router.submit(url, encodeForm(data, form.enctype === 'multipart/form-data'));
+      void router.submit(url, encodeForm(data, form.enctype === 'multipart/form-data'), { focusedAtStart });
       return;
     }
     const query = new URLSearchParams();
@@ -97,7 +100,7 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
     url.hash = '';
     // Built from the form's own action, which is not one of the app's typed routes.
     const href = url.href as Href;
-    void (replace ? router.replace(href) : router.push(href));
+    void (replace ? router.replace(href, { focusedAtStart }) : router.push(href, { focusedAtStart }));
   }
 
   return (
@@ -108,8 +111,8 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
   );
 }
 
-/** The props of `<SubmitButton>`: a button's own, except `type`. */
-export type SubmitButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'>;
+/** The props of `<SubmitButton>`: a button's own and its ref, except `type`. */
+export type SubmitButtonProps = Omit<ComponentPropsWithRef<'button'>, 'type'>;
 
 /**
  * A submit button whose `formAction` is rendered under the base path, so it posts to the right place with and