@antelopejs/dms-frontend 0.2.1 → 0.2.3

package/README.md

@@ -94,9 +94,11 @@ URL, either through `-b` or through the enclosing antelope project's
 `.antelope/dev.json`, and say so on exit 1 when they have neither;
 `verify-source` needs `--layer` instead.
 
-The CLI checks npm for a newer release at most once a day — a failed lookup
-counts as the day's attempt — and prints a one-line notice on stderr. The
-throttle stamp lives at `~/.antelopejs/dms-frontend/update-check.json`. Set
+The CLI checks npm for a newer release at most once a day and prints a one-line
+notice on stderr. A lookup that comes back empty — offline, throttled, or simply
+raced by a command that blocked the event loop past the deadline — is retried
+after an hour instead of counting as the day's attempt. The throttle stamp lives
+at `~/.antelopejs/dms-frontend/update-check.json`. Set
 `NO_UPDATE_NOTIFIER=1`, pass `--no-update-check`, or run under `CI` to turn the
 check off.
 

package/dist/config.js

@@ -39,6 +39,7 @@ exports.TEMPLATE_FILES = [
     ["frontend-module.ts", "frontend-module.ts"],
     ["globals.d.ts", "globals.d.ts"],
     ["compress-assets.mjs", "compress-assets.mjs"],
+    ["head-order.mjs", "head-order.mjs"],
     ["email-renderer.ts", "email-renderer.ts"],
     ["email-runtime.ts", "email-runtime.ts"],
     ["email-locales.ts", "email-locales.ts"],

package/dist/fs-sync.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripExtendedLengthPrefix = stripExtendedLengthPrefix;
+exports.toPosixPath = toPosixPath;
 exports.isBlocklistedCopyPath = isBlocklistedCopyPath;
 exports.sanitizedPackageContent = sanitizedPackageContent;
 exports.filesIdentical = filesIdentical;
@@ -18,11 +19,14 @@ const config_1 = require("./config");
 function stripExtendedLengthPrefix(p) {
     return p.replace(/^\\\\\?\\/, "");
 }
+function toPosixPath(path, separator = node_path_1.sep) {
+    return separator === "/" ? path : path.split(separator).join("/");
+}
 function isBlocklistedCopyPath(src, srcPath) {
     const rel = (0, node_path_1.relative)((0, node_path_1.resolve)(stripExtendedLengthPrefix(src)), (0, node_path_1.resolve)(stripExtendedLengthPrefix(srcPath)));
     if (!rel || rel.startsWith(".."))
         return false;
-    return config_1.layerCopyIgnore.ignores(rel.split(node_path_1.sep).join("/"));
+    return config_1.layerCopyIgnore.ignores(toPosixPath(rel));
 }
 function sanitizedPackageContent(raw) {
     const pkg = JSON.parse(raw);

package/dist/materialize.js

@@ -198,7 +198,7 @@ function discoverAssets(registry, directory, extensions) {
                 .sort()
                 .map((relativePath) => ({
                 moduleId: module.id,
-                relativePath: `${assetRoot.relativePrefix}${(0, node_path_1.join)(directory, relativePath).split(node_path_1.sep).join("/")}`,
+                relativePath: `${assetRoot.relativePrefix}${(0, fs_sync_1.toPosixPath)((0, node_path_1.join)(directory, relativePath))}`,
             }));
         });
     });
@@ -259,7 +259,7 @@ function writeShortcutExports(workspaceDir, registry) {
 }
 function writeDmsMainCss(workspaceDir, layers) {
     const sources = layers
-        .map((layer) => `@source "${(0, layers_1.getLayerWorkspacePath)(workspaceDir, layer)}/${config_1.TAILWIND_SOURCE_GLOB}";`)
+        .map((layer) => `@source "${(0, fs_sync_1.toPosixPath)((0, layers_1.getLayerWorkspacePath)(workspaceDir, layer))}/${config_1.TAILWIND_SOURCE_GLOB}";`)
         .join("\n");
     const content = `@import "tailwindcss";
 @import "@nuxt/ui";

package/dist/update-check.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.NO_UPDATE_CHECK_FLAG = exports.UPDATE_CHECK_TIMEOUT_MS = exports.UPDATE_CHECK_INTERVAL_MS = exports.UPDATE_CHECK_PACKAGE = void 0;
+exports.NO_UPDATE_CHECK_FLAG = exports.UPDATE_CHECK_TIMEOUT_MS = exports.UPDATE_CHECK_RETRY_INTERVAL_MS = exports.UPDATE_CHECK_INTERVAL_MS = exports.UPDATE_CHECK_PACKAGE = void 0;
 exports.stripUpdateCheckFlag = stripUpdateCheckFlag;
 exports.isUpdateCheckEnabled = isUpdateCheckEnabled;
 exports.updateCheckCacheFile = updateCheckCacheFile;
@@ -18,6 +18,7 @@ const config_1 = require("./config");
 exports.UPDATE_CHECK_PACKAGE = "@antelopejs/dms-frontend";
 const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/";
 exports.UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+exports.UPDATE_CHECK_RETRY_INTERVAL_MS = 60 * 60 * 1000;
 exports.UPDATE_CHECK_TIMEOUT_MS = 3000;
 exports.NO_UPDATE_CHECK_FLAG = "--no-update-check";
 const HELP_OR_VERSION_FLAGS = ["--help", "-h", "--version", "-v"];
@@ -73,7 +74,11 @@ function readCache(file) {
         if (latestVersion !== undefined && typeof latestVersion !== "string") {
             return undefined;
         }
-        return { checkedAt: parsed.checkedAt, latestVersion };
+        const succeeded = parsed.succeeded;
+        if (succeeded !== undefined && typeof succeeded !== "boolean") {
+            return undefined;
+        }
+        return { checkedAt: parsed.checkedAt, latestVersion, succeeded };
     }
     catch {
         return undefined;
@@ -156,13 +161,20 @@ async function checkForUpdate(options) {
             return;
         const cached = readCache(cacheFile);
         const checkedAt = now();
-        const withinInterval = cached !== undefined &&
-            checkedAt - cached.checkedAt < exports.UPDATE_CHECK_INTERVAL_MS;
+        const lastAttemptAnswered = cached?.succeeded ?? cached?.latestVersion !== undefined;
+        const interval = lastAttemptAnswered
+            ? exports.UPDATE_CHECK_INTERVAL_MS
+            : exports.UPDATE_CHECK_RETRY_INTERVAL_MS;
+        const withinInterval = cached !== undefined && checkedAt - cached.checkedAt < interval;
         let latestVersion = cached?.latestVersion;
         if (!withinInterval) {
-            latestVersion =
-                (await fetchLatestVersion(exports.UPDATE_CHECK_PACKAGE)) ?? latestVersion;
-            writeCache(cacheFile, { checkedAt, latestVersion });
+            const published = await fetchLatestVersion(exports.UPDATE_CHECK_PACKAGE);
+            latestVersion = published ?? latestVersion;
+            writeCache(cacheFile, {
+                checkedAt,
+                latestVersion,
+                succeeded: published !== undefined,
+            });
         }
         if (latestVersion && isNewer(currentVersion, latestVersion)) {
             write(formatNotice(currentVersion, latestVersion));

package/package.json

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

package/templates/vue/head-order.mjs

@@ -0,0 +1,39 @@
+// Restoring "paint before hydrate" in the built document.
+//
+// The source index.html marks the entry script `fetchpriority="low"` so the
+// browser spends its bandwidth on the render-blocking stylesheet first. Vite
+// rewrites that script tag when it builds and drops the attribute, and it emits
+// the script *before* the stylesheet — so the production document did the
+// opposite of what the template asked: it discovered a 250 kB hydration bundle
+// first and let it compete with the 27 kB the first paint actually waits on,
+// over the plain HTTP/1.1 the generated server speaks.
+//
+// Kept beside vite.config.ts rather than inside it so the transform can be
+// exercised on its own, the way client-manifest.mjs is.
+
+const SCRIPT = /<script[^>]*\stype="module"[^>]*><\/script>/;
+const STYLESHEET = /[ \t]*<link rel="stylesheet"[^>]*>\n?/;
+
+function deprioritize(html) {
+  return html.replace(SCRIPT, (tag) =>
+    tag.includes("fetchpriority")
+      ? tag
+      : tag.replace("<script ", '<script fetchpriority="low" '),
+  );
+}
+
+/**
+ * Give the entry script back its low fetch priority and move the stylesheet
+ * ahead of it. A document that already has them in that order is returned
+ * unchanged, so the transform is safe to run twice.
+ */
+export function orderHeadForFirstPaint(html) {
+  const prioritized = deprioritize(html);
+  const stylesheet = prioritized.match(STYLESHEET);
+  const script = prioritized.match(SCRIPT);
+  if (!stylesheet || !script || stylesheet.index < script.index)
+    return prioritized;
+  return prioritized
+    .replace(STYLESHEET, "")
+    .replace(SCRIPT, (tag) => `${stylesheet[0].trim()}\n    ${tag}`);
+}

package/templates/vue/main.ts

@@ -6,10 +6,47 @@ import { configureDmsApp, resolveDmsInertiaPage } from "./app-runtime";
 import { setupFrontendModules } from "./frontend-module";
 import { frontendModules } from "./frontend-modules.generated";
 
+const DEV_STYLE_ATTRIBUTE = "data-dms-dev-style";
+
+/**
+ * Hand each development stylesheet over to Vite.
+ *
+ * The development server puts the page's stylesheets in the document so it
+ * never paints unstyled (see `server/dev-styles.mjs`). Vite then injects its
+ * own copy of each one as a `<style data-vite-dev-id>`, and keeping both would
+ * make a later CSS edit look like it removed nothing: Vite rewrites its copy,
+ * ours keeps the deleted rules alive.
+ *
+ * We drop ours the moment Vite's appears, keyed by module id, rather than at a
+ * fixed point in the boot. A component reached through a dynamic import — most
+ * of them — has not been loaded when the app mounts, so removing its scoped
+ * rules then would flash exactly what this whole change exists to prevent.
+ */
+function adoptViteDevStyles(): void {
+  const pending = new Map<string, Element>();
+  for (const node of document.querySelectorAll(`[${DEV_STYLE_ATTRIBUTE}]`)) {
+    pending.set(node.getAttribute(DEV_STYLE_ATTRIBUTE) ?? "", node);
+  }
+  if (pending.size === 0) return;
+  const adopt = (): void => {
+    for (const style of document.querySelectorAll("style[data-vite-dev-id]")) {
+      const id = style.getAttribute("data-vite-dev-id") ?? "";
+      pending.get(id)?.remove();
+      pending.delete(id);
+    }
+    if (pending.size === 0) observer.disconnect();
+  };
+  const observer = new MutationObserver(adopt);
+  observer.observe(document.head, { childList: true });
+  adopt();
+}
+
 function markDmsReady(): void {
   document.documentElement.dataset.dmsReady = "true";
 }
 
+if (import.meta.env.DEV) adoptViteDevStyles();
+
 await setupFrontendModules(frontendModules);
 
 createInertiaApp({

package/templates/vue/server/dev-styles.mjs

@@ -0,0 +1,106 @@
+// Putting the page's stylesheets in the document the development server
+// returns, instead of letting the client entry inject them from JavaScript
+// once it has executed.
+//
+// Vite serves every stylesheet as a JavaScript module in development, so a
+// plain SSR document carries no styles at all and the browser paints raw HTML
+// until `/main.ts` and its module graph have run. Production has no such gap:
+// the built `index.html` already links the entry stylesheet, which is why this
+// module is development-only and lives beside client-manifest.mjs rather than
+// inside server.mjs, whose size the linter caps.
+//
+// Each tag carries the module id Vite will use for its own copy
+// (`data-vite-dev-id`), under our own attribute name. `main.ts` hands the
+// stylesheet over as soon as Vite injects that copy — see `adoptViteDevStyles`.
+// We deliberately do NOT reuse `data-vite-dev-id` itself: Vite's client adopts
+// any pre-existing link with that attribute and then skips `updateStyle` for
+// it, which would leave CSS edits stranded.
+
+import { join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pageModulePreloads } from "./client-manifest.mjs";
+
+const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const STYLE_ATTRIBUTE = "data-dms-dev-style";
+const SFC_STYLE = /[?&]vue&type=style/;
+const STYLE_EXTENSION =
+  /\.(?:css|less|pcss|postcss|sass|scss|styl|stylus)(?:$|\?)/;
+
+/**
+ * The workspace's generated entry stylesheet. `main.ts` is its only importer,
+ * so it never enters the SSR module graph, yet it carries Tailwind, Nuxt UI and
+ * one `@source` per materialized module — nearly every rule a page needs.
+ * Naming it is the one enumeration this module accepts, and the comment is the
+ * reason why.
+ *
+ * `ENTRY_STYLESHEET_ID` is matched against the `data-vite-dev-id` Vite puts on
+ * its own copy, and Vite normalizes every module id onto POSIX separators — so
+ * the native path `join` returns has to be normalized too, or the handover
+ * never happens on Windows and both copies stay in the document.
+ */
+const ENTRY_STYLESHEET = "/dms-main.css";
+const ENTRY_STYLESHEET_ID = join(PROJECT_ROOT, "dms-main.css")
+  .split(sep)
+  .join("/");
+
+function ssrModuleGraph(devServer) {
+  return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
+}
+
+function directUrl(url) {
+  return `${url}${url.includes("?") ? "&" : "?"}direct`;
+}
+
+function styleModules(devServer) {
+  const graph = ssrModuleGraph(devServer);
+  if (!graph) return [];
+  return [...graph.urlToModuleMap.entries()]
+    .filter(([url]) => SFC_STYLE.test(url) || STYLE_EXTENSION.test(url))
+    .map(([url, module]) => ({ url, id: module?.id ?? url }));
+}
+
+function linkTag({ url, id }) {
+  return `<link rel="stylesheet" ${STYLE_ATTRIBUTE}="${id}" href="${directUrl(url)}">`;
+}
+
+/**
+ * A single-file component's `<style>` block is served with a JavaScript content
+ * type even when requested directly, so a browser would refuse it as a
+ * stylesheet. They are small; inline them instead. A block that could close its
+ * own tag is dropped rather than escaped — CSS has no escape that is valid in
+ * every position, and a scoped component rule is not worth the risk.
+ */
+async function inlineTag(devServer, { url, id }) {
+  const result = await devServer
+    .transformRequest(directUrl(url))
+    .catch(() => undefined);
+  const css = result?.code;
+  if (!css || /<\/style/i.test(css)) return "";
+  return `<style ${STYLE_ATTRIBUTE}="${id}">${css}</style>`;
+}
+
+/** Style tags for everything the development render touched, entry sheet first. */
+export async function developmentStyleTags(devServer) {
+  const modules = styleModules(devServer);
+  const links = [
+    { url: ENTRY_STYLESHEET, id: ENTRY_STYLESHEET_ID },
+    ...modules.filter(({ url }) => !SFC_STYLE.test(url)),
+  ].map(linkTag);
+  const inlined = await Promise.all(
+    modules
+      .filter(({ url }) => SFC_STYLE.test(url))
+      .map((module) => inlineTag(devServer, module)),
+  );
+  return [...links, ...inlined].join("");
+}
+
+/**
+ * The style tags a document needs, whichever server is answering it: collected
+ * from the live module graph in development, read from the build manifest in
+ * production.
+ */
+export async function documentStyleTags(devServer, page, template) {
+  return devServer
+    ? developmentStyleTags(devServer)
+    : pageModulePreloads(page, template);
+}

package/templates/vue/server/homepage.mjs

@@ -0,0 +1,32 @@
+// Working out which page a visit to `/` means.
+//
+// The answer lives in the module registry the workspace was materialized with:
+// a module declares `homepage` somewhere in its options, at whatever depth its
+// own configuration shape puts it, and the highest-priority declaration wins —
+// the registry is already sorted. Read once at boot, because the registry is a
+// build artifact and cannot change while the server is up.
+//
+// Split out of server.mjs, whose size the linter caps.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const REGISTRY_PATH = join(PROJECT_ROOT, "generated-frontend-modules.json");
+const REGISTRY = existsSync(REGISTRY_PATH)
+  ? JSON.parse(readFileSync(REGISTRY_PATH, "utf8"))
+  : { modules: [] };
+
+function findHomepage(options) {
+  if (!options || typeof options !== "object") return undefined;
+  if (typeof options.homepage === "string") return options.homepage;
+  return Object.values(options)
+    .map(findHomepage)
+    .find((homepage) => homepage !== undefined);
+}
+
+export const HOMEPAGE =
+  REGISTRY.modules
+    .map((module) => findHomepage(module.options))
+    .find(Boolean) ?? "/";

package/templates/vue/server/inertia.mjs

@@ -7,6 +7,17 @@ const CLIENT_MANIFEST_PATH = fileURLToPath(
 );
 let productionAssetVersion;
 
+/**
+ * Every document and Inertia payload this server writes carries the visitor's
+ * own session: the user, the session, and the page tree their permissions
+ * allow. `private` is what keeps a shared cache from ever holding it;
+ * `no-cache` keeps the browser's own copy from being reused without asking us
+ * first, so a revoked session cannot resurface from disk. We stop short of
+ * `no-store`, which would additionally forfeit the back-forward cache on every
+ * page of a dashboard people navigate constantly.
+ */
+export const PRIVATE_CACHE_CONTROL = "private, no-cache";
+
 export function assetVersion() {
   if (process.env.DMS_DEV === "true" || !existsSync(CLIENT_MANIFEST_PATH))
     return "development";
@@ -32,6 +43,7 @@ export function createInertiaPage(url, props, version = assetVersion()) {
 
 export function inertiaHeaders(version = assetVersion()) {
   return {
+    "cache-control": PRIVATE_CACHE_CONTROL,
     "content-type": "application/json",
     "x-inertia": "true",
     vary: "X-Inertia",
@@ -39,6 +51,15 @@ export function inertiaHeaders(version = assetVersion()) {
   };
 }
 
+/** Headers for a rendered document: same cache stance as an Inertia payload. */
+export function htmlHeaders() {
+  return {
+    "cache-control": PRIVATE_CACHE_CONTROL,
+    "content-type": "text/html",
+    vary: "X-Inertia",
+  };
+}
+
 export function handleAssetVersionMismatch(request, response) {
   if (
     !request.headers["x-inertia"] ||

package/templates/vue/server.mjs

@@ -1,6 +1,6 @@
 import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
 import { createServer } from "node:http";
-import { extname, join, resolve } from "node:path";
+import { extname, join, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
@@ -18,14 +18,14 @@ import {
   refreshSession,
 } from "./server/auth/routes.mjs";
 import { readSession } from "./server/auth/session.mjs";
-import {
-  pageModulePreloads,
-  productionHtmlTemplate,
-} from "./server/client-manifest.mjs";
+import { productionHtmlTemplate } from "./server/client-manifest.mjs";
+import { documentStyleTags } from "./server/dev-styles.mjs";
 import { handleEmailRender } from "./server/email.mjs";
+import { HOMEPAGE } from "./server/homepage.mjs";
 import { handleTester } from "./server/tester.mjs";
 import {
   createInertiaPage,
+  htmlHeaders,
   inertiaAppHtml,
   inertiaHeaders,
   redirectFrontendVisit,
@@ -36,13 +36,6 @@ export * from "./server/inertia.mjs";
 const INERTIA_HEADER = "x-inertia";
 const JSON_TYPE = "application/json";
 const PROJECT_ROOT = fileURLToPath(new URL(".", import.meta.url));
-const MODULE_REGISTRY_PATH = join(
-  PROJECT_ROOT,
-  "generated-frontend-modules.json",
-);
-const MODULE_REGISTRY = existsSync(MODULE_REGISTRY_PATH)
-  ? JSON.parse(readFileSync(MODULE_REGISTRY_PATH, "utf8"))
-  : { modules: [] };
 const MIME_TYPES = {
   ".css": "text/css",
   ".js": "text/javascript",
@@ -74,19 +67,6 @@ let vite;
 let vitePromise;
 let frontendHttpServer;
 
-function findHomepage(options) {
-  if (!options || typeof options !== "object") return undefined;
-  if (typeof options.homepage === "string") return options.homepage;
-  return Object.values(options)
-    .map(findHomepage)
-    .find((homepage) => homepage !== undefined);
-}
-
-const HOMEPAGE =
-  MODULE_REGISTRY.modules
-    .map((module) => findHomepage(module.options))
-    .find(Boolean) ?? "/";
-
 class BackendResponseError extends Error {
   constructor(status) {
     super(`DMS backend returned ${status}`);
@@ -274,7 +254,9 @@ function acceptedAsset(pathname, request) {
 
 function serveAsset(pathname, request, response) {
   const selected = acceptedAsset(pathname, request);
-  const assetRoot = `${resolve(PROJECT_ROOT, "dist/client")}/`;
+  // Native separator: `selected.source` comes from `resolve`, so a hardcoded
+  // `/` here would make the containment check fail for every asset on Windows.
+  const assetRoot = `${resolve(PROJECT_ROOT, "dist/client")}${sep}`;
   if (
     !selected.source.startsWith(assetRoot) ||
     !existsSync(selected.file) ||
@@ -358,7 +340,7 @@ export async function renderHtml(page, requestUrl, serverFetch) {
   }
   if (rendered.redirect)
     return { html: "", status: 200, redirect: rendered.redirect };
-  const preloads = devServer ? "" : pageModulePreloads(page, template);
+  const preloads = await documentStyleTags(devServer, page, template);
   const html = template
     .replace("<title>Antelope DMS</title>", rendered.head.headTags)
     .replace("<html", `<html ${rendered.head.htmlAttrs}`)
@@ -410,13 +392,7 @@ async function writeBackendError(error, request, response) {
       request.url,
       serverComponentFetch(request),
     );
-    return writeContent(
-      request,
-      response,
-      status,
-      { "content-type": "text/html", vary: "X-Inertia" },
-      html,
-    );
+    return writeContent(request, response, status, htmlHeaders(), html);
   }
   const payload =
     error instanceof UpstreamError || error instanceof RequestBodyError
@@ -481,7 +457,7 @@ export async function handleRequest(request, response) {
     request,
     response,
     rendered.status,
-    { "content-type": "text/html", vary: "X-Inertia" },
+    htmlHeaders(),
     rendered.html,
   );
 }

package/templates/vue/vite.config.ts

@@ -2,7 +2,8 @@ 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 } from "vite";
+import { defineConfig, normalizePath, type Plugin } from "vite";
+import { orderHeadForFirstPaint } from "./head-order.mjs";
 
 interface FrontendModuleRegistryEntry {
   id: string;
@@ -37,6 +38,14 @@ const stableModuleAliases = Object.fromEntries(
     return [[`#${moduleName}`, module.root]];
   }),
 );
+/**
+ * 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.
+ */
 const importDirectories = frontendSourceRoots.flatMap((root) =>
   [
     "app/composables/**/*",
@@ -44,7 +53,7 @@ const importDirectories = frontendSourceRoots.flatMap((root) =>
     "app/utils/**/*",
     "app/build/composables/**/*",
     "app/build/types/**/*",
-  ].map((glob) => ({ glob: resolve(root, glob), types: true })),
+  ].map((glob) => ({ glob: normalizePath(resolve(root, glob)), types: true })),
 );
 const optimizedDependencies = [
   "vue",
@@ -66,6 +75,41 @@ const optimizedDependencies = [
   "json-schema-to-zod",
   "striptags",
 ];
+
+/**
+ * Entry points the dependency optimizer crawls at startup.
+ *
+ * Every materialized module brings its own dependency set — subpath exports and
+ * transitive CommonJS included — and none of it can be listed in
+ * `optimizedDependencies` by hand, because the modules are only known at
+ * materialization time. Leaving the crawl off and letting Vite discover them as
+ * pages load meant the first visit to a cold page re-ran the optimizer
+ * mid-request: the chunks already in flight answered 504 and the client was
+ * told to reload the whole document. Crawling the module sources once, at
+ * 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.
+ */
+const optimizerEntries = [
+  resolve(__dirname, "main.ts"),
+  ...moduleRoots.map((root) => resolve(root, "dms.frontend.ts")),
+  ...frontendSourceRoots.flatMap((root) => [
+    resolve(root, "app/**/*.vue"),
+    resolve(root, "app/**/*.ts"),
+  ]),
+].map(normalizePath);
+
+function paintBeforeHydrate(): Plugin {
+  return {
+    name: "dms-paint-before-hydrate",
+    apply: "build",
+    enforce: "post",
+    transformIndexHtml: { order: "post", handler: orderHeadForFirstPaint },
+  };
+}
+
 const uiLinkImport = "@nuxt/ui/components/Link.vue";
 const uiInertiaLinkImport = resolve(
   __dirname,
@@ -92,7 +136,13 @@ export default defineConfig({
         imports: [
           "vue",
           {
-            [resolve(__dirname, "frontend-module.ts")]: [
+            // This key is inlined verbatim as the module specifier of the
+            // import the auto-importer prepends to each file. A native Windows
+            // path would land inside a single-quoted JavaScript string with its
+            // backslashes intact, where `\U`, `\M` and `\f` are read as escape
+            // sequences: the specifier the bundler then resolves is a mangled
+            // path that cannot exist. Keep it POSIX.
+            [normalizePath(resolve(__dirname, "frontend-module.ts"))]: [
               "$fetch",
               "abortNavigation",
               "clearError",
@@ -131,6 +181,7 @@ export default defineConfig({
         vueTemplate: true,
       },
     }),
+    paintBeforeHydrate(),
   ],
   resolve: {
     dedupe: ["vue", "reka-ui", "@nuxt/ui"],
@@ -152,8 +203,7 @@ export default defineConfig({
   },
   optimizeDeps: {
     include: optimizedDependencies,
-    // Avoid crawling every module page at startup, but optimize dependencies as pages load.
-    entries: [],
+    entries: optimizerEntries,
   },
   ssr: { noExternal: ["@nuxt/icon", "@nuxt/ui"] },
   server: { strictPort: true, allowedHosts: [".onamp.dev"] },

package/templates/vue/vite.email.config.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import vue from "@vitejs/plugin-vue";
 import AutoImport from "unplugin-auto-import/vite";
-import { defineConfig } from "vite";
+import { defineConfig, normalizePath } from "vite";
 
 interface FrontendModuleRegistryEntry {
   id: string;
@@ -55,7 +55,10 @@ export default defineConfig({
       dts: false,
       imports: [
         {
-          [resolve(__dirname, "email-runtime.ts")]: [
+          // Inlined verbatim as a module specifier in the generated import, so
+          // it has to be POSIX: a native Windows path would reach the parser
+          // with its backslashes read as string escapes. See vite.config.ts.
+          [normalizePath(resolve(__dirname, "email-runtime.ts"))]: [
             "useDmsAppConfig",
             "useDmsRuntimeConfig",
             "defineAppConfig",