netjes 0.0.2 → 0.0.4

package/src/href.ts

@@ -25,25 +25,65 @@ 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.
+ * Whether a URL has the shape of a link, as a C# `Href` checks it: root-relative (`/…`, but not `//…` or `/\…`, which
+ * browsers read as another host), a link within the page (`?…`, `#…`), or an `http:`, `https:`, `mailto:` or `tel:`
+ * URL, with no ASCII control character and no space at either end. It does not ask which page a path names: a page
+ * package's generated file, which cannot know the app's pages, checks its `Href` with this.
  */
-export function isRouteHref(value: string, patterns: readonly string[]): boolean {
+export function isHrefShape(value: 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;
+  return value.startsWith('/') && !value.startsWith('//') && !value.startsWith('/\\');
+}
+
+/**
+ * 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. 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 {
+  if (!isHrefShape(value)) return false;
+  if (!value.startsWith('/')) return true;
   const path = (value.split(/[?#]/, 1)[0] ?? '').split('/').filter(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 +91,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,14 +9,32 @@ 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,
+  isHrefShape,
+  isRouteHref,
+} from './href.ts';
 export { Image, type ImageProps } from './image.tsx';
 export { Link, type LinkProps } from './link.tsx';
 export { useLocale } from './locale.ts';
 export type { ErrorPageProps, LayoutProps } from './modules.ts';
+export {
+  type Mounted,
+  type MountedFormProps,
+  type MountedLinkProps,
+  type MountedRouter,
+  type MountedSubmitButtonProps,
+  mounted,
+} from './mounted.tsx';
 export { useNonce } from './nonce.tsx';
 export type { PageKind, Params, SeededQuery, SegmentRef } from './payload.ts';
 export { usePublicConfig } from './public-config.tsx';

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;
     }

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/mounted.tsx

@@ -0,0 +1,160 @@
+import { type ReactNode, useMemo } from 'react';
+import { Form, type FormAction, type FormProps, SubmitButton, type SubmitButtonProps } from './form.tsx';
+import { type Href, isHrefShape } from './href.ts';
+import { Link, type LinkProps } from './link.tsx';
+import { isDotSegment } from './payload.ts';
+import { type Router, useHref, usePagePayload, usePathname, useRouter } from './router.tsx';
+
+/** The props of a page package's `<Link>`: those of the core `<Link>`, with an href below the package's mount. */
+export type MountedLinkProps<THref extends string = string> = Omit<LinkProps, 'href'> & { href: THref };
+
+/** The props of a page package's `<Form>`: those of the core `<Form>`, with a URL `action` below the package's mount. */
+export type MountedFormProps<THref extends string = string> = Omit<FormProps, 'action'> & { action?: THref | FormAction };
+
+/** The props of a page package's `<SubmitButton>`, with a URL `formAction` below the package's mount. */
+export type MountedSubmitButtonProps<THref extends string = string> = Omit<SubmitButtonProps, 'formAction'> & {
+  formAction?: THref | Exclude<SubmitButtonProps['formAction'], string>;
+};
+
+/** The client router, as a page package's `useRouter()` returns it: `push`, `replace` and `prefetch` go below its mount. */
+export type MountedRouter<THref extends string = string> = Omit<Router, 'push' | 'replace' | 'prefetch'> & {
+  push(href: THref, options?: { scroll?: boolean }): Promise<void>;
+  replace(href: THref, options?: { scroll?: boolean }): Promise<void>;
+  prefetch(href: THref): void;
+};
+
+/** What {@link mounted} returns: the links, forms and router hooks of one page package. */
+export type Mounted<THref extends string = string> = {
+  /** A `<Link>` whose href is below the mount: `/articles` goes to `/help/articles` for a package mounted at `/help`. */
+  Link: (props: MountedLinkProps<THref>) => ReactNode;
+  /** A `<Form>` whose URL `action` is below the mount. Without one it posts to the page on screen, as the core `<Form>`. */
+  Form: (props: MountedFormProps<THref>) => ReactNode;
+  /** A `<SubmitButton>` whose URL `formAction` is below the mount. */
+  SubmitButton: (props: MountedSubmitButtonProps<THref>) => ReactNode;
+  /** The client router, whose `push`, `replace` and `prefetch` take hrefs below the mount. */
+  useRouter: () => MountedRouter<THref>;
+  /**
+   * The path of the page on screen below the mount, without the base path: `/articles/x` for `/help/articles/x`, and
+   * `/` for the mount itself. A page outside the mount gets its whole path, as the core `usePathname` gives it.
+   */
+  usePathname: () => string;
+  /**
+   * An href below the mount, under the base path, for a plain `<a>`, another attribute or a `fetch`: a page's, or an
+   * endpoint's from the package's `endpointUrl()`. Untyped, as the core `useHref`.
+   */
+  useHref: (href: string) => string;
+};
+
+/** The package's URL for the page on screen, from the payload: null when the page has no value for the prefix. */
+function useMountOrNull(name: string): string | null {
+  const mounts = usePagePayload().mounts;
+  const mount = mounts && Object.hasOwn(mounts, name) ? mounts[name] : undefined;
+  if (mount === undefined) {
+    throw new Error(`netjes: the page package '${name}' is not mounted: map it with app.MapPagePackage(...) before app.MapPages()`);
+  }
+  return mount;
+}
+
+/** The package's URL for the page on screen; throws when the page has none. */
+function useMount(name: string): string {
+  const mount = useMountOrNull(name);
+  if (mount === null) throw new Error(`netjes: '${name}' is mounted at a prefix with a value, and this page has none for it`);
+  return mount;
+}
+
+/**
+ * A segment as routing compares it: decoded where it can be, as the server decodes a path, which leaves `%2F` as it is
+ * (so `a%2Fb` and `a%252Fb` hold the same value), in any case.
+ */
+function comparable(segment: string): string {
+  try {
+    return decodeURIComponent(segment.replace(/%2F/gi, '%252F')).toLowerCase();
+  } catch {
+    return segment.toLowerCase();
+  }
+}
+
+/** `pathname` without the mount in front, `/` for the mount itself; the whole path when it is not below the mount. */
+function belowMount(pathname: string, mount: string | null): string {
+  if (mount === null || mount === '/') return pathname;
+  const prefix = mount.split('/').slice(1);
+  const segments = pathname.split('/').slice(1);
+  if (segments.length < prefix.length || prefix.some((segment, i) => comparable(segment) !== comparable(segments[i] ?? ''))) return pathname;
+  const rest = segments.slice(prefix.length).join('/');
+  return rest === '' ? '/' : `/${rest}`;
+}
+
+/**
+ * `href` below `mount`: a path gets the mount in front, and a link within the page on screen (`?…`, `#…`) passes
+ * through. Anything else throws, as does a path with a dot segment, which would climb out of the mount.
+ */
+function underMount(href: string, mount: string, name: string): string {
+  const withinThePage = href.startsWith('?') || href.startsWith('#');
+  const path = href.split(/[?#]/, 1)[0] ?? '';
+  // Browsers read a backslash in a path as a slash, and %2e as a dot.
+  if (!isHrefShape(href) || (!withinThePage && (!href.startsWith('/') || path.split(/[/\\]/).some(isDotSegment)))) {
+    throw new Error(
+      `netjes: '${href}' is no link below the mount of '${name}': start it with '/' (but not '//' or '/\\'), with no '.' or ` +
+        "'..' segment, or with '?' or '#'. Link to another site, or elsewhere in the app, with the Link from 'netjes'.",
+    );
+  }
+  if (withinThePage || mount === '/') return href;
+  return href === '/' || href[1] === '?' || href[1] === '#' ? mount + href.slice(1) : mount + href;
+}
+
+/**
+ * The links, forms and router hooks of the page package `name`, its npm name, bound to where the app mounted it. Each
+ * puts the package's URL for the page on screen in front of its hrefs, and the base path in front of that, so a
+ * package links to its own pages as if it were mounted at the root. A package's generated file calls it once:
+ * `export const { Link, Form, SubmitButton, useRouter, usePathname, useHref } = mounted<MountHref>('@acme/help-center')`.
+ */
+export function mounted<THref extends string = string>(name: string): Mounted<THref> {
+  function MountedLink({ href, ...rest }: MountedLinkProps<THref>) {
+    const mount = useMount(name);
+    return <Link href={underMount(href, mount, name) as Href} {...rest} />;
+  }
+
+  function MountedForm({ action, ...rest }: MountedFormProps<THref>) {
+    const mount = useMount(name);
+    const url = typeof action === 'string' ? underMount(action, mount, name) : action;
+    return <Form {...(url === undefined ? {} : { action: url })} {...rest} />;
+  }
+
+  function MountedSubmitButton({ formAction, ...rest }: MountedSubmitButtonProps<THref>) {
+    const mount = useMount(name);
+    return <SubmitButton formAction={typeof formAction === 'string' ? underMount(formAction, mount, name) : formAction} {...rest} />;
+  }
+
+  function useMountedRouter(): MountedRouter<THref> {
+    const mount = useMount(name);
+    const router = useRouter();
+    return useMemo(
+      () => ({
+        push: (href, options) => router.push(underMount(href, mount, name) as Href, options),
+        replace: (href, options) => router.replace(underMount(href, mount, name) as Href, options),
+        prefetch: (href) => router.prefetch(underMount(href, mount, name) as Href),
+        refresh: () => router.refresh(),
+        back: () => router.back(),
+        forward: () => router.forward(),
+      }),
+      [router, mount],
+    );
+  }
+
+  function useMountedPathname(): string {
+    return belowMount(usePathname(), useMountOrNull(name));
+  }
+
+  function useMountedHref(href: string): string {
+    return useHref(underMount(href, useMount(name), name));
+  }
+
+  return {
+    Link: MountedLink,
+    Form: MountedForm,
+    SubmitButton: MountedSubmitButton,
+    useRouter: useMountedRouter,
+    usePathname: useMountedPathname,
+    useHref: useMountedHref,
+  };
+}