netjes 0.0.2 → 0.0.4

package/src/script.tsx

@@ -1,5 +1,6 @@
-import { type ScriptHTMLAttributes, useEffect, useRef } from 'react';
-import { preinit } from 'react-dom';
+import { type ScriptHTMLAttributes, useEffect, useRef, useSyncExternalStore } from 'react';
+import { preload } from 'react-dom';
+import { htmlSafeJson } from './deferred.ts';
 import { useNonce } from './nonce.tsx';
 
 /** When `<Script>` loads its script: before or after the page is interactive, or when the browser is idle. */
@@ -7,11 +8,17 @@ export type ScriptStrategy = 'beforeInteractive' | 'afterInteractive' | 'lazyOnl
 
 /** 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. */
+  /**
+   * Identifies the script (required for inline scripts): it is added once, however often it is rendered, except inline
+   * `beforeInteractive` code, which the server writes wherever a component renders it.
+   */
   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).
+   * `beforeInteractive`: in a server-rendered document, inline code runs where it stands, as the parser reaches it,
+   * and an external script in the shell runs once the shell is parsed, in order with the others, before the page's
+   * code and hydration; one in a Suspense boundary that streams in later runs when that part of the page hydrates.
+   * A component that mounts in the browser, after a client navigation for one, adds it as `afterInteractive` does.
    */
   strategy?: ScriptStrategy;
   onLoad?: (event: Event) => void;
@@ -20,9 +27,18 @@ export type ScriptProps = Omit<ScriptHTMLAttributes<HTMLScriptElement>, 'onLoad'
   children?: string;
 };
 
+/**
+ * The name of the `<meta>` a server-rendered `beforeInteractive` script puts in the head, which tells the client entry
+ * to run the external ones before it imports the page's modules.
+ */
+export const BEFORE_INTERACTIVE_MARKER = 'netjes-before-interactive';
+
+/** The attribute that marks a server-rendered `beforeInteractive` script, inline or inert, with its id or src. */
+const ENTRY = 'data-netjes-script';
+
 type Entry = { element: HTMLScriptElement; state: 'loading' | 'loaded' | 'failed'; event?: Event };
 
-/** Scripts already added to this document, by id or src. */
+/** Scripts already added to this document, or run by its parser, by id or src. */
 const added = new Map<string, Entry>();
 
 function whenIdle(run: () => void) {
@@ -32,52 +48,200 @@ function whenIdle(run: () => void) {
   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));
+/** A script's own attributes by their HTML names: strings, or true for one without a value. */
+type Attributes = Record<string, string | true>;
+
+/** A name `setAttribute` takes, other than an event handler's, which React never renders from a string either. */
+const isAttributeName = (name: string) => /^[A-Za-z_:][-\w.:]*$/.test(name) && !/^on/i.test(name);
+
+function attributesOf(props: Record<string, unknown>): Attributes {
+  const attributes: Attributes = {};
+  for (const [name, value] of Object.entries(props)) {
+    if (value === undefined || value === null || value === false || typeof value === 'function' || typeof value === 'object') continue;
+    const html = name === 'className' ? 'class' : name === 'crossOrigin' ? 'crossorigin' : name;
+    if (isAttributeName(html)) attributes[html] = value === true ? true : String(value);
   }
+  return attributes;
+}
+
+type Insertion = { src?: string; code?: string; id?: string; nonce?: string; attributes: Attributes; async: boolean; parent: HTMLElement };
+
+/** Adds a script element to the document and records it, with its outcome once it has one. */
+function insert(key: string, { src, code, id, nonce, attributes, async, parent }: Insertion): Entry {
+  const element = document.createElement('script');
+  for (const [name, value] of Object.entries(attributes)) element.setAttribute(name, value === true ? '' : 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;
+  if (nonce) element.nonce = 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;
+    element.async = async;
   } else {
-    element.textContent = children ?? '';
+    element.textContent = code ?? '';
     // 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);
+  parent.append(element);
   return entry;
 }
 
+function add(key: string, { src, children, strategy, id, onLoad: _onLoad, onError: _onError, ...rest }: ScriptProps): Entry {
+  // Inline beforeInteractive code as the server's document carries it, so that one hash allows it on either path.
+  const code = strategy === 'beforeInteractive' ? escapeScriptText(children ?? '') : (children ?? '');
+  return insert(key, {
+    ...(src ? { src } : { code }),
+    ...(id ? { id } : {}),
+    ...(rest.nonce ? { nonce: rest.nonce } : {}),
+    attributes: attributesOf(rest),
+    async: true,
+    parent: document.body,
+  });
+}
+
+/** What an inert entry holds, the script's src and its attributes, or null when it holds anything else. */
+function externalEntry(text: string | null): { src: string; attributes: Attributes } | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(text ?? '');
+  } catch {
+    return null;
+  }
+  if (typeof value !== 'object' || value === null) return null;
+  const { src, attributes } = value as { src?: unknown; attributes?: unknown };
+  if (typeof src !== 'string' || src === '') return null;
+  const checked: Attributes = {};
+  if (typeof attributes === 'object' && attributes !== null) {
+    for (const [name, attribute] of Object.entries(attributes)) {
+      if ((typeof attribute === 'string' || attribute === true) && isAttributeName(name) && name.toLowerCase() !== 'nonce') checked[name] = attribute;
+    }
+  }
+  return { src, attributes: checked };
+}
+
+/** The types besides none that browsers run as JavaScript: the HTML standard's JavaScript MIME types. */
+const JAVASCRIPT_TYPES = new Set([
+  'application/ecmascript',
+  'application/javascript',
+  'application/x-ecmascript',
+  'application/x-javascript',
+  'text/ecmascript',
+  'text/javascript',
+  'text/javascript1.0',
+  'text/javascript1.1',
+  'text/javascript1.2',
+  'text/javascript1.3',
+  'text/javascript1.4',
+  'text/javascript1.5',
+  'text/jscript',
+  'text/livescript',
+  'text/x-ecmascript',
+  'text/x-javascript',
+]);
+
+/**
+ * Whether a browser runs a script with these attributes, by the HTML standard's rules, and so fires its load or error
+ * event. One that runs the client entry, a module, skips a script with `nomodule` and one whose type is neither
+ * JavaScript nor `module`, such as the `text/plain` of a script a consent manager turns on once the visitor agrees, and
+ * fires neither event for it.
+ */
+function runs(attributes: Attributes): boolean {
+  const named: Partial<Record<string, string>> = {};
+  for (const [name, value] of Object.entries(attributes)) named[name.toLowerCase()] = value === true ? '' : value;
+  const type = named.type ?? (named.language ? `text/${named.language}` : '');
+  if (type === '') return named.nomodule === undefined;
+  const essence = type.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, '').toLowerCase();
+  return essence === 'module' || (JAVASCRIPT_TYPES.has(essence) && named.nomodule === undefined);
+}
+
+/** Resolves once the script has loaded or failed. */
+function outcome(entry: Entry): Promise<void> {
+  if (entry.state !== 'loading') return Promise.resolve();
+  return new Promise((resolve) => {
+    entry.element.addEventListener('load', () => resolve(), { once: true });
+    entry.element.addEventListener('error', () => resolve(), { once: true });
+  });
+}
+
 /**
- * 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.
+ * Takes over the `beforeInteractive` scripts the server rendered into the document, in document order, those not yet
+ * taken over. Inline code has run where it stands: it is recorded, so that a component that mounts again (after a
+ * hydration error) does not add it once more. Each external script's inert entry becomes a script at the end of the
+ * head, not async, so the browser runs them in this order as they arrive, with the page's nonce. Under a nonce, only
+ * entries with that nonce count: markup that reached the page some other way does not know it. Resolves once every
+ * external script it added has loaded or failed.
+ */
+export function adoptServerScripts(nonce: string | undefined): Promise<void> {
+  const waits: Promise<void>[] = [];
+  for (const element of document.querySelectorAll<HTMLScriptElement>(`script[${ENTRY}]`)) {
+    const key = element.getAttribute(ENTRY);
+    if (!key || added.has(key) || (nonce && element.nonce !== nonce)) continue;
+    const external = element.type === 'application/json' ? externalEntry(element.textContent) : null;
+    if (external) {
+      const entry = insert(key, { ...external, ...(nonce ? { nonce } : {}), async: false, parent: document.head });
+      if (runs(external.attributes)) waits.push(outcome(entry));
+    } else {
+      added.set(key, { element, state: 'loaded' });
+    }
+  }
+  return Promise.all(waits).then(() => undefined);
+}
+
+/**
+ * React's own rule for the text of an inline script: `</script` would close the element and `<script` would make the
+ * parser look for a second closing tag, so their `s` is written `\u0073` (or `S` as `\u0053`), which JavaScript reads as the
+ * same letter in strings, template literals, regular expressions and names.
+ */
+const SCRIPT_TAG = /(<\/|<)(s)(cript)/gi;
+const escapeScriptText = (code: string) =>
+  code.replace(SCRIPT_TAG, (_match, open: string, s: string, rest: string) => `${open}${s === 's' ? '\\u0073' : '\\u0053'}${rest}`);
+
+const subscribeToNothing = () => () => {};
+
+/** Scripts warned about already: each is warned about once. */
+const warned = new Set<string>();
+
+function warnAboutTiming(key: string, { async, defer, type }: ScriptProps) {
+  if (process.env.NODE_ENV === 'production' || warned.has(key)) return;
+  const found = [async && 'async', defer && 'defer', type === 'module' && 'type="module"'].filter(Boolean);
+  if (found.length === 0) return;
+  warned.add(key);
+  console.warn(
+    `netjes: <Script strategy="beforeInteractive"> "${key}" has ${found.join(', ')}. A beforeInteractive script runs ` +
+      "in order, before the page's code, whatever async and defer say, and type=\"module\" makes inline code wait until " +
+      'the whole document is parsed. Leave them out, or use strategy="afterInteractive".',
+  );
+}
+
+/**
+ * A script loaded by strategy, like `next/script`: `afterInteractive` and `lazyOnload` do not block the page. Scripts
+ * are added to the document once, whichever component renders them first, except inline `beforeInteractive` code, which
+ * the server writes wherever a component renders it. Only `beforeInteractive` renders anything where it stands, and
+ * only into a server-rendered document: the inline script, or an inert entry for an external one, and a marker in the
+ * head.
  */
 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 { src, id, strategy = 'afterInteractive', onLoad, onError, nonce, crossOrigin, integrity, children } = 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 } : {}) });
-  }
+  // True on the server and while this component hydrates, and for as long as it stays mounted after that, so that it
+  // keeps the markup it hydrated. False when it mounts in the browser.
+  const fromServer = useRef(useSyncExternalStore(subscribeToNothing, () => false, () => true)).current;
+  const inDocument = strategy === 'beforeInteractive' && fromServer && key !== undefined;
 
   useEffect(() => {
-    if (!key || (strategy === 'beforeInteractive' && src)) return;
+    if (!key) return;
     let cancelled = false;
     const attach = () => {
       if (cancelled) return;
+      // An entry that streamed in after the client entry took the others over is taken over now.
+      if (inDocument && !added.has(key)) void adoptServerScripts(pageNonce);
       const entry = added.get(key) ?? add(key, props);
       const notify = () => {
         if (cancelled) return;
@@ -99,5 +263,32 @@ export function Script(given: ScriptProps) {
     // The script is identified by its key; changing other props does not add it again.
   }, [key, strategy]);
 
-  return null;
+  if (!inDocument) return null;
+  warnAboutTiming(key, props);
+  const { strategy: _strategy, onLoad: _onLoad, onError: _onError, children: _children, src: _src, id: _id, nonce: _nonce, ...rest } = props;
+  // In the head, where the client entry looks for it once it has the payload.
+  const marker = <meta name={BEFORE_INTERACTIVE_MARKER} />;
+  if (!src) {
+    // Written as it is (React would escape text children, and they would not match the server's); escaped as React
+    // escapes its own scripts, so the text cannot end the element. A hash-based policy lists the hash of that text.
+    return (
+      <>
+        {marker}
+        <script {...rest} id={id} nonce={nonce} data-netjes-script={key} dangerouslySetInnerHTML={{ __html: escapeScriptText(children ?? '') }} />
+      </>
+    );
+  }
+  // The id goes to the script the entry becomes, not to the entry.
+  const attributes = attributesOf(id ? { ...rest, id } : rest);
+  // The browser fetches it while it parses; adoptServerScripts runs it from the entry. A script the browser will not run
+  // is not fetched: a consent manager's would reach its host before the visitor agreed.
+  if (runs(attributes)) {
+    preload(src, { as: 'script', ...(nonce ? { nonce } : {}), ...(integrity ? { integrity } : {}), ...(crossOrigin !== undefined ? { crossOrigin } : {}) });
+  }
+  return (
+    <>
+      {marker}
+      <script type="application/json" nonce={nonce} data-netjes-script={key} dangerouslySetInnerHTML={{ __html: htmlSafeJson({ src, attributes }) }} />
+    </>
+  );
 }

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 `/`. */
@@ -23,9 +26,18 @@ export type TestAppOptions = {
   params?: Params;
   /** What the server would send as `SharedProps`. */
   shared?: unknown;
+  /**
+   * Each mounted page package's URL for the page, by npm name, as the server sends it: `{ '@acme/help-center': '/help' }`,
+   * without the base path, or `null` for a prefix whose value the page has none for. The links, forms and router hooks
+   * of the package's generated file go below it.
+   */
+  mounts?: Record<string, string | null>;
   /** 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 +57,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 +94,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 +115,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 +140,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,
           };
     },
@@ -157,6 +189,7 @@ export function createTestApp(options: TestAppOptions = {}): TestApp {
         ...(antiforgery ? { antiforgery } : {}),
         ...(options.draftMode ? { draftMode: true } : {}),
         ...(options.locale ? { locale: options.locale } : {}),
+        ...(options.mounts ? { mounts: options.mounts } : {}),
       }),
       [url],
     );

package/src/virtual.d.ts

@@ -1,6 +1,13 @@
 declare module 'virtual:netjes/pages' {
-  /** Every page, layout and other convention file, keyed `/app/...`, as lazy imports. Generated by the netjes Vite plugin. */
+  /**
+   * Every page, layout and other convention file, as lazy imports, keyed by `/` and the file's id: `/app/...` for the
+   * app's, `/<npm name>/<its pages folder>/...` for a page package's. 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;
+  /** The page packages `netjes({ packages })` lists, each with the folder of its pages; `[]` when it lists none. */
+  export const packages: ReadonlyArray<{ readonly name: string; readonly pages: 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.