netjes 0.0.0-stage → 0.0.2

package/skills/netjes/references/routing.md

@@ -0,0 +1,65 @@
+# Routing
+
+ASP.NET Core does the routing: every page file becomes an endpoint with an ordinary route template, so precedence, constraints and conventions such as `RequireAuthorization()` work as for any minimal API. The browser never matches routes itself.
+
+## Files in `app/`
+
+| 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. |
+| `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. |
+| `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. |
+
+Built-in pages stand in for missing boundary files.
+
+## Folders
+
+| Folder | URL |
+|---|---|
+| `blog/[slug]` | `/blog/{slug}`: one segment |
+| `docs/[...path]` | `/docs/a/b`: one or more segments; the loader gets them joined by `/` |
+| `docs/[[...path]]` | `/docs` and anything below it |
+| `(group)` | No URL segment: groups pages under a shared layout (`app/(marketing)/layout.tsx`) |
+| `_private` | Not routed: components that live next to the pages |
+| `@slot` + `default.tsx` | A parallel route: the layout gets the slot as a prop |
+| `@modal/(.)photo/[id]` | An intercepting route, inside a slot only: a client navigation shows it in the slot, a reload shows the real page |
+
+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`).
+
+## 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.
+
+## 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`.
+- `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.
+- External URLs, `target`, `download` and modified clicks behave like a plain `<a>`; `reloadDocument` forces a full load.
+
+## 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.
+- 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).
+
+## 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.
+
+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.
+
+## 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.

package/skills/netjes/references/testing.md

@@ -0,0 +1,57 @@
+# Testing
+
+Test first: write the test, watch it fail for the reason you expect, then change the code. Assert what a user or a browser can observe (rendered text, roles, URLs, status codes, the props a page receives), not internals.
+
+## 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`.
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createTestApp } from 'netjes/testing';
+import { expect, it } from 'vitest';
+import { HelloForm } from './HelloForm.tsx';
+
+it('shows the validation error from C# next to the field', async () => {
+  const app = createTestApp({
+    actions: { 'home.greet': () => ({ ok: false, status: 422, errors: { name: ['Tell us your name.'] } }) },
+  });
+  render(<HelloForm />, { wrapper: app.Wrapper });
+
+  await userEvent.click(screen.getByRole('button', { name: 'Say hello' }));
+
+  expect(await screen.findByText('Tell us your name.')).toBeDefined();
+});
+```
+
+`createTestApp({ url, params, shared, queries, 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".
+- `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: ...`.
+
+## Loaders and actions: C#
+
+- 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.
+- 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.
+
+## Before calling a change done
+
+```bash
+npm test && npm run typecheck && dotnet build && npx netjes generate --check
+```
+
+and `npm run routes` without new warnings.
+
+## 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).

package/src/actions.tsx

@@ -0,0 +1,241 @@
+import { useActionState, useMemo } from 'react';
+import { encodeForm } from './form-data.ts';
+import { ANTIFORGERY_HEADER, type ActionResponse, type AntiforgeryToken, COOKIES_HEADER, DATA_HEADER, parseActionResponse } from './payload.ts';
+import { usePagePayload } from './router.tsx';
+import { type StandardSchemaV1, parseWith } from './schema.ts';
+
+/**
+ * What a server action resolves to: its result, or the validation errors (status 422) per field. An action typed with
+ * a result can still answer `ServerAction.Redirect(...)` (then `result` is undefined and the router has already moved
+ * on), so code that runs after `await action(...)` in a component that may stay mounted should not assume one.
+ */
+export type ActionState<TResult> =
+  | { ok: true; result: TResult }
+  | { ok: false; status: number; errors: Record<string, string[]>; values?: Record<string, string | string[]> };
+
+/**
+ * A reference to a C# server action (`app.MapAction(name, ...)`). Call it with a plain object (sent as JSON) or
+ * FormData (sent as a form post); use it in a form through {@link useAction}.
+ */
+export interface ServerAction<TInput, TResult> {
+  (input: TInput | FormData): Promise<ActionState<TResult>>;
+  readonly actionName: string;
+  readonly url: string;
+}
+
+/** Thrown into the nearest error boundary when the server could not run the action (not for validation errors). */
+export class ServerActionError extends Error {
+  override name = 'ServerActionError';
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.status = status;
+  }
+}
+
+/** Runs action calls for the page: the router in the browser (fetch, then redirect/refresh/query updates), a fake in tests. */
+export type ActionClient = {
+  invoke(name: string, url: string, input: unknown): Promise<ActionResponse>;
+  /** The antiforgery form field, left out of the values a failed call hands back. */
+  tokenField?(): string | undefined;
+};
+
+let client: ActionClient | null = null;
+
+/**
+ * Set from the moment a router renders until it registers: React dispatches the clicks that came in while it hydrated
+ * the page before it runs the router's effects, and runs a page's own effects before its router's. Calls made then
+ * wait here.
+ */
+let arriving: { ready: Promise<void>; resolve: () => void } | null = null;
+
+/** A router is mounting (called as it first renders, in the browser): calls from now on wait until it registers. */
+export function expectActionClient(): void {
+  if (arriving) return;
+  let resolve = () => {};
+  const ready = new Promise<void>((done) => {
+    resolve = done;
+  });
+  arriving = { ready, resolve };
+}
+
+/** The router registers itself; there is one per page in the browser. */
+export function setActionClient(next: ActionClient | null): () => void {
+  client = next;
+  if (next && arriving) {
+    arriving.resolve();
+    arriving = null;
+  }
+  return () => {
+    if (client === next) client = null;
+  };
+}
+
+/** How long a call waits for the router on its way; one whose render React threw away never registers. */
+const READY_TIMEOUT_MS = 10_000;
+
+/**
+ * The registered client, once the router on its way has registered; the error without a router on its way, or when it
+ * has not registered in time.
+ */
+async function readyClient(name: string): Promise<ActionClient> {
+  const waitingFor = arriving;
+  if (!client && waitingFor) {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timedOut = new Promise<'timeout'>((resolve) => {
+      timer = setTimeout(() => resolve('timeout'), READY_TIMEOUT_MS);
+    });
+    // Given up on, so that later calls fail at once.
+    if ((await Promise.race([waitingFor.ready, timedOut])) === 'timeout' && arriving === waitingFor) arriving = null;
+    clearTimeout(timer);
+  }
+  if (!client) throw new Error(`netjes: server action ${name} was called before the page was ready`);
+  return client;
+}
+
+export const RETURN_FIELD = '__netjes_return';
+const ACTION_META = Symbol.for('netjes.action');
+
+type ActionMeta = { url: string; name: string };
+
+/** The action URL and name a form action carries, so `<Form>` can render a real form post on the server. */
+export function actionMetaOf(action: unknown): ActionMeta | undefined {
+  return typeof action === 'function' ? (action as { [ACTION_META]?: ActionMeta })[ACTION_META] : undefined;
+}
+
+/**
+ * The fields of a rejected form, as the failure state's `values`: React resets a form after its action runs, so a
+ * `defaultValue={state.values.name}` is what keeps what the user typed. Files, the token and Netjes's own fields are
+ * left out, and so is anything outside `fields`: the server names the fields a post without JavaScript would echo
+ * (those the action declares, none private).
+ */
+function submittedValues(
+  input: unknown,
+  tokenField: string | undefined,
+  fields: readonly string[] | undefined,
+): Record<string, string | string[]> | undefined {
+  if (!(input instanceof FormData)) return undefined;
+  const values: Record<string, string | string[]> = {};
+  for (const [key, value] of input.entries()) {
+    if (typeof value !== 'string' || key === tokenField || key.startsWith('__netjes_')) continue;
+    if (fields && !fields.includes(key)) continue;
+    const existing = values[key];
+    values[key] = existing === undefined ? value : Array.isArray(existing) ? [...existing, value] : [existing, value];
+  }
+  return values;
+}
+
+export function actionRequest(input: unknown, token: AntiforgeryToken | undefined, returnUrl: string): RequestInit {
+  const headers: Record<string, string> = { [DATA_HEADER]: '1', Accept: 'application/json' };
+  if (token?.headerName && token.requestToken) headers[token.headerName] = token.requestToken;
+  if (input instanceof FormData) {
+    if (!input.has(RETURN_FIELD)) input.append(RETURN_FIELD, returnUrl);
+    const encoded = encodeForm(input);
+    if (encoded.contentType) headers['Content-Type'] = encoded.contentType;
+    return { method: 'POST', headers, body: encoded.body, credentials: 'same-origin' };
+  }
+  headers['Content-Type'] = 'application/json';
+  return { method: 'POST', headers, body: JSON.stringify(input ?? {}), credentials: 'same-origin' };
+}
+
+/**
+ * The fetch half of a call, for the router's action client. `tokenRefused` says the server refused the call's
+ * antiforgery token, so the action did not run; no other answer says that, whatever its status. `onCookiesChanged`
+ * runs as soon as the server says the call set or deleted a cookie (signed someone in or out), which script cannot
+ * see in the response itself, whatever the rest of the answer turns out to be.
+ */
+export async function fetchAction(
+  name: string,
+  url: string,
+  init: RequestInit,
+  onCookiesChanged?: () => void,
+): Promise<{ response: ActionResponse; tokenRefused: boolean }> {
+  const response = await fetch(url, init);
+  if (response.headers.get(COOKIES_HEADER) === 'changed') onCookiesChanged?.();
+  const type = response.headers.get('content-type') ?? '';
+  if (!type.includes('application/json')) throw new ServerActionError(`Server action ${name} failed with status ${response.status}`, response.status);
+  return { response: parseActionResponse(await response.json()), tokenRefused: response.headers.get(ANTIFORGERY_HEADER) === 'invalid' };
+}
+
+/**
+ * Declares a server action by name. The result is parsed with `options.result` when given (zod, valibot, ...).
+ * `npx netjes generate` writes these for every `MapAction`, with types from the C# signature.
+ */
+export function serverAction<TInput = FormData, TResult = unknown>(
+  name: string,
+  options: { result?: StandardSchemaV1<unknown, TResult> } = {},
+): ServerAction<TInput, TResult> {
+  const url = `/_netjes/actions/${name}`;
+  async function call(input: TInput | FormData): Promise<ActionState<TResult>> {
+    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);
+    }
+    if (!answer.ok) {
+      const values = submittedValues(input, active.tokenField?.(), answer.fields);
+      return { ok: false, status: answer.status, errors: answer.errors ?? {}, ...(values ? { values } : {}) };
+    }
+    // `ServerAction.Redirect(...)` and `Ok()` send no result, even from an action whose C# type promises one.
+    const result =
+      options.result && answer.result !== undefined ? parseWith(options.result, answer.result, `result of ${name}`) : (answer.result as TResult);
+    return { ok: true, result };
+  }
+  return Object.assign(call, { actionName: name, url });
+}
+
+/** Options for `useAction`. */
+export type UseActionOptions<TResult> = {
+  /** The state before the first submission. Default null. */
+  initialState?: ActionState<TResult> | null;
+  /**
+   * Called with the form's data inside the action's transition, just before the call to the server: the place for
+   * `useOptimistic` updates, which React keeps until the action (and the page refresh after it) finishes.
+   */
+  onSubmit?: (formData: FormData) => void;
+};
+
+/**
+ * `useActionState` for a server action: `[state, formAction, isPending]`. Pass `formAction` to `<Form action>`;
+ * `useFormStatus` works as usual, and `onSubmit` is where optimistic updates go. After a failed post without
+ * JavaScript, the state starts as that failure, with the submitted values.
+ */
+export function useAction<TInput, TResult>(
+  action: ServerAction<TInput, TResult>,
+  options: UseActionOptions<TResult> = {},
+): [state: ActionState<TResult> | null, formAction: (formData: FormData) => void, isPending: boolean] {
+  const { actionState } = usePagePayload();
+  const initial: ActionState<TResult> | null =
+    actionState?.action === action.actionName
+      ? { ok: false, status: 422, errors: actionState.errors, values: actionState.values }
+      : (options.initialState ?? null);
+  const { onSubmit } = options;
+  const [state, dispatch, pending] = useActionState((_previous: ActionState<TResult> | null, formData: FormData) => {
+    onSubmit?.(formData);
+    return action(formData);
+  }, initial);
+  if (!(ACTION_META in dispatch)) {
+    Object.defineProperty(dispatch, ACTION_META, { value: { url: action.url, name: action.actionName } satisfies ActionMeta });
+  }
+  return [state, dispatch, pending];
+}
+
+/** A page action's failure, in the shape of `useAction`'s failure state. */
+export type PageActionFailure = { ok: false; status: number; errors: Record<string, string[]>; values: Record<string, string | string[]> };
+
+/**
+ * After the input of the page's action (`MapPageAction`) failed its checks, its DataAnnotations or
+ * `IValidatableObject`: the errors per field and the submitted values of the fields the action declares, as the page
+ * is rendered again from its loader, with and without JavaScript. Else null, also after a server action's failure,
+ * which `useAction` reads.
+ */
+export function usePageActionState(): PageActionFailure | null {
+  const { actionState, route } = usePagePayload();
+  return useMemo(
+    () =>
+      actionState && route !== null && actionState.action === route
+        ? { ok: false, status: 422, errors: actionState.errors, values: actionState.values }
+        : null,
+    [actionState, route],
+  );
+}

package/src/client-entry.tsx

@@ -0,0 +1,126 @@
+// Must come first: installs the React Fast Refresh runtime before any component module runs (empty in builds).
+import '@vitejs/plugin-react/preamble';
+import { createRoot, hydrateRoot } from 'react-dom/client';
+import { pages } from 'virtual:netjes/pages';
+import { deferredRegistry, revivePayload } from './deferred.ts';
+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';
+
+/**
+ * The payload is the body's first element, so it is normally parsed by the time this async script runs. If the
+ * script won the race, wait for the element rather than for the whole (streaming) document.
+ */
+function payloadElement(): Promise<HTMLElement | null> {
+  // Complete once the parser has moved past it (a large payload can arrive in several chunks).
+  const complete = () => {
+    const element = document.getElementById(DATA_ELEMENT_ID);
+    return element && (element.nextSibling || document.readyState !== 'loading') ? element : null;
+  };
+  const found = complete();
+  if (found || document.readyState !== 'loading') return Promise.resolve(found ?? document.getElementById(DATA_ELEMENT_ID));
+  return new Promise((resolve) => {
+    const observer = new MutationObserver(() => {
+      const element = complete();
+      if (element) {
+        observer.disconnect();
+        resolve(element);
+      }
+    });
+    observer.observe(document, { childList: true, subtree: true });
+    document.addEventListener('DOMContentLoaded', () => {
+      observer.disconnect();
+      resolve(document.getElementById(DATA_ELEMENT_ID));
+    });
+  });
+}
+
+/**
+ * Resolves once the parser has passed the end of the shell, the empty element `Document` writes last in the body.
+ * This script is async, so a cached copy can run as soon as the payload is in, before most of the page is: hydrating
+ * then would meet half a document, give up and render the page in the browser, and the parser would add the rest of
+ * the server's HTML below it, so the page would show twice.
+ */
+function shellParsed(): Promise<void> {
+  if (document.getElementById(SHELL_END_ID) || document.readyState !== 'loading') return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      observer.disconnect();
+      document.removeEventListener('DOMContentLoaded', done);
+      resolve();
+    };
+    const observer = new MutationObserver(() => {
+      if (document.getElementById(SHELL_END_ID)) done();
+    });
+    observer.observe(document, { childList: true, subtree: true });
+    document.addEventListener('DOMContentLoaded', done);
+  });
+}
+
+const dataJson = (await payloadElement())?.textContent;
+if (!dataJson) throw new Error(`netjes: #${DATA_ELEMENT_ID} is missing; was this page rendered by Netjes?`);
+
+// Page.Defer values the server streamed in before this script ran, and from now on, the ones still to come.
+type DeferredGlobals = { __netjes_v?: unknown; __netjes_d?: (id: string, value: unknown, error?: string) => void };
+const globals = self as unknown as DeferredGlobals;
+const deferred = deferredRegistry();
+const settle = (id: string, value: unknown, error?: string) => (error === undefined || error === null ? deferred.resolve(id, value) : deferred.reject(id, error));
+
+/**
+ * The values the head bootstrap collected: its own plain object, `{ id: [value, error] }`. Anything else is page
+ * markup standing in for the global (an element with `id="__netjes_v"`), and must not stop the page from hydrating.
+ */
+function collectedValues(collected: unknown): [string, unknown][] {
+  if (typeof collected !== 'object' || collected === null) return [];
+  const prototype: unknown = Object.getPrototypeOf(collected);
+  return prototype === Object.prototype || prototype === null ? Object.entries(collected) : [];
+}
+for (const [id, entry] of collectedValues(globals.__netjes_v)) {
+  if (Array.isArray(entry)) settle(id, entry[0], typeof entry[1] === 'string' ? entry[1] : undefined);
+}
+globals.__netjes_d = settle;
+
+const parsed = revivePayload(parseInitialPayload(JSON.parse(dataJson)), deferred.source);
+// Judge the server's seeded data as fresh as the server did when it rendered, so hydration matches.
+const payload = withClockOffset(parsed, parsed.renderedAt);
+const loader = createModuleLoader(pages, { nameFailedImports: true });
+
+/** How long the first page waits before it tries a module that failed to load once more. */
+const RETRY_DELAY_MS = 500;
+
+/**
+ * The first page's modules. One that fails to load (a dropped request, a deploy that removed its chunk) gets one more
+ * try, which the browser fetches again. If that fails too, the page stays as the server sent it, without the client
+ * router: its links and forms are plain HTML, and the browser loads each in full.
+ */
+async function firstPageModules(): Promise<RouteModules | null> {
+  try {
+    return await loader.loadRoute(payload);
+  } catch {
+    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+  }
+  try {
+    return await loader.loadRoute(payload);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : `netjes: the page's modules could not be loaded (${String(error)})`;
+    const outcome = payload.document.clientRender
+      ? 'the page cannot render without it'
+      : 'the page stays as the server rendered it, without the client router, and its links and forms load pages in full';
+    console.error(`${reason}: ${outcome}`, error);
+    return null;
+  }
+}
+
+const modules = await firstPageModules();
+if (modules) {
+  const root = <Root payload={payload} modules={modules} loader={loader} dataJson={dataJson} />;
+  if (payload.document.clientRender) {
+    // No sidecar was ready, so the server sent the document without the page: there is nothing to hydrate. React keeps
+    // the scripts and stylesheets already in it and replaces the rest.
+    createRoot(document).render(root);
+  } else {
+    await shellParsed();
+    hydrateRoot(document, root);
+  }
+}

package/src/deferred.ts

@@ -0,0 +1,134 @@
+// 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 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. */
+export type Thenable<T> = Promise<T> & { status?: 'pending' | 'fulfilled' | 'rejected'; value?: T; reason?: unknown };
+
+export type Deferred<T> = { promise: Thenable<T>; resolve(value: T): void; reject(reason: unknown): void };
+
+export function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise: Thenable<T> = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  promise.status = 'pending';
+  return {
+    promise,
+    resolve(value) {
+      if (promise.status !== 'pending') return;
+      promise.status = 'fulfilled';
+      promise.value = value;
+      resolve(value);
+    },
+    reject(reason) {
+      if (promise.status !== 'pending') return;
+      promise.status = 'rejected';
+      promise.reason = reason;
+      reject(reason);
+    },
+  };
+}
+
+/** Where revived placeholders get their promise from, by id. */
+export type DeferredSource = (id: string) => Thenable<unknown>;
+
+function isPlaceholder(value: object): value is { $netjes: 'deferred'; id: string } {
+  return (value as Record<string, unknown>).$netjes === 'deferred' && typeof (value as Record<string, unknown>).id === 'string';
+}
+
+/** Replaces every `{ $netjes: 'deferred', id }` in a JSON value; returns the same object when there are none. */
+export function reviveDeferred(value: unknown, source: DeferredSource): unknown {
+  if (typeof value !== 'object' || value === null) return value;
+  if (Array.isArray(value)) {
+    let changed = false;
+    const items = value.map((item) => {
+      const revived = reviveDeferred(item, source);
+      if (revived !== item) changed = true;
+      return revived;
+    });
+    return changed ? items : value;
+  }
+  if (isPlaceholder(value)) return source(value.id);
+  let changed = false;
+  const entries = Object.entries(value).map(([key, item]) => {
+    const revived = reviveDeferred(item, source);
+    if (revived !== item) changed = true;
+    return [key, revived] as const;
+  });
+  // Keys are defined, not assigned: JSON.parse keeps "__proto__" as a key, and assigning it would set the prototype.
+  return changed ? Object.fromEntries(entries) : value;
+}
+
+/** Revives the placeholders in a page's props and its segments' props. */
+export function revivePayload<T extends PagePayload>(payload: T, source: DeferredSource): T {
+  const props = reviveDeferred(payload.props, source) as Record<string, unknown>;
+  let segmentsChanged = false;
+  const segments = payload.segments.map((segment): SegmentRef => {
+    if (!segment.props) return segment;
+    const revived = reviveDeferred(segment.props, source) as Record<string, unknown>;
+    if (revived === segment.props) return segment;
+    segmentsChanged = true;
+    return { ...segment, props: revived };
+  });
+  return props === payload.props && !segmentsChanged ? payload : { ...payload, props, segments };
+}
+
+/** A source that hands out one deferred per id and settles it when the value arrives. */
+export function deferredRegistry() {
+  const entries = new Map<string, Deferred<unknown>>();
+  const entry = (id: string) => {
+    let found = entries.get(id);
+    if (!found) {
+      found = createDeferred<unknown>();
+      // Unread values must not surface as unhandled rejections.
+      found.promise.catch(() => {});
+      entries.set(id, found);
+    }
+    return found;
+  };
+  return {
+    source: ((id) => entry(id).promise) as DeferredSource,
+    resolve(id: string, value: unknown) {
+      entry(id).resolve(value);
+    },
+    reject(id: string, message: string) {
+      entry(id).reject(new Error(message));
+    },
+    /** Rejects every value still pending, e.g. when the stream that was to deliver them ended. */
+    rejectPending(message: (id: string) => string) {
+      for (const [id, deferred] of entries) {
+        if (deferred.promise.status === 'pending') deferred.reject(new Error(message(id)));
+      }
+    },
+  };
+}
+
+/**
+ * Inline in every document: collects deferred values streamed as `<script>self.__netjes_d(id, value, error)</script>`
+ * until the client entry takes over (it replaces `__netjes_d`). The async client entry can run first, so this never
+ * replaces a handler that is already there. It creates `__netjes_v` up front, as a window property of its own: until
+ * then, page markup with `id="__netjes_v"` would be what that name reads (DOM clobbering).
+ */
+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={})";
+
+const UNSAFE = /[<>&\u2028\u2029]/g;
+
+/** JSON that can sit inside a <script> element. */
+export function htmlSafeJson(value: unknown): string {
+  return (JSON.stringify(value) ?? 'null').replace(UNSAFE, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/** The script that hands one deferred value (or its error) to the browser. */
+export function deferredScript(id: string, value: unknown, error?: string, nonce?: string): string {
+  // The value goes as JSON text for JSON.parse, which reads it as the other paths do: as an object literal, a
+  // "__proto__" key would set the object's prototype instead.
+  const json = htmlSafeJson(JSON.stringify(value) ?? 'null');
+  const args = error === undefined ? `${htmlSafeJson(id)},JSON.parse(${json})` : `${htmlSafeJson(id)},null,${htmlSafeJson(error)}`;
+  // Under a CSP with nonces, inline scripts run only with the page's nonce (base64, but escaped all the same).
+  const attribute = nonce ? ` nonce="${nonce.replace(/[^A-Za-z0-9+/=_-]/g, '')}"` : '';
+  return `<script${attribute}>self.__netjes_d(${args})</script>`;
+}