@antelopejs/dms-frontend 0.3.12 → 0.4.0

package/README.md

@@ -188,6 +188,61 @@ 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.
 
+### Private components
+
+A component registers as public by default: it joins the application's global components and resolves by name anywhere. A component that only exists to render the module's own backend pages registers as private instead:
+
+```ts
+sdk.registerComponent("BillingTotals", BillingTotals, { private: true });
+```
+
+A private component is not registered with `app.component`, so no template or other module reaches it by name. `resolveDmsComponent(name, owner)` returns it only when `owner` is the registering module, and then ahead of a public component of the same name; without an owner, only public components resolve. The generic page renderer passes the page's owner, so a backend page tree naming the component renders it, and the page preloader and the server render's hydration handover cover it too.
+
+The owner is the page payload's `module` field: the name of the frontend module that owns the page's component tree, as the backend added it (the module's `name` in the frontend manifest, which the generated loader hands each module's setup). A backend that does not send `module` reaches no private component, whatever the tree names.
+
+### 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 +467,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 +492,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 +513,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.4.0",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/DmsDynamicPage.vue

@@ -37,6 +37,7 @@ interface PageRoute {
 interface PagePayload {
   layout?: PageLayout;
   route?: PageRoute;
+  module?: string;
 }
 
 interface DynamicPageProps {
@@ -55,7 +56,8 @@ function resolveDefinition(
   return {
     id,
     component: definition.componentName
-      ? resolveDmsComponent(definition.componentName) || "div"
+      ? resolveDmsComponent(definition.componentName, props.page.module) ||
+        "div"
       : "div",
     componentName: definition.componentName,
     options: definition.options,

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