@antelopejs/dms-frontend 0.3.12 → 0.5.0

package/README.md

@@ -188,6 +188,72 @@ The SDK also exposes `use` for Vue plugins. Entries execute by descending manife
 
 Within one setup, the first module to register a name keeps it. `ajs-dms dev` sets every module up again each time a change to a layer reaches the server renderer, into empty registries, so the next server render uses the edited component without a restart. A `setup` may therefore run more than once in a process: it should only register, and keep no state of its own between runs.
 
+### Component prefix
+
+Every registered component joins the application's global components and resolves by name anywhere, in templates and in backend page trees. To keep the components of two modules from colliding, a module declares a `componentPrefix`, put in front of the name of every component it registers:
+
+```ts
+const frontendModule: DmsFrontendModule = {
+  componentPrefix: "Acme",
+  setup(sdk) {
+    sdk.registerComponent("Banner", Banner); // registered as AcmeBanner
+  },
+};
+```
+
+The full name, prefix included, is the one a template uses (`<AcmeBanner>`) and a backend sends (`CustomComponent("AcmeBanner")`, or `acme-banner`). Names are compared ignoring case, a leading `lazy` and non-alphanumeric characters; a leading `Dms` is no longer dropped, since it is the DMS module's own prefix.
+
+When two modules register the same name, the module of higher priority keeps it and a warning names both. A module that means to replace another's component registers its full name without its own prefix, which is not reported:
+
+```ts
+sdk.registerComponent("AcmeBanner", MyBanner, { prefix: false });
+```
+
+A module's `app/build/` directory is never auto-imported (see below): its components are registered so backend pages can name them, but they are the module's internals, not a surface other modules should build on.
+
+### Auto-imports (`dms.frontend.build.ts`)
+
+Nothing a module ships is auto-imported unless the module declares it, in an optional `dms.frontend.build.ts` next to its `dms.frontend.ts`:
+
+```ts
+import { defineDmsFrontendBuild } from "#dms/frontend-build";
+
+export default defineDmsFrontendBuild((build) => {
+  build.registerAutoImports([
+    "layers/*/app/composables",
+    "layers/*/app/utils",
+    "layers/*/app/types",
+  ]);
+});
+```
+
+Each entry is a directory relative to the module root, glob patterns allowed; every export of the files under it becomes available to the whole application without an import, in scripts and templates. A module without the file has nothing auto-imported. `app/build/` holds a module's private code and is never auto-imported: it is left out of what a broader entry covers, and an entry naming it, or a directory outside the module, is ignored with a warning when Vite starts.
+
+The file runs in Node.js when Vite starts, under `ajs dms dev` and `ajs dms build`, not in the application: it may import `#dms/frontend-build` and Node.js built-ins, never the application's code. Vite restarts when one changes.
+
+Up to 0.3, every module's `app/composables`, `app/types`, `app/utils`, `app/build/composables` and `app/build/types` were auto-imported. A module that relies on auto-imports declares its public directories in `dms.frontend.build.ts`, and imports its `app/build/` code by path.
+
+### Page loading state
+
+After a client navigation, the page renders under a `<Suspense>` until its chunk and any async `setup` resolve. `useDmsPageLoading()` (auto-imported) is `true` meanwhile, so a layout can show its own placeholder instead of an empty page body:
+
+```vue
+<script setup lang="ts">
+const pageLoading = useDmsPageLoading();
+</script>
+
+<template>
+  <slot />
+  <PageSkeleton v-if="pageLoading" />
+</template>
+```
+
+It stays `false` on the server and during hydration, which render the page resolved, for a page that does not suspend, and once a pending page is left.
+
+### Interface language
+
+The interface language follows the session (`useUserSession().user.language`), not the props of the page on screen: the first render takes it from the session the page arrived with, and it changes when the session's language does, after `useUserSession().fetch()` or a visit with a newer session. A page Inertia restores from history or serves from its prefetch cache carries the session it was fetched with: the frontend server stamps every session it writes (`session.updatedAt`), and a page carrying an older stamp of the same account updates neither the session nor the language. A session without a language, such as a signed-out one, keeps the language on screen; `$i18n.setLocale()` still switches it at any time.
+
 ### Declaring the loader releases a module supports
 
 A frontend module names the `@antelopejs/dms-frontend` releases it runs on in its own `package.json`, the way a package names the Node.js versions it supports:
@@ -412,7 +478,8 @@ The other files the workspace derives from every module follow their sources
 the same way. A file added to, changed in or removed from a module's `public/`
 is served, or no longer served, at once. Adding or removing an
 `app/config/shortcuts-registry.ts` or a `dms.frontend.ts` regenerates the
-aggregated shortcuts or the module loader, and the page reloads. A layer
+aggregated shortcuts or the module loader, and the page reloads. Adding,
+changing or removing a `dms.frontend.build.ts` restarts Vite. A layer
 directory added to or removed from `layers/` is the exception: Vite reads the
 `#<layer>` aliases and the auto-imported directories at startup only, so the
 dev server says it needs a restart.
@@ -436,6 +503,14 @@ needs no exception for the Iconify API. Icons reach the page two ways:
   answers `404`, and a name outside Iconify's naming rule `400`. `ajs dms dev`
   and `ajs dms start` run the same server, so both serve the route.
 
+The server render draws every icon, bundled or not: the frontend server loads
+each installed `@iconify-json/*` collection once and hands it to the renderer,
+and an icon is drawn in its first render as soon as its data is loaded, instead
+of after the component mounts. The data of each icon a render drew travels in
+the page, so the browser draws the same icons as it hydrates; an icon no
+installed collection holds stays empty on the server and is fetched in the
+browser as before.
+
 ## Options
 
 | Option | Environment | Purpose |
@@ -449,6 +524,7 @@ needs no exception for the Iconify API. Icons reach the page two ways:
 | | `HOST` | Address the frontend server binds to (default `0.0.0.0`) |
 | | `DMS_COOKIE_SECURE` | Secure cookies (`true` by default; `ajs dms dev` defaults to `false`) |
 | | `DMS_TRUSTED_PROXY_HOPS` | Number of trusted, rightmost reverse-proxy hops (default `0`) |
+| | `DMS_COUNTRY_HEADER` | Client country header the server relays to the backend, set by a trusted reverse proxy (default `CF-IPCountry`; empty relays none). Name the same header in the backend's `auth.signInCountry.header`. Relayed only when `DMS_TRUSTED_PROXY_HOPS` is above `0`, like the client address |
 | | `DMS_SESSION_SECRET` | Session cookie encryption key, 32 characters or more (required for login) |
 | | `DMS_HTML_RENDER_SECRET` | Secret that verifies the backend's signed HTML/email render requests; without it, e-mail renders are refused. Defaults to the `htmlRender.serviceSecret` the backend publishes in the frontend manifest |
 | | `DMS_OAUTH_RELAY_SECRET` | Secret the server presents to the backend's OAuth endpoints; without it, the backend refuses OAuth sign-in. Defaults to the `oauth.relaySecret` the backend publishes in the frontend manifest |

package/dist/config.d.ts

@@ -9,6 +9,7 @@ export declare function writeSecretBearingFile(file: string, content: string): v
 export declare const TEMPLATE_FILES: ReadonlyArray<readonly [string, string]>;
 export declare const LAYERS_SUBDIR = "frontend-modules";
 export declare const FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
+export declare const FRONTEND_BUILD_ENTRY = "dms.frontend.build.ts";
 export declare const AUTH_ESTABLISH_FILE = "generated-auth-establish.json";
 export declare const LAYER_COPY_BLOCKLIST: readonly string[];
 export declare const layerCopyIgnore: ignore.Ignore;

package/dist/config.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Options = exports.UsageError = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
+exports.Options = exports.UsageError = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_BUILD_ENTRY = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
 exports.writeSecretBearingFile = writeSecretBearingFile;
 exports.parseBackendUrl = parseBackendUrl;
 exports.requireBackendUrl = requireBackendUrl;
@@ -45,6 +45,9 @@ exports.TEMPLATE_FILES = [
     ["ui-app-config.ts", "ui-app-config.ts"],
     ["ssr-renderer.ts", "ssr-renderer.ts"],
     ["frontend-module.ts", "frontend-module.ts"],
+    ["frontend-build.ts", "frontend-build.ts"],
+    ["frontend-build-loader.ts", "frontend-build-loader.ts"],
+    ["icon-hydration.ts", "icon-hydration.ts"],
     ["globals.d.ts", "globals.d.ts"],
     ["compress-assets.mjs", "compress-assets.mjs"],
     ["head-order.mjs", "head-order.mjs"],
@@ -66,6 +69,7 @@ exports.TEMPLATE_FILES = [
 ];
 exports.LAYERS_SUBDIR = "frontend-modules";
 exports.FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
+exports.FRONTEND_BUILD_ENTRY = "dms.frontend.build.ts";
 exports.AUTH_ESTABLISH_FILE = "generated-auth-establish.json";
 exports.LAYER_COPY_BLOCKLIST = [
     "node_modules",

package/dist/derived-outputs.d.ts

@@ -1,10 +1,12 @@
 import { FrontendModuleOptions, ResolvedLayer } from "./workspace";
 export interface FrontendModuleRegistryEntry {
     id: string;
+    name?: string;
     packageName?: string;
     root: string;
     priority: number;
     entry?: string;
+    build?: string;
     options: FrontendModuleOptions;
 }
 export interface FrontendModuleRegistry {

package/dist/derived-outputs.js

@@ -21,6 +21,8 @@ function validateFrontendModuleRegistry(registry, workspaceDir) {
             throw new Error(`Invalid frontend module priority: ${module.id}`);
         if (module.entry !== undefined && module.entry !== config_1.FRONTEND_MODULE_ENTRY)
             throw new Error(`Invalid frontend module entry: ${module.id}`);
+        if (module.build !== undefined && module.build !== config_1.FRONTEND_BUILD_ENTRY)
+            throw new Error(`Invalid frontend module build entry: ${module.id}`);
         if (!(0, node_path_1.resolve)(module.root).startsWith(moduleRoot))
             throw new Error(`Frontend module root escapes the workspace: ${module.id}`);
         ids.add(module.id);
@@ -29,13 +31,16 @@ function validateFrontendModuleRegistry(registry, workspaceDir) {
 function createFrontendModuleRegistry(workspaceDir, layers) {
     const modules = layers.map((layer) => {
         const sourceEntry = (0, node_path_1.join)(layer.path, config_1.FRONTEND_MODULE_ENTRY);
+        const buildEntry = (0, node_path_1.join)(layer.path, config_1.FRONTEND_BUILD_ENTRY);
         const options = layer.options ?? {};
         return {
             id: (0, layers_1.getLayerSafeName)(layer),
+            name: layer.name ?? layer.packageName,
             packageName: layer.packageName,
             root: (0, layers_1.getLayerWorkspacePath)(workspaceDir, layer),
             priority: layer.priority ?? 0,
             entry: (0, node_fs_1.existsSync)(sourceEntry) ? config_1.FRONTEND_MODULE_ENTRY : undefined,
+            build: (0, node_fs_1.existsSync)(buildEntry) ? config_1.FRONTEND_BUILD_ENTRY : undefined,
             options: layer.configKey ? { [layer.configKey]: options } : options,
         };
     });
@@ -47,6 +52,7 @@ function createFrontendModuleRegistry(workspaceDir, layers) {
 function writeFrontendTypePaths(workspaceDir, registry) {
     const paths = {
         "#dms/frontend-module": ["./frontend-module.ts"],
+        "#dms/frontend-build": ["./frontend-build.ts"],
         "@frontend/*": ["./frontend-modules/*"],
         ...(0, layer_aliases_1.frontendLayerTypePaths)([...registry.modules].reverse().map((module) => module.root), { relativeTo: workspaceDir }),
     };
@@ -59,14 +65,27 @@ function writeFrontendModuleLoader(workspaceDir, registry) {
         .map((module, index) => `import module${index} from "@frontend/${module.id}/${module.entry}";`)
         .join("\n");
     const registrations = modules
-        .map((module, index) => `{ module: module${index}, options: { public: ${JSON.stringify(module.options)} } }`)
+        .map((module, index) => `{ name: ${JSON.stringify(module.name)}, module: module${index}, options: { public: ${JSON.stringify(module.options)} } }`)
         .join(", ");
     const content = `${imports}\n\nimport type { DmsFrontendModuleRegistration } from "./frontend-module";\n\nexport const frontendModules: DmsFrontendModuleRegistration[] = [${registrations}];\n`;
     return (0, fs_sync_1.applyContent)(content, (0, node_path_1.join)(workspaceDir, "frontend-modules.generated.ts"));
 }
+function writeFrontendBuildLoader(workspaceDir, registry) {
+    const modules = registry.modules.filter((module) => module.build);
+    const imports = modules
+        .map((module, index) => `import build${index} from "./${config_1.LAYERS_SUBDIR}/${module.id}/${module.build}";`)
+        .join("\n");
+    const declarations = modules
+        .map((module, index) => `{ id: ${JSON.stringify(module.id)}, setup: build${index} }`)
+        .join(", ");
+    const content = `${imports}\n\nimport type { FrontendBuildDeclaration } from "./frontend-build-loader";\n\nexport const frontendBuilds: FrontendBuildDeclaration[] = [${declarations}];\n`;
+    return (0, fs_sync_1.applyContent)(content, (0, node_path_1.join)(workspaceDir, "frontend-builds.generated.ts"));
+}
 function writeModuleRegistry(workspaceDir, registry) {
     const wroteRegistry = (0, fs_sync_1.applyContent)(`${JSON.stringify(registry, null, 2)}\n`, (0, node_path_1.join)(workspaceDir, "generated-frontend-modules.json"));
-    return writeFrontendModuleLoader(workspaceDir, registry) || wroteRegistry;
+    const wroteModules = writeFrontendModuleLoader(workspaceDir, registry);
+    const wroteBuilds = writeFrontendBuildLoader(workspaceDir, registry);
+    return wroteRegistry || wroteModules || wroteBuilds;
 }
 function moduleAssetRoots(moduleRoot) {
     const layersRoot = (0, node_path_1.join)(moduleRoot, "layers");
@@ -278,7 +297,7 @@ function writeShortcutExports(workspaceDir, registry) {
 exports.DERIVED_OUTPUTS = [
     {
         name: "module registry",
-        affects: (path) => (0, fs_sync_1.toPosixPath)(path) === config_1.FRONTEND_MODULE_ENTRY,
+        affects: (path) => [config_1.FRONTEND_MODULE_ENTRY, config_1.FRONTEND_BUILD_ENTRY].includes((0, fs_sync_1.toPosixPath)(path)),
         write: writeModuleRegistry,
     },
     {

package/dist/help.js

@@ -25,6 +25,10 @@ exports.ENVIRONMENT_VARIABLES = [
         "DMS_TRUSTED_PROXY_HOPS",
         "Trusted reverse-proxy hops, counted from the right (default: 0)",
     ],
+    [
+        "DMS_COUNTRY_HEADER",
+        "Proxy country header relayed to the backend when a proxy is trusted (default: CF-IPCountry; empty: none)",
+    ],
     [
         "DMS_HTML_RENDER_SECRET",
         "Overrides the e-mail render secret the backend publishes",

package/dist/layers.js

@@ -119,6 +119,7 @@ function readLayerPackageName(layerPath) {
 function resolveLayer(layerPath, mod) {
     return {
         path: layerPath,
+        name: mod.name,
         sourcePath: mod.path,
         packageName: readLayerPackageName(layerPath),
         priority: mod.priority,

package/dist/workspace.d.ts

@@ -27,6 +27,7 @@ export interface FrontendManifest {
 }
 export interface ResolvedLayer {
     path: string;
+    name?: string;
     sourcePath?: string;
     packageName?: string;
     priority?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.3.12",
+  "version": "0.5.0",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/app-runtime.ts

@@ -6,6 +6,7 @@ import { en as uiEn, fr as uiFr } from "@nuxt/ui/locale";
 import ui from "@nuxt/ui/vue-plugin";
 import { useHead } from "@unhead/vue";
 import type { VueHeadClient } from "@unhead/vue/types";
+import type { IconifyIcon } from "@iconify/vue";
 import type { FetchOptions } from "ofetch";
 import {
   type App,
@@ -23,7 +24,9 @@ import DmsDynamicPage from "./DmsDynamicPage.vue";
 import {
   type DmsLocaleLoader,
   type DmsPageProps,
+  type DmsUser,
   createDmsFrontendRuntime,
+  dmsPageSuspenseProps,
   getDmsErrorPage,
   getDmsLayout,
   getDmsLayoutProps,
@@ -39,7 +42,13 @@ import {
   useDmsAppConfig,
   useDmsState,
   useError,
+  useUserSession,
 } from "./frontend-module";
+import {
+  SSR_ICONS_ID,
+  addDmsIcons,
+  drawLoadedIconsAtOnce,
+} from "./icon-hydration";
 import {
   loadLocaleMessages,
   localeMessages,
@@ -94,30 +103,24 @@ function uiLocale(locale: string): UiLocale {
   return UI_LOCALES[locale as keyof typeof UI_LOCALES] ?? UI_LOCALES.en;
 }
 
-function pageLocale(props: DmsPageProps): string {
-  const language = props.user?.language;
-  if (typeof language !== "string") return DEFAULT_LOCALE;
+/** The supported locale of a user's language, if it has one. */
+function userLocale(user: DmsUser | null | undefined): string | undefined {
+  const language = user?.language;
+  if (typeof language !== "string") return undefined;
   const locale = language.slice(0, 2);
-  return supportedLocales.includes(locale) ? locale : DEFAULT_LOCALE;
+  return supportedLocales.includes(locale) ? locale : undefined;
 }
 
-function readDmsAsyncData(): Record<string, unknown> {
-  if (typeof document === "undefined") return {};
-  const element = document.getElementById(SSR_ASYNC_DATA_ID);
-  if (!element?.textContent) return {};
-  const data = JSON.parse(element.textContent) as Record<string, unknown>;
+function readServerRendered<T>(id: string, empty: T): T {
+  if (typeof document === "undefined") return empty;
+  const element = document.getElementById(id);
+  if (!element?.textContent) return empty;
+  const value = JSON.parse(element.textContent) as T;
   element.remove();
-  return data;
+  return value;
 }
 
-function readDmsAsyncComponents(): string[] {
-  if (typeof document === "undefined") return [];
-  const element = document.getElementById(SSR_ASYNC_COMPONENTS_ID);
-  if (!element?.textContent) return [];
-  const names = JSON.parse(element.textContent) as string[];
-  element.remove();
-  return names;
-}
+drawLoadedIconsAtOnce();
 
 const DmsInertiaPage = defineComponent({
   name: "DmsInertiaPage",
@@ -148,17 +151,25 @@ const DmsPersistentLayout = defineComponent({
   setup(_, { attrs, slots }) {
     const props = computed(() => attrs as unknown as DmsPageProps);
     const i18n = useI18n();
+    const { user } = useUserSession();
     let localeVersion = 0;
     useHead({
       htmlAttrs: { lang: computed(() => i18n.locale.value) },
     });
     watch(
       () => [attrs.path, attrs.page, attrs.user, attrs.session, attrs.error],
-      async () => {
+      () => hydrateDmsPageProps(props.value),
+      { immediate: true, flush: "sync" },
+    );
+    // The session, not the page props: a page restored from history or from
+    // the prefetch cache carries the user as it was when it was fetched, and
+    // would switch the interface back to a language the user has left. A
+    // session without a language keeps the one on screen.
+    watch(
+      () => userLocale(user.value),
+      async (locale) => {
         const version = ++localeVersion;
-        hydrateDmsPageProps(props.value);
-        const locale = pageLocale(props.value);
-        if (i18n.locale.value === locale) return;
+        if (!locale || i18n.locale.value === locale) return;
         const messages = await loadLocaleMessages(locale);
         if (version !== localeVersion) return;
         i18n.setLocaleMessage(locale, messages);
@@ -205,7 +216,7 @@ function renderDmsPage(
     error,
     key: props.path,
   });
-  return h(Suspense, null, { default: () => pageContent });
+  return h(Suspense, dmsPageSuspenseProps(), { default: () => pageContent });
 }
 
 function renderDmsPersistentLayout(
@@ -247,9 +258,9 @@ export async function configureDmsApp(
     options.runtime ??
     createDmsFrontendRuntime(
       options.serverFetch as typeof import("ofetch").ofetch,
-      readDmsAsyncData(),
+      readServerRendered<Record<string, unknown>>(SSR_ASYNC_DATA_ID, {}),
     );
-  const locale = pageLocale(options.initialPageProps);
+  const locale = userLocale(options.initialPageProps.user) ?? DEFAULT_LOCALE;
   const messages = await loadLocaleMessages(locale);
   const i18n = createI18n({
     legacy: false,
@@ -266,6 +277,9 @@ export async function configureDmsApp(
   options.app.runWithContext(() =>
     hydrateDmsPageProps(options.initialPageProps, options.initialPageUrl),
   );
+  addDmsIcons(
+    readServerRendered<Record<string, IconifyIcon>>(SSR_ICONS_ID, {}),
+  );
   if (typeof window !== "undefined") {
     const toast = options.app.runWithContext(() => useToast());
     showNetworkErrors(toast.add, i18n.global);
@@ -275,7 +289,9 @@ export async function configureDmsApp(
   // Hydration then adopts the server-rendered markup instead of discarding it.
   await Promise.all([
     preloadDmsPage(options.initialPageProps),
-    resolveDmsAsyncComponents(readDmsAsyncComponents()),
+    resolveDmsAsyncComponents(
+      readServerRendered<string[]>(SSR_ASYNC_COMPONENTS_ID, []),
+    ),
   ]);
   const mounted = await installDmsPlugins(
     options.app,

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

@@ -0,0 +1,78 @@
+import { isAbsolute, posix, resolve } from "node:path";
+import { normalizePath } from "vite";
+import type { DmsFrontendBuildSetup } from "./frontend-build";
+
+/** A module's `dms.frontend.build.ts`, as the generated loader imports it. */
+export interface FrontendBuildDeclaration {
+  /** The module's id in the generated module registry. */
+  id: string;
+  setup: DmsFrontendBuildSetup;
+}
+
+interface FrontendModuleRoot {
+  id: string;
+  root: string;
+}
+
+export interface AutoImportDirectory {
+  glob: string;
+  types: boolean;
+}
+
+/** A module's private code: never auto-imported, whatever it declares. */
+const PRIVATE_DIRECTORY = /(?:^|\/)app\/build(?:\/|$)/;
+
+function declaredDirectories(setup: DmsFrontendBuildSetup): string[] {
+  const directories: string[] = [];
+  setup({
+    registerAutoImports: (entries) => directories.push(...entries),
+  });
+  return directories;
+}
+
+function rejection(directory: string): string | undefined {
+  const path = posix.normalize(normalizePath(directory));
+  if (isAbsolute(directory) || path === ".." || path.startsWith("../"))
+    return "it is not inside the module";
+  if (PRIVATE_DIRECTORY.test(path))
+    return "app/build/ holds the module's private code, which is never auto-imported";
+  return undefined;
+}
+
+/**
+ * The directories the modules declared in their `dms.frontend.build.ts`, as
+ * the auto-importer's scan globs. Each module's `app/build/` directories are
+ * excluded even from a broader declaration; a declaration naming one, or
+ * leaving the module, is ignored with a warning.
+ *
+ * Globs are POSIX on every platform: the scanner reads a backslash as an
+ * escape, not as a separator.
+ */
+export function autoImportDirectories(
+  modules: readonly FrontendModuleRoot[],
+  declarations: readonly FrontendBuildDeclaration[],
+  warn: (message: string) => void,
+): AutoImportDirectory[] {
+  const roots = new Map(modules.map((module) => [module.id, module.root]));
+  return declarations.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 reason = rejection(directory);
+      if (reason)
+        warn(
+          `Frontend module ${id} declares "${directory}" for auto-import, which is ignored: ${reason}.`,
+        );
+      return !reason;
+    });
+    if (accepted.length === 0) return [];
+    return [
+      ...accepted.map((directory) => ({
+        glob: scan(`${directory}/**/*`),
+        types: true,
+      })),
+      { glob: `!${scan("**/app/build/**")}`, types: true },
+    ];
+  });
+}

package/templates/vue/frontend-build.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ * `ajs dms build` alike.
+ */
+export interface DmsFrontendBuild {
+  /**
+   * Makes every export of the files under these directories available to
+   * the whole application without an import, in scripts and templates.
+   *
+   * Each entry is a directory relative to the module root, and may hold glob
+   * patterns: `layers/*\/app/composables` covers that directory of every
+   * layer. Nothing under an `app/build/` directory is ever auto-imported: it
+   * holds the module's private code, which its own files import by path.
+   */
+  registerAutoImports(directories: readonly string[]): void;
+}
+
+export type DmsFrontendBuildSetup = (build: DmsFrontendBuild) => void;
+
+/**
+ * Declares how the application is built from a frontend module, as the
+ * default export of its `dms.frontend.build.ts`:
+ *
+ * ```ts
+ * import { defineDmsFrontendBuild } from "#dms/frontend-build";
+ *
+ * export default defineDmsFrontendBuild((build) => {
+ *   build.registerAutoImports(["layers/*\/app/composables"]);
+ * });
+ * ```
+ *
+ * A module without this file has nothing auto-imported. 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.
+ */
+export function defineDmsFrontendBuild(
+  setup: DmsFrontendBuildSetup,
+): DmsFrontendBuildSetup {
+  return setup;
+}

package/templates/vue/frontend-module.ts

@@ -15,6 +15,8 @@ import {
   type Component,
   type ComponentPublicInstance,
   type ComputedRef,
+  camelize,
+  capitalize,
   computed,
   defineComponent,
   type EffectScope,
@@ -31,6 +33,7 @@ import {
   type PropType,
   type Ref,
   reactive,
+  readonly,
   ref,
   watch,
 } from "vue";
@@ -82,6 +85,13 @@ export interface DmsUser extends Record<string, unknown> {}
 export interface DmsSession {
   accountId: string;
   activeTenantId?: string;
+  /**
+   * When the frontend server last wrote this session, in milliseconds since
+   * the epoch. A page restored from history or from the prefetch cache
+   * carries an older session than the one the app already holds, and does not
+   * replace it.
+   */
+  updatedAt?: number;
 }
 export interface DmsRuntimeConfig extends RuntimeConfig {
   public: PublicRuntimeConfig;
@@ -220,9 +230,21 @@ export interface DmsPluginRegistrationOptions {
   clientOnly?: boolean;
 }
 export type DmsComponentPreloader = () => Promise<unknown>;
+export interface DmsComponentRegistrationOptions {
+  /**
+   * Registers the component under `name` as given, without the module's
+   * `componentPrefix`: the way to replace a component another module
+   * registers, from a module of higher priority. Defaults to `true`.
+   */
+  prefix?: boolean;
+}
 export interface DmsFrontendSdk {
   options: DmsModuleOptions;
-  registerComponent(name: string, component: Component): void;
+  registerComponent(
+    name: string,
+    component: Component,
+    options?: DmsComponentRegistrationOptions,
+  ): void;
   registerPage(
     name: string,
     component: Component,
@@ -261,9 +283,18 @@ export interface DmsFrontendSdk {
   use(plugin: Plugin): void;
 }
 export interface DmsFrontendModule {
+  /**
+   * Put in front of the name of every component the module registers, so
+   * the components of two modules never collide: with `"Acme"`,
+   * `registerComponent("Banner", ...)` registers `AcmeBanner`, the name the
+   * backend sends and templates use.
+   */
+  componentPrefix?: string;
   setup(sdk: DmsFrontendSdk): void | Promise<void>;
 }
 export interface DmsFrontendModuleRegistration {
+  /** The module's manifest name, which collision warnings name it by. */
+  name?: string;
   module: DmsFrontendModule;
   options: DmsModuleOptions;
 }
@@ -283,6 +314,10 @@ export interface DmsRuntimeHooks {
 interface DmsComponentRegistration {
   name: string;
   component: Component;
+  /** The registering module, for a collision warning. */
+  module?: string;
+  /** Registered without the module's prefix, to replace another module's. */
+  unprefixed?: boolean;
 }
 
 interface DmsFrontendEntry {
@@ -333,6 +368,8 @@ export interface DmsFrontendRuntime {
   pendingNavigation?: Promise<void>;
   hasNavigationListener: boolean;
   pageVersion: number;
+  /** Whether the page `<Suspense>` waits on the page being navigated to. */
+  pageLoading: Ref<boolean>;
   /**
    * Identifies the page on screen (its path, or the error page shown at that
    * path), whose meta `route.meta` holds.
@@ -403,6 +440,7 @@ export function createDmsFrontendRuntime(
     }),
     hasNavigationListener: false,
     pageVersion: 0,
+    pageLoading: ref(false),
     scope: effectScope(true),
   };
 }
@@ -1187,20 +1225,86 @@ export function useUserSession<
   };
 }
 
+/**
+ * Whether the page loaded by the current navigation is still pending: its
+ * chunk, or an async `setup` it awaits, has not resolved yet. A layout reads
+ * it to show its own placeholder in place of the page. Always `false` on the
+ * server and during hydration, which render the page resolved.
+ */
+export function useDmsPageLoading(): Readonly<Ref<boolean>> {
+  return readonly(useDmsRuntime().pageLoading);
+}
+
+/**
+ * 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
+ * pending never leaves the state set.
+ */
+export function dmsPageSuspenseProps(): Record<string, () => void> {
+  const loading = useDmsRuntime().pageLoading;
+  const settle = () => {
+    loading.value = false;
+  };
+  return {
+    onPending: () => {
+      loading.value = true;
+    },
+    onResolve: settle,
+    onVnodeBeforeUnmount: settle,
+  };
+}
+
+/**
+ * The key a component name is registered and resolved under: case, a leading
+ * `lazy` and every non-alphanumeric character ignored, so PascalCase,
+ * kebab-case and lowercase spellings match. Unlike `normalizeDmsName`, a
+ * leading `Dms` is kept: it is the DMS module's prefix, and dropping it would
+ * make `DmsBanner` and another module's `Banner` the same component.
+ */
+function normalizeDmsComponentName(name: string): string {
+  return name
+    .replace(/^lazy/i, "")
+    .replace(/[^a-z0-9]/gi, "")
+    .toLowerCase();
+}
+
+function moduleLabel(module: string | undefined): string {
+  return module ? `module "${module}"` : "an unnamed module";
+}
+
+/**
+ * A component registered under a name already taken is ignored: the first
+ * registration, from the module of higher priority, keeps the name. That is
+ * how a module replaces another's component, by registering its full name
+ * without a prefix, and only a collision neither side asked for is reported.
+ */
 function registerDmsComponentEntry(
   entries: Map<string, DmsComponentRegistration>,
-  name: string,
-  component: Component,
+  registration: DmsComponentRegistration,
 ): void {
-  const key = normalizeDmsName(name);
-  if (!entries.has(key)) entries.set(key, { name, component });
+  const key = normalizeDmsComponentName(registration.name);
+  const existing = entries.get(key);
+  if (!existing) {
+    entries.set(key, registration);
+    return;
+  }
+  if (existing.unprefixed || registration.unprefixed) return;
+  console.warn(
+    `[dms] Component "${registration.name}" from ${moduleLabel(registration.module)} is ignored: ` +
+      `${moduleLabel(existing.module)} already registers "${existing.name}". ` +
+      "Give the modules different component prefixes.",
+  );
 }
 /** Registers a component unless a higher-priority module already owns its name. */
 export function registerDmsComponent(name: string, component: Component): void {
-  registerDmsComponentEntry(registry.components, name, component);
+  registerDmsComponentEntry(registry.components, { name, component });
 }
+/**
+ * Resolves a registered component by its full name, prefix included. Case,
+ * a leading `lazy` and non-alphanumeric characters are ignored.
+ */
 export function resolveDmsComponent(name: string): Component | undefined {
-  return registry.components.get(normalizeDmsName(name))?.component;
+  return registry.components.get(normalizeDmsComponentName(name))?.component;
 }
 export const getDmsComponent = resolveDmsComponent;
 
@@ -1371,6 +1475,24 @@ export function getDmsLayoutProps(
   };
 }
 
+/**
+ * Whether a page carries an older session of the same account than the one
+ * the app holds: Inertia restores a page from history, or serves it from the
+ * prefetch cache, with the props it was fetched with, and those must not undo
+ * a later `useUserSession().fetch()`.
+ */
+function isStaleSession(
+  incoming: DmsSession | undefined,
+  current: DmsSession | null,
+): boolean {
+  return (
+    !!incoming &&
+    !!current &&
+    incoming.accountId === current.accountId &&
+    (incoming.updatedAt ?? 0) < (current.updatedAt ?? 0)
+  );
+}
+
 export function hydrateDmsPageProps(props: DmsPageProps, url?: string): void {
   const runtime = useDmsRuntime();
   if (url) updateRoute(runtime, url);
@@ -1384,10 +1506,12 @@ export function hydrateDmsPageProps(props: DmsPageProps, url?: string): void {
   }
   runtime.pageVersion++;
   runtime.currentError.value = null;
-  useDmsState<DmsUser | null>("dms-user", () => null).value =
-    props.user ?? null;
-  useDmsState<DmsSession | null>("dms-session", () => null).value =
-    props.session ?? null;
+  const session = useDmsState<DmsSession | null>("dms-session", () => null);
+  if (!isStaleSession(props.session, session.value)) {
+    useDmsState<DmsUser | null>("dms-user", () => null).value =
+      props.user ?? null;
+    session.value = props.session ?? null;
+  }
   const shared = props.page.shared;
   if (shared) {
     useDmsState<unknown>("dms-siteLayout", () => undefined).value =
@@ -1451,14 +1575,28 @@ function registerDmsFrontendEntry(
   if (!entries.has(name)) entries.set(name, { component, preload });
 }
 
+/** `name` behind `prefix`, as a PascalCase component name. */
+function prefixedComponentName(prefix: string, name: string): string {
+  return prefix ? `${prefix}${capitalize(camelize(name))}` : name;
+}
+
 function createSdk(
   target: DmsFrontendRegistry,
-  options: DmsModuleOptions,
+  {
+    name: module,
+    module: { componentPrefix = "" },
+    options,
+  }: DmsFrontendModuleRegistration,
 ): DmsFrontendSdk {
   return {
     options,
-    registerComponent: (name, component) =>
-      registerDmsComponentEntry(target.components, name, component),
+    registerComponent: (name, component, { prefix = true } = {}) =>
+      registerDmsComponentEntry(target.components, {
+        name: prefix ? prefixedComponentName(componentPrefix, name) : name,
+        component,
+        module,
+        unprefixed: !prefix,
+      }),
     registerPage: (name, component, preload) => {
       const key = normalizeDmsPageKey(name);
       registerDmsFrontendEntry(target.pages, key, component, preload);
@@ -1519,7 +1657,7 @@ export async function setupFrontendModules(
       runtimeConfig.value.public,
       registration.options.public,
     );
-    await registration.module.setup(createSdk(next, registration.options));
+    await registration.module.setup(createSdk(next, registration));
   }
   registry = next;
 }

package/templates/vue/icon-hydration.ts

@@ -0,0 +1,78 @@
+import {
+  addCollection,
+  addIcon,
+  getIcon,
+  Icon,
+  type IconifyIcon,
+  type IconifyJSON,
+  iconLoaded,
+} from "@iconify/vue";
+import type { App, Component, ComponentPublicInstance } from "vue";
+
+/** The element a server render writes the data of the icons it drew to. */
+export const SSR_ICONS_ID = "dms-ssr-icons";
+
+interface IconProps {
+  icon?: unknown;
+}
+
+/**
+ * Draws an Iconify icon in its first render whenever its data is loaded, on
+ * the server as in the browser.
+ *
+ * `@iconify/vue` otherwise renders every icon empty until it mounts, which a
+ * server render never does: pages arrived without their icons, which popped in
+ * once hydrated. Its `ssr` prop opts out of the wait, but Nuxt UI's `UIcon`
+ * does not pass it, so its default is set here, and only for an icon whose
+ * data is loaded: an icon still to be fetched waits for the mount as before,
+ * so a server render never queries an Iconify API.
+ */
+export function drawLoadedIconsAtOnce(): void {
+  (Icon as unknown as { props: Record<string, unknown> }).props.ssr = {
+    type: Boolean,
+    default: ({ icon }: IconProps) =>
+      typeof icon !== "string" || iconLoaded(icon),
+  };
+}
+
+/**
+ * Loads whole icon collections, so a server render draws any icon of them,
+ * including those only named by backend data, which the client bundle's scan
+ * cannot see.
+ */
+export function registerDmsIconCollections(collections: IconifyJSON[]): void {
+  for (const collection of collections) addCollection(collection);
+}
+
+/** Records the name of every Iconify icon a server render reaches. */
+export function trackDmsIcons(app: App): Set<string> {
+  const names = new Set<string>();
+  app.mixin({
+    beforeCreate(this: ComponentPublicInstance) {
+      if (this.$.type !== (Icon as Component)) return;
+      const { icon } = this.$props as IconProps;
+      if (typeof icon === "string") names.add(icon);
+    },
+  });
+  return names;
+}
+
+/**
+ * The data of the icons a server render drew, which the browser loads before
+ * it hydrates: an icon outside the client bundle would otherwise hydrate
+ * empty over the server's markup.
+ */
+export function serializeDmsIcons(
+  names: Iterable<string>,
+): Record<string, IconifyIcon> {
+  return Object.fromEntries(
+    [...names].flatMap((name) => {
+      const data = getIcon(name);
+      return data ? [[name, data]] : [];
+    }),
+  );
+}
+
+export function addDmsIcons(icons: Record<string, IconifyIcon>): void {
+  for (const [name, data] of Object.entries(icons)) addIcon(name, data);
+}

package/templates/vue/server/auth/backend.mjs

@@ -1,4 +1,4 @@
-import { clientIp } from "./client-ip.mjs";
+import { clientCountryHeader, clientIp } from "./client-ip.mjs";
 
 const FORWARDED_HEADERS = [
   "user-agent",
@@ -26,12 +26,26 @@ export function publicBackendMessage(data) {
     : undefined;
 }
 
-export async function backend(path, request, options = {}) {
-  const headers = Object.fromEntries(
-    FORWARDED_HEADERS.flatMap((name) =>
-      request.headers[name] ? [[name, request.headers[name]]] : [],
+/**
+ * The headers of a client request the server relays to the backend.
+ *
+ * @param request The client request
+ * @param names Lowercase names of the request headers to copy when present
+ * @returns The client country header, then the copied headers
+ */
+export function relayedHeaders(request, names) {
+  return {
+    ...clientCountryHeader(request),
+    ...Object.fromEntries(
+      names.flatMap((name) =>
+        request.headers[name] ? [[name, request.headers[name]]] : [],
+      ),
     ),
-  );
+  };
+}
+
+export async function backend(path, request, options = {}) {
+  const headers = relayedHeaders(request, FORWARDED_HEADERS);
   headers["x-forwarded-for"] = clientIp(request);
   if (options.token) headers.authorization = `Bearer ${options.token}`;
   if (options.relay)

package/templates/vue/server/auth/client-ip.mjs

@@ -51,6 +51,34 @@ export function clientIp(request) {
   return chain[Math.max(0, chain.length - hops - 1)] ?? socketIp;
 }
 
+const DEFAULT_COUNTRY_HEADER = "CF-IPCountry";
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
+
+function countryHeader() {
+  const name = (process.env.DMS_COUNTRY_HEADER ?? DEFAULT_COUNTRY_HEADER)
+    .trim()
+    .toLowerCase();
+  return HEADER_NAME.test(name) ? name : undefined;
+}
+
+/**
+ * The client's country header, as the backend request headers to add.
+ *
+ * The header is the one `DMS_COUNTRY_HEADER` names (`CF-IPCountry` by
+ * default, empty to relay none), the name the DMS reads from
+ * `auth.signInCountry.header`. Like `X-Forwarded-For`, it is only believed
+ * from a trusted reverse proxy: with `DMS_TRUSTED_PROXY_HOPS` at `0`, any
+ * caller could have set it, so nothing is relayed.
+ */
+export function clientCountryHeader(request) {
+  const name = countryHeader();
+  if (!name || !trustedHops()) return {};
+  const value = request.headers?.[name];
+  return typeof value === "string" && value.trim()
+    ? { [name]: value.trim() }
+    : {};
+}
+
 /**
  * Body answered with the 403 of the CSRF origin check.
  *

package/templates/vue/server/auth/routes.mjs

@@ -66,6 +66,7 @@ export function publicSession(session) {
     session: {
       accountId: session.accountId,
       activeTenantId: session.activeTenantId,
+      updatedAt: session.updatedAt,
     },
   };
 }

package/templates/vue/server/auth/session.mjs

@@ -146,9 +146,15 @@ export function assertAccountInvariant(session, accountId) {
     throw new Error("Account session invariant violated");
 }
 
+/**
+ * Write `session` as the current one, and as one of the stored accounts.
+ * Stamps it with `updatedAt`, which lets the browser tell a page fetched
+ * before this write, and restored from its cache, from a current one.
+ */
 export function persistAccountSession(request, response, session, accountId) {
   const id = accountId ?? session.accountId ?? randomUUID();
   session.accountId = id;
+  session.updatedAt = Date.now();
   const account = storeAccount(request, response, session, id);
   assertAccountInvariant(session, account.accountId);
   writeSession(response, session);

package/templates/vue/server/icons.mjs

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,12 +14,16 @@ const READ_METHODS = new Set(["GET", "HEAD"]);
 const ICON_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const COLLECTION_FILE = /^([^/]+)\.json$/;
 const ICON_NAME_SEPARATOR = ",";
+const COLLECTION_PACKAGES = join("node_modules", "@iconify-json");
 // An icon's data only changes with the installed collection, which a
 // deployment replaces; a week bounds how long an upgraded icon can lag.
 const ICON_CACHE_CONTROL =
   "public, max-age=604800, stale-while-revalidate=86400";
 const ERROR_CACHE_CONTROL = "no-store";
 const collections = new Map();
+// By renderer module: a development server evaluates a new one after a layer
+// changes, and each must find the collections loaded before it renders.
+const rendererCollections = new WeakMap();
 
 function collectionSpecifiers(prefix) {
   return [
@@ -60,6 +64,44 @@ function collection(root, prefix) {
   return collections.get(key);
 }
 
+/**
+ * Every `@iconify-json/<prefix>` collection installed in the workspace under
+ * `root`, the ones the server render draws from. The workspace hoists every
+ * dependency, a module's collections included.
+ */
+export async function installedCollections(root) {
+  const prefixes = await readdir(join(root, COLLECTION_PACKAGES)).catch(
+    () => [],
+  );
+  const loaded = await Promise.all(
+    prefixes
+      .filter((prefix) => ICON_NAME.test(prefix))
+      .map((prefix) => collection(root, prefix)),
+  );
+  return loaded.filter(Boolean);
+}
+
+/**
+ * Hand a server renderer the installed collections, once per renderer module,
+ * before its first render. A collection that fails to load leaves the render
+ * with the bundled icons only.
+ */
+export function provideIconCollections(renderer, root = WORKSPACE_ROOT) {
+  if (!rendererCollections.has(renderer))
+    rendererCollections.set(
+      renderer,
+      installedCollections(root)
+        .then((loaded) => renderer.registerDmsIconCollections(loaded))
+        .catch((error) =>
+          console.error(
+            "DMS icon collections not loaded; server renders draw bundled icons only",
+            error,
+          ),
+        ),
+    );
+  return rendererCollections.get(renderer);
+}
+
 function jsonResponse(status, cacheControl, payload) {
   return {
     status,

package/templates/vue/server.mjs

@@ -5,7 +5,11 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 import { ofetch } from "ofetch";
-import { RequestBodyError, UpstreamError } from "./server/auth/backend.mjs";
+import {
+  relayedHeaders,
+  RequestBodyError,
+  UpstreamError,
+} from "./server/auth/backend.mjs";
 import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./server/auth/client-ip.mjs";
 import {
   handleAuth,
@@ -36,7 +40,7 @@ import { documentStyleTags } from "./server/dev-styles.mjs";
 import { handleEmailRender, watchEmailBundle } from "./server/email.mjs";
 import { HOMEPAGE } from "./server/homepage.mjs";
 import { htmlTag } from "./server/html-tag.mjs";
-import { handleIcons, isIconRequest } from "./server/icons.mjs";
+import * as icons from "./server/icons.mjs";
 import * as requestFailure from "./server/request-failure.mjs";
 import { handleTester } from "./server/tester.mjs";
 import {
@@ -75,7 +79,7 @@ const HTML_RENDER_ROUTE = "/api/html/render";
 const TESTER_ROUTE = /^\/api\/_dms\/tester\/?$/;
 const LOCAL_ROUTES = [
   [(pathname) => TESTER_ROUTE.test(pathname), handleTester],
-  [isIconRequest, handleIcons],
+  [icons.isIconRequest, icons.handleIcons],
 ];
 const AUTH_PAGE = "/auth";
 const ONBOARDING_PAGE = "/onboarding";
@@ -117,18 +121,13 @@ async function developmentServer() {
 }
 
 function backendHeaders(request) {
-  const names = [
+  const headers = relayedHeaders(request, [
     "accept",
     "content-type",
     "user-agent",
     "x-content-language",
     "x-realtime-session",
-  ];
-  const headers = Object.fromEntries(
-    names.flatMap((name) =>
-      request.headers[name] ? [[name, request.headers[name]]] : [],
-    ),
-  );
+  ]);
   const session = readSession(request);
   if (session?.accessToken)
     headers.authorization = `Bearer ${session.accessToken}`;
@@ -297,9 +296,11 @@ function serveAsset(pathname, request, response) {
 }
 
 async function ssrRenderer(devServer) {
-  if (devServer) return devServer.ssrLoadModule("/ssr-renderer.ts");
-  productionSsrRenderer ??= import(BUILT_SSR_RENDERER_PATH);
-  return productionSsrRenderer;
+  const renderer = devServer
+    ? await devServer.ssrLoadModule("/ssr-renderer.ts")
+    : await (productionSsrRenderer ??= import(BUILT_SSR_RENDERER_PATH));
+  await icons.provideIconCollections(renderer);
+  return renderer;
 }
 
 export async function renderHtml(

package/templates/vue/ssr-renderer.ts

@@ -24,6 +24,13 @@ import {
   trackDmsServerScopes,
 } from "./frontend-module";
 import { frontendModules } from "./frontend-modules.generated";
+import {
+  SSR_ICONS_ID,
+  serializeDmsIcons,
+  trackDmsIcons,
+} from "./icon-hydration";
+
+export { registerDmsIconCollections } from "./icon-hydration";
 
 export interface DmsSsrPage {
   component: string;
@@ -75,6 +82,14 @@ function asyncComponentsScript(names: Set<string>): string {
   return `<script id="${SSR_ASYNC_COMPONENTS_ID}" type="application/json">${value}</script>`;
 }
 
+function iconsScript(names: Set<string>): string {
+  const value = JSON.stringify(serializeDmsIcons(names)).replaceAll(
+    "<",
+    "\\u003c",
+  );
+  return `<script id="${SSR_ICONS_ID}" type="application/json">${value}</script>`;
+}
+
 await setupFrontendModules(frontendModules);
 
 export function isDmsFrontendPage(path: string): boolean {
@@ -117,6 +132,7 @@ async function renderDmsPageWithRuntime(
     const head = createHead();
     const ssrContext: DmsSsrContext = {};
     let asyncComponents = new Set<string>();
+    let icons = new Set<string>();
     const inertiaResult = await createInertiaApp({
       page,
       render: (app) => renderToString(app, ssrContext),
@@ -124,6 +140,7 @@ async function renderDmsPageWithRuntime(
       async setup({ App, props, plugin }) {
         const app = createSSRApp({ render: () => h(App, props) });
         asyncComponents = trackDmsAsyncComponents(app);
+        icons = trackDmsIcons(app);
         stopScopes = trackDmsServerScopes(app);
         const configured = await configureDmsApp({
           app,
@@ -173,7 +190,7 @@ async function renderDmsPageWithRuntime(
     const renderedHead = await renderSSRHead(head);
     return {
       error: page.props.error,
-      body: `${inertiaResult.body}${asyncDataScript(runtime)}${asyncComponentsScript(asyncComponents)}`,
+      body: `${inertiaResult.body}${asyncDataScript(runtime)}${asyncComponentsScript(asyncComponents)}${iconsScript(icons)}`,
       head: {
         bodyAttrs: renderedHead.bodyAttrs,
         headTags: `${inertiaResult.head.join("")}${renderedHead.headTags}`,

package/templates/vue/vite.config.ts

@@ -2,7 +2,15 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import ui from "@nuxt/ui/vite";
 import vue from "@vitejs/plugin-vue";
-import { defineConfig, type LogLevel, normalizePath, type Plugin } from "vite";
+import {
+  createLogger,
+  defineConfig,
+  type LogLevel,
+  normalizePath,
+  type Plugin,
+} from "vite";
+import { autoImportDirectories } from "./frontend-build-loader";
+import { frontendBuilds } from "./frontend-builds.generated";
 import { orderHeadForFirstPaint } from "./head-order.mjs";
 import { iconScanGlobs } from "./icon-scan.mjs";
 
@@ -40,21 +48,19 @@ const stableModuleAliases = Object.fromEntries(
   }),
 );
 /**
- * Globs are POSIX, always.
- *
- * `resolve` returns a native path, so on Windows every pattern below would
- * carry backslashes — which a glob matcher reads as escape characters, not as
- * separators, and which therefore match nothing at all. `normalizePath` is
- * Vite's own answer to this and is the identity function on POSIX.
+ * `ajs dms build` runs Vite at "warn" and reports the steps itself; a verbose
+ * run, `dev` and a hand-run build keep Vite's own output.
+ */
+const logLevel = (process.env.DMS_VITE_LOG_LEVEL ?? "info") as LogLevel;
+const logger = createLogger(logLevel);
+/**
+ * Only what each module declares in its `dms.frontend.build.ts`: a module
+ * without one has nothing auto-imported.
  */
-const importDirectories = frontendSourceRoots.flatMap((root) =>
-  [
-    "app/composables/**/*",
-    "app/types/**/*",
-    "app/utils/**/*",
-    "app/build/composables/**/*",
-    "app/build/types/**/*",
-  ].map((glob) => ({ glob: normalizePath(resolve(root, glob)), types: true })),
+const importDirectories = autoImportDirectories(
+  registry.modules,
+  frontendBuilds,
+  (message) => logger.warn(message),
 );
 const optimizedDependencies = [
   "vue",
@@ -90,8 +96,9 @@ const optimizedDependencies = [
  * startup, pays that cost a single time and in a place where it reads as
  * startup rather than as a crash.
  *
- * Normalized for the same reason as `importDirectories`: Vite hands these
- * patterns straight to its glob matcher without touching the separators.
+ * Globs are POSIX, always: `resolve` returns a native path, whose Windows
+ * backslashes a glob matcher reads as escape characters, not as separators.
+ * `normalizePath` is Vite's own answer to this, the identity on POSIX.
  */
 const optimizerEntries = [
   resolve(__dirname, "main.ts"),
@@ -117,12 +124,6 @@ const uiInertiaLinkImport = resolve(
   "node_modules/@nuxt/ui/dist/runtime/vue/overrides/inertia/Link.vue",
 );
 
-/**
- * `ajs dms build` runs Vite at "warn" and reports the steps itself; a verbose
- * run, `dev` and a hand-run build keep Vite's own output.
- */
-const logLevel = (process.env.DMS_VITE_LOG_LEVEL ?? "info") as LogLevel;
-
 export default defineConfig({
   logLevel,
   plugins: [
@@ -175,6 +176,7 @@ export default defineConfig({
               "useI18n",
               "useError",
               "useDmsLazyAsyncData",
+              "useDmsPageLoading",
               "useDmsApp",
               "useDmsRoute",
               "useDmsRouter",