@antelopejs/dms-frontend 0.8.0 → 0.9.0

package/templates/vue/frontend-module.ts

@@ -12,7 +12,9 @@ import { defu } from "defu";
 import { type FetchOptions, ofetch } from "ofetch";
 import {
   type App,
+  type AppConfig,
   type Component,
+  type ComponentInternalInstance,
   type ComponentPublicInstance,
   type ComputedRef,
   camelize,
@@ -1853,6 +1855,9 @@ function startAsyncData<T>(
   const idle = entry.result.status.value === "idle";
   if (runtime.isServer) {
     if (!immediate || !onServer) return undefined;
+    // A render that already answers a redirect throws its HTML away: what it
+    // still has to read would reach nobody.
+    if (runtime.serverRedirect) return undefined;
     if (idle && options.lazy) entry.schedule();
     else if (idle) void entry.load();
     const settled = entry.settled();
@@ -2488,6 +2493,35 @@ export function defineDmsPageMeta(meta: Record<string, unknown>): void {
     onServerPrefetch(() => navigation.then(ignoreSettlement, ignoreSettlement));
 }
 function ignoreSettlement(): void {}
+/**
+ * What Vue's development build passes `errorHandler` for an error thrown by a
+ * component's `setup`, sync or async (production passes a link instead; it has
+ * no warnings to scope either).
+ */
+const SETUP_FUNCTION_ERROR = "setup function";
+/**
+ * Whether a Vue warning comes from a component whose `setup` failed, or from
+ * under it. Vue still renders such a component, against the setup state that
+ * never came: in development, where a single-file component's template is
+ * compiled apart from its setup, the template reads the missing bindings, and
+ * every component it uses becomes `undefined` ("Invalid vnode type when
+ * creating vnode: undefined", then "Component <Anonymous> is missing template
+ * or render function" for the comment Vue renders in its place). The error
+ * page replaces that output (a server renders the page again, the browser
+ * swaps it), and the failure itself is already reported.
+ *
+ * Walks internal instances: a `<script setup>` component exposes itself, so
+ * its children's `$parent` is an expose proxy, not the proxy `errorHandler`
+ * received.
+ */
+function withinFailedSetup(
+  instance: ComponentInternalInstance | null,
+  failedSetups: WeakSet<ComponentInternalInstance>,
+): boolean {
+  for (let current = instance; current; current = current.parent)
+    if (failedSetups.has(current)) return true;
+  return false;
+}
 /** Shows the error page in place of the page, keeping the first failure. */
 function failPage(runtime: DmsFrontendRuntime, reason: unknown): void {
   runtime.currentError.value ??=
@@ -2578,6 +2612,80 @@ export const DmsLink: Component = defineComponent({
   },
 });
 
+/** How a keyboard hint prints its modifiers: macOS symbols, or PC key names. */
+export type DmsKbdPlatform = "mac" | "other";
+/**
+ * Where Nuxt UI's key hints read the platform: called in the setup of each
+ * component that prints one, it returns the platform that component renders.
+ * It must read on the server the platform it renders there, and keep it while
+ * its caller hydrates, so the browser's first render matches the server's.
+ */
+export type DmsKbdPlatformSource = () => Readonly<Ref<DmsKbdPlatform>>;
+
+const KBD_PLATFORM_KEY: InjectionKey<DmsKbdPlatformSource> =
+  Symbol("dms:kbd-platform");
+const MODIFIER_KBD_KEYS: Record<
+  DmsKbdPlatform,
+  Record<"meta" | "ctrl" | "alt", string>
+> = {
+  mac: { meta: "⌘", ctrl: "⌃", alt: "⌥" },
+  other: { meta: "Ctrl", ctrl: "Ctrl", alt: "Alt" },
+};
+const isModifierKbdKey = (value: string): value is "meta" | "ctrl" | "alt" =>
+  value === "meta" || value === "ctrl" || value === "alt";
+
+/**
+ * Gives Nuxt UI's key hints (`UKbd`, the `kbds` of its menus, the dashboard
+ * search button) the application's keyboard platform, so the server prints
+ * `meta` as "⌘" or "Ctrl" from the first render instead of a blank the
+ * browser fills in after mounting.
+ */
+export function provideDmsKbdPlatform(
+  app: App,
+  source: DmsKbdPlatformSource,
+): void {
+  app.provide(KBD_PLATFORM_KEY, source);
+}
+
+interface NuxtUiKbd {
+  macOS: ComputedRef<unknown>;
+  getKbdKey: (value?: string) => string | undefined;
+}
+
+/**
+ * Nuxt UI's `useKbd` as the DMS runs it (`ui-kbd.mjs` routes it here): a hint
+ * renders the same on the server and in the hydrating browser. Nuxt UI prints
+ * `meta`, `ctrl` and `alt` from a map shared by every hint and filled by the
+ * first one's `onMounted`, so a hint hydrating after that (in an async
+ * component) printed "⌘" over the server's blank. Each hint now keeps the
+ * server's value until its own `onMounted`; with a platform provided
+ * (`provideDmsKbdPlatform`), that value is the platform's from the start.
+ *
+ * @internal
+ */
+export function useDmsKbd(
+  shared: () => NuxtUiKbd,
+  keys: Readonly<Record<string, string>>,
+): NuxtUiKbd {
+  const { macOS } = shared();
+  const instance = getCurrentInstance();
+  const source = instance ? inject(KBD_PLATFORM_KEY, null) : null;
+  const platform = source ? source() : null;
+  // A hydrating component's vnode is bound to its server node before setup.
+  const hydrating = ref(!!instance?.vnode.el);
+  if (hydrating.value) onMounted(() => (hydrating.value = false));
+  return {
+    macOS,
+    getKbdKey(value) {
+      if (!value) return undefined;
+      if (!isModifierKbdKey(value)) return keys[value] || value;
+      if (platform) return MODIFIER_KBD_KEYS[platform.value][value];
+      if (typeof window === "undefined" || hydrating.value) return " ";
+      return MODIFIER_KBD_KEYS[macOS.value ? "mac" : "other"][value];
+    },
+  };
+}
+
 export const DmsClientOnly = defineComponent({
   name: "DmsClientOnly",
   setup(_, { slots }) {
@@ -2817,6 +2925,17 @@ export function useDmsPageLoading(): Readonly<Ref<boolean>> {
   return readonly(useDmsRuntime().pageLoading);
 }
 
+/**
+ * Whether the browser is hydrating the page the server rendered, whose first
+ * render must match the server's HTML: from the start of the application to
+ * the tick the page's `<Suspense>` resolves. False on the server, in a page
+ * the server did not render, and after a client navigation. As Nuxt's
+ * `nuxtApp.isHydrating`; read once, it is not reactive.
+ */
+export function isDmsHydrating(): boolean {
+  return useDmsRuntime().hydrating;
+}
+
 /**
  * The props of the `<Suspense>` around the page that keep `useDmsPageLoading`
  * in step with it. Cleared before the boundary unmounts, so a page left while
@@ -3368,7 +3487,31 @@ export async function installDmsPlugins(
       if (browserRuntime === runtime) browserRuntime = undefined;
     });
   }
-  app.config.errorHandler = (reason) => failPage(runtime, reason);
+  const failedSetups = new WeakSet<ComponentInternalInstance>();
+  const warnOutsideFailedSetups: AppConfig["warnHandler"] = (
+    message,
+    instance,
+    trace,
+  ) => {
+    // The comment Vue renders in place of an `undefined` component has no
+    // public instance: the template rendering it is the one that failed.
+    const source = instance?.$ ?? getCurrentInstance();
+    if (!withinFailedSetup(source, failedSetups))
+      console.warn(`[Vue warn]: ${message}${trace ? `\n${trace}` : ""}`);
+  };
+  app.config.errorHandler = (reason, instance, info) => {
+    if (instance && info === SETUP_FUNCTION_ERROR) {
+      failedSetups.add(instance.$);
+      // From the first failure on only: until then Vue keeps its own output,
+      // whose component trace shows the props. An app that already has a
+      // handler keeps it. A server renders a single page per app; in the
+      // browser the app outlives Inertia visits, so once a page has failed
+      // the handler stays for the session and later warnings print as plain
+      // text (no inspectable objects), still all of them.
+      app.config.warnHandler ??= warnOutsideFailedSetups;
+    }
+    failPage(runtime, reason);
+  };
   app.config.globalProperties.$dms = appContext;
   Reflect.set(app, "$dms", appContext);
   Reflect.set(app, "$i18n", i18n);

package/templates/vue/gitignore

@@ -10,6 +10,7 @@ frontend-modules/**/i18n/locales/
 # CSS hot update on plain navigation.
 auto-imports.d.ts
 components.d.ts
+sfc-global-types.generated.d.ts
 # Build output, which the email bundle watcher rewrites during development:
 # read as Tailwind sources, each rebuild would push a burst of CSS updates.
 dist/

package/templates/vue/main.ts

@@ -60,6 +60,26 @@ if (import.meta.env.DEV) adoptViteDevStyles();
 // the generated server answers those queries from the installed collections.
 addAPIProvider("", sameOriginIconProvider(location.origin));
 
+/**
+ * Shows the URL of the page the server sent, when it rendered a query the page
+ * completed in place of the one requested (`renderDocument` in server.mjs).
+ * Replaced before Inertia starts: Inertia records a first page whose URL is
+ * not the address bar's as a new history entry, and Back would then lead to
+ * the URL the page completes again.
+ */
+function showServedUrl(url: string): void {
+  const served = new URL(url, location.href);
+  if (
+    served.pathname === location.pathname &&
+    served.search !== location.search
+  )
+    history.replaceState(
+      history.state,
+      "",
+      `${served.pathname}${served.search}${location.hash}`,
+    );
+}
+
 /**
  * Sets the modules up, then starts the app.
  *
@@ -84,6 +104,7 @@ async function startDmsApp(): Promise<void> {
   createInertiaApp({
     resolve: resolveDmsInertiaPage,
     async setup({ App, el, props, plugin }) {
+      showServedUrl(props.initialPage.url);
       const root = { render: () => h(App, props) };
       const app = el.hasAttribute("data-server-rendered")
         ? createSSRApp(root)

package/templates/vue/network-error.ts

@@ -18,7 +18,9 @@ const NETWORK_ERROR_KEY = "error.network";
 const DEFAULT_LOCALE = "en";
 // Shipped with the renderer, since no module is guaranteed to translate the
 // case; a module overrides them with `error.network.title` and
-// `error.network.description` in its own locale files.
+// `error.network.description` in its own locale files. `te()` reads the
+// visitor's locale alone, and the generated catalogs leave these keys out of
+// their English fill, so only that locale's own message replaces them.
 const NETWORK_ERROR_MESSAGES: Record<
   string,
   Record<"title" | "description", string>

package/templates/vue/package.json

@@ -25,7 +25,7 @@
     "@unhead/vue": "^2.0.14",
     "@vitejs/plugin-vue": "^6.0.6",
     "@vue/server-renderer": "^3.5.0",
-    "@vueuse/core": "^14.3.0",
+    "@vueuse/core": "14.4.0",
     "defu": "^6.1.4",
     "devalue": "^5.9.4",
     "ofetch": "^1.4.1",

package/templates/vue/patches/@vueuse__core@14.4.0.patch

@@ -0,0 +1,24 @@
+diff --git a/dist/index.js b/dist/index.js
+index 772a5e9..d433a57 100644
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -2047,11 +2047,16 @@ function useColorMode(options = {}) {
+ 		let attributeToChange = null;
+ 		if (attribute === "class") {
+ 			const current = value.split(/\s/g);
++			// Patched by @antelopejs/dms-frontend until vueuse ships the fix: only
++			// the classes `el` lacks or still carries count as a change, so a mode
++			// already applied (by the server render, another instance or the
++			// mount re-run) skips the forced style recalculation below.
+ 			Object.values(modes).flatMap((i) => (i || "").split(/\s/g)).filter(Boolean).forEach((v) => {
+-				if (current.includes(v)) classesToAdd.add(v);
+-				else classesToRemove.add(v);
++				if (current.includes(v)) {
++					if (!el.classList.contains(v)) classesToAdd.add(v);
++				} else if (el.classList.contains(v)) classesToRemove.add(v);
+ 			});
+-		} else attributeToChange = {
++		} else if (el.getAttribute(attribute) !== value) attributeToChange = {
+ 			key: attribute,
+ 			value
+ 		};

package/templates/vue/pnpm-workspace.yaml

@@ -9,3 +9,8 @@ patchedDependencies:
   # Menu and breadcrumb links active on a sibling route (`/test` on `/test-a`):
   # nuxt/ui#6803, fixed by nuxt/ui#6809.
   "@nuxt/ui@4.10.0": patches/@nuxt__ui@4.10.0.patch
+  # useColorMode re-applies a color mode `<html>` already carries, forcing a
+  # full style recalculation on every call (6 on the dashboard home, 216 ms of
+  # main thread at 4x CPU): the guard of vueuse#4001 compares the modes with the
+  # requested value instead of the element. vueuse 15.0.0 still ships it.
+  "@vueuse/core@14.4.0": patches/@vueuse__core@14.4.0.patch

package/templates/vue/server/client-manifest.mjs

@@ -78,3 +78,15 @@ export function renderedModuleStyleTags(modules, template) {
     .map((file) => `<link rel="stylesheet" href="/${file}">`)
     .join("");
 }
+
+/**
+ * The link that preloads the built catalog of `locale`, the one the page was
+ * rendered with: the browser fetches it next to the entry rather than once the
+ * entry runs and asks for it, which would put a round trip before hydration.
+ * Nothing without a production build (Vite serves the sources in development).
+ */
+export function localeCatalogPreloadTag(locale) {
+  const manifest = productionClientManifest();
+  const file = locale && manifest?.[`locales.generated/${locale}.ts`]?.file;
+  return file ? `<link rel="modulepreload" crossorigin href="/${file}">` : "";
+}

package/templates/vue/server/in-place-render.mjs

@@ -0,0 +1,110 @@
+// A page that completes its query as it renders, rendered at that query in
+// the same request rather than answered with a redirect.
+//
+// Lives apart from server.mjs so the file stays under the size the linter
+// allows.
+
+import { ofetch } from "ofetch";
+
+/**
+ * How many times one request renders a page in place of a same-path redirect
+ * before it answers the redirect: a page that keeps changing its query.
+ */
+const IN_PLACE_RENDERS = 2;
+
+/**
+ * The key of a backend read a later render of the same request may reuse: a
+ * plain JSON `GET`, without hooks that would expect to see the response.
+ */
+function reusableReadKey(path, options, headers) {
+  const method = (options.method ?? "GET").toUpperCase();
+  if (method !== "GET" || options.body !== undefined) return undefined;
+  if (options.responseType && options.responseType !== "json") return undefined;
+  if (Object.keys(options).some((name) => /^on[A-Z]/.test(name)))
+    return undefined;
+  return JSON.stringify([
+    path,
+    options.query ?? options.params ?? null,
+    [...headers],
+  ]);
+}
+
+/**
+ * The backend reads of a request's server renders, sent with the request's
+ * `backendHeaders()` and the read's own. After `reuseCompletedReads()`, a later
+ * render of the same request is given a copy of each read a previous render
+ * completed instead of reading the backend again.
+ */
+export function serverReads(backendHeaders) {
+  const completed = new Map();
+  let reuse = false;
+  const read = (path, options = {}) => {
+    const headers = new Headers(backendHeaders());
+    new Headers(options.headers).forEach((value, name) => {
+      headers.set(name, value);
+    });
+    const key = reusableReadKey(path, options, headers);
+    if (reuse && key && completed.has(key))
+      return Promise.resolve(structuredClone(completed.get(key)));
+    const reading = ofetch(path, {
+      ...options,
+      baseURL: process.env.DMS_API_BASE_URL,
+      headers,
+    });
+    if (!key) return reading;
+    // A copy: the render that read it may still change the object it got. A
+    // body that cannot be copied is read again.
+    return reading.then((data) => {
+      try {
+        completed.set(key, structuredClone(data));
+      } catch {}
+      return data;
+    });
+  };
+  return Object.assign(read, {
+    reuseCompletedReads: () => {
+      reuse = true;
+    },
+  });
+}
+
+/**
+ * Whether a document request renders `location` in place of redirecting to
+ * it: a `GET` whose page only completes its query (`?workspace=`), on the
+ * same path. Any other redirect keeps its own response.
+ */
+function rendersInPlace(request, from, location) {
+  if (request.method !== "GET" || location.includes("#")) return false;
+  const current = new URL(from, "http://frontend.local");
+  const target = new URL(location, current);
+  return (
+    target.origin === current.origin && target.pathname === current.pathname
+  );
+}
+
+/**
+ * Renders a page document with `render(page)`. A page that completes its
+ * query as it renders (`router.replace` to the same path) is rendered again at
+ * that query, with the props `propsAt(props, url)` gives, reusing the reads
+ * the first render made (`fetch`), instead of being answered with a redirect
+ * the browser would follow with a whole new request. The page served then
+ * names the URL the document shows, which the browser puts in the address bar.
+ */
+export async function renderInPlace(request, page, fetch, render, propsAt) {
+  let rendered = await render(page);
+  let served = page;
+  for (
+    let pass = 0;
+    rendered.redirect &&
+    pass < IN_PLACE_RENDERS &&
+    rendersInPlace(request, served.url, rendered.redirect);
+    pass++
+  ) {
+    const url = new URL(rendered.redirect, "http://frontend.local");
+    const props = await propsAt(served.props, url);
+    served = { ...served, url: `${url.pathname}${url.search}`, props };
+    fetch.reuseCompletedReads();
+    rendered = await render(served);
+  }
+  return { rendered, served };
+}

package/templates/vue/server/page-props.mjs

@@ -100,6 +100,16 @@ async function loadPage(
   }
 }
 
+/**
+ * The props of the same page at another query of its path (`url`): the page
+ * is read again, since its layout reads the query, and the rest is kept,
+ * the site layout included.
+ */
+export async function propsForQuery(props, url, backend, auth) {
+  const { page } = await loadPage(url, false, backend, auth.signInPath);
+  return { ...props, page };
+}
+
 /**
  * The props of the page a request visits, with the once props to declare.
  *

package/templates/vue/server/proxy-transfers.mjs

@@ -1,14 +1,18 @@
 // Large transfers through the proxy, a file upload above all. The request
 // body is streamed to the backend, never buffered, and held to the
 // `maxBodyBytes` of the proxy it reached: a declared Content-Length over the
-// limit is refused before a byte is read, a chunked body is cut off as soon as
-// it goes over.
+// limit is refused before a byte is passed on, a chunked body is cut off as
+// soon as it goes over.
 
 const PAYLOAD_TOO_LARGE = 413;
 const TOO_LARGE_BODY = JSON.stringify({ message: "Payload Too Large" });
-// Reading on after the refusal would take the whole body the limit exists to
-// refuse, so the request stream is left as it is and the connection closed.
+// The refused body is never passed on: the iteration stops where it went
+// over, and the request stream stays open for the lingering close below.
 const BODY_ITERATION = { destroyOnReturn: false };
+// How long a refused body is read and dropped before the connection closes
+// anyway: long enough for a client to finish sending what was in flight,
+// short enough to bound what a refused client can make the server read.
+const LINGER_MS = 5_000;
 
 const BODILESS_METHODS = new Set(["GET", "HEAD"]);
 const REQUEST_TIMEOUT_MS = 60 * 60 * 1000;
@@ -54,13 +58,35 @@ function isBodyTooLarge(error) {
   );
 }
 
-/** Answers 413 and closes the connection, the rest of the body unread. */
-function refuseTooLargeBody(response) {
+/**
+ * Answers 413 and closes the connection once the client stopped sending.
+ *
+ * Closing a socket with unread bytes makes the kernel reset the connection,
+ * and a client stack that drops what it had not read yet when the reset
+ * arrives (macOS, BSD, Windows) reports a network error instead of the 413,
+ * the browser's upload failing without a reason. The rest of the body is read
+ * and dropped instead (RFC 9112, section 9.6, "tear-down"), for `LINGER_MS`
+ * at most; the response ends with it and the connection then closes cleanly.
+ */
+function refuseTooLargeBody(request, response) {
   response.writeHead(PAYLOAD_TOO_LARGE, {
     "content-type": "application/json",
     connection: "close",
   });
-  response.end(TOO_LARGE_BODY);
+  response.write(TOO_LARGE_BODY);
+  if (request.complete) return response.end();
+  const close = () => {
+    clearTimeout(timer);
+    response.end();
+  };
+  const timer = setTimeout(() => {
+    response.end();
+    request.socket.destroy();
+  }, LINGER_MS);
+  timer.unref();
+  request.once("end", close);
+  request.once("error", close);
+  request.resume();
 }
 
 /**
@@ -74,11 +100,11 @@ function refuseTooLargeBody(response) {
  */
 export async function sendWithinLimit(request, response, maxBodyBytes, send) {
   if (declaresTooLargeBody(request, maxBodyBytes))
-    return refuseTooLargeBody(response);
+    return refuseTooLargeBody(request, response);
   try {
     return await send(requestBody(request, maxBodyBytes));
   } catch (error) {
     if (!isBodyTooLarge(error)) throw error;
-    return refuseTooLargeBody(response);
+    return refuseTooLargeBody(request, response);
   }
 }

package/templates/vue/server.mjs

@@ -2,7 +2,6 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { createServer, maxHeaderSize } from "node:http";
 import { extname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ofetch } from "ofetch";
 import {
   CLIENT_HEADERS,
   relayedHeaders,
@@ -26,7 +25,10 @@ import {
 } from "./server/cli-report.mjs";
 import { publicBuildFile } from "./server/built-files.mjs";
 import { serveStaticFile } from "./server/static-files.mjs";
-import { productionHtmlTemplate } from "./server/client-manifest.mjs";
+import {
+  localeCatalogPreloadTag,
+  productionHtmlTemplate,
+} from "./server/client-manifest.mjs";
 import { writeContent } from "./server/content.mjs";
 import {
   captureViteErrors,
@@ -50,7 +52,8 @@ import {
 } from "./server/module-server.mjs";
 import { HOMEPAGE } from "./server/homepage.mjs";
 import { publicOptionsScript } from "./server/public-options.mjs";
-import { loadPageProps } from "./server/page-props.mjs";
+import { renderInPlace, serverReads } from "./server/in-place-render.mjs";
+import { loadPageProps, propsForQuery } from "./server/page-props.mjs";
 import { htmlTag } from "./server/html-tag.mjs";
 import { listenHost } from "./server/listen-host.mjs";
 import * as icons from "./server/icons.mjs";
@@ -149,17 +152,7 @@ function backendHeaders(request, access = { anonymous: false, headers: [] }) {
 }
 
 function serverComponentFetch(request) {
-  return (path, options = {}) => {
-    const headers = new Headers(backendHeaders(request));
-    new Headers(options.headers).forEach((value, name) => {
-      headers.set(name, value);
-    });
-    return ofetch(path, {
-      ...options,
-      baseURL: process.env.DMS_API_BASE_URL,
-      headers,
-    });
-  };
+  return serverReads(() => backendHeaders(request));
 }
 
 async function backendJson(path, request) {
@@ -177,18 +170,18 @@ async function currentAuth() {
   return (await loadServerModules(await developmentServer())).serverAuth;
 }
 
+function pageBackend(request) {
+  return {
+    fetchJson: (path) => backendJson(path, request),
+    isFrontendPage: async (pathname) =>
+      (await ssrRenderer(await developmentServer())).isDmsFrontendPage(
+        pathname,
+      ),
+  };
+}
+
 function pageProps(request, auth) {
-  return loadPageProps(
-    request,
-    {
-      fetchJson: (path) => backendJson(path, request),
-      isFrontendPage: async (pathname) =>
-        (await ssrRenderer(await developmentServer())).isDmsFrontendPage(
-          pathname,
-        ),
-    },
-    auth,
-  );
+  return loadPageProps(request, pageBackend(request), auth);
 }
 
 function redirectToHomepage(request, response, pathname) {
@@ -320,6 +313,7 @@ export async function renderHtml(
     return { html: "", status: 200, redirect: rendered.redirect };
   const headEnd =
     (await documentStyleTags(devServer, rendered.modules, template)) +
+    (devServer ? "" : localeCatalogPreloadTag(rendered.catalogLocale)) +
     publicOptionsScript();
   const html = template
     .replace("<title>Antelope DMS</title>", () =>
@@ -338,13 +332,28 @@ export async function renderHtml(
   return { html, status: rendered.error?.statusCode ?? 200 };
 }
 
-function renderRequestHtml(page, request, rule = {}) {
-  const fetch = serverComponentFetch(request);
+function renderRequestHtml(page, request, rule = {}, reads) {
+  const fetch = reads ?? serverComponentFetch(request);
   return renderHtml(page, request.url, fetch, request.headers.cookie, {
     ssr: rule.ssr,
   });
 }
 
+/**
+ * Renders a page document, at the query the page completes as it renders:
+ * see `renderInPlace`.
+ */
+function renderDocument(page, request, rule, auth) {
+  const fetch = serverComponentFetch(request);
+  return renderInPlace(
+    request,
+    page,
+    fetch,
+    (served) => renderRequestHtml(served, request, rule, fetch),
+    (props, url) => propsForQuery(props, url, pageBackend(request), auth),
+  );
+}
+
 async function writeBackendError(error, request, response) {
   const auth = await currentAuth();
   const status = Number.isInteger(error?.status) ? error.status : 502;
@@ -477,16 +486,17 @@ export async function handleRequest(request, response) {
       JSON.stringify(page),
     );
   }
-  const rendered = await renderRequestHtml(page, request, rule);
+  const { rendered, served } = await renderDocument(page, request, rule, auth);
   if (rendered.redirect) {
     redirectFrontendVisit(request, response, rendered.redirect);
     return;
   }
+  const location = served === page ? {} : { "content-location": served.url };
   return writeContent(
     request,
     response,
     rendered.status,
-    { ...htmlHeaders(), ...headersFor(rendered.status) },
+    { ...htmlHeaders(), ...headersFor(rendered.status), ...location },
     rendered.html,
   );
 }