@antelopejs/dms-frontend 0.9.3 → 0.10.0

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

@@ -1,4 +1,36 @@
 import { compilePathPattern } from "./path-patterns.mjs";
+import { isNonNullObject } from "./type-guards.mjs";
+
+/** @typedef {import("../server-module.ts").DmsBackendProxyOptions} ProxyOptions */
+/**
+ * A backend prefix the server proxies, compiled from a pattern `proxyRejection`
+ * accepted.
+ *
+ * @typedef {object} BackendProxy
+ * @property {import("./path-patterns.mjs").CompiledPathPattern} pattern
+ * @property {string} path The pattern as declared
+ * @property {string} owner Who declared it
+ * @property {NonNullable<ProxyOptions["auth"]>} auth
+ * @property {number} [maxBodyBytes]
+ */
+/**
+ * What `registerBackendProxy` declared, per call.
+ *
+ * @typedef {object} ProxyDeclaration
+ * @property {string} id The declaring frontend module
+ * @property {string} pattern
+ * @property {ProxyOptions} [options]
+ */
+/**
+ * What a backend module declared in the manifest, or an operator in
+ * `DMS_BACKEND_PROXIES`.
+ *
+ * @typedef {object} ManifestProxy
+ * @property {string} [module]
+ * @property {string} [path]
+ * @property {ProxyOptions["auth"]} [auth]
+ * @property {number} [maxBodyBytes]
+ */
 
 /** How the proxy authenticates a request to the backend. */
 export const PROXY_AUTH_MODES = Object.freeze(["session", "none"]);
@@ -6,8 +38,10 @@ const DEFAULT_AUTH = "session";
 /** The renderer's own paths, never a backend's. */
 const RENDERER_PREFIXES = ["/api/_dms", "/@", "/assets", "/node_modules"];
 
+/** @param {string} pattern */
 function literalPrefix(pattern) {
   const segments = pattern === "/" ? [] : pattern.slice(1).split("/");
+  /** @type {string[]} */
   const literal = [];
   for (const segment of segments) {
     if (segment === "*" || segment === "**") break;
@@ -16,7 +50,12 @@ function literalPrefix(pattern) {
   return `/${literal.join("/")}`;
 }
 
-/** Why a proxy declaration is ignored, or `undefined`. */
+/**
+ * Why a proxy declaration is ignored, or `undefined`.
+ *
+ * @param {string} pattern
+ * @param {ProxyOptions | undefined} options
+ */
 export function proxyRejection(pattern, options) {
   const compiled = compilePathPattern(pattern);
   if (!compiled) return "the pattern is not /x, /x/* or /x/**";
@@ -29,7 +68,7 @@ export function proxyRejection(pattern, options) {
     )
   )
     return `${RENDERER_PREFIXES.join(", ")} are the renderer's own paths`;
-  if (options !== undefined && (typeof options !== "object" || !options))
+  if (options !== undefined && !isNonNullObject(options))
     return "its options are not an object";
   if (options?.auth !== undefined && !PROXY_AUTH_MODES.includes(options.auth))
     return `auth is not one of ${PROXY_AUTH_MODES.map((mode) => `"${mode}"`).join(", ")}`;
@@ -41,6 +80,12 @@ export function proxyRejection(pattern, options) {
   return undefined;
 }
 
+/**
+ * @param {string} pattern A pattern `proxyRejection` accepted
+ * @param {ProxyOptions | undefined} options
+ * @param {string} owner Who declared it
+ * @returns {BackendProxy}
+ */
 function compileProxy(pattern, options, owner) {
   return {
     pattern: compilePathPattern(pattern),
@@ -60,16 +105,22 @@ function compileProxy(pattern, options, owner) {
  * (`backendProxies`, next to its `publicEndpoints`). A path no prefix covers is
  * never sent to the backend.
  *
- * @param declared `{ id, pattern, options }` per `registerBackendProxy` call,
+ * @param {readonly ProxyDeclaration[]} declared `{ id, pattern, options }` per `registerBackendProxy` call,
  *   from the highest-priority module down
- * @param manifest `{ module, path, auth?, maxBodyBytes? }` per backend
+ * @param {readonly (ManifestProxy | null | undefined)[]} manifest `{ module, path, auth?, maxBodyBytes? }` per backend
  *   module declaration
- * @param warn Reports a declaration problem
- * @returns The proxies, the most specific pattern first: a request reaches
+ * @param {(message: string) => void} warn Reports a declaration problem
+ * @returns {BackendProxy[]} The proxies, the most specific pattern first: a request reaches
  *   the first that matches
  */
 export function resolveBackendProxies(declared, manifest, warn) {
+  /** @type {Map<string | undefined, BackendProxy>} */
   const kept = new Map();
+  /**
+   * @param {string | undefined} pattern
+   * @param {ProxyOptions | undefined} options
+   * @param {string} owner
+   */
   const add = (pattern, options, owner) => {
     const reason = proxyRejection(pattern, options);
     const current = kept.get(pattern);
@@ -94,7 +145,12 @@ export function resolveBackendProxies(declared, manifest, warn) {
   );
 }
 
-/** The backend proxy a path reaches, or `undefined`. */
+/**
+ * The backend proxy a path reaches, or `undefined`.
+ *
+ * @param {readonly BackendProxy[]} proxies
+ * @param {string} pathname
+ */
 export function matchBackendProxy(proxies, pathname) {
   return proxies.find((proxy) => proxy.pattern.test(pathname));
 }
@@ -103,8 +159,8 @@ export function matchBackendProxy(proxies, pathname) {
  * The lines the server prints at startup: each backend prefix, who declared
  * it and how it authenticates, then who owns the rest.
  *
- * @param proxies What `resolveBackendProxies` returned
- * @param routeCount The number of module routes
+ * @param {readonly BackendProxy[]} proxies What `resolveBackendProxies` returned
+ * @param {number} routeCount The number of module routes
  */
 export function routingReport(proxies, routeCount) {
   const width = Math.max(0, ...proxies.map((proxy) => proxy.path.length));

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

@@ -0,0 +1,61 @@
+import { CLIENT_HEADERS, relayedHeaders } from "./auth/backend.mjs";
+import { forwardedHeaders } from "./auth/client-ip.mjs";
+import { readSession } from "./auth/session.mjs";
+import { backendResponseError } from "./backend-response.mjs";
+import { serverReads } from "./in-place-render.mjs";
+
+/**
+ * The headers of a backend request: the relayed client headers, the client's
+ * Origin and Referer as received, the `X-Forwarded-*` headers (set last, so no
+ * caller writes them), and the session's access token unless the request goes
+ * anonymously.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {{ anonymous: boolean, headers: readonly string[] }} [access]
+ * @returns {Record<string, string>}
+ */
+export function backendHeaders(
+  request,
+  access = { anonymous: false, headers: [] },
+) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    ...relayedHeaders(request, [
+      "accept",
+      "content-type",
+      "if-match",
+      "origin",
+      "referer",
+      ...CLIENT_HEADERS,
+      ...access.headers,
+    ]),
+    ...forwardedHeaders(request),
+  };
+  const session = access.anonymous ? undefined : readSession(request);
+  if (session?.accessToken)
+    headers.authorization = `Bearer ${session.accessToken}`;
+  return headers;
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {import("./in-place-render.mjs").ServerReads}
+ */
+export function serverComponentFetch(request) {
+  return serverReads(() => backendHeaders(request));
+}
+
+/**
+ * @param {string} path
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {Promise<unknown>}
+ */
+export async function backendJson(path, request) {
+  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
+    headers: backendHeaders(request),
+  });
+  if (!response.ok) {
+    throw await backendResponseError(response);
+  }
+  return response.json();
+}

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

@@ -1,5 +1,6 @@
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
+import { isString } from "./type-guards.mjs";
 
 /**
  * What a JSON caller gets when the backend fails: the generic i18n key of
@@ -18,6 +19,10 @@ const FORBIDDEN = 403;
 const FRONTEND_ORIGIN = "http://frontend.local";
 
 export class BackendResponseError extends Error {
+  /**
+   * @param {number} status
+   * @param {string | undefined} code The typed refusal code of the answer
+   */
   constructor(status, code) {
     super(`DMS backend returned ${status}`);
     this.status = status;
@@ -28,21 +33,28 @@ 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).
+ *
+ * @param {Response} response
+ * @returns {Promise<string | undefined>}
  */
 async function refusalCode(response) {
   const text = (await response.text().catch(() => "")).trim();
   if (text.length > REFUSAL_CODE_MAX_LENGTH) return undefined;
+  /** @type {unknown} */
   let value = text;
   try {
+    /** @type {unknown} */
     const data = JSON.parse(text);
-    value = typeof data === "string" ? data : data?.message;
+    value = isString(data) ? data : data?.message;
   } catch {}
-  return typeof value === "string" && REFUSAL_CODE.test(value)
-    ? value
-    : undefined;
+  return isString(value) && REFUSAL_CODE.test(value) ? value : undefined;
 }
 
-/** The error for a failed backend response, with its typed code if any. */
+/**
+ * The error for a failed backend response, with its typed code if any.
+ *
+ * @param {Response} response
+ */
 export async function backendResponseError(response) {
   return new BackendResponseError(response.status, await refusalCode(response));
 }
@@ -54,7 +66,11 @@ export async function backendResponseError(response) {
  * `loadRenderer` resolves. Only a same-origin path other than the refused one
  * qualifies: a refused destination sent to itself again would loop.
  *
- * @returns Whether the visit was redirected
+ * @param {unknown} error What the request failed with
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {() => Promise<typeof import("../ssr-renderer.ts")>} loadRenderer
+ * @returns {Promise<boolean>} Whether the visit was redirected
  */
 export async function redirectAccessRefusal(
   error,
@@ -69,6 +85,7 @@ export async function redirectAccessRefusal(
     !error.code
   )
     return false;
+  /** @type {string | undefined} */
   let location;
   try {
     location = (await loadRenderer()).accessRedirect?.(error.code);

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

@@ -14,6 +14,9 @@ const PUBLIC_DOT_DIRECTORY = ".well-known";
  * 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.
+ *
+ * @param {string} relativePath
+ * @returns {boolean}
  */
 export function isPublicBuildPath(relativePath) {
   return relativePath
@@ -33,6 +36,10 @@ export function isPublicBuildPath(relativePath) {
  *
  * The prefix uses the native separator: `resolve` answers with backslashes on
  * Windows.
+ *
+ * @param {string} root
+ * @param {string} pathname
+ * @returns {string | undefined}
  */
 export function publicBuildFile(root, pathname) {
   let decoded;

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

@@ -1,9 +1,16 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { stripVTControlCharacters } from "node:util";
+import { isNumber, isObjectLike, isRecord, isString } from "./type-guards.mjs";
 
 const WILDCARD_ADDRESSES = ["0.0.0.0", "::"];
 
+/**
+ * @param {import("node:child_process").Serializable} message
+ * @param {string} line
+ * @param {(line: string) => void} write
+ * @returns {Promise<void>}
+ */
 async function report(message, line, write) {
   if (!process.send) return write(line);
   await new Promise((sent) => process.send(message, () => sent()));
@@ -15,6 +22,10 @@ async function report(message, line, write) {
  * 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.
+ *
+ * @param {string} address
+ * @param {number} port
+ * @returns {Promise<void>}
  */
 export async function reportReady(address, port) {
   const host = WILDCARD_ADDRESSES.includes(address)
@@ -33,6 +44,11 @@ export async function reportReady(address, port) {
  * The server cannot listen: a port taken by another process, an address this
  * host does not have. Reported instead of Node's unhandled-error dump, then
  * the server exits.
+ *
+ * @param {NodeJS.ErrnoException} error
+ * @param {string} host
+ * @param {number} port
+ * @returns {Promise<void>}
  */
 export async function reportListenError(error, host, port) {
   await report(
@@ -52,31 +68,46 @@ export async function reportListenError(error, host, port) {
 /** The `[PARSE_ERROR] ` Rolldown puts in front of what it says. */
 const RULE_PREFIX = /^\[[A-Z_]+\]\s*/;
 
-/** The first problem Rolldown reports when it cannot bundle a config. */
+/**
+ * The first problem Rolldown reports when it cannot bundle a config.
+ *
+ * @param {unknown} error What the startup threw
+ */
 function bundlerError(error) {
-  const first = error?.errors?.[0];
-  return first && typeof first === "object" ? first : undefined;
+  const errors = isObjectLike(error) ? error.errors : undefined;
+  const first = isObjectLike(errors) ? errors[0] : undefined;
+  return isRecord(first) ? first : undefined;
 }
 
 /**
  * Where a startup error points, when it says: Rolldown's location for a config
  * it could not bundle (the line is read back from the file, which Rolldown
  * only draws in a colored frame), Rollup's for a plugin that failed on a file.
+ *
+ * @param {unknown} error What the startup threw
  */
 function errorLocation(error) {
-  const source = bundlerError(error) ?? error;
-  const file = source?.loc?.file ?? source?.id;
-  if (typeof file !== "string") return undefined;
-  const { line, column } = source.loc ?? {};
+  const source =
+    bundlerError(error) ?? (isObjectLike(error) ? error : undefined);
+  const loc = isObjectLike(source?.loc) ? source.loc : undefined;
+  const file = loc?.file ?? source?.id;
+  if (!isString(file)) return undefined;
+  const line = isNumber(loc?.line) ? loc.line : undefined;
   return {
     file: resolve(file),
     line,
-    column,
+    column: isNumber(loc?.column) ? loc.column : undefined,
     lineText: line === undefined ? undefined : readLine(file, line),
   };
 }
 
-/** Line `line` (1-based) of `file`, `undefined` when it cannot be read. */
+/**
+ * Line `line` (1-based) of `file`, `undefined` when it cannot be read.
+ *
+ * @param {string} file
+ * @param {number} line
+ * @returns {string | undefined}
+ */
 function readLine(file, line) {
   try {
     return readFileSync(file, "utf8").split(/\r?\n/)[line - 1];
@@ -85,7 +116,11 @@ function readLine(file, line) {
   }
 }
 
-/** The first line of what went wrong, without Rolldown's rule and frame. */
+/**
+ * The first line of what went wrong, without Rolldown's rule and frame.
+ *
+ * @param {unknown} error What the startup threw
+ */
 function errorText(error) {
   const reported = bundlerError(error);
   const message = reported
@@ -101,6 +136,8 @@ function errorText(error) {
 /**
  * Vite could not start, so no page can be served: the error and where it
  * points instead of a stack trace, then the server exits.
+ *
+ * @param {unknown} error What the startup threw
  */
 export async function reportStartError(error) {
   const message = errorText(error);
@@ -109,7 +146,12 @@ export async function reportStartError(error) {
     ? `${location.file}${location.line ? `:${location.line}:${location.column ?? 0}` : ""}: `
     : "";
   await report(
-    { type: "dms:start-error", message, code: error?.code, location },
+    {
+      type: "dms:start-error",
+      message,
+      code: isObjectLike(error) ? error.code : undefined,
+      location,
+    },
     `DMS development server failed to start: ${where}${message}`,
     console.error,
   );

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

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { viteManifestOf } from "./generated-files.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
 const BUILT_TEMPLATE_PATH = join(PROJECT_ROOT, "dist/client/index.html");
@@ -14,7 +15,9 @@ 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.
  */
+/** @type {import("vite").Manifest | undefined} */
 let clientManifest;
+/** @type {string | undefined} */
 let productionTemplate;
 
 /**
@@ -31,13 +34,22 @@ export function productionHtmlTemplate() {
   return productionTemplate;
 }
 
+/** @returns {import("vite").Manifest | undefined} */
 function productionClientManifest() {
   if (clientManifest) return clientManifest;
   if (!existsSync(CLIENT_MANIFEST_PATH)) return undefined;
-  clientManifest = JSON.parse(readFileSync(CLIENT_MANIFEST_PATH, "utf8"));
+  clientManifest = viteManifestOf(
+    JSON.parse(readFileSync(CLIENT_MANIFEST_PATH, "utf8")),
+  );
   return clientManifest;
 }
 
+/**
+ * @param {import("vite").Manifest} manifest
+ * @param {string} key
+ * @param {Set<string>} styles
+ * @param {Set<string>} visited
+ */
 function collectManifestStyles(manifest, key, styles, visited) {
   if (visited.has(key)) return;
   visited.add(key);
@@ -56,11 +68,16 @@ function collectManifestStyles(manifest, key, styles, visited) {
  * component, so the lookup needs no guessing from names. A component bundled
  * into another chunk is no key of its own: its stylesheet comes with that
  * chunk's, reached through the `imports` of the component that loaded it.
+ *
+ * @param {Iterable<string>} [modules]
+ * @returns {Set<string>}
  */
 function renderedModuleStyles(modules = []) {
   const manifest = productionClientManifest();
+  /** @type {Set<string>} */
   const styles = new Set();
   if (!manifest) return styles;
+  /** @type {Set<string>} */
   const visited = new Set();
   for (const id of modules)
     collectManifestStyles(manifest, id, styles, visited);
@@ -72,6 +89,9 @@ function renderedModuleStyles(modules = []) {
  * template does not link already, so that none of them waits for its chunk's
  * JavaScript to arrive: the HTML would otherwise paint unstyled and shift once
  * it does. A component the render did not reach gets no link.
+ *
+ * @param {Iterable<string> | undefined} modules
+ * @param {string} template
  */
 export function renderedModuleStyleTags(modules, template) {
   return [...renderedModuleStyles(modules)]
@@ -85,6 +105,8 @@ export function renderedModuleStyleTags(modules, template) {
  * rendered with: the browser fetches it next to the entry rather than once the
  * entry runs and asks for it, which would put a round trip before hydration.
  * Nothing without a production build (Vite serves the sources in development).
+ *
+ * @param {string | undefined} locale
  */
 export function localeCatalogPreloadTag(locale) {
   const manifest = productionClientManifest();

package/templates/vue/server/content.mjs

@@ -17,9 +17,13 @@ const DYNAMIC_BROTLI_QUALITY = 4;
  * client gets each part when it is written, not when a block fills.
  *
  * Implicit identity is a fallback, not a preference over compression.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {{ streaming?: boolean }} [options]
  */
 export function acceptedEncoder(request, { streaming = false } = {}) {
   const accepted = request.headers["accept-encoding"] ?? "";
+  /** @type {Map<string, number>} */
   const qualities = new Map();
   for (const entry of accepted.split(",")) {
     const [token, ...parameters] = entry.trim().toLowerCase().split(";");
@@ -37,6 +41,7 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
       Math.min(qualities.get(token.trim()) ?? 1, quality),
     );
   }
+  /** @param {string} token */
   const quality = (token) => qualities.get(token) ?? qualities.get("*") ?? 0;
   const br = quality("br");
   const gzip = quality("gzip");
@@ -61,12 +66,24 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
     };
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string | Buffer} content
+ */
 function responseEncoder(request, content) {
   if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
   return acceptedEncoder(request);
 }
 
-/** Send a generated body, compressed when the client accepts it. */
+/**
+ * Send a generated body, compressed when the client accepts it.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {number} status
+ * @param {import("node:http").OutgoingHttpHeaders} headers
+ * @param {string | Buffer} content
+ */
 export async function writeContent(
   request,
   response,

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

@@ -28,6 +28,10 @@ export const DEV_FS_DENY = [
  * file, a module's server entry, or a file under a `server/` directory of a
  * module materialized under `root`. Compared without case, as a
  * case-insensitive file system would serve them.
+ *
+ * @param {string} file
+ * @param {string} root
+ * @returns {boolean}
  */
 export function isPrivateFile(file, root) {
   const name = (resolve(file).split(/[\\/]/).at(-1) ?? "").toLowerCase();
@@ -39,12 +43,22 @@ export function isPrivateFile(file, root) {
   );
 }
 
+/**
+ * @param {string} id
+ * @returns {string}
+ */
 function stripQuery(id) {
   const query = id.search(/[?#]/);
   return query === -1 ? id : id.slice(0, query);
 }
 
-/** The file a request URL names under `root`, `undefined` when it names none. */
+/**
+ * The file a request URL names under `root`, `undefined` when it names none.
+ *
+ * @param {string | undefined} url
+ * @param {string} root
+ * @returns {string | undefined}
+ */
 function requestedFile(url, root) {
   let pathname;
   try {
@@ -74,6 +88,8 @@ function requestedFile(url, root) {
  *
  * The middleware is registered directly, not returned: it runs before Vite's
  * middlewares.
+ *
+ * @returns {import("vite").Plugin}
  */
 export function denyPrivateFiles() {
   let root = process.cwd();

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

@@ -8,6 +8,13 @@ const SFC_STYLE = /[?&]vue&type=style/;
 const STYLE_EXTENSION =
   /\.(?:css|less|pcss|postcss|sass|scss|styl|stylus)(?:$|\?)/;
 
+/**
+ * A stylesheet module of the development server's graph: its URL, and the id
+ * its tag is matched by.
+ *
+ * @typedef {{ url: string, id: string }} StyleModule
+ */
+
 /**
  * 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
@@ -25,6 +32,16 @@ const ENTRY_STYLESHEET_ID = join(PROJECT_ROOT, "dms-main.css")
   .split(sep)
   .join("/");
 
+/**
+ * @typedef {{ urlToModuleMap: ReadonlyMap<string, { id: string | null } | undefined> }} StyleGraph
+ * @typedef {{
+ *   environments?: { ssr?: { moduleGraph?: StyleGraph } },
+ *   moduleGraph?: StyleGraph,
+ *   transformRequest(url: string): Promise<{ code: string } | null>,
+ * }} StyleServer
+ */
+
+/** @param {StyleServer} devServer */
 function ssrModuleGraph(devServer) {
   return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
 }
@@ -39,6 +56,10 @@ function ssrModuleGraph(devServer) {
  */
 const TRAILING_LANG = /&(lang\.[^&?]*)$/;
 
+/**
+ * @param {string} url
+ * @returns {string}
+ */
 function directUrl(url) {
   if (SFC_STYLE.test(url) && TRAILING_LANG.test(url)) {
     return url.replace(TRAILING_LANG, "&direct&$1");
@@ -46,6 +67,10 @@ function directUrl(url) {
   return `${url}${url.includes("?") ? "&" : "?"}direct`;
 }
 
+/**
+ * @param {StyleServer} devServer
+ * @returns {StyleModule[]}
+ */
 function styleModules(devServer) {
   const graph = ssrModuleGraph(devServer);
   if (!graph) return [];
@@ -54,6 +79,7 @@ function styleModules(devServer) {
     .map(([url, module]) => ({ url, id: module?.id ?? url }));
 }
 
+/** @param {StyleModule} module */
 function linkTag({ url, id }) {
   return `<link rel="stylesheet" ${STYLE_ATTRIBUTE}="${id}" href="${directUrl(url)}">`;
 }
@@ -64,6 +90,10 @@ function linkTag({ url, id }) {
  * 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.
+ *
+ * @param {StyleServer} devServer
+ * @param {StyleModule} module
+ * @returns {Promise<string>}
  */
 async function inlineTag(devServer, { url, id }) {
   const result = await devServer
@@ -87,6 +117,9 @@ async function inlineTag(devServer, { url, id }) {
  * 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.
+ *
+ * @param {StyleServer} devServer
+ * @returns {Promise<string>}
  */
 export async function developmentStyleTags(devServer) {
   const modules = styleModules(devServer);
@@ -106,6 +139,11 @@ export async function developmentStyleTags(devServer) {
  * The style tags a document needs, whichever server is answering it: collected
  * from the live module graph in development, read from the build manifest for
  * the components the render created (`modules`) in production.
+ *
+ * @param {import("vite").ViteDevServer | undefined} devServer
+ * @param {Iterable<string> | undefined} modules
+ * @param {string} template
+ * @returns {Promise<string>}
  */
 export async function documentStyleTags(devServer, modules, template) {
   return devServer