netjes 0.0.1 → 0.0.3

package/src/client-entry.tsx

@@ -1,12 +1,15 @@
-// Must come first: installs the React Fast Refresh runtime before any component module runs (empty in builds).
+// Must come first, ahead of anything that could make a zod schema: turns zod's compiled parsers off (ADR 0036).
+import './zod-jitless.ts';
+// Must come before any component module: installs the React Fast Refresh runtime before one runs (empty in builds).
 import '@vitejs/plugin-react/preamble';
 import { createRoot, hydrateRoot } from 'react-dom/client';
 import { pages } from 'virtual:netjes/pages';
 import { deferredRegistry, revivePayload } from './deferred.ts';
 import { type RouteModules, createModuleLoader } from './modules.ts';
-import { DATA_ELEMENT_ID, parseInitialPayload } from './payload.ts';
+import { DATA_ELEMENT_ID, SHELL_END_ID, parseInitialPayload } from './payload.ts';
 import { Root } from './root.tsx';
 import { withClockOffset } from './router.tsx';
+import { BEFORE_INTERACTIVE_MARKER, adoptServerScripts } from './script.tsx';
 
 /**
  * The payload is the body's first element, so it is normally parsed by the time this async script runs. If the
@@ -36,6 +39,28 @@ function payloadElement(): Promise<HTMLElement | null> {
   });
 }
 
+/**
+ * Resolves once the parser has passed the end of the shell, the empty element `Document` writes last in the body.
+ * This script is async, so a cached copy can run as soon as the payload is in, before most of the page is: hydrating
+ * then would meet half a document, give up and render the page in the browser, and the parser would add the rest of
+ * the server's HTML below it, so the page would show twice.
+ */
+function shellParsed(): Promise<void> {
+  if (document.getElementById(SHELL_END_ID) || document.readyState !== 'loading') return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      observer.disconnect();
+      document.removeEventListener('DOMContentLoaded', done);
+      resolve();
+    };
+    const observer = new MutationObserver(() => {
+      if (document.getElementById(SHELL_END_ID)) done();
+    });
+    observer.observe(document, { childList: true, subtree: true });
+    document.addEventListener('DOMContentLoaded', done);
+  });
+}
+
 const dataJson = (await payloadElement())?.textContent;
 if (!dataJson) throw new Error(`netjes: #${DATA_ELEMENT_ID} is missing; was this page rendered by Netjes?`);
 
@@ -90,6 +115,18 @@ async function firstPageModules(): Promise<RouteModules | null> {
   }
 }
 
+/**
+ * A `<Script strategy="beforeInteractive">` in the server's document puts a marker in the head, which is complete by
+ * the time the payload is read. Such a page waits for the end of the shell, where the parser has run the inline ones,
+ * then runs the external ones in order and waits for them, before the page's modules run and hydrate (ADR 0044). A
+ * page without one loads its modules while the rest of the shell arrives (ADR 0022).
+ */
+const beforeInteractive = document.head.querySelector(`meta[name="${BEFORE_INTERACTIVE_MARKER}"]`) !== null;
+if (beforeInteractive) {
+  await shellParsed();
+  await adoptServerScripts(payload.document.nonce);
+}
+
 const modules = await firstPageModules();
 if (modules) {
   const root = <Root payload={payload} modules={modules} loader={loader} dataJson={dataJson} />;
@@ -98,6 +135,10 @@ if (modules) {
     // the scripts and stylesheets already in it and replaces the rest.
     createRoot(document).render(root);
   } else {
+    if (!beforeInteractive) {
+      await shellParsed();
+      await adoptServerScripts(payload.document.nonce);
+    }
     hydrateRoot(document, root);
   }
 }

package/src/deferred.ts

@@ -1,5 +1,6 @@
 // Deferred loader values (Page.Defer in C#): placeholders in the payload that become promises the page reads with
 // React's use() inside a Suspense boundary.
+import { withheldError } from './errors.ts';
 import type { PagePayload, SegmentRef } from './payload.ts';
 
 /** A promise that records its outcome the way React's `use()` reads it, so a settled one renders without suspending. */
@@ -94,8 +95,9 @@ export function deferredRegistry() {
     resolve(id: string, value: unknown) {
       entry(id).resolve(value);
     },
+    /** Fails a value with the server's message; an empty one is a message the server withheld (no error details). */
     reject(id: string, message: string) {
-      entry(id).reject(new Error(message));
+      entry(id).reject(message === '' ? withheldError() : new Error(message));
     },
     /** Rejects every value still pending, e.g. when the stream that was to deliver them ended. */
     rejectPending(message: (id: string) => string) {
@@ -115,6 +117,17 @@ export function deferredRegistry() {
 export const DEFERRED_BOOTSTRAP =
   "self.__netjes_d=self.__netjes_d||function(i,v,e){self.__netjes_v[i]=[v,e]};Object.prototype.hasOwnProperty.call(self,'__netjes_v')||(self.__netjes_v={})";
 
+/**
+ * The `script-src` sources that allow Netjes's fixed inline scripts by their hashes, for a policy without a nonce: each
+ * `'sha256-…'` in its quotes, separated by spaces, as in `` `script-src 'self' ${CSP_SCRIPT_HASHES}` ``. A fixed script
+ * has the same text in every document. In this version there is one, the bootstrap that collects streamed `Page.Defer`
+ * values, and a Netjes version that changes it or adds another changes the value. The scripts that deliver those
+ * values, and React's scripts that reveal Suspense boundaries, differ from render to render, so no hash covers them.
+ * React's script for form actions that are functions is left out too, since its text follows the React version. The
+ * same value as `NetjesContentSecurityPolicy.ScriptHashes` in C#.
+ */
+export const CSP_SCRIPT_HASHES: string = "'sha256-FSjVV+FzmXP8KKrLKLdvst/5N/bEWSkde01XzpGKRgs='";
+
 const UNSAFE = /[<>&\u2028\u2029]/g;
 
 /** JSON that can sit inside a <script> element. */

package/src/document.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 import { DEFERRED_BOOTSTRAP } from './deferred.ts';
-import { DATA_ELEMENT_ID, type DocumentInfo } from './payload.ts';
+import { DATA_ELEMENT_ID, type DocumentInfo, SHELL_END_ID } from './payload.ts';
 
 type DocumentProps = { info: DocumentInfo; dataJson: string; children: ReactNode };
 
@@ -8,14 +8,24 @@ type DocumentProps = { info: DocumentInfo; dataJson: string; children: ReactNode
  * The `<html>` shell around every page. React renders and hydrates the whole document, so `<title>`, `<meta>`
  * and `<link>` rendered by pages and layouts end up in the head.
  *
- * Documents stream, so the client entry is `async`: it hydrates the shell as soon as it loads, not once the last
- * Suspense boundary has arrived. Everything it reads comes before the content: the deferred-values bootstrap in the
- * head, the payload first in the body.
+ * Documents stream, so the client entry is `async`: it hydrates the shell as soon as the shell is in, not once the
+ * last Suspense boundary has arrived. Everything it reads comes before the content: the deferred-values bootstrap in
+ * the head, the payload first in the body. The empty element at the end of the body is the last thing in the shell,
+ * which the client entry waits for before it hydrates: a cached entry can run long before the parser gets there.
  */
 export function Document({ info, dataJson, children }: DocumentProps) {
   const { nonce } = info;
+  // Netjes owns <html> and <body>: the app's layout renders inside the body, so its markup cannot give either one an
+  // attribute. A script that runs before hydration can (a theme, a browser extension, a translator), and in development
+  // React logs a mismatch for each attribute on an element that its props do not have. suppressHydrationWarning ends
+  // that check for the element's own attributes. It also makes React accept any text that is the element's own child,
+  // in production too: text that a layout or a page renders outside any element or Suspense boundary sits directly in
+  // the body, and a mismatch there is neither reported nor repaired. The elements in the body are checked as before,
+  // their attributes and their text. React does not write the prop into the markup, and production does not check
+  // attributes at all. The check is off for `lang` too: the server and the client read it from the same payload, so it
+  // differs only when a script changed it, or when Netjes has a bug.
   return (
-    <html lang={info.lang}>
+    <html lang={info.lang} suppressHydrationWarning>
       <head>
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -27,8 +37,18 @@ export function Document({ info, dataJson, children }: DocumentProps) {
         {info.assets.stylesheets.map((href) => (
           <link key={href} rel="stylesheet" href={href} nonce={nonce} />
         ))}
+        {/* In development, the CSS the page imports, so that it is styled before its scripts run. Vite's client owns
+            each element's text once it runs: the CSS module with that id sets it as it loads, before hydration, and
+            again after every edit. The sidecar inlines the build that module carries, but a file edited between the
+            render and the import differs, so React leaves the text unchecked. */}
         {info.devStyles?.map((style) => (
-          <style key={style.id} data-vite-dev-id={style.id} nonce={nonce} dangerouslySetInnerHTML={{ __html: style.css }} />
+          <style
+            key={style.id}
+            data-vite-dev-id={style.id}
+            nonce={nonce}
+            suppressHydrationWarning
+            dangerouslySetInnerHTML={{ __html: style.css }}
+          />
         ))}
         {info.assets.modulePreloads.map((href) => (
           <link key={href} rel="modulepreload" href={href} nonce={nonce} />
@@ -37,10 +57,11 @@ export function Document({ info, dataJson, children }: DocumentProps) {
           <script key={src} type="module" src={src} async nonce={nonce} />
         ))}
       </head>
-      <body>
+      <body suppressHydrationWarning>
         {/* Already escaped for HTML by the server; the client reads it back verbatim to hydrate. */}
         <script id={DATA_ELEMENT_ID} type="application/json" nonce={nonce} dangerouslySetInnerHTML={{ __html: dataJson }} />
         {children}
+        <template id={SHELL_END_ID} />
       </body>
     </html>
   );

package/src/errors.ts

@@ -0,0 +1,12 @@
+// The mark on errors whose message Netjes withheld: `withheld` is true when the message is Netjes's stand-in for one it
+// does not show (error details are off, or the thrown value had none), so `!error.withheld` means it is worth showing.
+
+/** Netjes's stand-in for a message it does not show, marked as one. */
+export function withheldError(): Error & { withheld: true } {
+  return Object.assign(new Error('Something went wrong'), { withheld: true as const });
+}
+
+/** Whether `error` is marked as one whose message was withheld. */
+export function isWithheld(error: unknown): boolean {
+  return error instanceof Error && (error as { withheld?: unknown }).withheld === true;
+}

package/src/form.tsx

@@ -1,4 +1,4 @@
-import type { ButtonHTMLAttributes, FormHTMLAttributes, SubmitEvent } from 'react';
+import type { ComponentPropsWithRef, SubmitEvent } from 'react';
 import { RETURN_FIELD, actionMetaOf } from './actions.tsx';
 import { encodeForm } from './form-data.ts';
 import type { Href } from './href.ts';
@@ -7,8 +7,8 @@ import { useBasePath, useInternalRouter, usePagePayload, withBasePath } from './
 /** A React form action, e.g. the `formAction` from `useAction(serverAction('name'))`. */
 export type FormAction = (formData: FormData) => void | Promise<void>;
 
-/** The props of `<Form>`: a form's own, with client navigation and server action support. */
-export type FormProps = Omit<FormHTMLAttributes<HTMLFormElement>, 'method' | 'action'> & {
+/** The props of `<Form>`: a form's own and its ref, with client navigation and server action support. */
+export type FormProps = Omit<ComponentPropsWithRef<'form'>, 'method' | 'action'> & {
   method?: 'get' | 'post';
   /**
    * Where to submit. Default: the current URL, which is where `MapPageAction` handlers for this page listen. Or a
@@ -74,6 +74,9 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
   }
 
   function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
+    // Read before the app's own onSubmit, which runs as the form is submitted: where it moves the focus, the router
+    // leaves it, as after a link's onClick.
+    const focusedAtStart = document.activeElement;
     onSubmit?.(event);
     if (event.defaultPrevented || reloadDocument) return;
     const form = event.currentTarget;
@@ -88,7 +91,7 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
     const data = formDataOf(form, submitter);
     const submitMethod = (submitter?.getAttribute('formmethod') ?? method).toLowerCase();
     if (submitMethod === 'post') {
-      void router.submit(url, encodeForm(data, form.enctype === 'multipart/form-data'));
+      void router.submit(url, encodeForm(data, form.enctype === 'multipart/form-data'), { focusedAtStart });
       return;
     }
     const query = new URLSearchParams();
@@ -97,7 +100,7 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
     url.hash = '';
     // Built from the form's own action, which is not one of the app's typed routes.
     const href = url.href as Href;
-    void (replace ? router.replace(href) : router.push(href));
+    void (replace ? router.replace(href, { focusedAtStart }) : router.push(href, { focusedAtStart }));
   }
 
   return (
@@ -108,8 +111,8 @@ export function Form({ method = 'get', action, replace = false, reloadDocument =
   );
 }
 
-/** The props of `<SubmitButton>`: a button's own, except `type`. */
-export type SubmitButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'>;
+/** The props of `<SubmitButton>`: a button's own and its ref, except `type`. */
+export type SubmitButtonProps = Omit<ComponentPropsWithRef<'button'>, 'type'>;
 
 /**
  * A submit button whose `formAction` is rendered under the base path, so it posts to the right place with and

package/src/href.ts

@@ -26,9 +26,13 @@ function matches(pattern: readonly string[], path: readonly string[]): boolean {
 
 /**
  * Whether a URL is one of the app's pages (by route pattern), a link within the page (`?…`, `#…`), or another
- * site. The generated `isHref()` and `Href` schema call this to check URLs that come from data.
+ * site. The generated `isHref()` and `Href` schema call this to check URLs that come from data. A URL with an ASCII
+ * control character, or with a space at either end, is none of these.
  */
 export function isRouteHref(value: string, patterns: readonly string[]): boolean {
+  // Browsers drop tabs and newlines anywhere in a URL, and control characters and spaces at either end: `/\t/host`
+  // would be `//host`. A C# Href refuses the same.
+  if (/[\u0000-\u001F\u007F]/.test(value) || value.startsWith(' ') || value.endsWith(' ')) return false;
   if (/^(https?:|mailto:|tel:)/i.test(value) || value.startsWith('?') || value.startsWith('#')) return true;
   // "//host" and "/\host" are other hosts as far as browsers are concerned.
   if (!value.startsWith('/') || value.startsWith('//') || value.startsWith('/\\')) return false;
@@ -36,14 +40,39 @@ export function isRouteHref(value: string, patterns: readonly string[]): boolean
   return patterns.some((pattern) => matches(pattern.split('/').filter(Boolean), path));
 }
 
+/**
+ * A segment that would change the URL's path when a browser or `fetch` resolves it: `.` and `..` are dot segments,
+ * which move up the path, and an empty one doubles a slash, which right after the leading one names another host.
+ */
+function changesThePath(segment: string): boolean {
+  return segment === '' || segment === '.' || segment === '..';
+}
+
+const changesThePathMessage = "a '.', '..' or empty segment would change the URL's path";
+
 /**
  * Builds the URL for a route pattern written in file-name syntax (`/blog/[slug]`, `/docs/[...path]`,
- * `/shop/[[...filters]]`), encoding every segment value. The generated `route()` helper calls this with typed params.
+ * `/shop/[[...filters]]`), encoding every segment value. A value, or a catch-all entry, that is `.`, `..` or empty
+ * throws, since it would change the path the URL names. `options.hash` adds a fragment after the query: the id of an
+ * element in the page, with one leading `#` dropped and the rest encoded; with nothing left, no fragment is added. The
+ * generated `route()` helper calls this with typed params.
  */
-export function buildHref(pattern: string, params: Record<string, unknown>, search?: SearchParamsInput): string {
+export function buildHref(
+  pattern: string,
+  params: Record<string, unknown>,
+  search?: SearchParamsInput,
+  options?: { hash?: string | undefined },
+): string {
   const missing = (name: string): never => {
     throw new Error(`netjes: route '${pattern}' needs the parameter '${name}'`);
   };
+  const encode = (name: string, value: unknown): string => {
+    const text = String(value);
+    if (changesThePath(text)) {
+      throw new Error(`netjes: route '${pattern}' cannot take '${text}' for the parameter '${name}': ${changesThePathMessage}`);
+    }
+    return encodeURIComponent(text);
+  };
   const segments = pattern
     .split('/')
     .filter(Boolean)
@@ -51,29 +80,115 @@ export function buildHref(pattern: string, params: Record<string, unknown>, sear
       const optional = /^\[\[\.\.\.(\w+)\]\]$/.exec(segment)?.[1];
       if (optional) {
         const values = params[optional];
-        return Array.isArray(values) ? values.map((v) => encodeURIComponent(String(v))) : [];
+        return Array.isArray(values) ? values.map((v) => encode(optional, v)) : [];
       }
       const catchAll = /^\[\.\.\.(\w+)\]$/.exec(segment)?.[1];
       if (catchAll) {
         const values = params[catchAll];
         if (!Array.isArray(values) || values.length === 0) return missing(catchAll);
-        return values.map((v) => encodeURIComponent(String(v)));
+        return values.map((v) => encode(catchAll, v));
       }
       const single = /^\[(\w+)\]$/.exec(segment)?.[1];
       if (single) {
         const value = params[single];
         if (value === undefined || value === null || value === '') return missing(single);
-        return [encodeURIComponent(String(value))];
+        return [encode(single, value)];
       }
       return [segment];
     });
 
   const query = new URLSearchParams();
+  appendSearch(query, search);
+  const queryString = query.toString();
+  const fragment = (options?.hash ?? '').replace(/^#/, '');
+  return `/${segments.join('/')}${queryString ? `?${queryString}` : ''}${fragment ? `#${encodeURIComponent(fragment)}` : ''}`;
+}
+
+/** Appends each value of `search`, a list repeating its key; `null` and `undefined` leave the key out. */
+function appendSearch(query: URLSearchParams, search: Readonly<Record<string, unknown>> | undefined): void {
   for (const [key, value] of Object.entries(search ?? {})) {
-    for (const item of Array.isArray(value) ? value : [value]) {
+    for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
       if (item !== undefined && item !== null) query.append(key, String(item));
     }
   }
+}
+
+/** A missing route value: `undefined`, `null` or `''`. */
+function absent(value: unknown): boolean {
+  return value === undefined || value === null || value === '';
+}
+
+/**
+ * Builds the URL of one of the app's endpoints from its route template, as the generated file writes it: the
+ * literals as they are (with `%`, `{`, `}`, `#` and `\` encoded), `{name}`, `{name?}`, `{name=default}` (the default
+ * encoded), `{*name}` and `{**name}`, without constraints. Each route value is encoded; a `{**name}` value keeps its
+ * slashes, and a `{*name}` value has them encoded. A value that would make a segment `.` or `..`, or a `{**name}` value
+ * with such a piece or with an empty one before its end (`/x`, `a//b`), throws `netjes: endpoint '<endpoint>' cannot
+ * take '<value>' for the route value '<name>'`, since it would change the path the URL names. A missing, `null` or
+ * empty optional value drops its segment, or its
+ * part of a segment with the `.` before it (`{name}.{ext?}`); a missing value with a default is filled in, unless it
+ * is a whole segment at the end, which is dropped; a missing, `null` or empty required value, or an optional one whose
+ * segment is followed by one that stays, throws `netjes: endpoint '<endpoint>' needs the route value '<name>'`. The
+ * values the template does not name are the query string, followed by `search`. The result is root-relative and has no base path: pass it through
+ * `useHref` for a `fetch` or an `<a href>`. The generated `endpointUrl()` calls this with typed values.
+ */
+export function buildEndpointUrl(
+  template: string,
+  values: Readonly<Record<string, unknown>>,
+  search?: SearchParamsInput,
+  endpoint?: string,
+): string {
+  const needs = (name: string) => new Error(`netjes: endpoint '${endpoint ?? template}' needs the route value '${name}'`);
+  const cannotTake = (name: string, value: unknown) =>
+    new Error(`netjes: endpoint '${endpoint ?? template}' cannot take '${String(value)}' for the route value '${name}': ${changesThePathMessage}`);
+  const named = new Set<string>();
+  // Each segment's text, and the name of the value it is missing, when the segment can go for want of it.
+  const segments: { text: string; missing: string | undefined }[] = [];
+  for (const segment of template.split('/').filter(Boolean)) {
+    let text = '';
+    let missing: string | undefined;
+    // The value that made the segment's text, which must not leave it a dot segment.
+    let filled: string | undefined;
+    for (const part of segment.split(/(\{[^}]*\})/).filter(Boolean)) {
+      const parameter = /^\{(\*\*?)?([^=?]+?)(\?|=([^]*))?\}$/.exec(part);
+      if (!parameter) {
+        text += part;
+        continue;
+      }
+
+      const [, star, name = '', marker, fallback] = parameter;
+      named.add(name);
+      const value = values[name];
+      if (!absent(value) && star === '**') {
+        // Each piece is a segment of its own; an empty last one is a trailing slash.
+        const pieces = String(value).split('/');
+        if (pieces.some((piece, i) => (piece === '' ? i < pieces.length - 1 : changesThePath(piece)))) throw cannotTake(name, value);
+        text += pieces.map((piece) => encodeURIComponent(piece)).join('/');
+      } else if (!absent(value)) {
+        text += encodeURIComponent(String(value));
+        filled = name;
+      } else if (fallback !== undefined) {
+        text += fallback;
+        if (part === segment) missing = name;
+      } else if (marker === '?' || star) {
+        // An optional value after a literal `.` takes the dot with it.
+        if (text.endsWith('.')) text = text.slice(0, -1);
+        if (!text) missing = name;
+      } else {
+        throw needs(name);
+      }
+    }
+    if (filled && changesThePath(text)) throw cannotTake(filled, values[filled]);
+    if (text || missing) segments.push({ text, missing });
+  }
+  while (segments.at(-1)?.missing) segments.pop();
+  // A segment left out before one that stays: routing would not match, or would read the next value as this one.
+  const leftOut = segments.find((segment) => !segment.text)?.missing;
+  if (leftOut) throw needs(leftOut);
+
+  const query = new URLSearchParams();
+  appendSearch(query, Object.fromEntries(Object.entries(values).filter(([key]) => !named.has(key))));
+  appendSearch(query, search);
   const queryString = query.toString();
-  return `/${segments.join('/')}${queryString ? `?${queryString}` : ''}`;
+  return `/${segments.map((s) => s.text).join('/')}${queryString ? `?${queryString}` : ''}`;
 }

package/src/image.tsx

@@ -1,4 +1,4 @@
-import { type ImgHTMLAttributes, createContext, useContext } from 'react';
+import { type ComponentPropsWithRef, createContext, useContext } from 'react';
 import { preload } from 'react-dom';
 
 /**
@@ -17,8 +17,8 @@ const ImageConfigContext = createContext<ImageConfig>(DEFAULT_CONFIG);
 
 export const ImageConfigProvider = ImageConfigContext.Provider;
 
-/** The props of `<Image>`: an `<img>`'s own, with a required size and `alt`, and the optimizer's options. */
-export type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'width' | 'height' | 'loading' | 'alt'> & {
+/** The props of `<Image>`: an `<img>`'s own and its ref, with a required size and `alt`, and the optimizer's options. */
+export type ImageProps = Omit<ComponentPropsWithRef<'img'>, 'src' | 'srcSet' | 'width' | 'height' | 'loading' | 'alt'> & {
   /** A path in `public/` (`/img/hero.png`) or a URL on a host in Netjes:Images:RemoteHosts. */
   src: string;
   /** Required, as for any image; `""` for decorative ones. */

package/src/index.ts

@@ -9,10 +9,11 @@ export {
   usePageActionState,
 } from './actions.tsx';
 export { defineLayout, definePage } from './define-page.tsx';
+export { CSP_SCRIPT_HASHES } from './deferred.ts';
 export { useDraftMode } from './draft-mode.ts';
 export { type DynamicOptions, clientOnly, dynamic } from './dynamic.tsx';
 export { Form, type FormAction, type FormProps, SubmitButton, type SubmitButtonProps } from './form.tsx';
-export { type Href, type Register, type SearchParamsInput, type SearchValue, buildHref, isRouteHref } from './href.ts';
+export { type Href, type Register, type SearchParamsInput, type SearchValue, buildEndpointUrl, buildHref, isRouteHref } from './href.ts';
 export { Image, type ImageProps } from './image.tsx';
 export { Link, type LinkProps } from './link.tsx';
 export { useLocale } from './locale.ts';

package/src/link.tsx

@@ -1,25 +1,50 @@
-import type { AnchorHTMLAttributes, MouseEvent } from 'react';
+import type { ComponentPropsWithRef, MouseEvent } from 'react';
 import type { Href } from './href.ts';
-import { useBasePath, useInternalRouter, usePathname, withBasePath } from './router.tsx';
+import { useBasePath, useInternalRouter, usePathname, useSearchParams, withBasePath } from './router.tsx';
 
-/** The props of `<Link>`: an anchor's own, with a typed `href` and the client navigation options. */
-export type LinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
+/** The props of `<Link>`: an anchor's own and its ref, with a typed `href` and the client navigation options. */
+export type LinkProps = Omit<ComponentPropsWithRef<'a'>, 'href'> & {
   /** Typed by the app's routes once `netjes generate` has registered them. */
   href: Href;
   replace?: boolean;
-  /** Scroll to the top (or the #fragment) after navigating. Default true. */
+  /**
+   * Scroll to the top after navigating, or to the #fragment's element, which then takes the focus. Default true. `false`
+   * keeps the scroll position, and the focus on the link while the link has it.
+   */
   scroll?: boolean;
-  /** `intent` (default) fetches the next page on hover or focus. */
+  /** `intent` (default) fetches the next page on hover, focus or touch. */
   prefetch?: 'intent' | 'none';
-  /** Let the browser follow it with a full page load, e.g. for a file download or a page outside Netjes. */
+  /** Let the browser follow it with a full page load: for a page of the app that must load in full, or a page on another site. */
   reloadDocument?: boolean;
 };
 
 const BASE = 'http://netjes.invalid';
 
-function isCurrentPath(href: string, pathname: string) {
-  const url = new URL(href, BASE + pathname);
-  return url.origin === BASE && url.pathname === pathname;
+/** One trailing slash makes no other page: `/docs/` is `/docs`, and `/` stays `/`. */
+function withoutTrailingSlash(path: string) {
+  return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
+/** The same values, in any order, as often each. */
+function sameValues(a: string[], b: string[]) {
+  const sorted = [...b].sort();
+  return a.length === b.length && [...a].sort().every((value, i) => value === sorted[i]);
+}
+
+/**
+ * Whether the link goes to the page on screen. An href with a `#` points to a place in a page, so it never does.
+ * Otherwise its URL under the base path has the page's path, give or take one trailing slash, and the page's
+ * values for each query parameter it names; parameters it leaves out do not count. Only the path and the query
+ * enter, against a fixed origin, so the server and the browser agree.
+ */
+function isCurrentPage(href: string, pathname: string, search: URLSearchParams, basePath: string) {
+  if (href.includes('#')) return false;
+  const query = search.toString();
+  // The page's URL as the browser has it: the base path, then the page's path, even one that starts like the base path.
+  const page = new URL(BASE + basePath + pathname + (query ? `?${query}` : ''));
+  const target = new URL(withBasePath(href, basePath), page);
+  if (target.origin !== BASE || withoutTrailingSlash(target.pathname) !== withoutTrailingSlash(page.pathname)) return false;
+  return [...new Set(target.searchParams.keys())].every((key) => sameValues(target.searchParams.getAll(key), search.getAll(key)));
 }
 
 function isPlainLeftClick(event: MouseEvent<HTMLAnchorElement>) {
@@ -35,10 +60,16 @@ function isPlainLeftClick(event: MouseEvent<HTMLAnchorElement>) {
   );
 }
 
-/** An `<a>` that navigates on the client. Ctrl/cmd-click, new tabs and external URLs behave like a normal link. */
+/**
+ * An `<a>` that navigates on the client. Ctrl/cmd-click, new tabs and external URLs behave like a normal link. It sets
+ * `aria-current="page"` on a link to the page on screen: the same path, one trailing slash aside, and the page's values
+ * for each query parameter the link names. A link with a `#` is never marked, and an `aria-current` prop wins. After a
+ * navigation to another page, the router announces the page and starts the focus over at the top of the document.
+ */
 export function Link({ href, replace = false, scroll = true, prefetch = 'intent', reloadDocument = false, onClick, onMouseEnter, onFocus, onTouchStart, ...rest }: LinkProps) {
   const router = useInternalRouter();
   const pathname = usePathname();
+  const search = useSearchParams();
   const basePath = useBasePath();
   const warm = () => {
     if (prefetch === 'intent' && !reloadDocument) router.prefetch(href);
@@ -47,14 +78,17 @@ export function Link({ href, replace = false, scroll = true, prefetch = 'intent'
   return (
     <a
       href={withBasePath(href, basePath)}
-      aria-current={isCurrentPath(href, pathname) ? 'page' : undefined}
+      aria-current={isCurrentPage(href, pathname, search, basePath) ? 'page' : undefined}
       {...rest}
       onClick={(event) => {
+        // Read before the app's own onClick, which runs as the link is followed: where it moves the focus, such as
+        // back to the button of a menu that closes, the router leaves it.
+        const focusedAtStart = document.activeElement;
         onClick?.(event);
         if (event.defaultPrevented || reloadDocument || !isPlainLeftClick(event)) return;
         if (new URL(href, window.location.href).origin !== window.location.origin) return;
         event.preventDefault();
-        void (replace ? router.replace(href, { scroll }) : router.push(href, { scroll }));
+        void (replace ? router.replace(href, { scroll, focusedAtStart }) : router.push(href, { scroll, focusedAtStart }));
       }}
       onMouseEnter={(event) => {
         onMouseEnter?.(event);

package/src/metadata.tsx

@@ -3,7 +3,11 @@
 
 import { Fragment } from 'react';
 
-/** A title, or a layout's `default` and `template` (`'%s · Site'`), or an `absolute` title that skips templates. */
+/**
+ * A title, a layout's `template` (`'%s · Site'`) and `default`, or an `absolute` title that skips templates. A
+ * `default`, on a layout or a page, goes through the nearest `template` of the layouts above it like a string title,
+ * never through the one beside it; a layout's `default` is also the title of the pages below it that set none.
+ */
 export type MetadataTitle = string | { default?: string; template?: string; absolute?: string };
 
 /** An image for a link preview: `og:image` with `og:image:width`, `og:image:height` and `og:image:alt` when given, or `twitter:image` with `twitter:image:alt`. */
@@ -48,12 +52,18 @@ export type ResolvedMetadata = Omit<Metadata, 'title' | 'openGraph' | 'twitter'>
   twitter?: Omit<Twitter, 'images'> & { images?: ResolvedImage[] };
 };
 
+/**
+ * The title that `title` stands for, given the template from the layouts above it. A string and a `default` go
+ * through the template, an `absolute` title does not, and an object with no `default` and no `absolute` (a layout
+ * that only sets a template) has no title of its own.
+ */
 function titleOf(title: MetadataTitle | undefined, template: string | undefined): string | undefined {
   if (title === undefined) return undefined;
   // A function replacer: a title such as "Save $& now" must not be read as a replacement pattern.
-  if (typeof title === 'string') return template ? template.replace('%s', () => title) : title;
+  const inTemplate = (text: string) => (template ? template.replace('%s', () => text) : text);
+  if (typeof title === 'string') return inTemplate(title);
   if (title.absolute !== undefined) return title.absolute;
-  return title.default;
+  return title.default === undefined ? undefined : inTemplate(title.default);
 }
 
 /** The images as a list of descriptors with string URLs; like Next.js, a null image or one without a URL is left out. */
@@ -72,7 +82,9 @@ function withImages<T extends { images?: MetadataImages }>(group: T): Omit<T, 'i
 
 /**
  * Merges the layouts' metadata (outermost first), the page's, and the server's. A layout's `title.template` applies
- * to titles below it, `title.default` is used when nothing below sets one, `title.absolute` skips templates.
+ * to the titles below it. `title.default`, on a layout or a page, goes through the templates above it like a string
+ * title and never through its own; on a layout it is the title when nothing below sets one. `title.absolute` skips
+ * templates.
  */
 export function resolveMetadata(layouts: readonly (Metadata | undefined)[], page: Metadata | undefined, server?: Metadata): ResolvedMetadata {
   let resolved: ResolvedMetadata = {};
@@ -82,8 +94,9 @@ export function resolveMetadata(layouts: readonly (Metadata | undefined)[], page
     const { title, openGraph, twitter, alternates, icons, other, ...rest } = metadata;
     resolved = { ...resolved, ...rest };
     if (title !== undefined) {
-      // A layout's own default is not put through its own template, only templates from above.
-      const own = titleOf(title, typeof title === 'string' || title.default === undefined ? template : undefined);
+      // The template from above applies to every title but an absolute one, a default included. This title's own
+      // template is stored after its title is written, so it applies only to the titles below.
+      const own = titleOf(title, template);
       if (own !== undefined) resolved.title = own;
       if (typeof title === 'object' && title.template) template = title.template;
     }