netjes 0.0.1 → 0.0.3

package/src/server-render.tsx

@@ -2,6 +2,7 @@ import { type Readable, Transform, Writable } from 'node:stream';
 import type { ReactNode } from 'react';
 import { renderToPipeableStream } from 'react-dom/server';
 import { type DeferredSource, deferredScript, revivePayload } from './deferred.ts';
+import { isWithheld } from './errors.ts';
 import { type ModuleMap, createModuleLoader } from './modules.ts';
 import { type InitialPayload, parseInitialPayload } from './payload.ts';
 import { RenderCleanupContext } from './render-cleanup.ts';
@@ -75,7 +76,9 @@ function renderToStream(
     for (const id of deferredIds) {
       source(id).then(
         (value) => send(deferredScript(id, value, undefined, nonce)),
-        (error: unknown) => send(deferredScript(id, null, error instanceof Error ? error.message : String(error), nonce)),
+        // A withheld message goes on as an empty one, which the browser replaces with its own stand-in.
+        (error: unknown) =>
+          send(deferredScript(id, null, isWithheld(error) ? '' : error instanceof Error ? error.message : String(error), nonce)),
       );
     }
     let started = false;

package/src/testing-vitest.ts

@@ -0,0 +1,37 @@
+// Registered by netjes() as a Vitest setup file in every app, after the app's own: what the test harness needs from the
+// runner. Named by path, not exported.
+import type { DefaultOptions } from '@tanstack/react-query';
+import { inject, vi } from 'vitest';
+
+declare module 'vitest' {
+  interface ProvidedContext {
+    /** The app's `netjes({ query: { defaultOptions } })`, which netjes() provides to its tests. */
+    'netjes:query': DefaultOptions;
+  }
+}
+
+// The app's query defaults, for createTestApp. They wait under a global symbol rather than in a module: the app's
+// imports of netjes/testing need not share module instances with this file, which Vitest loads by its path.
+const appQueryDefaults: unknown = inject('netjes:query');
+if (typeof appQueryDefaults === 'object' && appQueryDefaults !== null) {
+  (globalThis as Record<symbol, unknown>)[Symbol.for('netjes.testing.queryDefaults')] = appQueryDefaults;
+}
+
+// Testing Library advances fake timers only through Jest's global: without one, waitFor, findBy and every user-event
+// call wait on a faked setTimeout that nothing advances, so they never return. While Vitest's timers are fake, `jest`
+// is a bridge to them; otherwise it is undefined, so code that looks for Jest finds none. A jest global that was
+// already there is left alone, and one a test assigns replaces the bridge.
+if (!('jest' in globalThis)) {
+  const bridge = {
+    advanceTimersByTime(ms: number) {
+      vi.advanceTimersByTime(ms);
+    },
+  };
+  Object.defineProperty(globalThis, 'jest', {
+    configurable: true,
+    get: () => (vi.isFakeTimers() ? bridge : undefined),
+    set(value: unknown) {
+      Object.defineProperty(globalThis, 'jest', { configurable: true, enumerable: true, writable: true, value });
+    },
+  });
+}

package/src/testing.tsx

@@ -1,5 +1,6 @@
 // Test harness for components and pages that use Netjes: `render(<Page />, { wrapper: createTestApp().Wrapper })`.
 // The router is a fake: it records what the component asked for and moves to the new URL, but loads nothing.
+// renderDocument renders a page's whole document instead, as the server would send it.
 import { type DefaultOptions, QueryClient, QueryClientProvider, hydrate } from '@tanstack/react-query';
 import { type ReactNode, useLayoutEffect, useMemo, useState } from 'react';
 import { type ActionClient, type ActionState, setActionClient } from './actions.tsx';
@@ -8,6 +9,8 @@ import { PublicConfigProvider } from './public-config.tsx';
 import { dehydratedStateOf, mergeOptions } from './query.tsx';
 import { type InternalRouter, type NavigationState, RouterContexts, type SubmitBody } from './router.tsx';
 
+export { type RenderDocumentOptions, inlineScriptHashes, renderDocument } from './render-document.tsx';
+
 /** What the fake app of `createTestApp` reports to the components under test. */
 export type TestAppOptions = {
   /** The current URL. Default `/`. */
@@ -25,7 +28,10 @@ export type TestAppOptions = {
   shared?: unknown;
   /** Seeded into the QueryClient the way `PageResult.WithQuery` seeds it, as of now. */
   queries?: ReadonlyArray<{ key: readonly unknown[]; data: unknown }>;
-  /** Like `netjes({ query: { defaultOptions } })`; the harness also turns retries off. */
+  /**
+   * Like `netjes({ query: { defaultOptions } })`, merged over the harness's own: failed queries and mutations are tried
+   * as often as in the app, with no wait between the tries, and no query's data is garbage-collected.
+   */
   defaultOptions?: DefaultOptions;
   /** What `useNavigation()` returns. Default idle. */
   navigation?: NavigationState;
@@ -45,6 +51,12 @@ export type TestActionAnswer = ActionState<unknown> & {
   invalidate?: ReadonlyArray<readonly unknown[]>;
   /** After a failure: the submitted fields the state's `values` keep, as the server names them (the action's declared, non-private fields). Default: all. */
   fields?: readonly string[];
+  /**
+   * After a failure other than a 422: the message the server would send, which the `ServerActionError` then carries, as
+   * the server does for a 4xx (`Forbidden`) and for a 5xx with error details on. Without one, the call fails as a 5xx
+   * does with error details off: the error's message is Netjes's own and `withheld` is true.
+   */
+  message?: string;
 };
 
 /** One thing the component under test did: a navigation, a router call, a form post or a server action call. */
@@ -76,6 +88,20 @@ function RegisterActionClient({ client }: { client: ActionClient }) {
 
 const TEST_TOKEN: AntiforgeryToken = { formFieldName: '__RequestVerificationToken', headerName: 'RequestVerificationToken', requestToken: 'test-token' };
 
+/**
+ * The harness's own query defaults, over the app's: a failed query or mutation is tried as often as in the app, but
+ * without the wait between the tries (TanStack Query's 1, 2 and 4 seconds would outlast a test), and data stays in the
+ * client for the whole test.
+ */
+const HARNESS_DEFAULTS: DefaultOptions = { queries: { retryDelay: 0, gcTime: Number.POSITIVE_INFINITY }, mutations: { retryDelay: 0 } };
+
+/** The app's `netjes({ query })` defaults, where Netjes's Vitest setup file keeps them (src/testing-vitest.ts). */
+const APP_QUERY_DEFAULTS = Symbol.for('netjes.testing.queryDefaults');
+
+function appQueryDefaults(): DefaultOptions | undefined {
+  return (globalThis as Record<symbol, DefaultOptions | undefined>)[APP_QUERY_DEFAULTS];
+}
+
 function dataOf(body: SubmitBody): URLSearchParams | FormData {
   return body.contentType === null ? body.body : new URLSearchParams(body.body);
 }
@@ -83,10 +109,9 @@ function dataOf(body: SubmitBody): URLSearchParams | FormData {
 /** Creates a fake app around the components under test: pass its `Wrapper` to Testing Library's `render`. The router loads nothing; it records what was asked of it. */
 export function createTestApp(options: TestAppOptions = {}): TestApp {
   const navigations: TestNavigation[] = [];
-  const defaults = mergeOptions(options.defaultOptions);
-  const queryClient =
-    options.queryClient ??
-    new QueryClient({ defaultOptions: { ...defaults, queries: { retry: false, gcTime: Number.POSITIVE_INFINITY, ...defaults.queries } } });
+  // The Netjes defaults, then the app's, then the harness's, then the test's.
+  const defaultOptions = mergeOptions(appQueryDefaults(), HARNESS_DEFAULTS, options.defaultOptions);
+  const queryClient = options.queryClient ?? new QueryClient({ defaultOptions });
   const now = Date.now();
   const seeded = dehydratedStateOf(options.queries?.map((query) => ({ ...query, updatedAt: now })));
   if (seeded) hydrate(queryClient, seeded);
@@ -109,6 +134,7 @@ export function createTestApp(options: TestAppOptions = {}): TestApp {
             status: answer.status,
             errors: answer.errors,
             ...(answer.fields ? { fields: [...answer.fields] } : {}),
+            ...(answer.message !== undefined ? { message: answer.message } : {}),
             revalidate: false,
           };
     },

package/src/virtual.d.ts

@@ -1,6 +1,8 @@
 declare module 'virtual:netjes/pages' {
   /** Every page, layout and other convention file, keyed `/app/...`, as lazy imports. Generated by the netjes Vite plugin. */
   export const pages: Record<string, () => Promise<unknown>>;
+  /** The folder of the page files, as the plugin's `appDir` names it: `app`, or e.g. `src/app`. */
+  export const appDir: string;
 }
 
 declare module 'virtual:netjes/query' {

package/src/zod-jitless.ts

@@ -0,0 +1,15 @@
+// Turns zod's compiled parsers off in the browser (ADR 0036). zod 4.4.0 and newer read this object whenever they make
+// an object schema, whether zod loaded before this ran or after. Without `jitless`, zod tests whether it may make a
+// function from a string, and a browser reports that test as a violation of any Content-Security-Policy whose
+// script-src (or default-src, without a script-src) leaves out 'unsafe-eval', although zod catches the error.
+//
+// It must stay the client entry's first import, so that it runs ahead of the entry's other imports and of the page
+// modules, which make their schemas as they load. (A production build moves the modules the entry shares with pages,
+// such as React and the router, into chunks that run before the entry's own code; none of them makes a zod schema.)
+// It imports nothing, so the entry still loads no zod.
+type ZodGlobals = { __zod_globalConfig?: { jitless?: boolean } };
+
+((globalThis as unknown as ZodGlobals).__zod_globalConfig ??= {}).jitless = true;
+
+// A module, not a script, so that the type above stays its own.
+export {};

package/template/.dockerignore

@@ -5,6 +5,9 @@ publish
 **/dist
 **/.vite
 **/test-results
+**/playwright-report
+tests
+e2e
 .git
 **/.env
 **/.env.*

package/template/Dockerfile

@@ -44,9 +44,15 @@ COPY . .
 COPY --from=client /src/dist dist
 RUN dotnet publish -c Release -o /app --no-restore -p:NetjesSkipClientBuild=true
 
+# tini, the production image's PID 1 (below): Ubuntu's package, installed in the SDK image the build stage uses. The
+# production stage takes its static binary, which needs no package manager and no library in RUNTIME_IMAGE.
+FROM ${SDK_IMAGE} AS tini
+RUN apt-get update && apt-get install -y --no-install-recommends tini && rm -rf /var/lib/apt/lists/*
+
 # Production: ASP.NET Core runtime plus the node binary for the SSR sidecar. Runs as the non-root app user.
 FROM ${RUNTIME_IMAGE} AS production
 COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=tini /usr/bin/tini-static /usr/bin/tini
 # Where ASP.NET Core keeps its Data Protection keys; docker-compose.prod.yml mounts a volume here.
 RUN mkdir -p /home/app/.aspnet/DataProtection-Keys && chown -R app:app /home/app/.aspnet
 WORKDIR /app
@@ -55,4 +61,8 @@ USER $APP_UID
 EXPOSE 8080
 HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
   CMD ["node", "-e", "fetch('http://127.0.0.1:8080/healthz').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
-ENTRYPOINT ["dotnet", "__NAME__.dll"]
+# tini is PID 1 and runs the app as its child. The kernel ignores a signal that a container's PID 1 has no handler for,
+# so an app that is PID 1 never dies of its own abort(): after a crash it spins (arm64) or exits with another code than
+# 134. tini passes signals on (docker stop), reaps orphans and exits with the app's code; -s keeps it reaping when
+# another process is PID 1, as under docker run --init.
+ENTRYPOINT ["tini", "-s", "--", "dotnet", "__NAME__.dll"]

package/template/README.md

@@ -1,24 +1,28 @@
 # __TITLE__
 
-A React app on ASP.NET Core, built with Netjes: Vite, Tailwind CSS, TanStack Query, zod and Vitest are set up.
+A React app on ASP.NET Core, built with Netjes: Vite, Tailwind CSS, TanStack Query, zod, Vitest, xUnit and Playwright are set up.
 
 ```bash
 npm run dev        # dotnet watch + Vite HMR, http://localhost:5080
-npm test           # Vitest component tests
-npm run typecheck
+npm test           # Vitest: component tests and the home page's document
+dotnet test tests/__NAME__.Tests   # C# tests of the loader and the server action, in memory
+npm run test:e2e   # Playwright, on a development and a production server (npx playwright install chromium once first)
+npm run typecheck  # every .ts and .tsx file
 npm run routes     # the route table, from C#
 npx netjes build   # types, client and server bundles
 npx netjes info    # check Node.js, the .NET SDK, the packages and this setup
 dotnet publish -c Release
 ```
 
-- `app/` holds the pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `layout.tsx` wraps them all, `not-found.tsx` and `error.tsx` handle the rest.
+- `app/` holds the pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `layout.tsx` wraps them all, `not-found.tsx` and `error.tsx` handle the rest. `app/document.test.ts` renders the home page's whole document, as the server sends it, with `renderDocument` from `netjes/testing`.
 - `public/` is served at the site root. `public/favicon.svg`, which the metadata in `app/layout.tsx` links, is the Netjes mark: replace it with the app's own.
 - `Features/` holds the C# side, one folder per feature: `Features/Home/HomePage.cs` maps the home page's loader and the `home.greet` server action the form calls.
+- `tests/__NAME__.Tests/` holds the C# tests: `AppFactory.cs` runs the real app in memory, with no Node and no client build, and `HomePageTests.cs` tests the home page's loader and form. `e2e/` holds the Playwright tests, which `playwright.config.ts` runs against the app in Development and in Production. `__NAME__.csproj` leaves these two root folders out of the app's build, so keep the app's own C# out of them.
+- `tsconfig.json` points to two configs: `tsconfig.app.json` checks the app's code without Node's types, `tsconfig.node.json` checks `vite.config.ts`, `playwright.config.ts`, `e2e/` and `scripts/` with them.
 - `AGENTS.md` tells coding agents how the app is laid out and what the rules are; `CLAUDE.md` imports it for Claude Code.
 - `Properties/launchSettings.json` holds the `http` launch profile that `dotnet run` and IDEs (F5) use: the app in Development on http://localhost:5080, as `npm run dev` runs it but without `dotnet watch`.
-- `generated/netjes.ts` holds zod schemas for what the loaders and actions return, typed server action references and typed routes. The app rewrites it when it starts in Development; commit it, and run `npx netjes generate --check` in CI.
+- `generated/netjes.ts` holds zod schemas for what the loaders and actions return, typed server action references, typed routes and typed endpoint URLs. The app rewrites it when it starts in Development; commit it, and run `npx netjes generate --check` in CI.
 
-Outside Development, `Program.cs` sends HSTS on https responses and redirects http to https once the app knows its https port (`ASPNETCORE_HTTPS_PORT` or `ASPNETCORE_HTTPS_PORTS`). Behind a proxy that terminates TLS, add `UseForwardedHeaders()` (trusting only that proxy) so proxied requests count as https and get HSTS, and let the proxy redirect plain http. Netjes adds `X-Content-Type-Options`, `Referrer-Policy` and `X-Frame-Options: SAMEORIGIN` to every page; see `NetjesOptions.SecurityHeaders` to change that.
+Outside Development, `Program.cs` sends HSTS on https responses and redirects http to https once the app knows its https port (`ASPNETCORE_HTTPS_PORT` or `ASPNETCORE_HTTPS_PORTS`). Behind a proxy that terminates TLS, add `UseForwardedHeaders()` (trusting only that proxy) so proxied requests count as https and get HSTS, and let the proxy redirect plain http. Netjes adds `X-Content-Type-Options: nosniff` to every response that passes through `UseNetjes()`, static files and API endpoints included, and `Referrer-Policy` and `X-Frame-Options` (`SAMEORIGIN`, or what a Content-Security-Policy's `frame-ancestors` implies) to every document it renders; see `NetjesOptions.SecurityHeaders` to change that.
 
-With Docker: `docker compose up` for development, `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d` for production. In Development `appsettings.Development.json` limits `AllowedHosts` to loopback names (a DNS-rebinding guard); add a name there if you reach the dev app by another host. The Docker build restores Netjes from NuGet and npm, which is how any app made by `npx netjes new` references it. Only an app scaffolded from a Netjes checkout references the checkout instead; scaffold it with `netjes new --packages` to build it in Docker.
+With Docker: `docker compose up` for development, `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d` for production. Both publish the app on port 8080 of the host, development on 127.0.0.1 only; set `APP_PORT`, in the shell or a `.env` file, to use another port (`APP_PORT=8090 docker compose up`). The production image runs the app under tini, which passes the signal of `docker stop` on to the app and ends the container when the app crashes, with exit code 134, so `restart: always` starts it again. In Development `appsettings.Development.json` limits `AllowedHosts` to loopback names (a DNS-rebinding guard); add a name there if you reach the dev app by another host. The Docker build restores Netjes from NuGet and npm, which is how any app made by `npx netjes new` references it. Only an app scaffolded from a Netjes checkout references the checkout instead; scaffold it with `netjes new --packages` to build it in Docker.

package/template/_AGENTS.md

@@ -12,11 +12,17 @@ How this app is built, for coding agents and the people working with them. It is
 
 | Path | What |
 |---|---|
-| `app/` | Pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `blog/[slug]/page.tsx` is `/blog/{slug}`. `layout.tsx` wraps the pages below it and stays mounted; `loading.tsx`, `error.tsx`, `not-found.tsx`, `forbidden.tsx` and `unauthorized.tsx` are boundaries. `(group)` folders add no URL segment, `_private` folders are not routed. |
+| `app/` | Pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `blog/[slug]/page.tsx` is `/blog/{slug}`. `layout.tsx` wraps the pages below it and stays mounted. Netjes renders `<html>`, `<head>` and `<body>` around the root layout, so no layout renders them: the root one returns what goes inside `<body>`. `loading.tsx`, `error.tsx`, `not-found.tsx`, `forbidden.tsx` and `unauthorized.tsx` are boundaries. `(group)` folders add no URL segment, `_private` folders are not routed. `document.test.ts` renders the home page's whole document, as the server sends it, with `renderDocument` from `netjes/testing`. |
 | `Features/` | The C# side, one folder per feature (`namespace __NAME__.Features.Home`): page loaders (`MapPageLoader`), layout loaders (`MapLayoutLoader`), server actions (`MapAction`) and JSON endpoints, with records for what they take and return. Each feature has a `Map...` extension method that `Program.cs` calls. |
 | `Program.cs` | Services and the pipeline: `AddNetjes`, `UseNetjes`, authentication (when you add it), `UseAntiforgery`, each feature's `Map...`, and `app.MapPages()` last. |
 | `components/` | React components, with their Vitest tests next to them (`*.test.tsx`). |
-| `generated/netjes.ts` | Generated from the C# types and the page files: zod schemas for page and layout props (`pages`, `layouts`), `sharedProps`, typed `serverActions`, `api` schemas for JSON endpoints, `route()` and the `Href` type. Never edit it. |
+<!--netjes:if tests-->
+| `tests/__NAME__.Tests/` | The C# tests: a new test of a loader or an action goes here. In the project `netjes new` writes, on xUnit v3, `AppFactory.cs` runs the real app in memory with `WebApplicationFactory`, with no Node and no client build, and `HomePageTests.cs` requests the home page and posts its form as the client router does. C# for the app does not go in the root folders `tests/` and `e2e/`, which `netjes new` leaves out of the app's build (`DefaultItemExcludes` in `__NAME__.csproj`). |
+<!--netjes:end-->
+<!--netjes:if e2e-->
+| `e2e/` | Playwright tests, which `npm run test:e2e` runs. The `playwright.config.ts` that `netjes new` writes runs them against the app twice: in Development (the Vite dev server) and in Production (the build). |
+<!--netjes:end-->
+| `generated/netjes.ts` | Generated from the C# types and the page files: zod schemas for page and layout props (`pages`, `layouts`), `sharedProps`, typed `serverActions`, `api` schemas for JSON endpoints, `endpointUrl()` for the URLs of the app's endpoints, `route()` and the `Href` type. Never edit it. |
 | `styles/global.css` | Tailwind CSS (`@import 'tailwindcss'`), imported by `app/layout.tsx`. |
 | `public/` | Static files, served at the site root. `favicon.svg` is the Netjes mark, linked by `icons` in the root layout's `metadata`; replace it with the app's own. |
 
@@ -25,8 +31,14 @@ How this app is built, for coding agents and the people working with them. It is
 ```bash
 npm run dev                 # dotnet watch + Vite HMR on http://localhost:5080; rewrites generated/netjes.ts on start
 npm test                    # Vitest
-npm run typecheck           # strict TypeScript
+npm run typecheck           # strict TypeScript; in the configs netjes new writes, the app's code without Node's types
 dotnet build                # C#, warnings are errors
+<!--netjes:if tests-->
+dotnet test tests/__NAME__.Tests   # the C# tests; a plain dotnet test here finds only the app's project and runs none
+<!--netjes:end-->
+<!--netjes:if e2e-->
+npm run test:e2e            # Playwright (run npx playwright install chromium once first)
+<!--netjes:end-->
 npx netjes generate         # rewrite generated/netjes.ts after changing a C# type (--check: fail when stale)
 npm run routes              # the route table as ASP.NET Core sees it, with route warnings
 npx netjes build            # types, then the client and server bundles
@@ -39,7 +51,7 @@ dotnet publish -c Release   # runs the build and ships dist/
 2. Call its `Map...` method from `Program.cs`, before `app.MapPages()`.
 3. Run `npx netjes generate` (or restart `npm run dev`).
 4. Write `app/blog/[slug]/page.tsx`: `export default definePage(pages['/blog/[slug]'], function Post({ post }) { ... })`.
-5. Test the component with Vitest and `createTestApp` from `netjes/testing`; run the checks below.
+5. Test the loader in C# (in `tests/__NAME__.Tests`, where the app has it) and the component with Vitest and `createTestApp` from `netjes/testing`; run the checks below.
 
 A page without a loader is a plain default export and gets empty props. Forms call server actions: `app.MapAction("posts.like", ...)` in C#, `useAction(serverActions['posts.like'])` and `<Form action={formAction}>` in React; they also work without JavaScript.
 
@@ -47,18 +59,34 @@ A page without a loader is a plain default export and gets empty props. Forms ca
 
 - C# decides: data access, validation, authorization (`.RequireAuthorization()` on a loader, a layout loader or `MapPages()`; `Page.Forbidden()`), redirects and caching. React renders what the loader sends; hiding a button is not access control.
 - Never edit `generated/netjes.ts`. Change the C# type and regenerate; commit the file with the change. CI runs `npx netjes generate --check`.
-- zod at every boundary: `definePage` and `defineLayout` with the generated schemas, `useSearchParams(schema)` and `useParams(schema)` for the URL, `api['GET /api/...'].response.parse(...)` for JSON you fetch, `usePublicConfig(schema)` for public config, `Href` (or `isHref`) from the generated file for URLs that come from data. No `any`, no casts of server data.
+- zod at every boundary: `definePage` and `defineLayout` with the generated schemas (extended, as in `pages['/x'].extend({ link: Href })`, only where no C# type fits), `useSearchParams(schema)` and `useParams(schema)` for the URL, `api['GET /api/...'].response.parse(...)` for JSON you fetch from `useHref(endpointUrl('GET /api/...', params))`, `usePublicConfig(schema)` for public config, `Href` (or `isHref`) from the generated file for URLs that come from data, such as a CMS. No `any`, no casts of server data.
+- A link that C# sends to one of the app's pages is a `Href` in the C# record (`new Href("/about")`): it is generated as the `Href` schema, checked against the pages when the props are parsed, and goes to `<Link href>` as it is. C# checks only its shape, and a root-relative `Href` that no page serves fails the whole page, so a link to an endpoint or a file stays a `string`.
 - Server state goes through TanStack Query (`useQuery`), not `useEffect` and `fetch`. Seed it from the loader with `.WithQuery(key, data)` so it is server-rendered; actions update it with `.Invalidate(key)` or `.WithQuery(key, data)`.
-- Internal links are `<Link href={route('/blog/[slug]', { slug })}>`; a typo in an href is a type error.
+- Internal links are `<Link href={route('/blog/[slug]', { slug })}>`; a typo in an href 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; pass `undefined` as `search` for a link with a fragment and no query.
+- After a client navigation to another page, the router starts the focus over at the top of the document, as a page load does, and announces the page to screen readers by its title. Keep the "Skip to content" link the first thing in `app/layout.tsx` that takes the focus, with the content in `<main id="content">`, and give each page a title of its own (`metadata`, or `PageMetadata` from C#): the router says nothing for a page whose title is the previous page's.
 - Action inputs are records with `init` properties: `public sealed record NoteInput { [Required] public string? Text { get; init; } public bool Pinned { get; init; } }`. A field the post leaves out, such as an unchecked checkbox, keeps its default; form binding refuses (400) a post that lacks one of a positional record's constructor fields. DataAnnotations on them (`[Required]`, `[StringLength]`) are checked before the action runs and come back as field errors, with no setup, also for a post that has none of the input's fields. Return `ServerAction.Invalid(field, message)` for other errors the user can fix.
-- `.CachePage(...)` only for pages that are the same for every visitor: their loaders and shared props must not depend on cookies or other per-visitor state.
-- `Netjes:PublicConfig` is sent to the browser: never put secrets there.
+- `.CachePage(...)` only for pages that are the same for every visitor: their loaders and shared props must not depend on cookies or other per-visitor state. In the Development environment pages are never output-cached (each request renders them), so check caching on `npx netjes build && npx netjes start`, or in a `WebApplicationFactory` test in the `Testing` environment with `Netjes:Mode` set to `Development`, as the `AppFactory.cs` that `netjes new` writes runs. Each query string as sent is an entry of its own: name the keys a cached page reads with `.CacheQueryKeys("page")`, or `.CacheQueryKeys()` for none, so other query strings render without being stored (`.claude/skills/netjes/references/caching-and-streaming.md`).
+- In the TypeScript configs `netjes new` writes, `tsconfig.app.json` checks the app's code without Node's types, so a component or page that reads `process` or imports `node:*` fails `npm run typecheck`. Code that runs only in Node goes in `scripts/`, which `tsconfig.node.json` checks with them; do not add `node` to the `types` of `tsconfig.app.json`.
+- An `error.tsx` renders `error.message` only when `!error.withheld`, and shows `error.status ?? 500` if it shows a status.
+- `Netjes:PublicConfig` is sent to the browser: never put secrets there. So is the route of each endpoint with an `endpointUrl` key, one mapped only in Development included, once any component calls `endpointUrl`: keep secrets out of routes, and authorize on the endpoint ([security](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/security.md#errors-and-configuration)).
 - Write the failing test first, then the change.
 
 ## Before you finish
 
+<!--netjes:if tests-->
+```bash
+npm test && npm run typecheck && dotnet build && dotnet test tests/__NAME__.Tests && npx netjes generate --check
+```
+<!--netjes:else-->
 ```bash
 npm test && npm run typecheck && dotnet build && npx netjes generate --check
 ```
 
+No C# test project was at `tests/__NAME__.Tests/` when this file was written. If the app has C# tests elsewhere, run them too; [testing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/testing.md#c-tests-of-loaders-and-actions) says how to add a project there. After adding one, run `npx netjes agents --force`, which writes this file again with it, and `CLAUDE.md` and `.claude/skills/netjes/` too; keep your own additions to them with `git diff`.
+<!--netjes:end-->
+
 Then `npm run routes` should print no warnings, and the page should work in `npm run dev`, including with JavaScript turned off for forms.
+<!--netjes:if e2e-->
+
+For a change to a page or a form, also run `npm run test:e2e`.
+<!--netjes:end-->

package/template/__NAME__.csproj

@@ -5,6 +5,8 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <!-- The SDK compiles everything below this file: the C# tests and the Playwright specs have builds of their own. -->
+    <DefaultItemExcludes>$(DefaultItemExcludes);tests/**;e2e/**</DefaultItemExcludes>
   </PropertyGroup>
 
 <!--NETJES_REFERENCES-->

package/template/app/document.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment node
+// The home page's whole document, as the server sends it to a crawler, from the props its C# loader returns
+// (Features/Home/HomePage.cs). renderDocument renders without a DOM, as the server does, hence the node environment.
+import { CSP_SCRIPT_HASHES } from 'netjes';
+import { inlineScriptHashes, renderDocument } from 'netjes/testing';
+import { describe, expect, it } from 'vitest';
+
+const home = () =>
+  renderDocument('app/page.tsx', {
+    props: { message: 'Hello from C#', renderedAt: '2026-11-05T12:00:00Z' },
+    shared: { siteName: '__TITLE__' },
+  });
+
+describe('the home page', () => {
+  it("is a document with the loader's heading, inside the root layout", async () => {
+    const html = await home();
+
+    expect(html.startsWith('<!DOCTYPE html><html lang="en">')).toBe(true);
+    expect(html).toMatch(/<h1[^>]*>Hello from C#<\/h1>/);
+    expect(html).toContain('<nav aria-label="Main"');
+  });
+
+  it('has no inline script in its document but the one whose hash Netjes lists for a policy without a nonce', async () => {
+    // NetjesContentSecurityPolicy.ScriptHashes in C# holds the same hashes. The inline code of an afterInteractive or
+    // lazyOnload <Script> is added in the browser and is in no document: its hash goes in the policy, not here. That of
+    // a beforeInteractive <Script> is in the document: its hash goes in both.
+    expect(await inlineScriptHashes(await home())).toEqual(CSP_SCRIPT_HASHES.split(' '));
+  });
+});

package/template/app/error.tsx

@@ -5,8 +5,9 @@ export default function ErrorPage({ error, reset }: ErrorPageProps) {
   return (
     <section role="alert" className="space-y-4">
       <h1 className="text-3xl font-bold tracking-tight">Something went wrong</h1>
-      {/* In development the message can take several lines: a syntax error comes with a code frame. */}
-      <p className="whitespace-pre-wrap wrap-anywhere text-slate-600">{error.message}</p>
+      {/* Withheld: a stand-in for a message Netjes does not show, such as an exception's with error details off. A
+          message can take several lines: in development a syntax error comes with a code frame. */}
+      {!error.withheld && <p className="whitespace-pre-wrap wrap-anywhere text-slate-600">{error.message}</p>}
       <button type="button" onClick={reset} className="cursor-pointer rounded-full bg-slate-900 px-4 py-2 font-medium text-white">
         Try again
       </button>

package/template/app/layout.tsx

@@ -14,6 +14,15 @@ export default function RootLayout({ children }: LayoutProps) {
   const site = useSharedProps(sharedProps);
   return (
     <div className="mx-auto min-h-screen max-w-3xl px-6 py-10 font-sans text-slate-900">
+      {/* The first element Tab reaches, after a page load and after every client navigation, when the router starts
+          the focus over at the top of the document. It points to a place on this page, which needs no prefetch. */}
+      <Link
+        href="#content"
+        prefetch="none"
+        className="sr-only focus:not-sr-only focus:fixed focus:top-3 focus:left-3 focus:z-50 focus:rounded focus:bg-white focus:px-4 focus:py-2 focus:shadow"
+      >
+        Skip to content
+      </Link>
       <header className="mb-12 flex items-baseline justify-between">
         <Link href="/" className="text-xl font-semibold no-underline">
           {site.siteName}
@@ -27,7 +36,7 @@ export default function RootLayout({ children }: LayoutProps) {
           </Link>
         </nav>
       </header>
-      <main>{children}</main>
+      <main id="content">{children}</main>
     </div>
   );
 }

package/template/docker-compose.override.yml

@@ -1,11 +1,12 @@
-# Development: dotnet watch for C#, the Vite dev server for pages (HMR on 5173). Open http://localhost:8080.
-# Both ports are bound to localhost only: dev error pages show stack traces and Vite serves the source.
+# Development: dotnet watch for C#, the Vite dev server for pages (HMR on 5173). Open http://localhost:8080, or the port
+# APP_PORT names. Both ports are bound to localhost only: dev error pages show stack traces and Vite serves the source.
 services:
   app:
     build:
       target: dev
     ports:
-      - "127.0.0.1:8080:8080"
+      # The host's port for the app: APP_PORT, from the shell or a .env file next to this file, or 8080. Vite keeps 5173.
+      - "127.0.0.1:${APP_PORT:-8080}:8080"
       - "127.0.0.1:5173:5173"
     volumes:
       - .:/src

package/template/docker-compose.prod.yml

@@ -3,7 +3,8 @@ services:
   app:
     restart: always
     ports:
-      - "8080:8080"
+      # The host's port: APP_PORT, from the shell or a .env file next to this file, or 8080.
+      - "${APP_PORT:-8080}:8080"
     read_only: true
     tmpfs:
       - /tmp

package/template/e2e/home.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from '@playwright/test';
+
+// These tests pass with or without hydration: a link and a form work before the client router runs. A test that needs
+// the client, such as one that clicks a button with an onClick handler, first waits for it after each full page load:
+//   await expect(page.locator('html')).toHaveAttribute('data-netjes-hydrated', '');
+
+test('the home page shows the message from its C# loader', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Hello from C#');
+});
+
+test('the link on the home page leads to the about page', async ({ page }) => {
+  await page.goto('/');
+
+  await page.getByRole('link', { name: 'About this app' }).click();
+
+  await expect(page).toHaveURL('/about');
+  await expect(page.getByRole('heading', { level: 1 })).toHaveText('About');
+});
+
+test.describe('with JavaScript turned off', () => {
+  test.use({ javaScriptEnabled: false });
+
+  test('the form asks for the name it did not get', async ({ page }) => {
+    await page.goto('/');
+
+    await page.getByRole('button', { name: 'Say hello' }).click();
+
+    await expect(page.getByText('Tell us your name.')).toBeVisible();
+  });
+});

package/template/generated/netjes.ts

@@ -1,8 +1,19 @@
 // Generated by Netjes from the app's C# types and page files. Do not edit: the app rewrites it when it starts in
 // Development, and `netjes generate` writes it for CI (`netjes generate --check` fails when it is out of date).
-import { buildHref, isRouteHref, serverAction, type SearchParamsInput } from 'netjes';
+import { buildEndpointUrl, buildHref, isRouteHref, serverAction, type SearchParamsInput } from 'netjes';
 import { z } from 'zod';
 
+/** Every page's URL pattern. */
+export const routePatterns = ["/", "/about"] as const;
+
+/** Whether a URL that comes from data (a CMS, shared props) is one of the app's pages or another site. */
+export function isHref(value: string): value is Href {
+  return isRouteHref(value, routePatterns);
+}
+
+/** Checks such a URL at the boundary: `<Link href={Href.parse(item.href)}>`. The schemas below use it for each C# `Netjes.Href`. */
+export const Href = z.custom<Href>((value) => typeof value === 'string' && isHref(value), 'Not a URL this app serves');
+
 export const HomeProps = z.object({
   message: z.string(),
   renderedAt: z.iso.datetime({ offset: true, local: true }),
@@ -29,6 +40,29 @@ export const sharedProps = SiteProps;
 /** JSON endpoints by method and route: what they accept and return. */
 export const api = {} as const;
 
+/**
+ * What the app's endpoints read from their URLs, by method and route as in `api`: the route values, then the
+ * query string values the handler binds. A JSON endpoint has a key for each of its methods except HEAD, and any
+ * other endpoint one for GET, if it answers GET.
+ */
+export type EndpointParams = Record<never, never>;
+export type EndpointKey = keyof EndpointParams;
+const endpointTemplates: Record<EndpointKey, string> = {};
+
+/**
+ * The URL of one of the app's endpoints, with its values encoded: `endpointUrl('GET /api/posts/{slug}/likes/', { slug })`.
+ * The values the route does not name go in the query string, followed by the third argument. The URL has no base
+ * path: pass it through `useHref` for a `fetch` or an `<a href>`.
+ */
+export function endpointUrl<K extends EndpointKey>(
+  key: K,
+  ...args: {} extends EndpointParams[K]
+    ? [params?: EndpointParams[K], search?: SearchParamsInput]
+    : [params: EndpointParams[K], search?: SearchParamsInput]
+): string {
+  return buildEndpointUrl(endpointTemplates[key], args[0] ?? {}, args[1], key);
+}
+
 /** Form fields of page actions (`MapPageAction`), by page pattern. */
 export const forms = {} as const;
 
@@ -48,23 +82,18 @@ export type Route = '/' | '/about';
 /** What `<Link href>` and `router.push` accept: the app's routes, with a query or fragment, or another site. */
 export type Href = Route | `${Route}?${string}` | `${Route}#${string}` | `?${string}` | `#${string}` | `http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}`;
 
-/** The URL of a page, with its parameters encoded: `route('/blog/[slug]', { slug })`. */
+/**
+ * The URL of a page, with its parameters encoded: `route('/blog/[slug]', { slug })`. The third argument is the
+ * query, and `{ hash }` in the fourth adds a fragment: `route('/docs/[...path]', { path }, undefined, { hash: 'keys' })`.
+ */
 export function route<P extends RoutePattern>(
   pattern: P,
-  ...args: {} extends RouteParams[P] ? [params?: RouteParams[P], search?: SearchParamsInput] : [params: RouteParams[P], search?: SearchParamsInput]
+  ...args: {} extends RouteParams[P]
+    ? [params?: RouteParams[P], search?: SearchParamsInput, options?: { hash?: string | undefined }]
+    : [params: RouteParams[P], search?: SearchParamsInput, options?: { hash?: string | undefined }]
 ): Href {
-  return buildHref(pattern, args[0] ?? {}, args[1]) as Href;
+  return buildHref(pattern, args[0] ?? {}, args[1], args[2]) as Href;
 }
-/** Every page's URL pattern. */
-export const routePatterns = ["/", "/about"] as const;
-
-/** Whether a URL that comes from data (a CMS, shared props) is one of the app's pages or another site. */
-export function isHref(value: string): value is Href {
-  return isRouteHref(value, routePatterns);
-}
-
-/** Checks such a URL at the boundary: `<Link href={Href.parse(item.href)}>`. */
-export const Href = z.custom<Href>((value) => typeof value === 'string' && isHref(value), 'Not a URL this app serves');
 
 declare module 'netjes' {
   interface Register {

package/template/package.json

@@ -9,7 +9,8 @@
     "dev": "netjes dev",
     "build": "vite build && vite build --ssr",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:e2e": "dotnet build && playwright test",
+    "typecheck": "tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.node.json --noEmit",
     "generate": "netjes generate",
     "routes": "netjes routes"
   },
@@ -21,10 +22,12 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@playwright/test": "^1.64.1",
     "@tailwindcss/vite": "^4.3.3",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.8",
+    "@types/node": "^22.20.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^30.1.3",

package/template/playwright.config.ts

@@ -0,0 +1,36 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Each project runs the app as its own ASP.NET Core process: one in Development (the Vite dev server) and one in
+// Production (the `npm run build` output). `npm run test:e2e` builds the .NET app first; install the browser once with
+// `npx playwright install chromium`. E2E_DEV_PORT, E2E_PROD_PORT and E2E_VITE_PORT move the ports, so that several runs
+// can share a machine. With CI set, Playwright always starts fresh servers; otherwise it reuses one that is listening.
+const DEV_URL = `http://127.0.0.1:${process.env['E2E_DEV_PORT'] ?? '5090'}`;
+const PROD_URL = `http://127.0.0.1:${process.env['E2E_PROD_PORT'] ?? '5091'}`;
+const VITE_PORT = process.env['E2E_VITE_PORT'] ?? '5190';
+
+export default defineConfig({
+  testDir: './e2e',
+  forbidOnly: !!process.env['CI'],
+  retries: process.env['CI'] ? 1 : 0,
+  use: { ...devices['Desktop Chrome'], trace: 'retain-on-failure' },
+  projects: [
+    { name: 'development', use: { baseURL: DEV_URL } },
+    { name: 'production', use: { baseURL: PROD_URL } },
+  ],
+  webServer: [
+    {
+      command: 'dotnet run --no-build --no-launch-profile',
+      url: `${DEV_URL}/healthz`,
+      env: { ASPNETCORE_ENVIRONMENT: 'Development', ASPNETCORE_URLS: DEV_URL, Netjes__ViteDevPort: VITE_PORT },
+      reuseExistingServer: !process.env['CI'],
+      timeout: 120_000,
+    },
+    {
+      command: 'npm run build && dotnet run --no-build --no-launch-profile',
+      url: `${PROD_URL}/healthz`,
+      env: { ASPNETCORE_ENVIRONMENT: 'Production', ASPNETCORE_URLS: PROD_URL },
+      reuseExistingServer: !process.env['CI'],
+      timeout: 180_000,
+    },
+  ],
+});