@antelopejs/dms-frontend 0.9.1 → 0.9.3

package/templates/vue/message-subset.ts

@@ -0,0 +1,65 @@
+/** The `<script>` the server render leaves in the document for {@link DmsMessageSubset}. */
+export const SSR_MESSAGES_ID = "dms-ssr-messages";
+
+type Messages = Record<string, unknown>;
+
+/**
+ * The messages a server render read from a locale's catalog, as a catalog of
+ * their own, with the locale they belong to.
+ */
+export interface DmsMessageSubset {
+  locale: string;
+  messages: Messages;
+}
+
+export interface MessageReadRecorder {
+  /** The catalog to give the render: every read through it is recorded. */
+  messages: Messages;
+  /** What the render read so far. */
+  subset: () => Messages;
+}
+
+function isTraversable(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+function isMessages(value: unknown): value is Messages {
+  return isTraversable(value);
+}
+
+type Slot = () => Messages;
+
+/**
+ * Wraps a catalog so that the messages read through it are collected, with
+ * the path they sit at, into a catalog of their own.
+ *
+ * A message is recorded when a string is read from the catalog, whether by a
+ * lookup (`t`), an existence check (`te`) or a walk over a subtree (`tm`).
+ */
+export function recordMessageReads(messages: Messages): MessageReadRecorder {
+  const used: Messages = {};
+  const place = (source: object, parent: Slot, key: string): Slot => {
+    return () => {
+      const holder = parent();
+      const existing = holder[key];
+      if (isMessages(existing)) return existing;
+      const container: Messages = Array.isArray(source) ? [] : {};
+      holder[key] = container;
+      return container;
+    };
+  };
+  const wrap = <T extends object>(source: T, slot: Slot): T =>
+    new Proxy(source, {
+      get(target, key, receiver) {
+        const value: unknown = Reflect.get(target, key, receiver);
+        if (typeof key !== "string" || key === "__proto__") return value;
+        if (typeof value === "string") {
+          slot()[key] = value;
+          return value;
+        }
+        if (isTraversable(value)) return wrap(value, place(value, slot, key));
+        return value;
+      },
+    });
+  return { messages: wrap(messages, () => used), subset: () => used };
+}

package/templates/vue/network-error.ts

@@ -15,6 +15,10 @@ export interface DmsNetworkErrorTranslator {
 
 const NETWORK_ERROR_TOAST_ID = "dms-network-error";
 const NETWORK_ERROR_KEY = "error.network";
+/** The messages a module overrides the built-in texts with. */
+export const NETWORK_ERROR_KEYS = ["title", "description"].map(
+  (name) => `${NETWORK_ERROR_KEY}.${name}`,
+);
 const DEFAULT_LOCALE = "en";
 // Shipped with the renderer, since no module is guaranteed to translate the
 // case; a module overrides them with `error.network.title` and

package/templates/vue/prepare-types.mjs

@@ -1,10 +1,3 @@
-// Writes the files Vite generates and the type check reads (auto-imports.d.ts
-// and the Nuxt UI templates) without building anything: it resolves
-// vite.config.ts and runs its build hooks over an empty entry, in seconds
-// where a client build takes a minute. `ajs dms verify-source` runs it first
-// (`pnpm run build:types`), so the type check no longer waits for the client
-// bundle.
-
 import { build } from "vite";
 
 const ENTRY = "dms-prepare-types-entry";
@@ -23,7 +16,6 @@ await build({
   build: {
     write: false,
     emptyOutDir: false,
-    // The entry is empty on purpose; Rolldown does not warn about it.
     rolldownOptions: { input: ENTRY },
   },
 });

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

@@ -21,8 +21,10 @@ export class UpstreamError extends Error {
 }
 
 const PUBLIC_AUTH_MESSAGE = /^error\.[a-z0-9_.-]{1,100}$/;
-// The API error contract's generic key: the technical cause of a failure the
-// backend did not describe stays in the server log.
+/**
+ * The API error contract's generic key: the technical cause of a failure the
+ * backend did not describe stays in the server log.
+ */
 export const GENERIC_ERROR_MESSAGE = "error.500.description";
 
 export function publicBackendMessage(data) {

package/templates/vue/server/auth/establish-endpoints.mjs

@@ -1,17 +1,17 @@
-// The backend endpoints a module may open a session from: what the backend's
-// modules declared in the frontend manifest, and what the environment adds
-// (`DMS_AUTH_ESTABLISH_ENDPOINTS`). The module that owns sign-in reads them as
-// `event.app.authEstablishEndpoints`.
-
 import { readFileSync } from "node:fs";
 
-// Absolute backend API paths only: no scheme, no authority, no query string,
-// and no segment that could climb out of `/api/`.
+/**
+ * Absolute backend API paths only: no scheme, no authority, no query string,
+ * and no segment that could climb out of `/api/`.
+ */
 const BACKEND_API_PATH =
   /^\/api\/[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9][A-Za-z0-9._~-]*)*$/;
 
-// Written at the workspace root by the loader, from the endpoints each backend
-// module declared in the frontend manifest. This file sits two directories up.
+/**
+ * Written at the workspace root by the loader, from the endpoints each
+ * backend module declared in the frontend manifest. This file sits two
+ * directories up.
+ */
 const DECLARED_ENDPOINTS_FILE = new URL(
   "../../generated-auth-establish.json",
   import.meta.url,
@@ -49,6 +49,11 @@ export function readDeclaredEstablishEndpoints(file = DECLARED_ENDPOINTS_FILE) {
  * stays refused, so no backend endpoint that happens to mint a token pair can
  * be turned into a login by a request from the browser.
  *
+ * The backend endpoints a module may open a session from: what the backend's
+ * modules declared in the frontend manifest, and what the environment adds
+ * (`DMS_AUTH_ESTABLISH_ENDPOINTS`). The module that owns sign-in reads them as
+ * `event.app.authEstablishEndpoints`.
+ *
  * @param declaration Comma-separated absolute backend paths from the environment
  * @param declared Paths declared by the backend's frontend modules
  * @returns The well-formed backend API paths, without duplicates

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

@@ -15,6 +15,9 @@ const MAX_AGE = 60 * 60 * 24 * 30;
  * frontends on localhost:3000 and localhost:3001 would overwrite each other's
  * session, each failing to decrypt the other's and signing the user out. The
  * suffix follows the backend, so a restart keeps the cookies it wrote.
+ *
+ * A `DMS_API_BASE_URL` that is not a URL is hashed as written: the raw string
+ * still tells two backends apart.
  */
 function cookieScope() {
   const backendUrl = (process.env.DMS_API_BASE_URL ?? "").trim();
@@ -24,9 +27,7 @@ function cookieScope() {
     if (url.hostname === "localhost" || url.hostname === "[::1]")
       url.hostname = "127.0.0.1";
     canonical = url.toString().replace(/\/$/, "");
-  } catch {
-    // Not a URL: the raw string still tells two backends apart.
-  }
+  } catch {}
   return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
 }
 

package/templates/vue/server/auth-hooks.mjs

@@ -1,9 +1,3 @@
-// The session logic the server runs outside any route: renewing a session the
-// backend refused, the session a page carries, and where a signed-out visit
-// goes. The module that owns sign-in provides it through `registerAuth` in its
-// `dms.server.ts`. Without one, a page carries no session and a refused
-// session is not renewed.
-
 import { readSession, setRequestSession } from "./auth/session.mjs";
 import { createServerEvent } from "./module-event.mjs";
 import { compilePathPattern } from "./path-patterns.mjs";
@@ -40,6 +34,12 @@ function hookView(publicSession, session) {
 /**
  * The server's session logic for a set of server modules.
  *
+ * The session logic the server runs outside any route: renewing a session the
+ * backend refused, the session a page carries, and where a signed-out visit
+ * goes. The module that owns sign-in provides it through `registerAuth` in its
+ * `dms.server.ts`. Without one, a page carries no session and a refused session
+ * is not renewed.
+ *
  * @param provider The resolved auth hooks, `undefined` when no module
  *   registers any
  * @param context `(id) => ({ module, app })`, a module's event context

package/templates/vue/server/backend-proxies.mjs

@@ -1,9 +1,3 @@
-// The backend prefixes the frontend server proxies. The renderer hardcodes
-// none: a frontend module declares them in its `dms.server.ts`
-// (`registerBackendProxy`), and a backend module in the frontend manifest
-// (`backendProxies`, next to its `publicEndpoints`). A path no prefix covers
-// is never sent to the backend.
-
 import { compilePathPattern } from "./path-patterns.mjs";
 
 /** How the proxy authenticates a request to the backend. */
@@ -60,6 +54,12 @@ function compileProxy(pattern, options, owner) {
 /**
  * The deployment's backend proxies, one per pattern.
  *
+ * The backend prefixes the frontend server proxies. The renderer hardcodes
+ * none: a frontend module declares them in its `dms.server.ts`
+ * (`registerBackendProxy`), and a backend module in the frontend manifest
+ * (`backendProxies`, next to its `publicEndpoints`). A path no prefix covers is
+ * never sent to the backend.
+ *
  * @param declared `{ id, pattern, options }` per `registerBackendProxy` call,
  *   from the highest-priority module down
  * @param manifest `{ module, path, auth?, maxBodyBytes? }` per backend

package/templates/vue/server/backend-response.mjs

@@ -1,18 +1,17 @@
-// Reading a failed DMS backend response for the page a visitor gets instead.
-//
-// Lives apart from server.mjs so the file stays under the size the linter
-// allows.
-
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
 
-// What a JSON caller gets when the backend fails: the generic i18n key of the
-// API error contract. A page gets the status code alone, which the DMS error
-// page describes in the visitor's language; the technical cause only reaches
-// the server log.
+/**
+ * What a JSON caller gets when the backend fails: the generic i18n key of
+ * the API error contract. A page gets the status code alone, which the DMS
+ * error page describes in the visitor's language; the technical cause only
+ * reaches the server log.
+ */
 export const UNEXPECTED_ERROR_BODY = { message: GENERIC_ERROR_MESSAGE };
-// A typed refusal carries a machine-readable i18n key as its body, bare or
-// JSON-encoded, e.g. `saas.errors.workspace.access_blocked`.
+/**
+ * A typed refusal carries a machine-readable i18n key as its body, bare or
+ * JSON-encoded, e.g. `saas.errors.workspace.access_blocked`.
+ */
 const REFUSAL_CODE = /^[a-z0-9_-]+(?:\.[a-z0-9_-]+)+$/i;
 const REFUSAL_CODE_MAX_LENGTH = 200;
 const FORBIDDEN = 403;
@@ -26,6 +25,10 @@ export class BackendResponseError extends Error {
   }
 }
 
+/**
+ * The refusal code in a backend answer: the string or the `message` of its
+ * JSON body, or the body itself when it is not JSON (a bare code).
+ */
 async function refusalCode(response) {
   const text = (await response.text().catch(() => "")).trim();
   if (text.length > REFUSAL_CODE_MAX_LENGTH) return undefined;
@@ -33,9 +36,7 @@ async function refusalCode(response) {
   try {
     const data = JSON.parse(text);
     value = typeof data === "string" ? data : data?.message;
-  } catch {
-    // A bare code.
-  }
+  } catch {}
   return typeof value === "string" && REFUSAL_CODE.test(value)
     ? value
     : undefined;

package/templates/vue/server/built-files.mjs

@@ -1,10 +1,3 @@
-// The built files the production server hands to a browser: what the client
-// build wrote to `dist/client`, except a file or directory whose name starts
-// with a dot. Vite keeps its build metadata there (`.vite/manifest.json`, the
-// source path of every module file), and a module's `public/` may hold dot
-// files too. `/.well-known/`, which RFC 8615 reserves for files meant to be
-// public, stays served.
-
 import { existsSync, statSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 
@@ -14,6 +7,13 @@ const PUBLIC_DOT_DIRECTORY = ".well-known";
  * Whether a path relative to the build root may be served: no segment starts
  * with a dot, but a leading `.well-known`. Split on both separators: on
  * Windows, `relative` answers with backslashes, and a decoded `%5C` is one.
+ *
+ * The built files the production server hands to a browser: what the client
+ * build wrote to `dist/client`, except a file or directory whose name starts
+ * with a dot. Vite keeps its build metadata there (`.vite/manifest.json`, the
+ * source path of every module file), and a module's `public/` may hold dot
+ * files too. `/.well-known/`, which RFC 8615 reserves for files meant to be
+ * public, stays served.
  */
 export function isPublicBuildPath(relativePath) {
   return relativePath
@@ -30,6 +30,9 @@ export function isPublicBuildPath(relativePath) {
  * serves none there: the path is malformed, leaves `root`, names a dot file or
  * directory, or is not a regular file. Decoded first, as the browser encoded
  * it, so the file checked is the file served.
+ *
+ * The prefix uses the native separator: `resolve` answers with backslashes on
+ * Windows.
  */
 export function publicBuildFile(root, pathname) {
   let decoded;
@@ -40,7 +43,6 @@ export function publicBuildFile(root, pathname) {
   }
   const base = resolve(root);
   const file = resolve(base, `.${decoded}`);
-  // Native separator: `resolve` answers with backslashes on Windows.
   if (!file.startsWith(`${base}${sep}`)) return undefined;
   if (!isPublicBuildPath(relative(base, file))) return undefined;
   if (!existsSync(file) || !statSync(file).isFile()) return undefined;

package/templates/vue/server/cli-report.mjs

@@ -1,7 +1,3 @@
-// What the server tells whoever started it. Started by `ajs dms dev` or
-// `ajs dms start`, it reports over IPC and the CLI words what the user reads.
-// Started on its own, it prints the line itself.
-
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -13,7 +9,13 @@ async function report(message, line, write) {
   await new Promise((sent) => process.send(message, () => sent()));
 }
 
-/** The server answers at `address`:`port`. */
+/**
+ * The server answers at `address`:`port`.
+ *
+ * What the server tells whoever started it. Started by `ajs dms dev` or `ajs
+ * dms start`, it reports over IPC and the CLI words what the user reads.
+ * Started on its own, it prints the line itself.
+ */
 export async function reportReady(address, port) {
   const host = WILDCARD_ADDRESSES.includes(address)
     ? "localhost"

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

@@ -1,14 +1,12 @@
-// Answers for requests Node rejects before the request handler runs. Without
-// a `clientError` listener Node answers on its own and logs nothing, so a page
-// refused for its headers left no trace in the server output.
-
 const HEADER_OVERFLOW = "HPE_HEADER_OVERFLOW";
 const HEADER_OVERFLOW_RESPONSE =
   "HTTP/1.1 431 Request Header Fields Too Large\r\nConnection: close\r\n\r\n";
 const BAD_REQUEST_RESPONSE =
   "HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n";
-// A browser retries a refused page with the same cookies: one hint per minute
-// is enough to explain them all.
+/**
+ * A browser retries a refused page with the same cookies: one hint per
+ * minute is enough to explain them all.
+ */
 const HEADER_OVERFLOW_HINT_INTERVAL_MS = 60_000;
 
 let lastHeaderOverflowHint = -Infinity;
@@ -27,6 +25,13 @@ function warnHeaderOverflow(maxHeaderSize) {
 /**
  * The server's `clientError` listener: explains a 431 in the logs, and
  * otherwise answers as Node does without a listener.
+ *
+ * Answers requests Node rejects before the request handler runs. Without a
+ * `clientError` listener Node answers on its own and logs nothing, so a page
+ * refused for its headers left no trace in the server output.
+ *
+ * Once a response went out on this connection, a status line would land in the
+ * middle of it.
  */
 export function handleClientError(error, socket, maxHeaderSize) {
   let response = BAD_REQUEST_RESPONSE;
@@ -34,8 +39,6 @@ export function handleClientError(error, socket, maxHeaderSize) {
     response = HEADER_OVERFLOW_RESPONSE;
     warnHeaderOverflow(maxHeaderSize);
   }
-  // Once a response went out on this connection, a status line would land in
-  // the middle of it.
   if (socket.writable && socket.bytesWritten === 0) socket.write(response);
   socket.destroy();
 }

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

@@ -1,9 +1,3 @@
-// Reading the built client manifest and turning the components a server render
-// created into the stylesheet links its HTML needs.
-//
-// Lives apart from server.mjs so the file stays under the size the linter
-// allows. Production-only: in dev, Vite serves these itself.
-
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,11 +10,18 @@ const CLIENT_MANIFEST_PATH = join(
 );
 const SOURCE_TEMPLATE_PATH = join(PROJECT_ROOT, "index.html");
 
-// Read once and kept: both files are build output and cannot change while the
-// server is up.
+/**
+ * Read once and kept: both files are build output and cannot change while
+ * the server is up.
+ */
 let clientManifest;
 let productionTemplate;
 
+/**
+ * Reads the built client manifest and turns the components a server render
+ * created into the stylesheet links its HTML needs. Production-only: in dev,
+ * Vite serves these itself.
+ */
 export function productionHtmlTemplate() {
   if (productionTemplate) return productionTemplate;
   const templatePath = existsSync(BUILT_TEMPLATE_PATH)

package/templates/vue/server/content.mjs

@@ -15,6 +15,8 @@ const DYNAMIC_BROTLI_QUALITY = 4;
  * accepts (Brotli first), or `undefined` when it accepts neither. `streaming`
  * flushes what each write gives at once, for a body written over time: the
  * client gets each part when it is written, not when a block fills.
+ *
+ * Implicit identity is a fallback, not a preference over compression.
  */
 export function acceptedEncoder(request, { streaming = false } = {}) {
   const accepted = request.headers["accept-encoding"] ?? "";
@@ -38,7 +40,6 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
   const quality = (token) => qualities.get(token) ?? qualities.get("*") ?? 0;
   const br = quality("br");
   const gzip = quality("gzip");
-  // Implicit identity is a fallback, not a preference over compression.
   const identity = qualities.get("identity") ?? 0;
   if (identity > Math.max(br, gzip)) return undefined;
   if (br > 0 && br >= gzip)

package/templates/vue/server/dev-private-files.mjs

@@ -1,15 +1,3 @@
-// The files of the workspace the development server never hands to a browser.
-//
-// Vite's root is the workspace root, where the generated server options (the
-// modules' private options: the backend's secrets) and the cached manifest are
-// written, and the modules' server code is materialized under it. Vite serves
-// any file under its root, as is, `?raw`, `?import` or `?url`. Its
-// `server.fs.deny` list covers most of these, but not every query combination
-// (`?import&raw` got through in Vite 7.2; Vite 8.3 refuses it itself), so a middleware ahead of Vite's own
-// answers 403 by path, whatever the query, and a load guard refuses them to
-// any client request that reaches the transform pipeline another way.
-// `ssrLoadModule`, which loads the server modules, is left alone.
-
 import { relative, resolve, sep } from "node:path";
 
 const PRIVATE_FILE_NAMES = new Set([
@@ -22,7 +10,8 @@ const FORBIDDEN_STATUS = 403;
 
 /**
  * Vite's `server.fs.deny` for the development server: Vite's own defaults,
- * which a `deny` list replaces, and the private files.
+ * which a `deny` list replaces, and the private files: the generated secrets
+ * and the modules' server code are never served.
  */
 export const DEV_FS_DENY = [
   ".env",
@@ -68,7 +57,24 @@ function requestedFile(url, root) {
   return resolve(root, `.${sep}${pathname.replace(/^[\\/]+/, "")}`);
 }
 
-/** Answers 403 to private files, and fails a client load of one. */
+/**
+ * Answers 403 to private files, and fails a client load of one.
+ *
+ * The files of the workspace the development server never hands to a
+ * browser. Vite's root is the workspace root, where the generated server
+ * options (the modules' private options: the backend's secrets) and the
+ * cached manifest are written, and the modules' server code is materialized
+ * under it. Vite serves any file under its root, as is, `?raw`, `?import` or
+ * `?url`. Its `server.fs.deny` list covers most of these, but not every
+ * query combination (`?import&raw` got through in Vite 7.2; Vite 8.3 refuses
+ * it itself), so a middleware ahead of Vite's own answers 403 by path,
+ * whatever the query, and a load guard refuses them to any client request
+ * that reaches the transform pipeline another way. `ssrLoadModule`, which
+ * loads the server modules, is left alone.
+ *
+ * The middleware is registered directly, not returned: it runs before Vite's
+ * middlewares.
+ */
 export function denyPrivateFiles() {
   let root = process.cwd();
   return {
@@ -79,7 +85,6 @@ export function denyPrivateFiles() {
       root = config.root;
     },
     configureServer(server) {
-      // Registered directly, not returned: it runs before Vite's middlewares.
       server.middlewares.use((request, response, next) => {
         const file = requestedFile(request.url, root);
         if (!file || !isPrivateFile(file, root)) return next();

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

@@ -1,21 +1,3 @@
-// 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 { renderedModuleStyleTags } from "./client-manifest.mjs";
@@ -47,12 +29,14 @@ function ssrModuleGraph(devServer) {
   return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
 }
 
-// Vite only treats an id as a stylesheet when the language is the LAST thing in
-// it, and a component's style block ends in `&lang.css`. Appending `&direct`
-// after that makes Vite skip its stylesheet pipeline, so the block comes back
-// as written: `@import "package/dist/style.css"` is left for the browser, which
-// resolves it against the page URL and gets a 404. `direct` therefore goes in
-// front of the trailing language segment.
+/**
+ * Vite only treats an id as a stylesheet when the language is the last thing
+ * in it, and a component's style block ends in `&lang.css`. Appending
+ * `&direct` after that makes Vite skip its stylesheet pipeline, so the block
+ * comes back as written: `@import "package/dist/style.css"` is left for the
+ * browser, which resolves it against the page URL and gets a 404. `direct`
+ * therefore goes in front of the trailing language segment.
+ */
 const TRAILING_LANG = /&(lang\.[^&?]*)$/;
 
 function directUrl(url) {
@@ -90,7 +74,20 @@ async function inlineTag(devServer, { url, id }) {
   return `<style ${STYLE_ATTRIBUTE}="${id}">${css}</style>`;
 }
 
-/** Style tags for everything the development render touched, entry sheet first. */
+/**
+ * Style tags for everything the development render touched, entry sheet
+ * first.
+ *
+ * Puts 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.
+ */
 export async function developmentStyleTags(devServer) {
   const modules = styleModules(devServer);
   const links = [

package/templates/vue/server/email-bundle-watch.mjs

@@ -1,20 +1,8 @@
-// Development-only email bundle builder, forked by the frontend server.
-//
-// Runs Vite's email build in watch mode so `dist/server` exists as soon as the
-// dev server does and follows every template edit the layer watchers mirror
-// into the workspace. It lives in its own process so its builds never hold the
-// dev server's event loop, and it reports each build over IPC so the server
-// renders from a finished bundle only. A build empties `dist/server` first, so
-// it asks the server before it starts and waits for the go-ahead, which the
-// server gives once no render reads the previous bundle any more.
-
 import { fileURLToPath } from "node:url";
 import { build } from "vite";
 
 const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
-// The server owns this process: when its IPC channel closes, however the
-// server ended, there is nobody left to build for.
 process.on("disconnect", () => process.exit(0));
 
 let startBuild;

package/templates/vue/server/email.mjs

@@ -10,18 +10,23 @@ const EMAIL_BUNDLE_WATCH_URL = new URL(
   "./email-bundle-watch.mjs",
   import.meta.url,
 );
-// Bound the request's wait, but never read a bundle being replaced.
+/** Bound the request's wait, but never read a bundle being replaced. */
 const EMAIL_BUILD_WAIT_MS = 60_000;
 
-// Settled whenever no email build is running. The version changes with each
-// finished build: Node caches an imported module by URL, so the renderer is
-// imported under a new one to pick up rebuilt templates.
+/**
+ * Settled whenever no email build is running. The version changes with each
+ * finished build: Node caches an imported module by URL, so the renderer is
+ * imported under a new one to pick up rebuilt templates.
+ */
 let emailBuild = Promise.resolve();
 let settleEmailBuild;
 let emailBundleVersion = 0;
-// A build empties dist/server before it writes the new bundle, so it never
-// starts while a render still imports from the previous one: the builder asks
-// first, and gets the go-ahead once the renders in progress have finished.
+/**
+ * A build empties dist/server before it writes the new bundle, so it never
+ * starts while a render still imports from the previous one: the builder
+ * asks first, and gets the go-ahead once the renders in progress have
+ * finished.
+ */
 let rendersInProgress = 0;
 let startPendingBuild;
 
@@ -56,7 +61,8 @@ function renderFinished() {
  * Build the email bundle now and again on every template change, for
  * development: only the production build otherwise produces it. The builder
  * runs in a child process at low priority, so the dev server keeps answering
- * while it works.
+ * while it works. Lowering the priority is skipped where the platform does not
+ * permit it: the build then runs at normal priority.
  */
 export function watchEmailBundle() {
   emailBuildStarted();
@@ -65,9 +71,7 @@ export function watchEmailBundle() {
   });
   try {
     setPriority(builder.pid, constants.priority.PRIORITY_BELOW_NORMAL);
-  } catch {
-    // Not permitted on this platform; the build only runs at normal priority.
-  }
+  } catch {}
   builder.on("message", (message) => {
     if (message?.state !== "building") {
       emailBuildSettled();
@@ -85,9 +89,9 @@ export function watchEmailBundle() {
   return builder;
 }
 
+/** Another build may start while a render waits for the previous one. */
 async function waitForEmailBuild() {
   const deadline = Date.now() + EMAIL_BUILD_WAIT_MS;
-  // Another build may start while a render waits for the previous one.
   while (settleEmailBuild && Date.now() < deadline) {
     let timer;
     await Promise.race([
@@ -113,15 +117,16 @@ function loadEmailRenderer() {
  * Renders an email template of the application's email bundle, waiting for a
  * development build in progress.
  *
+ * The render is counted with no await in between, so a build the builder asks
+ * for now waits for this render, which imports templates and reads catalogs
+ * from the bundle until it ends.
+ *
  * @param template The template's name
  * @param props The template's props
  * @param options `locale`, the language to render in
  */
 export async function renderEmailTemplate(template, props, options = {}) {
   await waitForEmailBuild();
-  // Counted from here, with no await in between, so a build the builder asks
-  // for now waits for this render, which imports templates and reads catalogs
-  // from the bundle until it ends.
   rendersInProgress += 1;
   try {
     const { renderEmail } = await loadEmailRenderer();