@alxia/react-router 0.11.0 → 0.12.1

package/docs/guide/document.md

@@ -0,0 +1,321 @@
+# The document
+
+This page covers what the root route renders for the page's CSP nonce, from
+`@alxia/react-router/document`: the nonce on the server and in the browser,
+an inline script that carries it, the theme-boot recipe, and the page's
+language and text direction.
+
+`/document` is safe to import in the browser and imports only `react`.
+
+| export | |
+| --- | --- |
+| `DocumentNonce({ nonce, children })` | provides this response's nonce to the server render |
+| `useNonce()` | the page's nonce, on the server and in the browser |
+| `InlineScript({ code, nonce? })` | an inline `<script>` with the nonce; refuses `</script` and `<!--` |
+| `CspNonceMeta()` | `<meta property="csp-nonce" nonce>` |
+| `createPageLanguage({ languages, fallback })` | `pageLanguage`, `metaLanguage`, `chooseLanguage`, `useChosenLanguage` |
+| `textDirection(language)` | `'ltr'` or `'rtl'` for `<html dir>` |
+
+## The nonce on the server
+
+With `secureHeaders({ nonce: true })` the context carries a fresh nonce per
+request ([A CSP nonce](csp-nonce.md)). The server render needs it in the
+React tree too, so that the root, and every boundary that replaces it, can
+read it with `useNonce()`. Wrap the router in `entry.server.tsx`:
+
+```tsx
+// app/entry.server.tsx
+import { nonceOf } from '@alxia/react-router';
+import { DocumentNonce } from '@alxia/react-router/document';
+
+const nonce = nonceOf(loadContext);
+
+<DocumentNonce nonce={nonce}>
+	<ServerRouter context={routerContext} url={request.url} />
+</DocumentNonce>;
+```
+
+Do not put the nonce in a loader's data: the browser hides a nonce from the
+page, and loader data would print it as text in the hydration script and in
+every `.data` answer. An error page after an action's error runs no loader,
+and still reads the nonce, since the provider is above the router.
+
+## The nonce in the browser
+
+React Router's client knows no nonce, and React would find `nonce` on the
+server's elements and none in its own: a hydration mismatch. So in the
+browser `useNonce()` reads the `nonce` property of the first script or
+`csp-nonce` meta in the document's `<head>` (the browser hides the
+attribute, not the property), else of the first `script[nonce]` anywhere,
+once, and caches it. `DocumentNonce` is not needed there. With none of them
+it returns `undefined`.
+
+"The browser" means a global `document`. A server that installs a DOM shim
+on `globalThis` takes the browser path and finds no nonce, so it must not
+render `useNonce()` that way (and passes `browser: () => false` to
+`createPageLanguage`).
+
+The first read is cached per module copy. A test with a DOM keeps it across
+tests: reset modules between them, or render the server path with
+`DocumentNonce`.
+
+## What React Router renders
+
+With `@alxia/react-router/entry`, `<Scripts>` and `<ScrollRestoration>` need
+no `nonce`: they fall back to the nonce `<ServerRouter nonce>` put in React
+Router's framework context, and they suppress the hydration warning for the
+attribute the browser hides. `<Links>` falls back to it on the server too, but
+does not suppress the warning, so pass it `useNonce()`:
+
+```tsx
+// app/root.tsx
+import { useNonce } from '@alxia/react-router/document';
+
+export function Layout({ children }: { children: React.ReactNode }) {
+	const nonce = useNonce();
+	return (
+		<html lang="en">
+			<head>
+				<meta charSet="utf-8" />
+				<Links nonce={nonce} />
+			</head>
+			<body>
+				{children}
+				<ScrollRestoration />
+				<Scripts />
+			</body>
+		</html>
+	);
+}
+```
+
+Why `<Links>` needs it: in development, React Router renders the critical CSS
+as a `<style nonce>`. The server writes the nonce on it, the browser hides the
+attribute and React Router's client knows none, so without the prop the client
+renders the `<style>` with no nonce and React reports a mismatch
+([Troubleshooting](../troubleshooting.md#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties-on-a-style-with-a-nonce)).
+`useNonce()` returns the same value on both sides.
+
+Keep `useNonce()` for what React Router does not render: an `InlineScript`,
+a `CspNonceMeta`, and any script or style the app inserts itself.
+
+A page that carries a nonce is made for one response. A route's `headers`
+export must never make it `public`: a shared cache would hand the same nonce
+to every visitor.
+
+## The theme-boot script
+
+A theme library stores the choice (light, dark) and applies it with a class
+or an attribute on `<html>`. Applied after hydration, the page paints in the
+wrong theme first. The cure is an inline, synchronous script in `<head>`,
+which runs before the first paint. alxia ships the mechanism, not the
+script: the code is the theme library's own boot script (for example a UI
+kit's `themeBootScript()`), kept as a constant.
+
+```tsx
+// app/root.tsx
+import { CspNonceMeta, InlineScript } from '@alxia/react-router/document';
+import { themeBootScript } from '<your theme library>';
+
+const THEME_BOOT = themeBootScript();
+
+export function Layout({ children }: { children: React.ReactNode }) {
+	return (
+		<html lang="en" suppressHydrationWarning>
+			<head>
+				<InlineScript code={THEME_BOOT} />
+				<meta charSet="utf-8" />
+				<CspNonceMeta />
+				<Links />
+			</head>
+			<body>{children}</body>
+		</html>
+	);
+}
+```
+
+- **Place it first in `<head>`**, before `<Links>`: an inline script is
+  synchronous and runs before the first paint, without waiting for a
+  stylesheet. Only a `<meta charSet>` may come before it.
+- **Keep `suppressHydrationWarning` on `<html>`**: the script changes its
+  `class` and `style` before React hydrates, and React would warn that they
+  differ from the server's HTML. It silences that element's attributes only.
+- **The nonce is the response's**: `script-src 'nonce-…' 'strict-dynamic'`
+  allows the script because it carries it. `InlineScript` uses `useNonce()`
+  on the server and the document's nonce in the browser, so the attribute
+  matches during hydration. `nonce` overrides it for one script.
+- **With no nonce**, the script renders with no `nonce` attribute. The policy
+  must then allow it by `'unsafe-inline'` or a hash of the code.
+
+> **Warning:** the code is written unescaped. It is a constant of the app,
+> never user input. `InlineScript` throws a `TypeError` when it holds
+> `</script` or `<!--`, which end or confuse the element
+> ([the message](../troubleshooting.md#typeerror-inlinescript-the-code-contains-script-or----which-ends-or-confuses-the-script-element-escape-it-such-as-script-inside-a-string)):
+> escape it in a string: the code must contain `<\/script`, written
+> `"<\\/script"` in source.
+
+
+`CspNonceMeta` renders `<meta property="csp-nonce" nonce>`, which UI
+libraries read to give the scripts and styles they add at runtime the same
+nonce.
+
+## The entry
+
+`@alxia/react-router/entry` is `entry.server.tsx` for an app on Bun. It is
+server only, and it renders with the web stream renderer
+(`renderToReadableStream`), so it needs neither `@react-router/node` nor
+`node:stream`. It imports `react`, `react-dom/server`, `react-router` and
+`isbot` only when no `isBot` option is given (it is imported on the first bot
+check); `react-dom` and `isbot` are optional peers, which React Router's
+templates install.
+
+```tsx
+// app/entry.server.tsx
+export {
+	handleRequest as default,
+	streamTimeout,
+} from '@alxia/react-router/entry';
+```
+
+It does what React Router's revealed entry does:
+
+- **Streams** the shell and the rest as it resolves.
+- **Waits for the whole page** for a bot (`isbot`) and in SPA mode.
+- **Answers HEAD** with the status and the headers, and no body. Under
+  alxia a HEAD reaches the entry as a GET (the core drops the body), so this
+  is for a server that is not alxia.
+- **Aborts** the render `streamTimeout + 1 000` ms in, or as soon as the
+  client leaves (before the shell, or while a bot waits for the whole
+  page), and clears the timer when the body ends or the client goes away.
+- **Rejects when the shell fails**, so React Router logs it once and answers
+  with its error boundary. Once the shell is out, an error goes to `onError`
+  and the status stays as it was sent.
+- Sends `Content-Type: text/html`.
+
+And it gives the router the response's nonce: `<ServerRouter nonce>`,
+React's `nonce` option, and `<DocumentNonce>` around the router, so the
+root reads it with `useNonce()`.
+
+To change something, build the entry:
+
+```tsx
+// app/entry.server.tsx
+import { createEntry } from '@alxia/react-router/entry';
+
+const entry = createEntry({
+	streamTimeout: 8_000,
+	// Default: nonceOf(loadContext)
+	nonce: (loadContext, request) => nonceFor(request),
+	// Default: isbot(userAgent)
+	isBot: (userAgent) => /bot|crawl|spider/i.test(userAgent),
+	// Default: console.error
+	onError: (error) => logger.error(error),
+});
+
+export const streamTimeout = entry.streamTimeout;
+export default entry.handleRequest;
+```
+
+`createEntry` returns an `Entry`, `{ handleRequest, streamTimeout }`.
+
+| option | default | |
+| --- | --- | --- |
+| `streamTimeout` | `5_000` | ms React Router waits for a pending promise; export it as `streamTimeout` |
+| `nonce` | `nonceOf(loadContext)` | this response's CSP nonce |
+| `isBot` | `isbot`, imported when no `isBot` is given | whether a user agent gets the whole page |
+| `onError` | `console.error` | an error after the shell is out |
+
+An error inside a `<Suspense>` that fails during the first render pass, before the shell is out, turns the status into 500 and is not reported to `onError`, as in React Router's own entry; log it in the route's loader or `ErrorBoundary`.
+
+The nonce is passed to `ServerRouter` only when there is one, which
+satisfies `exactOptionalPropertyTypes`
+([the message](../troubleshooting.md#type---nonce-string--undefined--is-not-assignable-to-type-serverrouterprops-with-exactoptionalpropertytypes-true)).
+Under `react-router dev`, keep `alxia()` in `vite.config.ts`: it keeps one
+copy of `react-router` for the entry and the root
+([the message](../troubleshooting.md#error-you-must-render-this-element-inside-a-hydratedrouter-element)).
+
+## An entry of your own
+
+An entry that is not the package's wraps `<ServerRouter>` in
+`<DocumentNonce nonce={nonceOf(loadContext)}>` as shown
+[above](#the-nonce-on-the-server). Without it `useNonce()` is `undefined`
+on the server, and the page's inline scripts render with no nonce
+([the message](../troubleshooting.md#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-script-src-self-nonce-)).
+
+## The page's language
+
+`createPageLanguage` gives the root the page's language for `<html lang>` and
+a route's `meta`, and `textDirection` the `dir` that goes with it. The server
+side, negotiating the request's language from a cookie and `Accept-Language`,
+is [`@alxia/language`](https://github.com/softistx/alxia/blob/develop/packages/language/README.md):
+
+```ts
+// app/server.ts
+import { language } from '@alxia/language';
+import { createServer } from '@alxia/react-router';
+
+const server = createServer({
+	configure: (app) =>
+		app.use(language({ supported: ['en', 'fr', 'ar'], fallback: 'en', order: ['cookie', 'header'] })),
+});
+export default server;
+declare module '@alxia/react-router' {
+	interface Register { server: typeof server }
+}
+```
+
+```ts
+// app/language.ts: one instance, imported by the root and the routes
+import { createPageLanguage } from '@alxia/react-router/document';
+
+export const { pageLanguage, metaLanguage, chooseLanguage, useChosenLanguage } =
+	createPageLanguage({ languages: ['en', 'fr', 'ar'], fallback: 'en' });
+```
+
+```tsx
+// app/root.tsx
+import { type AlxiaArgs, withAlxia } from '@alxia/react-router';
+import { textDirection } from '@alxia/react-router/document';
+import { useRouteLoaderData } from 'react-router';
+import { metaLanguage, pageLanguage, useChosenLanguage } from './language';
+import type { Route } from './+types/root';
+
+const titles = { en: 'Home', fr: 'Accueil', ar: 'الرئيسية' };
+
+// the root loader returns alxia.language, set by the middleware
+export const loader = withAlxia(({ alxia }: Route.LoaderArgs & AlxiaArgs) => ({ language: alxia.language }));
+
+export function Layout({ children }: { children: React.ReactNode }) {
+	const data = useRouteLoaderData<typeof loader>('root');
+	const language = pageLanguage(data?.language);
+	useChosenLanguage(); // re-renders the shell when the menu picks a language
+	return (
+		<html lang={language} dir={textDirection(language)} suppressHydrationWarning>
+			{/* … */}
+		</html>
+	);
+}
+
+export const meta: Route.MetaFunction = ({ matches }) => [
+	{ title: titles[metaLanguage(matches)] },
+];
+```
+
+- `pageLanguage(language)` is the supported language, else the fallback. In
+  the browser the one picked with `chooseLanguage(language)` wins, and the
+  last one seen stands in when the root's data is gone. On the server it
+  remembers nothing: one module serves every request. A server that
+  registers a DOM shim globally (happy-dom or jsdom) is read as a browser:
+  pass `browser: false` there.
+- `metaLanguage(matches)` reads `matches[0].loaderData.language`.
+- `useChosenLanguage()` is the picked language, or `undefined`; it
+  re-renders on a pick, and is `undefined` in the server render so
+  hydration matches.
+- `textDirection(tag)` is `'rtl'` for `ar`, `fa`, `he`, `ur`, `ps`, `yi`,
+  `dv`, `ckb`, `sd` and `ug` (and the legacy `iw` and `ji`), else `'ltr'`, reading the base tag whatever its
+  case (`ar-EG`, `AR`). A script subtag is not read: `az-Arab` is `'ltr'`.
+- A fallback outside `languages` throws
+  ([the message](../troubleshooting.md#typeerror-createpagelanguage-the-fallback--is-not-one-of-the-languages-got-)).
+  An error page keeps the root's data, so it keeps the language, except
+  for a URL that matches no route or a root loader that threw: there it
+  shows the last language seen in the browser, or the fallback ([why](../troubleshooting.md#the-error-page-shows-in-the-fallback-language)).

package/docs/roadmap.md

@@ -7,7 +7,7 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing in progress.
+Nothing planned.
 
 ## Next
 
@@ -15,6 +15,8 @@ Nothing planned.
 
 ## Later
 
+- **Hreflang alternates** for an app with one URL per language. Today the
+  language is negotiated on a single URL, so there is no alternate to link.
 - **`service-worker.js` served revalidated with no setup.** Today the app
   adds `noCache` for `SERVICE_WORKER_URL` itself.
 - **A check of an offline page's policy.** The offline page declares its
@@ -33,6 +35,8 @@ Nothing planned.
 
 ## Not planned
 
+- **The theme's own boot script.** `InlineScript` renders it with the nonce;
+  its text, its storage keys and class names, are the UI library's.
 - **React Router 7.** Its loaders' context is a `RouterContextProvider`
   only behind `future.v8_middleware`, and the line is in maintenance.
 - **Node or Cloudflare.** alxia is a Bun framework; React Router's own
@@ -53,6 +57,18 @@ Nothing planned.
 
 ## Shipped
 
+### 0.12.0
+
+- **`@alxia/react-router/document` and `/entry`: the boot of a page.**
+  `DocumentNonce`, `useNonce`, `InlineScript` and `CspNonceMeta` give the
+  root the response's CSP nonce, an inline boot script that carries it and
+  the `csp-nonce` meta; `createPageLanguage` and `textDirection` give the
+  page's language and text direction. `entry.server.tsx` becomes
+  `export { handleRequest as default, streamTimeout } from '@alxia/react-router/entry'`:
+  a streamed shell on Bun's web renderer, the whole page for a bot and in SPA
+  mode, no body for HEAD, and the nonce handed to the router, with no
+  `@react-router/node` and no `node:stream`.
+
 ### 0.11.0
 
 - **`@alxia/react-router/errors`: an API's refusals, worded for the page.**

package/docs/troubleshooting.md

@@ -26,6 +26,14 @@ a loader, a message React Router or the browser prints, or an error from
 - [`TypeError: reactRouter(): client is …, which is not a directory. …`](#typeerror-reactrouter-client-is--which-is-not-a-directory-)
 - [`TypeError: reactRouter(): … cannot be served at a path of its own name; rename it. …`](#typeerror-reactrouter--cannot-be-served-at-a-path-of-its-own-name-rename-it-)
 - [`Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'none'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-default-src-none)
+- [`Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-script-src-self-nonce-)
+- [`A tree hydrated but some attributes of the server rendered HTML didn't match the client properties`](#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties)
+- [`A tree hydrated but some attributes of the server rendered HTML didn't match the client properties` on a `<style>` with a `nonce`](#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties-on-a-style-with-a-nonce)
+- [`useNonce()` is undefined on the server](#usenonce-is-undefined-on-the-server)
+- [`TypeError: InlineScript(): the code contains "</script" or "<!--", which ends or confuses the script element; escape it, such as "<\/script" inside a string`](#typeerror-inlinescript-the-code-contains-script-or----which-ends-or-confuses-the-script-element-escape-it-such-as-script-inside-a-string)
+- [`TypeError: createPageLanguage(): the fallback … is not one of the languages; got ….`](#typeerror-createpagelanguage-the-fallback--is-not-one-of-the-languages-got-)
+- [The error page shows in the fallback language](#the-error-page-shows-in-the-fallback-language)
+- [`Error: You must render this element inside a <HydratedRouter> element`](#error-you-must-render-this-element-inside-a-hydratedrouter-element)
 - [`alxia-react-router: … already exists, and reveal leaves it as it is. Run alxia-react-router reveal --force to overwrite it.`](#alxia-react-router--already-exists-and-reveal-leaves-it-as-it-is-run-alxia-react-router-reveal---force-to-overwrite-it)
 - [`alxia-react-router: no vite.config.ts in …. Run reveal from the app's root, beside vite.config.ts.`](#alxia-react-router-no-viteconfigts-in--run-reveal-from-the-apps-root-beside-viteconfigts)
 - [`alxia-react-router: … gives alxia() an entry reveal cannot read. …`](#alxia-react-router--gives-alxia-an-entry-reveal-cannot-read-)
@@ -44,6 +52,7 @@ a loader, a message React Router or the browser prints, or an error from
 - [`TypeError: defineWorkerContract(): cacheVersion must be a non-empty name without '-', …`](#typeerror-defineworkercontract-cacheversion-must-be-a-non-empty-name-without---)
 - [`parseBrowserManifest(): not React Router's browser manifest …`](#parsebrowsermanifest-not-react-routers-browser-manifest-)
 - [`error: Cannot find package 'react' from '…/@alxia/react-router/dist/pwa/react/index.js'`](#error-cannot-find-package-react-from-alxiareact-routerdistpwareactindexjs)
+- [`error: Cannot find package 'isbot' from '…/@alxia/react-router/dist/entry/index.js'`](#error-cannot-find-package-isbot-from-alxiareact-routerdistentryindexjs)
 - [`startWorker(): no precache list. …`](#startworker-no-precache-list-)
 - [`TypeError: startWorker(): contract is required: …`](#typeerror-startworker-contract-is-required-)
 - [`error: Could not resolve: "workbox-core". Maybe you need to "bun install"?`](#error-could-not-resolve-workbox-core-maybe-you-need-to-bun-install)
@@ -538,6 +547,236 @@ or `contentSecurityPolicy: false`. Better than `'unsafe-inline'`: a nonce
 per request, with `nonce: true` and `nonceOf(loadContext)` in
 `entry.server.tsx` ([guide](guide/csp-nonce.md#a-csp-nonce)).
 
+### `Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`
+
+**When:** the root renders an `<InlineScript>` (a theme's boot script, say)
+and the policy names a nonce.
+
+**Why:** the script rendered with no `nonce` attribute, because
+`useNonce()` found no nonce: the server render has no `<DocumentNonce>`
+around the router (an entry of your own that does not provide it), so
+`InlineScript` renders a bare `<script>`. The browser then refuses it, and
+the page flashes the wrong theme.
+
+**Fix:** wrap the router in the nonce `secureHeaders({ nonce: true })`
+made, in `entry.server.tsx`, or pass one to the script:
+
+```tsx
+// app/entry.server.tsx
+import { nonceOf } from '@alxia/react-router';
+import { DocumentNonce } from '@alxia/react-router/document';
+
+return (
+	<DocumentNonce nonce={nonceOf(loadContext)}>
+		<ServerRouter context={routerContext} url={request.url} />
+	</DocumentNonce>
+);
+```
+
+or, for one script, `<InlineScript code={THEME_BOOT} nonce={nonce} />`.
+
+Check the response: `curl -s -A 'Mozilla/5.0 Chrome/130' http://localhost:5173/ | grep -o '<script[^>]*>'`
+should show `nonce="…"` on the boot script too
+([guide](guide/document.md#the-nonce-on-the-server)).
+
+### `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties`
+
+**When:** the page hydrates, and the warning names `<html>` with a `class`
+or `style` the server did not render.
+
+**Why:** a boot script (a theme's) sets `class` and `style` on `<html>`
+before React hydrates, so the DOM no longer equals the server's HTML.
+
+**Fix:** keep `suppressHydrationWarning` on `<html>`. It silences that
+element's own attributes only, not its children:
+
+```tsx
+// app/root.tsx
+<html lang="en" suppressHydrationWarning>
+	<head>
+		<InlineScript code={THEME_BOOT} />
+	</head>
+	<body>{children}</body>
+</html>
+```
+
+A warning on another element is a real mismatch: a `nonce` the browser hid
+is read by `useNonce()` from the document, so never pass it from loader
+data ([guide](guide/document.md#the-theme-boot-script)).
+
+### `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties` on a `<style>` with a `nonce`
+
+**When:** in development (`react-router dev`) with a CSP nonce, the console
+warns that a tree hydrated but some attributes did not match, and the diff
+shows `nonce="…"` on the `<style data-react-router-critical-css>` in `<head>`.
+
+**Why:** React Router renders the critical CSS as a `<style nonce>`. The
+server writes the nonce from `<ServerRouter nonce>`, the browser hides the
+attribute, and `<Links />` has no nonce to render on the client. Unlike
+`<Scripts>` and `<ScrollRestoration>`, `<Links>` does not suppress that
+warning.
+
+**Fix:** pass it the nonce `useNonce()` reads, on both sides:
+
+```tsx
+// app/root.tsx
+import { useNonce } from '@alxia/react-router/document';
+
+export function Layout({ children }: { children: React.ReactNode }) {
+	const nonce = useNonce();
+	return (
+		<html lang="en">
+			<head>
+				<Links nonce={nonce} />
+			</head>
+			<body>{children}</body>
+		</html>
+	);
+}
+```
+
+`<Scripts>` and `<ScrollRestoration>` need nothing
+([guide](guide/document.md#what-react-router-renders)).
+
+### `useNonce()` is undefined on the server
+
+**When:** the page's inline scripts or `<CspNonceMeta />` render with no
+`nonce` attribute although `secureHeaders({ nonce: true })` set one, and
+`useNonce()` returns `undefined` in the root.
+
+**Why:** the server render has no `<DocumentNonce>` around the router. The
+entry of `@alxia/react-router/entry` adds it; an entry of your own, such
+as React Router's revealed one, does not, and `ServerRouter`'s own `nonce`
+prop only reaches the scripts React Router writes.
+
+**Fix:** re-export the package's entry, or wrap the router in your own:
+
+```tsx
+// app/entry.server.tsx
+export {
+	handleRequest as default,
+	streamTimeout,
+} from '@alxia/react-router/entry';
+```
+
+```tsx
+// An entry of your own
+import { nonceOf } from '@alxia/react-router';
+import { DocumentNonce } from '@alxia/react-router/document';
+
+<DocumentNonce nonce={nonceOf(loadContext)}>
+	<ServerRouter context={routerContext} url={request.url} />
+</DocumentNonce>;
+```
+
+([guide](guide/document.md#the-entry))
+
+### `TypeError: InlineScript(): the code contains "</script" or "<!--", which ends or confuses the script element; escape it, such as "<\/script" inside a string`
+
+**When:** a page renders an `<InlineScript code={…} />` whose code holds
+`</script` (in any case) or `<!--`.
+
+**Why:** the code is written into the page unescaped. A `</script` ends the
+element early, so what follows is HTML, not script, and can be markup an
+attacker chose; a `<!--` makes the HTML parser treat the following
+`<script` as part of the script's text. A nonce does not help: it only says
+the script may run. The component refuses the code instead of rendering it.
+
+**Fix:** keep the code a constant of the app and escape the sequence inside
+a string. The code that reaches `InlineScript` must contain `<\/`, which the
+browser's script reads as `</`, and which is written `"<\\/script"` in a
+source string literal:
+
+```tsx
+<InlineScript code={'document.title = "<\\/script>"'} />
+```
+
+Never build the code from user input; pass such a value through a `data-`
+attribute and read it from the script.
+([guide](guide/document.md#the-theme-boot-script))
+
+### `TypeError: createPageLanguage(): the fallback … is not one of the languages; got ….`
+
+```text
+TypeError: createPageLanguage(): the fallback "de" is not one of the languages; got ["en","fr"].
+```
+
+**When:** the module that calls `createPageLanguage` loads.
+
+**Why:** `fallback` is the language of a page whose root data gives none, so
+it must be one of `languages`. The usual cause is a fallback in another
+spelling (`en-US` for `en`), or a `languages` list built from a different
+source than the fallback.
+
+**Fix:** name a language of the list:
+
+```ts
+createPageLanguage({ languages: ['en', 'fr'], fallback: 'en' });
+```
+
+### The error page shows in the fallback language
+
+**When:** on an error document, the root's `<html lang>` or text shows the
+fallback language although the visitor uses another.
+
+**Why:** a child route's error keeps the root's loader data. React Router
+keeps `loaderData` for every loader that succeeded, so
+`useRouteLoaderData('root')` still has it in `Layout` and `ErrorBoundary`.
+The data is missing in only two cases:
+
+- the URL matches no route, which is a 404 that runs no loader at all, the
+  root's included;
+- the root's own loader threw.
+
+With no data, `pageLanguage(undefined)` has no language to read. In the
+browser it keeps the last language it saw and the one picked with
+`chooseLanguage`; a document the server renders as an error has seen
+neither, so the fallback shows.
+
+**Fix, 404:** add a splat route whose loader throws a 404, so the URL
+matches and the root loader runs:
+
+```ts
+// app/routes.ts: add it last in your route config
+import { route } from '@react-router/dev/routes';
+
+route('*', 'routes/not-found.tsx');
+```
+
+```ts
+// app/routes/not-found.tsx
+import { data } from 'react-router';
+
+export const loader = () => {
+	throw data(null, { status: 404 });
+};
+```
+
+**Fix, root loader:** keep the root loader to `{ language: alxia.language }`,
+with nothing fallible in it. Load fallible data in child routes, or catch it
+and return it as a field.
+
+**Fix, client:** none is needed: a failed client navigation keeps the last
+language through `pageLanguage`.
+
+### `Error: You must render this element inside a <HydratedRouter> element`
+
+**When:** under `react-router dev` or after `react-router build`, every page
+answers "Unexpected Server Error" with this message, once
+`entry.server.tsx` re-exports `@alxia/react-router/entry`.
+
+**Why:** the server holds two copies of `react-router`: the one that
+renders `ServerRouter` in the entry, and the one `<Links>` and `<Scripts>`
+in the root read. They share no context. `alxia()` from
+`@alxia/react-router/vite` keeps them to one (it inlines `/entry` and
+`/document`, by an alias in dev and in the build, so they import the app's
+`react-router`). The message means `@alxia/react-router` is listed in
+`ssr.external` and `alxia()` is not in use.
+
+**Fix:** add `alxia()` to `vite.config.ts` beside `reactRouter()`, or list
+`@alxia/react-router` in `ssr.noExternal` and remove it from
+`ssr.external`.
+
 ### `alxia-react-router: … already exists, and reveal leaves it as it is. Run alxia-react-router reveal --force to overwrite it.`
 
 ```text
@@ -910,6 +1149,30 @@ this message too.
 `/pwa/react` from the page alone. The worker and a build script import
 `@alxia/react-router/pwa`, which imports nothing.
 
+### `error: Cannot find package 'isbot' from '…/@alxia/react-router/dist/entry/index.js'`
+
+**When:** a request with a user agent reaches `entry.server.tsx` re-exporting
+`@alxia/react-router/entry` (or a `createEntry()` with no `isBot` option).
+
+```text
+error: Cannot find package 'isbot' from '/app/node_modules/@alxia/react-router/dist/entry/index.js'
+```
+
+**Why:** with no `isBot` option, `/entry` asks `isbot` whether a request
+comes from a crawler, which then gets the whole page, and imports it on the
+first request that needs it. `isbot` and `react-dom` are optional peers of
+the package, so nothing installs them for you. React Router's templates
+install both; an app made another way may not.
+
+**Fix:** add them where the server is built and run:
+
+```sh
+bun add isbot react-dom
+```
+
+Or give the `isBot` option, which replaces the check: `isbot` is then never
+imported, and only `react-dom` is needed.
+
 ### `startWorker(): no precache list. …`
 
 **Why:** the full message ends "Build this worker with `alxia()` from
@@ -1490,7 +1753,9 @@ error TS2375: Type '{ context: EntryContext; url: string; nonce: string | undefi
 `ServerRouterProps.nonce` is optional without `undefined`. React's
 `nonce` option takes `undefined`, so only the prop complains.
 
-**Fix:** spread the prop in only when there is a nonce:
+**Fix:** use `@alxia/react-router/entry`, whose `handleRequest` does it
+([guide](guide/document.md#the-entry)), or spread the prop in only when
+there is a nonce, in an entry of your own:
 
 ```tsx
 const nonce = nonceOf(loadContext);