@antelopejs/dms-frontend 0.8.0 → 0.9.1

package/templates/vue/entry-weight.mjs

@@ -0,0 +1,132 @@
+// What each frontend module adds to the client entry.
+//
+// Every page loads the entry, and everything it imports statically, before it
+// runs anything: a module's `dms.frontend.ts`, its plugins and whatever they
+// import land there, on every page of every application that loads the
+// module. The client build records, from the bundle's own metadata, how much
+// of the entry each module's sources make up; `ajs dms build` reports it and
+// warns about a module above its threshold.
+//
+// Kept beside vite.config.ts rather than inside it so the plugin can be
+// exercised on its own, the way client-chunking.mjs is.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+
+/** Where the client build writes the attribution, under `dist/client`. */
+export const ENTRY_WEIGHT_FILE = ".vite/entry-weight.json";
+
+/** Owners of the entry's bytes that are no frontend module. */
+export const SHARED_OWNER = "shared";
+export const TRANSLATIONS_OWNER = "translations";
+
+const LOCALE_CATALOG = /[\\/]locales\.generated[\\/]/;
+
+function stripQuery(id) {
+  const query = id.indexOf("?");
+  return query === -1 ? id : id.slice(0, query);
+}
+
+function isInside(root, file) {
+  const path = relative(root, file);
+  return Boolean(path) && !path.startsWith("..") && !path.startsWith(sep);
+}
+
+/**
+ * The owner of a module id of the bundle: the frontend module whose sources
+ * hold the file, by its manifest name; the merged translation catalogs; else
+ * what every page shares (the renderer's runtime, the UI and icon libraries,
+ * an installed package).
+ *
+ * @param {{ root: string, name?: string, packageName?: string, id: string }[]} modules
+ */
+export function entryOwner(id, modules) {
+  if (id.startsWith("\0")) return SHARED_OWNER;
+  const file = stripQuery(id);
+  if (/[\\/]node_modules[\\/]/.test(file)) return SHARED_OWNER;
+  if (LOCALE_CATALOG.test(file)) return TRANSLATIONS_OWNER;
+  const module = modules.find(({ root }) => isInside(root, file));
+  return module
+    ? (module.name ?? module.packageName ?? module.id)
+    : SHARED_OWNER;
+}
+
+/**
+ * The files a page loads before its first line runs: the entry chunks and
+ * their static imports, transitively, by file name.
+ */
+function entryClosure(bundle) {
+  const chunks = Object.values(bundle).filter(
+    (output) => output.type === "chunk",
+  );
+  const byName = new Map(chunks.map((chunk) => [chunk.fileName, chunk]));
+  const seen = new Set();
+  const visit = (chunk) => {
+    if (!chunk || seen.has(chunk.fileName)) return;
+    seen.add(chunk.fileName);
+    for (const file of chunk.imports ?? []) visit(byName.get(file));
+  };
+  for (const chunk of chunks) if (chunk.isEntry) visit(chunk);
+  return [...seen].map((file) => byName.get(file));
+}
+
+/**
+ * The bytes of the entry each owner accounts for. Each chunk's bytes are
+ * shared out among the modules it holds in proportion to the code Rolldown
+ * rendered for each (`renderedLength`, before minification): an estimate that
+ * needs nothing the bundle does not already hold.
+ *
+ * @returns {{ files: string[], bytes: number, owners: Record<string, number> }}
+ */
+export function attributeEntry(bundle, modules) {
+  const files = entryClosure(bundle);
+  const owners = {};
+  let bytes = 0;
+  for (const chunk of files) {
+    const size = Buffer.byteLength(chunk.code);
+    bytes += size;
+    const rendered = Object.entries(chunk.modules ?? {});
+    const total = rendered.reduce(
+      (sum, [, info]) => sum + info.renderedLength,
+      0,
+    );
+    if (!total) {
+      owners[SHARED_OWNER] = (owners[SHARED_OWNER] ?? 0) + size;
+      continue;
+    }
+    for (const [id, info] of rendered) {
+      const owner = entryOwner(id, modules);
+      owners[owner] =
+        (owners[owner] ?? 0) + (size * info.renderedLength) / total;
+    }
+  }
+  for (const owner of Object.keys(owners))
+    owners[owner] = Math.round(owners[owner]);
+  return { files: files.map((chunk) => chunk.fileName), bytes, owners };
+}
+
+/**
+ * Records, in the client build, what each frontend module adds to the entry
+ * (`ENTRY_WEIGHT_FILE`). Server builds are left alone: their bundle is no
+ * page's entry.
+ */
+export function recordEntryWeight(modules) {
+  let ssrBuild = false;
+  return {
+    name: "dms-entry-weight",
+    configResolved(config) {
+      ssrBuild = Boolean(config.build.ssr);
+    },
+    // Once the bundle is written: plugins that generate the bundle after this
+    // one still rewrite the chunks' code.
+    writeBundle(options, bundle) {
+      if (ssrBuild || !options.dir) return;
+      const file = join(options.dir, ENTRY_WEIGHT_FILE);
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(
+        file,
+        `${JSON.stringify(attributeEntry(bundle, modules), null, 2)}\n`,
+      );
+    },
+  };
+}

package/templates/vue/frontend-build-loader.ts

@@ -1,6 +1,9 @@
 import { isAbsolute, posix, resolve } from "node:path";
-import { normalizePath } from "vite";
-import type { DmsFrontendBuildSetup } from "./frontend-build.ts";
+import { normalizePath, type Plugin } from "vite";
+import type {
+  DmsFrontendBuild,
+  DmsFrontendBuildSetup,
+} from "./frontend-build.ts";
 
 /** A module's `dms.frontend.build.ts`, as the generated loader imports it. */
 export interface FrontendBuildDeclaration {
@@ -22,12 +25,31 @@ export interface AutoImportDirectory {
 /** A module's private code: never auto-imported, whatever it declares. */
 const PRIVATE_DIRECTORY = /(?:^|\/)app\/build(?:\/|$)/;
 
-function declaredDirectories(setup: DmsFrontendBuildSetup): string[] {
-  const directories: string[] = [];
+interface FrontendModuleName {
+  id: string;
+  name?: string;
+}
+
+type VitePluginFactory = Parameters<DmsFrontendBuild["registerVitePlugins"]>[0];
+
+interface DeclaredBuild {
+  directories: string[];
+  pluginFactories: VitePluginFactory[];
+}
+
+/** Each setup runs once, whichever declaration is read first. */
+const declarations = new WeakMap<DmsFrontendBuildSetup, DeclaredBuild>();
+
+function declared(setup: DmsFrontendBuildSetup): DeclaredBuild {
+  const known = declarations.get(setup);
+  if (known) return known;
+  const build: DeclaredBuild = { directories: [], pluginFactories: [] };
   setup({
-    registerAutoImports: (entries) => directories.push(...entries),
+    registerAutoImports: (entries) => build.directories.push(...entries),
+    registerVitePlugins: (create) => build.pluginFactories.push(create),
   });
-  return directories;
+  declarations.set(setup, build);
+  return build;
 }
 
 function rejection(directory: string): string | undefined {
@@ -50,15 +72,15 @@ function rejection(directory: string): string | undefined {
  */
 export function autoImportDirectories(
   modules: readonly FrontendModuleRoot[],
-  declarations: readonly FrontendBuildDeclaration[],
+  buildDeclarations: readonly FrontendBuildDeclaration[],
   warn: (message: string) => void,
 ): AutoImportDirectory[] {
   const roots = new Map(modules.map((module) => [module.id, module.root]));
-  return declarations.flatMap(({ id, setup }) => {
+  return buildDeclarations.flatMap(({ id, setup }) => {
     const root = roots.get(id);
     if (root === undefined) return [];
     const scan = (pattern: string) => normalizePath(resolve(root, pattern));
-    const accepted = declaredDirectories(setup).filter((directory) => {
+    const accepted = declared(setup).directories.filter((directory) => {
       const reason = rejection(directory);
       if (reason)
         warn(
@@ -76,3 +98,199 @@ export function autoImportDirectories(
     ];
   });
 }
+
+/** The keys of a Vite plugin that hold a value, not a function Vite calls. */
+const PLUGIN_PROPERTIES = new Set([
+  "name",
+  "enforce",
+  "apply",
+  "sharedDuringBuild",
+  "perEnvironmentState",
+  "api",
+]);
+
+/** The hooks whose function result is itself a hook, run after the server starts. */
+const SERVER_HOOKS = new Set(["configureServer", "configurePreviewServer"]);
+
+const attributedErrors = new WeakSet<object>();
+
+/** The fields of a Rollup or Vite error that diagnostics and the overlay read. */
+const ERROR_FIELDS = [
+  "id",
+  "loc",
+  "frame",
+  "plugin",
+  "pluginCode",
+  "hook",
+  "code",
+] as const;
+
+/**
+ * A new error naming the module, with the original as its cause: the original
+ * may be frozen. It carries the original's diagnostic fields and its stack
+ * frames, so the error still points at the file and the line.
+ */
+function attribute(label: string, error: unknown): Error {
+  if (error instanceof Error && attributedErrors.has(error)) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const attributed = new Error(`Frontend module ${label}: ${message}`, {
+    cause: error,
+  });
+  attributedErrors.add(attributed);
+  if (!(error instanceof Error)) return attributed;
+  for (const field of ERROR_FIELDS) {
+    if (field in error)
+      Reflect.set(attributed, field, Reflect.get(error, field));
+  }
+  const frames = error.stack?.split(error.message).slice(1).join(error.message);
+  if (frames !== undefined && error.stack?.includes(error.message)) {
+    attributed.stack = `${error.name}: ${attributed.message}${frames}`;
+  }
+  return attributed;
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}
+
+function attributedHook(
+  label: string,
+  hook: unknown,
+  returnsHook: boolean,
+): unknown {
+  if (typeof hook === "function") {
+    const attributedResult = (result: unknown): unknown =>
+      returnsHook ? attributedHook(label, result, false) : result;
+    return function (this: unknown, ...args: unknown[]) {
+      try {
+        const result: unknown = hook.apply(this, args);
+        if (isThenable(result)) {
+          return Promise.resolve(result).then(
+            attributedResult,
+            (error: unknown) => {
+              throw attribute(label, error);
+            },
+          );
+        }
+        return attributedResult(result);
+      } catch (error) {
+        throw attribute(label, error);
+      }
+    };
+  }
+  if (typeof hook === "object" && hook !== null && "handler" in hook) {
+    return {
+      ...hook,
+      handler: attributedHook(label, hook.handler, returnsHook),
+    };
+  }
+  return hook;
+}
+
+function isPlugin(value: unknown): value is Plugin {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "name" in value &&
+    typeof value.name === "string" &&
+    value.name !== ""
+  );
+}
+
+/** Every property name of an object, inherited ones included. */
+function propertyNames(plugin: object): Set<string> {
+  const names = new Set<string>();
+  for (
+    let object: object | null = plugin;
+    object !== null && object !== Object.prototype;
+    object = Object.getPrototypeOf(object)
+  ) {
+    for (const name of Object.getOwnPropertyNames(object)) {
+      if (name !== "constructor") names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * A copy of the plugin whose hooks, own or inherited from its class, name the
+ * module in the errors they throw. The module's own object is left as it is.
+ */
+function attributedPlugin(label: string, plugin: Plugin): Plugin {
+  const copy: Record<string, unknown> = {};
+  for (const key of propertyNames(plugin)) {
+    const value: unknown = Reflect.get(plugin, key);
+    copy[key] = PLUGIN_PROPERTIES.has(key)
+      ? value
+      : attributedHook(label, value, SERVER_HOOKS.has(key));
+  }
+  if (!isPlugin(copy)) throw invalidPlugins(label);
+  return copy;
+}
+
+function invalidPlugins(label: string): Error {
+  return new Error(
+    `Frontend module ${label} registered Vite plugins that are not valid: the function given to registerVitePlugins must return an array of Vite plugin objects, each with a name (false, null and undefined entries are skipped, nested arrays are flattened), or nothing.`,
+  );
+}
+
+function flattened(label: string, entries: readonly unknown[]): Plugin[] {
+  return entries.flatMap((entry): Plugin[] => {
+    if (entry === false || entry === null || entry === undefined) return [];
+    if (Array.isArray(entry)) return flattened(label, entry);
+    if (isThenable(entry)) throw promisedPlugins(label);
+    if (!isPlugin(entry)) throw invalidPlugins(label);
+    return [entry];
+  });
+}
+
+function promisedPlugins(label: string): Error {
+  return new Error(
+    `Frontend module ${label} registered Vite plugins as a Promise: Vite's configuration is built synchronously, so the function given to registerVitePlugins must return the plugins themselves, not a Promise.`,
+  );
+}
+
+function createdPlugins(label: string, create: VitePluginFactory): Plugin[] {
+  let created: unknown;
+  try {
+    created = create();
+  } catch (error) {
+    throw attribute(label, error);
+  }
+  if (created === undefined) return [];
+  if (isThenable(created)) throw promisedPlugins(label);
+  if (!Array.isArray(created)) throw invalidPlugins(label);
+  return flattened(label, created);
+}
+
+/**
+ * The Vite plugins the modules registered with `registerVitePlugins`, in module
+ * order and then call order. Each module's factories run here, in the build
+ * process. A factory that throws, returns a Promise, or returns anything but an
+ * array of plugin objects (or nothing) fails with a message naming the module,
+ * and so does an error thrown by a hook of one of its plugins. As in a Vite
+ * configuration, false, null and undefined entries are skipped and nested
+ * arrays are flattened.
+ */
+export function vitePlugins(
+  modules: readonly FrontendModuleName[],
+  buildDeclarations: readonly FrontendBuildDeclaration[],
+): Plugin[] {
+  const names = new Map(
+    modules.map((module) => [module.id, module.name ?? module.id]),
+  );
+  return buildDeclarations.flatMap(({ id, setup }) => {
+    const label = names.get(id) ?? id;
+    return declared(setup).pluginFactories.flatMap((create) =>
+      createdPlugins(label, create).map((plugin) =>
+        attributedPlugin(label, plugin),
+      ),
+    );
+  });
+}

package/templates/vue/frontend-build.ts

@@ -1,3 +1,17 @@
+import type { Plugin } from "vite";
+
+/**
+ * What a `registerVitePlugins` function may return, as in a Vite
+ * configuration's `plugins`, except that a Promise is refused: Vite's
+ * configuration is built synchronously.
+ */
+export type DmsVitePluginEntry =
+  | Plugin
+  | false
+  | null
+  | undefined
+  | readonly DmsVitePluginEntry[];
+
 /**
  * What a frontend module's `dms.frontend.build.ts` declares about how the
  * application is built from it. Read when Vite starts, by `ajs dms dev` and
@@ -14,6 +28,24 @@ export interface DmsFrontendBuild {
    * holds the module's private code, which its own files import by path.
    */
   registerAutoImports(directories: readonly string[]): void;
+
+  /**
+   * Adds Vite plugins to the application's build, for `ajs dms dev`,
+   * `ajs dms build` and the preview alike.
+   *
+   * `create` runs in the build process each time Vite loads its configuration,
+   * and returns real Vite plugin objects (an array, each with a `name`; false,
+   * null and undefined entries are skipped and nested arrays flattened, as in a
+   * Vite configuration) or nothing. It is synchronous: a Promise is refused,
+   * because the configuration is built synchronously. The plugins come after
+   * the renderer's own plugins, in module order, then in the order of the
+   * calls. A value that is not an array of plugin objects, or an error thrown
+   * by `create` or by any hook of a plugin (the function `configureServer`
+   * returns included), fails Vite with a message that names the module.
+   */
+  registerVitePlugins(
+    create: () => readonly DmsVitePluginEntry[] | undefined,
+  ): void;
 }
 
 export type DmsFrontendBuildSetup = (build: DmsFrontendBuild) => void;
@@ -27,10 +59,11 @@ export type DmsFrontendBuildSetup = (build: DmsFrontendBuild) => void;
  *
  * export default defineDmsFrontendBuild((build) => {
  *   build.registerAutoImports(["layers/*\/app/composables"]);
+ *   build.registerVitePlugins(() => [boundaryPlugin()]);
  * });
  * ```
  *
- * A module without this file has nothing auto-imported. The file runs in
+ * A module without this file has nothing auto-imported and adds no plugin. The file runs in
  * Node.js when Vite starts, not in the application: it may import Node.js
  * built-ins, never the application's own code.
  */

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)