netjes 0.0.0-stage → 0.0.2

package/src/schema.ts

@@ -0,0 +1,98 @@
+/** The Standard Schema interface (https://standardschema.dev), implemented by zod, valibot, arktype and others. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaV1.Result<Output> | Promise<StandardSchemaV1.Result<Output>>;
+    readonly types?: { readonly input: Input; readonly output: Output } | undefined;
+  };
+}
+
+export declare namespace StandardSchemaV1 {
+  type Result<Output> = { readonly value: Output; readonly issues?: undefined } | { readonly issues: ReadonlyArray<Issue> };
+  type Issue = { readonly message: string; readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined };
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
+function describeIssue(issue: StandardSchemaV1.Issue): string {
+  const path = issue.path?.map((segment) => String(typeof segment === 'object' ? segment.key : segment)).join('.');
+  return path ? `${path}: ${issue.message}` : issue.message;
+}
+
+function validateSync(schema: StandardSchemaV1, value: unknown, what: string) {
+  const result = schema['~standard'].validate(value);
+  if (result instanceof Promise) throw new Error(`netjes: async schemas are not supported for ${what}`);
+  return result;
+}
+
+function topLevelKey(issue: StandardSchemaV1.Issue): string | undefined {
+  const first = issue.path?.[0];
+  const key = typeof first === 'object' ? first.key : first;
+  return typeof key === 'string' ? key : undefined;
+}
+
+/**
+ * Like {@link parseWith}, for input visitors control: values the schema rejects are dropped (so defaults and
+ * optional fields apply) before giving up. Only a value that stays invalid without them throws.
+ */
+export function parseLenient<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  value: Record<string, unknown>,
+  what: string,
+): StandardSchemaV1.InferOutput<Schema> {
+  const input = { ...value };
+  // Each pass drops what the issues name; a schema that names one key at a time must not cost a pass per key.
+  for (let pass = 0; ; pass++) {
+    const result = validateSync(schema, input, what);
+    if (!result.issues) return result.value as StandardSchemaV1.InferOutput<Schema>;
+    if (pass >= MAX_PASSES) throw new Error(`Invalid ${what}: ${result.issues.map(describeIssue).join('; ')}`);
+    const rejected = result.issues.map(topLevelKey).filter((key): key is string => key !== undefined && key in input);
+    // Issues without a path, such as a strict object's unrecognized keys: the keys the issue lists (zod's do), else
+    // (for a handful of keys) one whose absence leaves fewer such issues.
+    const listed = rejected.length === 0 ? listedKeys(result.issues, input) : [];
+    const culprit = rejected.length === 0 && listed.length === 0 ? keyBehindPathlessIssues(schema, input, result.issues, what) : undefined;
+    const drop = rejected.length > 0 ? rejected : listed.length > 0 ? listed : culprit === undefined ? [] : [culprit];
+    if (drop.length === 0) throw new Error(`Invalid ${what}: ${result.issues.map(describeIssue).join('; ')}`);
+    for (const key of drop) delete input[key];
+  }
+}
+
+/** Keys a pathless issue names itself, like zod's `unrecognized_keys` (`issue.keys`). */
+function listedKeys(issues: readonly StandardSchemaV1.Issue[], input: Record<string, unknown>): string[] {
+  return issues.flatMap((issue) => {
+    const keys = topLevelKey(issue) === undefined ? (issue as { keys?: unknown }).keys : undefined;
+    return Array.isArray(keys) ? keys.filter((key): key is string => typeof key === 'string' && key in input) : [];
+  });
+}
+
+/** Above these, the search costs too much for input a visitor controls; the parse fails instead. */
+const MAX_SEARCHED_KEYS = 32;
+const MAX_PASSES = 64;
+
+function keyBehindPathlessIssues(
+  schema: StandardSchemaV1,
+  input: Record<string, unknown>,
+  issues: readonly StandardSchemaV1.Issue[],
+  what: string,
+): string | undefined {
+  const keys = Object.keys(input);
+  if (keys.length > MAX_SEARCHED_KEYS) return undefined;
+  const pathless = (list: readonly StandardSchemaV1.Issue[]) =>
+    new Set(list.filter((issue) => topLevelKey(issue) === undefined).map((issue) => issue.message));
+  const before = pathless(issues);
+  return keys.find((key) => {
+    const { [key]: _, ...rest } = input;
+    const result = validateSync(schema, rest, what);
+    if (!result.issues) return true;
+    // Only a removal that leaves a strict subset: dropping a key a refinement needs adds an issue instead.
+    const after = pathless(result.issues);
+    return after.size < before.size && [...after].every((message) => before.has(message));
+  });
+}
+
+/** Validates synchronously (rendering cannot wait) and throws `Invalid <what>: <issues>` when the value is rejected. */
+export function parseWith<Schema extends StandardSchemaV1>(schema: Schema, value: unknown, what: string): StandardSchemaV1.InferOutput<Schema> {
+  const result = validateSync(schema, value, what);
+  if (result.issues) throw new Error(`Invalid ${what}: ${result.issues.map(describeIssue).join('; ')}`);
+  return result.value as StandardSchemaV1.InferOutput<Schema>;
+}

package/src/script.tsx

@@ -0,0 +1,103 @@
+import { type ScriptHTMLAttributes, useEffect, useRef } from 'react';
+import { preinit } from 'react-dom';
+import { useNonce } from './nonce.tsx';
+
+/** When `<Script>` loads its script: before or after the page is interactive, or when the browser is idle. */
+export type ScriptStrategy = 'beforeInteractive' | 'afterInteractive' | 'lazyOnload';
+
+/** The props of `<Script>`: a script's own, with a loading strategy and load callbacks. */
+export type ScriptProps = Omit<ScriptHTMLAttributes<HTMLScriptElement>, 'onLoad' | 'onError' | 'children' | 'dangerouslySetInnerHTML'> & {
+  /** Identifies the script (required for inline scripts): each is added once, however often it is rendered. */
+  id?: string;
+  /**
+   * `afterInteractive` (default): once the page is interactive. `lazyOnload`: when the browser is idle.
+   * `beforeInteractive`: in the server-rendered head, before the page's own scripts (external scripts only).
+   */
+  strategy?: ScriptStrategy;
+  onLoad?: (event: Event) => void;
+  onError?: (event: Event) => void;
+  /** Inline code, instead of `src`. */
+  children?: string;
+};
+
+type Entry = { element: HTMLScriptElement; state: 'loading' | 'loaded' | 'failed'; event?: Event };
+
+/** Scripts already added to this document, by id or src. */
+const added = new Map<string, Entry>();
+
+function whenIdle(run: () => void) {
+  const schedule = () =>
+    typeof window.requestIdleCallback === 'function' ? window.requestIdleCallback(run) : window.setTimeout(run, 1);
+  if (document.readyState === 'complete') schedule();
+  else window.addEventListener('load', schedule, { once: true });
+}
+
+function add(key: string, { src, children, strategy: _strategy, id, onLoad: _onLoad, onError: _onError, ...attributes }: ScriptProps): Entry {
+  const element = document.createElement('script');
+  for (const [name, value] of Object.entries(attributes)) {
+    if (value === undefined || value === false || typeof value === 'function' || typeof value === 'object') continue;
+    element.setAttribute(name === 'className' ? 'class' : name === 'crossOrigin' ? 'crossorigin' : name, value === true ? '' : String(value));
+  }
+  if (id) element.id = id;
+  // The property, not the attribute: browsers hide nonce attributes once a policy applies.
+  if (attributes.nonce) element.nonce = attributes.nonce;
+  const entry: Entry = { element, state: 'loading' };
+  element.addEventListener('load', (event) => Object.assign(entry, { state: 'loaded', event }));
+  element.addEventListener('error', (event) => Object.assign(entry, { state: 'failed', event }));
+  if (src) {
+    element.src = src;
+    element.async = true;
+  } else {
+    element.textContent = children ?? '';
+    // Inline scripts run as they are appended; there is no load event to wait for.
+    entry.state = 'loaded';
+  }
+  added.set(key, entry);
+  document.body.append(element);
+  return entry;
+}
+
+/**
+ * Like `next/script`: third-party scripts that should not block the page. Renders nothing in place; scripts are
+ * added to the document once, whichever component renders them first.
+ */
+export function Script(given: ScriptProps) {
+  const pageNonce = useNonce();
+  const props = given.nonce || !pageNonce ? given : { ...given, nonce: pageNonce };
+  const { src, id, strategy = 'afterInteractive', onLoad, onError, nonce, crossOrigin, integrity } = props;
+  const callbacks = useRef({ onLoad, onError });
+  callbacks.current = { onLoad, onError };
+  const key = id ?? src;
+
+  if (strategy === 'beforeInteractive' && src) {
+    preinit(src, { as: 'script', ...(nonce ? { nonce } : {}), ...(integrity ? { integrity } : {}), ...(crossOrigin ? { crossOrigin } : {}) });
+  }
+
+  useEffect(() => {
+    if (!key || (strategy === 'beforeInteractive' && src)) return;
+    let cancelled = false;
+    const attach = () => {
+      if (cancelled) return;
+      const entry = added.get(key) ?? add(key, props);
+      const notify = () => {
+        if (cancelled) return;
+        if (entry.state === 'loaded') callbacks.current.onLoad?.(entry.event ?? new Event('load'));
+        else if (entry.state === 'failed') callbacks.current.onError?.(entry.event ?? new Event('error'));
+      };
+      if (entry.state !== 'loading') {
+        notify();
+        return;
+      }
+      entry.element.addEventListener('load', notify, { once: true });
+      entry.element.addEventListener('error', notify, { once: true });
+    };
+    if (strategy === 'lazyOnload') whenIdle(attach);
+    else attach();
+    return () => {
+      cancelled = true;
+    };
+    // The script is identified by its key; changing other props does not add it again.
+  }, [key, strategy]);
+
+  return null;
+}

package/src/server-entry.tsx

@@ -0,0 +1,4 @@
+import { pages } from 'virtual:netjes/pages';
+import { createServerRenderer } from './server-render.tsx';
+
+export const { render, renderToStream } = createServerRenderer(pages);

package/src/server-render.tsx

@@ -0,0 +1,223 @@
+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 { type ModuleMap, createModuleLoader } from './modules.ts';
+import { type InitialPayload, parseInitialPayload } from './payload.ts';
+import { RenderCleanupContext } from './render-cleanup.ts';
+import { Root } from './root.tsx';
+
+export type RenderOptions = {
+  /** Aborts the render (React stops waiting on suspended content), e.g. when the server stops waiting for it. */
+  signal?: AbortSignal;
+  /** Promises for the payload's Page.Defer placeholders, by id (the sidecar settles them as .NET resolves them). */
+  deferred?: (id: string) => PromiseLike<unknown>;
+};
+
+export type StreamOptions = RenderOptions & {
+  /** Start sending only once everything has rendered (no Suspense fallbacks): for crawlers and the static export. */
+  waitForAll?: boolean;
+};
+
+/**
+ * React writes a Suspense boundary that is ready when the shell goes out in place, unless what it has written so far
+ * (the shell, with the payload and dev styles) and the boundary pass this many bytes (12.8 kB by default): then it
+ * sends the boundary after the shell, hidden, for an inline script to reveal, which a browser without JavaScript never
+ * runs. No limit: whatever is ready goes in place, and only what is still pending streams.
+ */
+const progressiveChunkSize = Number.POSITIVE_INFINITY;
+
+/**
+ * Streams the document: resolves once the shell (everything outside unresolved Suspense boundaries) is ready, with
+ * a stream that carries it and then each boundary as it resolves. Rejects, before anything is sent, if the shell
+ * fails to render.
+ */
+function renderToStream(
+  element: ReactNode,
+  options: StreamOptions,
+  deferredIds: readonly string[],
+  source: DeferredSource,
+  nonce: string | undefined,
+): Promise<Readable> {
+  const { signal, waitForAll = false } = options;
+  return new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+    // Passes React's chunks through, and puts a script for each deferred value between them once the shell is out.
+    // React writes a flush as several synchronous chunks, so a chunk can end in the middle of an element: scripts are
+    // only ever pushed from a later turn (setImmediate, or a promise callback), when React is between flushes.
+    let shellSent = false;
+    let draining = false;
+    const queued: string[] = [];
+    const drain = () => {
+      draining = false;
+      if (output.writableEnded || output.destroyed) return;
+      for (const script of queued.splice(0)) output.push(script);
+    };
+    const output = new Transform({
+      transform(chunk, _encoding, callback) {
+        shellSent = true;
+        this.push(chunk);
+        if (queued.length > 0 && !draining) {
+          draining = true;
+          setImmediate(drain);
+        }
+        callback();
+      },
+      flush(callback) {
+        for (const script of queued.splice(0)) this.push(script);
+        callback();
+      },
+    });
+    const send = (script: string) => {
+      if (shellSent && !draining && !output.writableEnded) output.push(script);
+      else queued.push(script);
+    };
+    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)),
+      );
+    }
+    let started = false;
+    const start = () => {
+      started = true;
+      stream.pipe(output);
+      resolve(output);
+    };
+    const stream = renderToPipeableStream(element, {
+      // React's own inline scripts (Suspense reveals) carry the CSP nonce.
+      ...(nonce ? { nonce } : {}),
+      progressiveChunkSize,
+      onShellReady() {
+        if (!waitForAll) start();
+      },
+      onAllReady() {
+        if (waitForAll) start();
+      },
+      onShellError: reject,
+      onError(error) {
+        // Errors inside a Suspense boundary: React streams the fallback and retries on the client.
+        if (!signal?.aborted) console.error(error);
+      },
+    });
+    signal?.addEventListener(
+      'abort',
+      () => {
+        stream.abort(signal.reason);
+        if (started) output.destroy(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
+        else reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}
+
+function renderToHtml(element: ReactNode, signal: AbortSignal | undefined, nonce: string | undefined): Promise<string> {
+  return new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+    const chunks: Buffer[] = [];
+    const sink = new Writable({
+      write(chunk: Buffer | string, _encoding, callback) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        callback();
+      },
+      final(callback) {
+        resolve(Buffer.concat(chunks).toString('utf8'));
+        callback();
+      },
+    });
+    const stream = renderToPipeableStream(element, {
+      // For any inline script React itself writes.
+      ...(nonce ? { nonce } : {}),
+      progressiveChunkSize,
+      // Wait for every Suspense boundary: the sidecar answers with one complete document.
+      onAllReady() {
+        stream.pipe(sink);
+      },
+      onShellError: reject,
+      onError(error) {
+        // Errors inside a Suspense boundary: React renders the fallback and retries on the client.
+        if (!signal?.aborted) console.error(error);
+      },
+    });
+    signal?.addEventListener(
+      'abort',
+      () => {
+        reject(signal.reason);
+        stream.abort(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}
+
+/** Revives the payload's deferred placeholders, noting which ids it found. */
+function withDeferred(payload: InitialPayload, deferred: RenderOptions['deferred']) {
+  const ids: string[] = [];
+  const promises = new Map<string, Promise<unknown>>();
+  const source: DeferredSource = (id) => {
+    let promise = promises.get(id);
+    if (!promise) {
+      ids.push(id);
+      // Without a source (e.g. a test render) a deferred value never arrives; its boundary shows the fallback.
+      promise = deferred ? Promise.resolve(deferred(id)) : new Promise<unknown>(() => {});
+      promise.catch(() => {});
+      promises.set(id, promise);
+    }
+    return promise;
+  };
+  return { payload: revivePayload(payload, source), ids, source };
+}
+
+/** What one render registered through {@link RenderCleanupContext}, run once its document is done. */
+function cleanups() {
+  const registered: (() => void)[] = [];
+  return {
+    wrap: (element: ReactNode) => <RenderCleanupContext value={(cleanup) => registered.push(cleanup)}>{element}</RenderCleanupContext>,
+    run: () => {
+      for (const cleanup of registered.splice(0)) cleanup();
+    },
+  };
+}
+
+export function createServerRenderer(modules: ModuleMap) {
+  const loader = createModuleLoader(modules);
+  return {
+    /** Renders the page described by the (HTML-safe) payload JSON to a complete HTML document. */
+    async render(dataJson: string, options: RenderOptions = {}): Promise<string> {
+      const { payload } = withDeferred(parseInitialPayload(JSON.parse(dataJson)), options.deferred);
+      const routeModules = await loader.loadRoute(payload);
+      const done = cleanups();
+      try {
+        return await renderToHtml(
+          done.wrap(<Root payload={payload} modules={routeModules} loader={loader} dataJson={dataJson} />),
+          options.signal,
+          payload.document.nonce,
+        );
+      } finally {
+        done.run();
+      }
+    },
+    /** Like {@link render}, streamed: see {@link StreamOptions}. */
+    async renderToStream(dataJson: string, options: StreamOptions = {}): Promise<Readable> {
+      const { payload, ids, source } = withDeferred(parseInitialPayload(JSON.parse(dataJson)), options.deferred);
+      const routeModules = await loader.loadRoute(payload);
+      const done = cleanups();
+      try {
+        const stream = await renderToStream(
+          done.wrap(<Root payload={payload} modules={routeModules} loader={loader} dataJson={dataJson} />),
+          options,
+          ids,
+          source,
+          payload.document.nonce,
+        );
+        // Ended, failed or abandoned: the document needs nothing more from the render.
+        stream.once('close', done.run);
+        return stream;
+      } catch (error) {
+        done.run();
+        throw error;
+      }
+    },
+  };
+}

package/src/testing-setup.ts

@@ -0,0 +1,8 @@
+// Registered by netjes() as a Vitest setup file: unmount what each test rendered (Vitest has no globals, so
+// Testing Library cannot register this itself).
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+afterEach(() => {
+  cleanup();
+});

package/src/testing.tsx

@@ -0,0 +1,177 @@
+// 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.
+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';
+import type { AntiforgeryToken, PagePayload, Params } from './payload.ts';
+import { PublicConfigProvider } from './public-config.tsx';
+import { dehydratedStateOf, mergeOptions } from './query.tsx';
+import { type InternalRouter, type NavigationState, RouterContexts, type SubmitBody } from './router.tsx';
+
+/** What the fake app of `createTestApp` reports to the components under test. */
+export type TestAppOptions = {
+  /** The current URL. Default `/`. */
+  url?: string;
+  /** The page's route pattern, e.g. `/blog/[slug]`. */
+  route?: string;
+  /** What `useLocale()` returns. */
+  locale?: string;
+  /** What `useDraftMode()` reports. */
+  draftMode?: boolean;
+  /** What `usePublicConfig()` returns, like the server's `Netjes:PublicConfig` section. */
+  publicConfig?: Record<string, unknown>;
+  params?: Params;
+  /** What the server would send as `SharedProps`. */
+  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. */
+  defaultOptions?: DefaultOptions;
+  /** What `useNavigation()` returns. Default idle. */
+  navigation?: NavigationState;
+  /** The token `<Form method="post">` adds. Default a test token; `false` for none. */
+  antiforgery?: AntiforgeryToken | false;
+  queryClient?: QueryClient;
+  /**
+   * Answers server action calls by name; unknown actions succeed with no result. Like `.WithQuery` and
+   * `.Invalidate` in C#, an answer can set and invalidate query entries.
+   */
+  actions?: Record<string, (input: unknown) => TestActionAnswer | Promise<TestActionAnswer>>;
+};
+
+/** What a fake server action answers: a success or failure state, plus query entries to set or invalidate. */
+export type TestActionAnswer = ActionState<unknown> & {
+  queries?: ReadonlyArray<{ key: readonly unknown[]; data: 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[];
+};
+
+/** One thing the component under test did: a navigation, a router call, a form post or a server action call. */
+export type TestNavigation =
+  | { type: 'push' | 'replace'; href: string }
+  | { type: 'refresh' | 'back' | 'forward' }
+  | { type: 'submit'; action: string; data: URLSearchParams | FormData }
+  | { type: 'action'; name: string; input: unknown };
+
+/** The fake app `createTestApp` returns: a wrapper for Testing Library and a record of what the components did. */
+export type TestApp = {
+  /** Pass as Testing Library's `wrapper`. */
+  Wrapper: (props: { children: ReactNode }) => ReactNode;
+  /** Every navigation, router call and form post, in order. */
+  navigations: TestNavigation[];
+  queryClient: QueryClient;
+};
+
+/**
+ * Registers the stand-in in the commit, and only then: a render React throws away (`renderToString`, children that
+ * threw) leaves calls made outside any Wrapper failing at once. React runs the effects of earlier siblings first, and
+ * a component's after those of the components inside it, so rendered ahead of the children this runs before any of
+ * their effects, layout effects included.
+ */
+function RegisterActionClient({ client }: { client: ActionClient }) {
+  useLayoutEffect(() => setActionClient(client), [client]);
+  return null;
+}
+
+const TEST_TOKEN: AntiforgeryToken = { formFieldName: '__RequestVerificationToken', headerName: 'RequestVerificationToken', requestToken: 'test-token' };
+
+function dataOf(body: SubmitBody): URLSearchParams | FormData {
+  return body.contentType === null ? body.body : new URLSearchParams(body.body);
+}
+
+/** 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 } } });
+  const now = Date.now();
+  const seeded = dehydratedStateOf(options.queries?.map((query) => ({ ...query, updatedAt: now })));
+  if (seeded) hydrate(queryClient, seeded);
+  const initialUrl = new URL(options.url ?? '/', window.location.origin);
+  // Forms without an action post to the current URL, which they read from the window.
+  window.history.replaceState(null, '', initialUrl.href);
+  const antiforgery = options.antiforgery === false ? undefined : (options.antiforgery ?? TEST_TOKEN);
+  // The router's stand-in for server action calls: records each one and answers it from `options.actions`.
+  const actionClient: ActionClient = {
+    async invoke(name, _url, input) {
+      navigations.push({ type: 'action', name, input });
+      const answer: TestActionAnswer = (await options.actions?.[name]?.(input)) ?? { ok: true, result: undefined };
+      for (const query of answer.queries ?? []) queryClient.setQueryData(query.key, query.data);
+      for (const queryKey of answer.invalidate ?? []) void queryClient.invalidateQueries({ queryKey: [...queryKey] });
+      return answer.ok
+        ? { kind: 'action', ok: true, status: 200, result: answer.result, revalidate: false }
+        : {
+            kind: 'action',
+            ok: false,
+            status: answer.status,
+            errors: answer.errors,
+            ...(answer.fields ? { fields: [...answer.fields] } : {}),
+            revalidate: false,
+          };
+    },
+  };
+
+  function Wrapper({ children }: { children: ReactNode }) {
+    const [url, setUrl] = useState(initialUrl);
+    const router = useMemo<InternalRouter>(() => {
+      const go = (type: 'push' | 'replace', href: string) => {
+        navigations.push({ type, href });
+        const next = new URL(href, window.location.href);
+        window.history.replaceState(null, '', next.href);
+        setUrl(next);
+        return Promise.resolve();
+      };
+      return {
+        push: (href) => go('push', href),
+        replace: (href) => go('replace', href),
+        prefetch: () => {},
+        refresh: () => {
+          navigations.push({ type: 'refresh' });
+          return Promise.resolve();
+        },
+        back: () => navigations.push({ type: 'back' }),
+        forward: () => navigations.push({ type: 'forward' }),
+        submit: (action, body) => {
+          navigations.push({ type: 'submit', action: action.href, data: dataOf(body) });
+          return Promise.resolve();
+        },
+        onActionResponse: () => () => {},
+        onCookiesChanged: () => () => {},
+      };
+    }, []);
+    const payload = useMemo<PagePayload>(
+      () => ({
+        kind: 'page',
+        route: options.route ?? null,
+        page: null,
+        segments: [],
+        props: {},
+        params: options.params ?? {},
+        shared: options.shared ?? null,
+        status: 200,
+        url: url.pathname + url.search,
+        version: 'test',
+        ...(antiforgery ? { antiforgery } : {}),
+        ...(options.draftMode ? { draftMode: true } : {}),
+        ...(options.locale ? { locale: options.locale } : {}),
+      }),
+      [url],
+    );
+
+    return (
+      <QueryClientProvider client={queryClient}>
+        <PublicConfigProvider value={options.publicConfig ?? {}}>
+          <RouterContexts router={router} payload={payload} url={url} navigation={options.navigation ?? { state: 'idle' }}>
+            <RegisterActionClient client={actionClient} />
+            {children}
+          </RouterContexts>
+        </PublicConfigProvider>
+      </QueryClientProvider>
+    );
+  }
+
+  return { Wrapper, navigations, queryClient };
+}

package/src/virtual.d.ts

@@ -0,0 +1,12 @@
+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>>;
+}
+
+declare module 'virtual:netjes/query' {
+  import type { ComponentType, ReactNode } from 'react';
+  /** The QueryClient provider, or undefined when the app turned TanStack Query off (`netjes({ query: false })`). */
+  export const QueryShell: ComponentType<{ children: ReactNode }> | undefined;
+}
+
+declare module '@vitejs/plugin-react/preamble';

package/src/vitals-config.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+
+/** Where `<WebVitals />` sends reports: set when the server collects them (`NetjesOptions.CollectWebVitals`). */
+export const VitalsEndpointContext = createContext<string | undefined>(undefined);
+
+export const VitalsEndpointProvider = VitalsEndpointContext.Provider;