netjes 0.0.1 → 0.0.3

package/src/modules.ts

@@ -6,8 +6,21 @@ export type PageComponent = ComponentType<Record<string, unknown>>;
 /** The props every layout gets: its `children` and the route `params`. The loader's props and parallel route slots arrive as further props. */
 export type LayoutProps = { children: ReactNode; params: Params };
 export type LayoutComponent = ComponentType<LayoutProps & Record<string, unknown>>;
-/** The props of an `error.tsx`: what was thrown, and a way to try rendering the segment again. */
-export type ErrorPageProps = { error: Error & { status?: number }; reset: () => void };
+/**
+ * The props of an `error.tsx`: what was thrown, and a way to try again.
+ *
+ * - `error.status` is the HTTP status of a server answer behind the error: the status of the error page the server
+ *   rendered, or of a server action call that failed. An error thrown in the browser has none.
+ * - `error.withheld` is true when the message is Netjes's stand-in for one it does not show: the server's reason
+ *   phrase for an exception while error details are off, "Something went wrong" for a `Page.Defer` failure the server
+ *   withheld or a thrown value that has no message, or Netjes's own text for a server action whose answer had no
+ *   message. Render `error.message` only when `!error.withheld`.
+ * - `error.stack` is the server's stack when error details are on, and undefined for a server error sent without one.
+ * - `reset()` renders the segment again after an error a segment's boundary caught. On an error page the server
+ *   rendered it loads the page from the server again (`router.refresh()`), and on the page the router's own boundary
+ *   shows it does nothing: offer a link or a full reload there.
+ */
+export type ErrorPageProps = { error: Error & { status?: number; withheld?: boolean }; reset: () => void };
 
 export type LoadedSegment = {
   id: string;

package/src/navigation-focus.ts

@@ -0,0 +1,75 @@
+/** Input types the user does not type into: the focus can leave them when the page they are on is replaced. */
+const NOT_TYPED_IN = new Set(['button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit']);
+
+/** Whether the user types into the element, or picks a value in it from the keyboard: a text field, a select, editable content. */
+export function isEditable(element: Element): boolean {
+  if (element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) return true;
+  if (element instanceof HTMLInputElement) return !NOT_TYPED_IN.has(element.type);
+  return element instanceof HTMLElement && element.isContentEditable;
+}
+
+/**
+ * Focuses an element without scrolling to it. One that takes no focus of its own, such as a heading or `main`, gets
+ * `tabindex="-1"` for it, which goes again when it loses the focus. Returns whether the element has the focus.
+ */
+export function focusElement(element: HTMLElement): boolean {
+  element.focus({ preventScroll: true });
+  if (document.activeElement === element) return true;
+  // A tabindex of the app's own did not help (a hidden or inert element): leave it as it is.
+  if (element.hasAttribute('tabindex')) return false;
+  element.setAttribute('tabindex', '-1');
+  element.focus({ preventScroll: true });
+  if (document.activeElement !== element) {
+    element.removeAttribute('tabindex');
+    return false;
+  }
+  element.addEventListener('blur', () => element.removeAttribute('tabindex'), { once: true });
+  return true;
+}
+
+/**
+ * Starts the focus over at the top of the document, as a page load does: the next Tab goes to the first element that
+ * takes the focus, such as a skip link. `body` takes the focus for this only, without scrolling, and gets its own
+ * `tabindex` back, or none.
+ */
+export function resetFocus() {
+  const body = document.body;
+  const own = body.getAttribute('tabindex');
+  body.tabIndex = -1;
+  body.focus({ preventScroll: true, focusVisible: false });
+  if (own === null) body.removeAttribute('tabindex');
+  else body.setAttribute('tabindex', own);
+}
+
+export type NavigationFocus = {
+  /** The element the URL's fragment names, which the router scrolled to; null without a fragment, or when none matched. */
+  target: HTMLElement | null;
+  /** The page on screen is another one: its page key changed. */
+  replaced: boolean;
+  /** The navigation keeps the scroll position: `scroll={false}`. */
+  keep: boolean;
+  /** What had the focus when the navigation started. */
+  focusedAtStart: Element | null;
+};
+
+/**
+ * Moves the focus after a navigation, once the router has scrolled, by the first of these rules that applies:
+ *
+ * 1. The fragment's target takes it, on this page or on another. One that cannot (a hidden element) leaves it to the
+ *    rules below.
+ * 2. It stays on the same page: a query that changed, a refresh, a post that stays on its page, a modal opening or
+ *    closing over the page under it.
+ * 3. It stays where it went while the navigation ran: to the new page (`autoFocus`), or where the user or a handler
+ *    of the app (a menu that closes) put it.
+ * 4. It stays on what had it when the navigation started, with `scroll={false}` or in a field the user types into,
+ *    such as a search box in a layout that navigates as the user types.
+ * 5. Otherwise it starts over at the top of the document, as after a page load.
+ */
+export function moveFocusAfterNavigation({ target, replaced, keep, focusedAtStart }: NavigationFocus) {
+  if (target && focusElement(target)) return;
+  if (!replaced) return;
+  const focused = document.activeElement;
+  if (focused && focused !== document.body && focused !== focusedAtStart) return;
+  if (focused && focused === focusedAtStart && (keep || isEditable(focused))) return;
+  resetFocus();
+}

package/src/payload.ts

@@ -13,6 +13,8 @@ export const ANTIFORGERY_HEADER = 'X-Netjes-Antiforgery';
  */
 export const COOKIES_HEADER = 'X-Netjes-Cookies';
 export const DATA_ELEMENT_ID = '__NETJES_DATA__';
+/** The id of the empty element that ends the body of every server-rendered document, and so the shell. */
+export const SHELL_END_ID = '__NETJES_SHELL_END__';
 
 /** The page's route values by parameter name: a string per single segment, an array per catch-all (empty for an optional one). A single parameter the request has no value for is `null`, as when a page is rendered with `Page.Render` from an endpoint whose route lacks it. */
 export type Params = Record<string, string | string[] | null>;

package/src/query.tsx

@@ -11,14 +11,20 @@ export type QueryShellOptions = {
 
 const DEFAULTS: DefaultOptions = { queries: { staleTime: 60_000 } };
 
-/** The Netjes defaults with the app's options merged over them, as the built-in client and the test harness use. */
-export function mergeOptions(options: DefaultOptions | undefined): DefaultOptions {
-  return {
-    ...DEFAULTS,
-    ...options,
-    queries: { ...DEFAULTS.queries, ...options?.queries },
-    mutations: { ...DEFAULTS.mutations, ...options?.mutations },
-  };
+/**
+ * The Netjes defaults with each layer of options merged over the ones before it, query and mutation options one by
+ * one: the built-in client merges the app's options, and the test harness more layers.
+ */
+export function mergeOptions(...layers: ReadonlyArray<DefaultOptions | undefined>): DefaultOptions {
+  return [DEFAULTS, ...layers].reduce<DefaultOptions>(
+    (merged, layer) => ({
+      ...merged,
+      ...layer,
+      queries: { ...merged.queries, ...layer?.queries },
+      mutations: { ...merged.mutations, ...layer?.mutations },
+    }),
+    {},
+  );
 }
 
 /**

package/src/render-document.tsx

@@ -0,0 +1,386 @@
+// renderDocument and inlineScriptHashes, which netjes/testing exports: a page's whole document, rendered from its
+// props as the Node sidecar renders it for a crawler, and the hashes of the inline scripts in it. The server builds
+// the payload the sidecar renders; documentPayload builds one here from the pages map and the test's options, by the
+// server's rules for the route and the segments (RouteTable and PageRenderer in src/Netjes). The two are checked
+// against the same cases, test/fixtures/segments/cases.json, so a change to either rule fails a suite until both agree.
+import { htmlSafeJson } from './deferred.ts';
+import type { InitialPayload, PageKind, Params, SegmentRef } from './payload.ts';
+
+/** What {@link renderDocument} renders a page with: what the server would send with it. */
+export type RenderDocumentOptions = {
+  /** The page's props, as its C# loader sends them. A Promise anywhere in them is a `Page.Defer` value. */
+  props?: Record<string, unknown>;
+  /** The route values, as `useParams()` returns them: a string per segment, an array per catch-all. Default none. */
+  params?: Params;
+  /** The page's URL, its path and query. Default `/`. */
+  url?: string;
+  /**
+   * The props of each layout's C# layout loader, by the layout's file, such as `app/blog/layout.tsx`. A Promise in
+   * them is a `Page.Defer` value. A layout that is not named here gets none.
+   */
+  layouts?: Record<string, Record<string, unknown>>;
+  /** What the server sends as the shared props (`UseSharedProps`). Default `null`. */
+  shared?: unknown;
+  /**
+   * The page's status. Default 200, or the status the server gives the file: 404 for a not-found file, 403 for a
+   * forbidden one, 401 for an unauthorized one and 500 for an error or global-error one.
+   */
+  status?: number;
+  /** A Content-Security-Policy nonce, which goes on every script and stylesheet, as for a policy with `{nonce}`. */
+  nonce?: string;
+  /** The `lang` of `<html>`. Default `en`, as `NetjesOptions.Lang`. */
+  lang?: string;
+  /** What `usePublicConfig()` reads, as the `Netjes:PublicConfig` section. */
+  publicConfig?: Record<string, unknown>;
+  /** The page files, keyed `/app/...` as `import.meta.glob` keys them. Default: the app's, from the `netjes()` plugin. */
+  modules?: Record<string, () => Promise<unknown>>;
+  /** Stops the render, which then rejects with the signal's reason: for a page that waits on a Promise that never settles. */
+  signal?: AbortSignal;
+};
+
+/** The options {@link documentPayload} reads, with any Promise in the props already a placeholder. */
+type DocumentOptions = Omit<RenderDocumentOptions, 'modules' | 'signal'>;
+
+/** The files renderDocument renders besides pages, with the kind and the status the server gives them. */
+const BOUNDARIES = new Map<string, { kind: PageKind; status: number }>([
+  ['not-found', { kind: 'notFound', status: 404 }],
+  ['forbidden', { kind: 'forbidden', status: 403 }],
+  ['unauthorized', { kind: 'unauthorized', status: 401 }],
+  ['error', { kind: 'error', status: 500 }],
+  ['global-error', { kind: 'error', status: 500 }],
+]);
+
+/** The files that make a folder a segment of the pages below it; the payload names the first four. */
+const SEGMENT_FILES = ['layout', 'template', 'loading', 'error', 'not-found', 'forbidden', 'unauthorized'];
+
+const PAGE_EXTENSION = /\.(?:tsx|jsx)$/i;
+const isGroup = (folder: string) => folder.length > 2 && folder.startsWith('(') && folder.endsWith(')');
+const isSlot = (folder: string) => folder.length > 1 && folder.startsWith('@');
+const isPrivate = (folder: string) => folder.startsWith('_');
+/** UTF-16 code unit order, as the server's ordinal order. */
+const ordinal = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** "a", "a and b", "a, b and c". */
+function list(items: readonly string[]): string {
+  return items.length < 2 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items.at(-1) ?? ''}`;
+}
+
+/** A file in the app directory: the folders below the directory and the file's name without its extension; null for any other file. */
+function parse(file: string, appDir: string): { folders: string[]; name: string } | null {
+  if (!file.startsWith(`${appDir}/`) || !PAGE_EXTENSION.test(file)) return null;
+  const folders = file.slice(appDir.length + 1).split('/');
+  const name = (folders.pop() ?? '').replace(PAGE_EXTENSION, '');
+  return { folders, name };
+}
+
+type AppFiles = {
+  /** Each folder's convention files by name, by its path below the app directory (`''` for the directory itself). */
+  folders: Map<string, Map<string, string>>;
+  /** The folders with parallel route slots, each with the first of its slots. */
+  slots: Map<string, string>;
+};
+
+/** The convention files the server routes: none in private folders, and the slots that pages and defaults make. */
+function appFiles(files: readonly string[], appDir: string): AppFiles {
+  const folders = new Map<string, Map<string, string>>();
+  const slots = new Map<string, string>();
+  for (const file of [...files].sort(ordinal)) {
+    const parsed = parse(file, appDir);
+    if (!parsed || parsed.folders.some(isPrivate)) continue;
+    const slot = parsed.folders.findIndex(isSlot);
+    if (slot >= 0) {
+      const parent = parsed.folders.slice(0, slot).join('/');
+      if ((parsed.name === 'page' || parsed.name === 'default') && !slots.has(parent)) {
+        slots.set(parent, [appDir, ...parsed.folders.slice(0, slot + 1)].join('/'));
+      }
+      continue;
+    }
+    const folder = parsed.folders.join('/');
+    let conventions = folders.get(folder);
+    if (!conventions) folders.set(folder, (conventions = new Map()));
+    if (!conventions.has(parsed.name)) conventions.set(parsed.name, file);
+  }
+  return { folders, slots };
+}
+
+/**
+ * How many URL segments a layout's folders cover for these route values, as the server counts them: one per folder,
+ * none for a route group, and a catch-all as many as its value has.
+ */
+function urlDepth(folders: readonly string[], params: Params): number {
+  let depth = 0;
+  for (const folder of folders.filter((name) => !isGroup(name))) {
+    if (!folder.startsWith('[...') && !folder.startsWith('[[...')) {
+      depth++;
+      continue;
+    }
+    const value = params[folder.replace(/^[[\]]+|[[\]]+$/g, '').slice(3)];
+    depth += (Array.isArray(value) ? value.join('/') : (value ?? '')).split('/').filter(Boolean).length;
+  }
+  return depth;
+}
+
+function slotError(page: string, where: string, slot: string): Error {
+  return new Error(
+    `netjes: renderDocument cannot render ${page}, which ${where} the parallel route slot ${slot}: the server chooses what a slot renders.`,
+  );
+}
+
+/**
+ * The folders above `folders` and the folder itself that are segments, outermost first, as the server sends them:
+ * each folder with a segment file, its layout's props from `layouts` and, for a layout, the URL depth it covers.
+ */
+function segmentsFor(page: string, app: AppFiles, folders: readonly string[], appDir: string, options: DocumentOptions): SegmentRef[] {
+  const segments: SegmentRef[] = [];
+  for (let end = 0; end <= folders.length; end++) {
+    const path = folders.slice(0, end);
+    const folder = path.join('/');
+    const slot = app.slots.get(folder);
+    if (slot) throw slotError(page, 'renders under', slot);
+    const conventions = app.folders.get(folder);
+    if (!conventions || !SEGMENT_FILES.some((name) => conventions.has(name))) continue;
+    const segment: SegmentRef = { id: folder ? `${appDir}/${folder}` : appDir };
+    for (const name of ['layout', 'template', 'loading', 'error'] as const) {
+      const file = conventions.get(name);
+      if (file) segment[name] = file;
+    }
+    if (segment.layout) {
+      if (options.layouts && Object.hasOwn(options.layouts, segment.layout)) segment.props = options.layouts[segment.layout];
+      segment.depth = urlDepth(path, options.params ?? {});
+    }
+    segments.push(segment);
+  }
+  return segments;
+}
+
+/** Every file renderDocument could render from these: the pages and the boundary files, in ordinal order. */
+function renderable(files: readonly string[], appDir: string): string[] {
+  return files
+    .filter((file) => {
+      const parsed = parse(file, appDir);
+      if (!parsed || parsed.folders.some((folder) => isPrivate(folder) || isSlot(folder))) return false;
+      return parsed.name === 'page' || (BOUNDARIES.has(parsed.name) && (parsed.name !== 'global-error' || parsed.folders.length === 0));
+    })
+    .sort(ordinal);
+}
+
+/**
+ * The payload the server sends with the document of `page`, a file of the pages map named without its leading slash,
+ * for the values in `options`: the route, kind, status and segments by the server's rules, and a build with no
+ * stylesheets or scripts. Throws for a file it cannot render: one not in `files`, a layout, or a page in a private
+ * folder or under a parallel route slot.
+ */
+export function documentPayload(page: string, options: DocumentOptions, files: readonly string[], appDir: string): InitialPayload {
+  const paths = files.map((file) => file.replace(/^\//, ''));
+  if (!paths.includes(page)) {
+    const hint = page.startsWith('/') && paths.includes(page.slice(1))
+      ? `; name the file without the leading slash: ${page.slice(1)}.`
+      : `. The files it can render are ${list(renderable(paths, appDir))}.`;
+    throw new Error(`netjes: renderDocument has no ${page} in the pages map${hint}`);
+  }
+  const parsed = parse(page, appDir);
+  if (!parsed) throw new Error(`netjes: renderDocument cannot render ${page}, which is not in the app's directory, ${appDir}.`);
+  if (parsed.folders.some(isPrivate)) throw new Error(`netjes: renderDocument cannot render ${page}: a private folder is not routed.`);
+  const slot = parsed.folders.findIndex(isSlot);
+  if (slot >= 0) throw slotError(page, 'is in', [appDir, ...parsed.folders.slice(0, slot + 1)].join('/'));
+  const boundary = BOUNDARIES.get(parsed.name);
+  if ((parsed.name !== 'page' && !boundary) || (parsed.name === 'global-error' && parsed.folders.length > 0)) {
+    throw new Error(
+      `netjes: renderDocument renders a page or a not-found, error, forbidden, unauthorized or global-error file, not ${page}.`,
+    );
+  }
+
+  // The global error page renders without any layout, the others inside the segments down to their own folder.
+  const segments = parsed.name === 'global-error' ? [] : segmentsFor(page, appFiles(paths, appDir), parsed.folders, appDir, options);
+  for (const file of Object.keys(options.layouts ?? {})) {
+    if (!segments.some((segment) => segment.layout === file)) {
+      const layouts = segments.flatMap((segment) => (segment.layout ? [segment.layout] : []));
+      throw new Error(
+        `netjes: renderDocument has props for ${file}, which is not a layout of ${page}. ` +
+          (layouts.length > 0 ? `Its layouts are ${list(layouts)}.` : 'It has no layouts.'),
+      );
+    }
+  }
+  // An error boundary renders in place of the pages below its folder, so it is not wrapped in itself.
+  for (const segment of segments) if (segment.error === page) delete segment.error;
+
+  return {
+    kind: 'page',
+    route: parsed.name === 'page' ? `/${parsed.folders.filter((folder) => !isGroup(folder)).join('/')}` : null,
+    page,
+    ...(boundary ? { pageKind: boundary.kind } : {}),
+    segments,
+    props: options.props ?? {},
+    params: options.params ?? {},
+    shared: options.shared ?? null,
+    status: options.status ?? boundary?.status ?? 200,
+    url: options.url ?? '/',
+    version: 'test',
+    document: {
+      lang: options.lang ?? 'en',
+      assets: { stylesheets: [], modulePreloads: [], scripts: [] },
+      errorPage: null,
+      ...(options.publicConfig ? { publicConfig: options.publicConfig } : {}),
+      ...(options.nonce ? { nonce: options.nonce } : {}),
+    },
+  };
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return false;
+  return typeof (value as { then?: unknown }).then === 'function';
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** A JSON value with each Promise in it, at any depth, replaced by a `Page.Defer` placeholder; `values` keeps the Promises by id. */
+function withPlaceholders(value: unknown, values: Map<string, PromiseLike<unknown>>): unknown {
+  if (isThenable(value)) {
+    const id = `d${values.size}`;
+    values.set(id, value);
+    // Read once the document renders; until then a rejection is not an unhandled one.
+    Promise.resolve(value).catch(() => {});
+    return { $netjes: 'deferred', id };
+  }
+  if (Array.isArray(value)) return value.map((item: unknown) => withPlaceholders(item, values));
+  return isPlainObject(value) ? placeholdersIn(value, values) : value;
+}
+
+function placeholdersIn(props: Record<string, unknown>, values: Map<string, PromiseLike<unknown>>): Record<string, unknown> {
+  // Keys are defined, not assigned, so a "__proto__" key stays a key.
+  return Object.fromEntries(Object.entries(props).map(([key, item]) => [key, withPlaceholders(item, values)]));
+}
+
+async function text(stream: AsyncIterable<unknown>): Promise<string> {
+  const decoder = new TextDecoder();
+  let html = '';
+  for await (const chunk of stream) {
+    html += chunk instanceof Uint8Array ? decoder.decode(chunk, { stream: true }) : decoder.decode() + String(chunk);
+  }
+  return html + decoder.decode();
+}
+
+/**
+ * Renders a page's whole document, from `<!DOCTYPE html>` to `</html>`, as the Node sidecar renders it for a crawler:
+ * the page from `page`, a file of the pages map such as `app/blog/[slug]/page.tsx`, inside the layouts the server
+ * would wrap it in, with the head, Netjes's inline scripts and the payload. It waits for every Suspense boundary, and
+ * a Promise in the props or in a layout's props is a `Page.Defer` value: rendered in place once it resolves, left as its
+ * Suspense fallback when it rejects. The build's stylesheets and scripts, development styles and an antiforgery token
+ * are left out, and no C# runs: the props come from `options`. Runs in Vitest's node environment, with the `netjes()`
+ * plugin, which provides the pages map, the app's folder and the query shell, also when `modules` is given.
+ */
+export async function renderDocument(page: string, options: RenderDocumentOptions = {}): Promise<string> {
+  const { modules, signal, props, layouts, ...rest } = options;
+  // Before the first await, so that a Promise that has failed already gets its handler before Node looks for one.
+  const values = new Map<string, PromiseLike<unknown>>();
+  const sent: DocumentOptions = {
+    ...rest,
+    props: placeholdersIn(props ?? {}, values),
+    ...(layouts
+      ? { layouts: Object.fromEntries(Object.entries(layouts).map(([file, layoutProps]) => [file, placeholdersIn(layoutProps, values)])) }
+      : {}),
+  };
+  // A form's server action, the query client and the router's first URL take their browser path where these exist.
+  if (typeof window !== 'undefined' || typeof document !== 'undefined') {
+    throw new Error(
+      'netjes: renderDocument renders a page as the Node sidecar does, without a DOM. ' +
+        "Put '// @vitest-environment node' at the top of the test file.",
+    );
+  }
+  signal?.throwIfAborted();
+  const app = await import('virtual:netjes/pages');
+  const pages = modules ?? app.pages;
+  const payload = documentPayload(page, sent, Object.keys(pages), app.appDir);
+  // Loaded here, so that component tests, which import netjes/testing too, never load react-dom/server.
+  const { createServerRenderer } = await import('./server-render.tsx');
+  const stream = await createServerRenderer(pages).renderToStream(htmlSafeJson(payload), {
+    waitForAll: true,
+    deferred: (id) => values.get(id) ?? new Promise<never>(() => {}),
+    ...(signal ? { signal } : {}),
+  });
+  return text(stream);
+}
+
+/** JavaScript MIME type essences: a script element whose type is one of them, in any case, runs as a classic script. */
+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',
+]);
+
+/** The other script types whose inline text a browser checks against a policy's script sources. */
+const OTHER_SCRIPT_TYPES = new Set(['module', 'importmap', 'speculationrules']);
+
+/** A script element: its start tag's attributes (quoted values can hold a `>`) and its text, up to `</script`. */
+const SCRIPT = /<script(?=[\s/>])((?:"[^"]*"|'[^']*'|[^'">])*)>([\s\S]*?)<\/script(?=[\s/>])[^>]*>/gi;
+const ATTRIBUTE = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+
+const asciiLowerCase = (text: string) => text.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+
+function attributesOf(source: string): Map<string, string> {
+  const attributes = new Map<string, string>();
+  for (const [, name = '', double, single, bare] of source.matchAll(ATTRIBUTE)) {
+    const key = asciiLowerCase(name);
+    // As in HTML, the first of two attributes with one name counts.
+    if (!attributes.has(key)) attributes.set(key, double ?? single ?? bare ?? '');
+  }
+  return attributes;
+}
+
+/** Whether a browser runs an inline script element with these attributes, by HTML's rules for its type. */
+function runs(attributes: Map<string, string>): boolean {
+  const type = attributes.get('type');
+  const language = attributes.get('language');
+  const typeString =
+    type === '' || (type === undefined && !language)
+      ? 'text/javascript'
+      : type === undefined
+        ? `text/${language ?? ''}`
+        : type.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, '');
+  const kind = asciiLowerCase(typeString);
+  if (JAVASCRIPT_TYPES.has(kind)) return !attributes.has('nomodule');
+  return OTHER_SCRIPT_TYPES.has(kind);
+}
+
+async function hashSource(script: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(script)));
+  let bytes = '';
+  for (const byte of digest) bytes += String.fromCharCode(byte);
+  return `'sha256-${btoa(bytes)}'`;
+}
+
+/**
+ * The hash-sources, `'sha256-…'` in their quotes, of the inline scripts in `html` that a browser runs and checks
+ * against a Content-Security-Policy's script sources: each script element without `src` whose type a browser runs
+ * (none, a JavaScript type, `module`, `importmap` or `speculationrules`), with text. Each hash is listed once, in the
+ * order of the first script with it. Data blocks such as the page payload (`application/json`) are left out.
+ */
+export async function inlineScriptHashes(html: string): Promise<string[]> {
+  const scripts: string[] = [];
+  for (const [, tag = '', body = ''] of html.matchAll(SCRIPT)) {
+    const attributes = attributesOf(tag);
+    if (attributes.has('src') || !runs(attributes)) continue;
+    // The HTML parser turns each CR LF, and each CR on its own, into LF before the script sees its text.
+    const script = body.replace(/\r\n?/g, '\n');
+    // A browser checks an empty script against no policy, since it does not run it.
+    if (script !== '') scripts.push(script);
+  }
+  return [...new Set(await Promise.all(scripts.map(hashSource)))];
+}

package/src/route-announcer.tsx

@@ -0,0 +1,69 @@
+import { type CSSProperties, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+
+/**
+ * Out of sight and still read by screen readers. React sets these styles through the CSSOM on an element it creates
+ * in the browser, which a Content-Security-Policy without `'unsafe-inline'` in `style-src` allows.
+ */
+const VISUALLY_HIDDEN: CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  margin: -1,
+  padding: 0,
+  border: 0,
+  overflow: 'hidden',
+  clip: 'rect(0 0 0 0)',
+  clipPath: 'inset(50%)',
+  whiteSpace: 'nowrap',
+};
+
+const subscribe = () => () => {};
+const inBrowser = () => true;
+const onServer = () => false;
+
+/** A segment as a person reads it, `café` rather than `caf%C3%A9`; one that does not decode stays as it is. */
+function decodeSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+/** How a screen reader can name the page on screen: its title, else its first `h1`, else its path, decoded. */
+function pageName(path: string): string {
+  return document.title.trim() || document.querySelector('h1')?.textContent?.trim() || path.split('/').map(decodeSegment).join('/');
+}
+
+type RouteAnnouncerProps = {
+  /** The page's path and query: a navigation that changes neither (a refresh, a fragment link) names no page. */
+  location: string;
+  /** The path without the base path, the name of a page with neither a title nor an `h1`. */
+  path: string;
+};
+
+/**
+ * A polite live region that names the page after a client navigation, as a screen reader names the page a document
+ * load opens. It renders in the browser only, after hydration, so the server's HTML has none. It has no role, which
+ * would make it one more `status` or `alert` for an app's tests to find. Its effect runs after the app's, as a later
+ * sibling of the pages, so it reads the title and headings the new page has set. The first run records the name of
+ * the page the document loaded with; a later one, for another path or query, puts the new page's name in the region
+ * when it differs from the name of the page before. An intercepted page keeps the title of the page under it, so it
+ * is not named.
+ */
+export function RouteAnnouncer({ location, path }: RouteAnnouncerProps) {
+  const rendered = useSyncExternalStore(subscribe, inBrowser, onServer);
+  const [message, setMessage] = useState('');
+  const named = useRef<string | null>(null);
+  useEffect(() => {
+    const name = pageName(path);
+    if (named.current !== null && name !== named.current) setMessage(name);
+    named.current = name;
+  }, [location, path]);
+  if (!rendered) return null;
+  return (
+    <div aria-live="polite" aria-atomic="true" data-netjes-route-announcer="" style={VISUALLY_HIDDEN}>
+      {message}
+    </div>
+  );
+}

package/src/route-tree.tsx

@@ -1,4 +1,5 @@
 import { Component, type ReactElement, type ReactNode, Suspense, createContext } from 'react';
+import { withheldError } from './errors.ts';
 import { type Metadata, MetadataTags, resolveMetadata } from './metadata.tsx';
 import type { ErrorPageProps, LoadedSegment, RouteModules } from './modules.ts';
 import type { PageKind, Params, SegmentRef } from './payload.ts';
@@ -17,6 +18,8 @@ type RouteTreeProps = {
   pageKey: string;
   /** What `reset` does on an error page the server chose: load the page again. */
   retry?: () => void;
+  /** The error an error page (`pageKind` error) gets in place of the one the server's props describe: one caught here. */
+  error?: ErrorPageProps['error'];
   /** Metadata from the C# loader. */
   metadata?: Metadata | undefined;
 };
@@ -53,15 +56,23 @@ export class ErrorBoundary extends Component<BoundaryProps, { error: unknown; fa
   }
 }
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Something went wrong');
+/** What a boundary caught, as the Error `error.tsx` gets: an Error as it is, a string as its message, else a stand-in. */
+export function asError(error: unknown): ErrorPageProps['error'] {
+  if (error instanceof Error) return error;
+  return typeof error === 'string' ? new Error(error) : withheldError();
 }
 
-/** The error the server reported (props of the error page it rendered), as an Error for `error.tsx`. */
+/**
+ * The error the server reported (props of the error page it rendered), as an Error for `error.tsx`: marked withheld
+ * when the server says its message stands in for the exception's, and with the server's stack or none, never the
+ * stack of the code here that built it.
+ */
 function serverError(props: Record<string, unknown>): ErrorPageProps['error'] {
   const error: ErrorPageProps['error'] = new Error(typeof props.message === 'string' ? props.message : 'Something went wrong');
   if (typeof props.status === 'number') error.status = props.status;
-  if (typeof props.stack === 'string') error.stack = props.stack;
+  if (props.withheld === true) error.withheld = true;
+  // Defined rather than assigned, as an own property: Firefox keeps the stack in an accessor on Error.prototype.
+  Object.defineProperty(error, 'stack', { value: typeof props.stack === 'string' ? props.stack : undefined, writable: true, configurable: true });
   return error;
 }
 
@@ -70,9 +81,9 @@ function serverError(props: Record<string, unknown>): ErrorPageProps['error'] {
  * layout > template > error boundary > Suspense (loading) > the next segment or the page. Layouts keep their state
  * while the page underneath changes; templates remount.
  */
-export function RouteTree({ modules, segments = [], props, params, status, pageKind, pageKey, retry, metadata }: RouteTreeProps): ReactElement {
+export function RouteTree({ modules, segments = [], props, params, status, pageKind, pageKey, retry, metadata, error }: RouteTreeProps): ReactElement {
   const Page = modules.page;
-  const pageProps = pageKind === 'error' ? { ...props, error: serverError(props), reset: retry ?? (() => {}) } : props;
+  const pageProps = pageKind === 'error' ? { ...props, error: error ?? serverError(props), reset: retry ?? (() => {}) } : props;
   let element: ReactElement = Page ? <Page key={pageKey} {...pageProps} /> : <BuiltInPage key={pageKey} status={status} props={props} />;
   for (let i = modules.segments.length - 1; i >= 0; i--) {
     const { Layout, Template, Loading, Error: SegmentError, slots } = modules.segments[i]!;