@ultimat3/cli 29.3.2 → 30.0.0

package/src/output-findings.ts

@@ -0,0 +1,123 @@
+// What a reader is owed beyond a finding as it was thrown: a fix that runs where `x` is not on
+// PATH, and one line for one cause. Render layer only, so every throw site keeps spelling `x …`,
+// which is what `fix-command.ts` reads to prove the command exists.
+
+import type { Finding, JsonValue } from './output';
+
+const SEGMENT_END = /^(?:&&|\|\||;)/;
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|[^\s'"]*)\s+/;
+
+/** Where the command word of a segment starts, past its `A=b` prefix. */
+const commandWordAt = (fix: string, from: number): number => {
+  let at = from;
+  for (;;) {
+    while (fix[at] === ' ') at += 1;
+    const assignment = ENV_ASSIGNMENT.exec(fix.slice(at));
+    if (assignment === null) return at;
+    at += assignment[0].length;
+  }
+};
+
+const isBareX = (fix: string, at: number): boolean =>
+  fix[at] === 'x' && (at + 1 === fix.length || fix[at + 1] === ' ');
+
+/**
+ * A leading `x ` becomes `bunx x `, and after `&&`, `||` and `;`. Quoted text is an argument and a
+ * `#` tail is never run, so both are copied as they are. `bunx x` itself does not match, so a report
+ * read back by `x verify merge` and rendered again does not grow.
+ */
+export function runnableFix(fix: string): string {
+  let out = '';
+  let quote: string | undefined;
+  let at = 0;
+  let segmentStart = true;
+  while (at < fix.length) {
+    if (segmentStart) {
+      const word = commandWordAt(fix, at);
+      out += fix.slice(at, word);
+      at = word;
+      if (isBareX(fix, at)) out += 'bunx ';
+      segmentStart = false;
+      continue;
+    }
+    const char = fix[at] ?? '';
+    if (quote !== undefined) {
+      if (char === quote) quote = undefined;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === '#' && (at === 0 || fix[at - 1] === ' ')) {
+      return out + fix.slice(at);
+    } else {
+      const end = SEGMENT_END.exec(fix.slice(at));
+      if (end !== null) {
+        out += end[0];
+        at += end[0].length;
+        segmentStart = true;
+        continue;
+      }
+    }
+    out += char;
+    at += 1;
+  }
+  return out;
+}
+
+const keyOf = (finding: Finding): string =>
+  [finding.code, finding.cause, finding.fix].join('\u0000');
+
+/**
+ * One finding per code + cause + fix, with how many reported it and where. A broken `$view` throws
+ * from every module importing its entity: 3 findings on one load, 29 on a larger app, one repair.
+ * The fix is in the key because a rule whose cause is generic names the file in its fix, and those
+ * are separate repairs. `reportedAt` keeps what `at` can no longer say.
+ */
+export function collapseFindings(findings: readonly Finding[]): readonly Finding[] {
+  const groups = new Map<string, Finding[]>();
+  for (const finding of findings) {
+    const key = keyOf(finding);
+    const group = groups.get(key);
+    if (group === undefined) groups.set(key, [finding]);
+    else group.push(finding);
+  }
+  return [...groups.values()].map((group) => {
+    const first = group[0] as Finding;
+    if (group.length === 1) return first;
+    const reportedAt = group.flatMap((one) => (one.at === undefined ? [] : [one.at]));
+    const meta: { [key: string]: JsonValue } = { ...first.meta, count: group.length };
+    if (reportedAt.length > 0) meta['reportedAt'] = reportedAt;
+    return { ...first, meta };
+  });
+}
+
+/** How many sites the human line names. `--json` carries all of them in `meta.reportedAt`. */
+const SITES_SHOWN = 3;
+
+/** The human half of a count: `meta` is never the only home of a fact. */
+export function causeWithCount(finding: Finding): string {
+  const count = finding.meta?.['count'];
+  if (typeof count !== 'number') return finding.cause;
+  const sites = finding.meta?.['reportedAt'];
+  const named = Array.isArray(sites) ? sites.slice(0, SITES_SHOWN).join(', ') : '';
+  return `${finding.cause} (reported ${String(count)} times${named === '' ? '' : `: ${named}`})`;
+}
+
+export interface ReaderOptions {
+  /** `x` is not this reader's command: its fixes name `bunx x`. `dispatch` decides. */
+  readonly bunxRunner?: boolean;
+}
+
+/** A finding read out of a CI log is fenced text and is never turned into an instruction. */
+const withRunnableFix = (finding: Finding): Finding => {
+  if (finding.source === 'ci-log') return finding;
+  const fix = runnableFix(finding.fix);
+  return fix === finding.fix ? finding : { ...finding, fix };
+};
+
+/** The list a renderer prints. */
+export const findingsForReader = (
+  findings: readonly Finding[],
+  options: ReaderOptions,
+): readonly Finding[] => {
+  const collapsed = collapseFindings(findings);
+  return options.bunxRunner === true ? collapsed.map(withRunnableFix) : collapsed;
+};

package/src/output.ts

@@ -3,7 +3,9 @@
 // output (axiom 4). The human renderer owns the canonical 3-line error format.
 
 import { ERROR_DOCS_URL, renderThrowable, singleLine, stringField } from '@ultimat3/core';
+import { unresolvedImportFinding } from './app-load-unresolved';
 import { msg } from './messages';
+import { causeWithCount, findingsForReader, type ReaderOptions } from './output-findings';
 import type { TestCounts } from './test-counts';
 
 /** One shard's share of one step's corpus — what `x verify merge` checks the parts against. */
@@ -164,6 +166,9 @@ export function findingFrom(value: unknown): Finding {
     const docs = stringField(value, 'docs');
     return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
   }
+  // An import that will not resolve, on a path outside the app scan: `bun add`, not `x doctor`.
+  const unresolved = unresolvedImportFinding(value, process.cwd());
+  if (unresolved !== undefined) return unresolved;
   // This is the LAST renderer between a thrown value and the terminal: a hostile `toString`, a
   // throwing `message` getter or a trapped `instanceof` here loses the whole report, not one line
   // of it. `renderThrowable` is total on all three.
@@ -263,13 +268,19 @@ const why = (step: StepResult): string => {
 const showsOutput = (step: StepResult, verbose: boolean): boolean =>
   step.output !== undefined && step.output.length > 0 && (verbose || !step.ok);
 
-export function renderHuman(result: CommandResult, verbose = false): string {
+export function renderHuman(
+  result: CommandResult,
+  verbose = false,
+  reader: ReaderOptions = {},
+): string {
   const out: string[] = [];
   for (const step of result.steps ?? []) {
     out.push(
       `  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}${why(step)}`,
     );
-    for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    for (const finding of findingsForReader(step.findings, reader)) {
+      out.push(renderFinding({ ...finding, cause: causeWithCount(finding) }, '      '));
+    }
     // Escaped like every other line text reaches fd 1 through: a warning names a file path. A
     // green terminal run shows the count, not the list: `filesize`'s band alone is ~150 lines,
     // and a wall of advice on every run is read by nobody. `--json` always carries the list.
@@ -298,19 +309,25 @@ export function renderHuman(result: CommandResult, verbose = false): string {
   // comment retitled the window and cleared the screen, and a newline in one entry printed a
   // second line a reader — or the agent this command exists for — takes for the renderer's own.
   for (const line of result.lines ?? []) out.push(singleLine(line));
-  for (const finding of result.findings ?? []) out.push(renderFinding(finding, '  '));
+  for (const finding of findingsForReader(result.findings ?? [], reader)) {
+    out.push(renderFinding({ ...finding, cause: causeWithCount(finding) }, '  '));
+  }
   // The summary is foreign too: `cli.shot.threw` interpolates a page's own error message.
   out.push(`${result.ok ? '✓' : '✗'} ${singleLine(result.summary)}`);
   return out.join('\n');
 }
 
-export function renderJson(result: CommandResult, verbose = false): string {
+export function renderJson(
+  result: CommandResult,
+  verbose = false,
+  reader: ReaderOptions = {},
+): string {
   const steps = (result.steps ?? []).map((step) => ({
     name: step.name,
     ok: step.ok,
     durationMs: step.durationMs,
     skipped: step.skipped === true,
-    findings: step.findings,
+    findings: findingsForReader(step.findings, reader),
     // Never gated on `ok` or `--verbose`, unlike `output` below: see `StepResult.warnings`.
     ...(step.warnings === undefined || step.warnings.length === 0
       ? {}
@@ -348,14 +365,21 @@ export function renderJson(result: CommandResult, verbose = false): string {
     command: result.command,
     summary: result.summary,
     ...(result.steps === undefined ? {} : { steps }),
-    ...(result.findings === undefined ? {} : { findings: result.findings }),
+    ...(result.findings === undefined
+      ? {}
+      : { findings: findingsForReader(result.findings, reader) }),
     ...(result.data === undefined ? {} : { data: result.data }),
   };
   return JSON.stringify(payload);
 }
 
-export function render(result: CommandResult, json: boolean, verbose = false): string {
-  return json ? renderJson(result, verbose) : renderHuman(result, verbose);
+export function render(
+  result: CommandResult,
+  json: boolean,
+  verbose = false,
+  reader: ReaderOptions = {},
+): string {
+  return json ? renderJson(result, verbose, reader) : renderHuman(result, verbose, reader);
 }
 
 export function exitCodeFor(result: CommandResult): number {

package/src/package-boundaries.ts

@@ -0,0 +1,110 @@
+// `packages/` may not import `apps/`: a shared package that depends on one app is no longer shared.
+// Its own rule and its own read, beside `app-boundaries.ts`: `readAppSources` is what the surface
+// graph walks, and a package source joining that graph would change every surface verdict too.
+// No per-package tiers: the layout of an app's `packages/` is the app's.
+
+import { existsSync } from 'node:fs'; // why: a synchronous directory probe; Bun.file answers files.
+// why: Bun ships no `Bun.*` path API: `joinPath` reaches a file on disk with the host's separator.
+import { join as joinPath } from 'node:path';
+// why: no Bun path API; the POSIX variants resolve specifiers against repo-relative keys, which
+// are POSIX on every host.
+import { dirname, join, normalize } from 'node:path/posix';
+import { ERROR_DOCS_URL, stringField } from '@ultimat3/core';
+import type { SourceFile } from './app-boundaries';
+import { commentSafe } from './comment-safe';
+import { scanRuntimeImports } from './import-scan';
+import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
+import { toPosix } from './posix-path';
+import { isEntityModule } from './templates/entity-module';
+
+const DB_SOURCES = 'packages/db/src/';
+
+/** Each app workspace's package name → its directory: `@acme/web` → `apps/web`. */
+export type AppWorkspaces = ReadonlyMap<string, string>;
+
+/** Where a specifier lands inside `apps/`, or `undefined` when it lands anywhere else. */
+const appTarget = (
+  from: string,
+  specifier: string,
+  workspaces: AppWorkspaces,
+): string | undefined => {
+  if (specifier.startsWith('.')) {
+    const target = normalize(join(dirname(from), specifier));
+    return target.startsWith('apps/') ? target : undefined;
+  }
+  if (specifier.startsWith('apps/')) return specifier;
+  for (const [name, dir] of workspaces) {
+    if (specifier === name) return dir;
+    if (specifier.startsWith(`${name}/`)) return `${dir}${specifier.slice(name.length)}`;
+  }
+  return undefined;
+};
+
+/**
+ * The one generated exception: `x g entity` adds its entity to the typed handle and `x new` to
+ * `schema.ts`, both in `packages/db/src/`, reading it from the slice that declares it
+ * (`templates/scaffold-db-client.ts`). An entity module, exactly: a `repo` there is a violation.
+ */
+const isDbEntry = (from: string, target: string): boolean =>
+  from.startsWith(DB_SOURCES) && isEntityModule(`${target}.ts`);
+
+/** Pure, so a caller holding the text needs no disk. Runtime imports only: `import type` erases. */
+export function packageToAppFindings(
+  files: readonly SourceFile[],
+  workspaces: AppWorkspaces,
+): readonly Finding[] {
+  return files.flatMap((file) =>
+    scanRuntimeImports(file).flatMap((specifier) => {
+      const target = appTarget(file.path, specifier, workspaces);
+      if (target === undefined || isDbEntry(file.path, target)) return [];
+      return [
+        {
+          code: 'X_BOUNDARY_PACKAGE_TO_APP',
+          cause: `package source imports an app ("${specifier}", in ${target}) — a package an app depends on cannot depend back on one app`,
+          fix: `x verify --only boundaries --json   # after moving ${commentSafe(target)} into the package, or importing in the opposite direction`,
+          docs: ERROR_DOCS_URL,
+          at: file.path,
+        },
+      ];
+    }),
+  );
+}
+
+const PACKAGE_GLOB = 'packages/*/**/*.{ts,tsx}';
+
+/** Every package source of an app: never a test, a dependency or a build's output. */
+export async function readPackageSources(root: string): Promise<readonly SourceFile[]> {
+  const files: SourceFile[] = [];
+  for await (const path of new Bun.Glob(PACKAGE_GLOB).scan({ cwd: root, absolute: false })) {
+    if (hasPathSegment(path, 'node_modules') || hasPathSegment(path, 'dist')) continue;
+    if (path.includes('.test.') || path.endsWith('.d.ts')) continue;
+    const posix = toPosix(path);
+    files.push({ path: posix, source: await Bun.file(joinPath(root, posix)).text() });
+  }
+  return files.sort((left, right) => (left.path < right.path ? -1 : 1));
+}
+
+/** `apps/*\/package.json`'s names, or `undefined` for a tree that holds no app at all. */
+const readAppWorkspaces = async (root: string): Promise<AppWorkspaces | undefined> => {
+  // A root with no `apps/` at all, before the walk: Bun's glob throws on a missing directory.
+  if (!existsSync(joinPath(root, 'apps'))) return undefined;
+  const found = new Map<string, string>();
+  for await (const path of new Bun.Glob('apps/*/package.json').scan({ cwd: root })) {
+    const manifest: unknown = await Bun.file(joinPath(root, path)).json();
+    // `stringField`: a parsed manifest is a value this process did not build (`caught-value-reads`).
+    const name = stringField(manifest, 'name');
+    if (name !== undefined) found.set(name, dirname(toPosix(path)));
+  }
+  return found;
+};
+
+/**
+ * The rule over a real tree. A tree with no `apps/` answers nothing: that is the framework's own
+ * repository, whose `packages/` is 3,000 files this rule has nothing to say about.
+ */
+export async function packageBoundaryFindings(root: string): Promise<readonly Finding[]> {
+  const workspaces = await readAppWorkspaces(root);
+  if (workspaces === undefined) return [];
+  return packageToAppFindings(await readPackageSources(root), workspaces);
+}

package/src/page-pins.ts

@@ -0,0 +1,23 @@
+// The pins a rendered document stamps (`@ultimat3/render`'s `clientPinTags`): every registered
+// action and query that declares `http: { path }`, read off the registries per render, so a
+// browser caller reaching one by NAME goes where the declaration put it — nothing restated.
+
+import { actionHttpPinOf, describeActions, getAction } from '@ultimat3/action';
+import type { ActionPin, ClientPins } from '@ultimat3/core';
+import { describeQueries, getQuery, queryHttpPinOf } from '@ultimat3/query';
+
+export function servedPins(): ClientPins {
+  const actions: Record<string, ActionPin> = {};
+  for (const { name } of describeActions()) {
+    const target = getAction(name);
+    const pin = target === undefined ? undefined : actionHttpPinOf(target);
+    if (pin !== undefined) actions[name] = pin;
+  }
+  const queries: Record<string, string> = {};
+  for (const { name } of describeQueries()) {
+    const target = getQuery(name);
+    const pin = target === undefined ? undefined : queryHttpPinOf(target);
+    if (pin !== undefined) queries[name] = pin.path;
+  }
+  return { actions, queries };
+}

package/src/plain-routes.ts

@@ -0,0 +1,13 @@
+// The plain routes both boots mount and `x routes` lists: `apps/<app>/runtime.ts`'s `routes`, then
+// every declared `webhookReceiver()`'s. Declaring a receiver is its one registration; a route the
+// app also named by hand is mounted once, never twice (`X_ROUTE_CONFLICT`).
+
+import type { Route } from '@ultimat3/http';
+import { webhookReceiverRoutes } from '@ultimat3/jobs';
+
+/** Called after the app's modules loaded: the receivers are read off the job registry. */
+export function plainRoutes(declared: readonly Route[] | undefined): readonly Route[] {
+  const own = declared ?? [];
+  const named = new Set(own);
+  return [...own, ...webhookReceiverRoutes().filter((route) => !named.has(route))];
+}

package/src/prerender-entries.ts

@@ -0,0 +1,59 @@
+// The pages each public `site/` route's `prerender()` lists, enumerated ONCE by the static export
+// while its in-process API scope and database are still open — and handed to `siteSeo` on the
+// report, so the sitemap never asks `prerender()` again after the build released both.
+
+import type { PrerenderEntry, RouteEntry } from '@ultimat3/render';
+import { enumeratePrerenderEntries } from '@ultimat3/render/server';
+
+/** Every route's enumeration, by its DECLARED path (`/posts/:slug`). */
+export type RouteEntries = ReadonlyMap<string, readonly PrerenderEntry[]>;
+
+export type EnumerateRoute = (entry: RouteEntry) => Promise<readonly PrerenderEntry[]>;
+
+/**
+ * `enumeratePrerenderEntries`, asked at most once per route: the build hands the one memo to the
+ * weigh-only branch (`measurePaths`) and to `enumerateRoutes`, so a budgeted dynamic route's
+ * `prerender()` runs once per build.
+ */
+export function enumerateOnce(): EnumerateRoute {
+  const asked = new Map<string, Promise<readonly PrerenderEntry[]>>();
+  return (entry) => {
+    const known = asked.get(entry.path);
+    if (known !== undefined) return known;
+    const answer = enumeratePrerenderEntries(entry);
+    asked.set(entry.path, answer);
+    return answer;
+  };
+}
+
+/**
+ * A route `siteSeo` would ask: public `site/` with a `prerender()` declared. One without has
+ * nothing to enumerate (`enumeratePrerenderEntries` answers from the pattern alone), so an app with
+ * none starts no database for it.
+ */
+export const asksPrerender = (entry: RouteEntry): boolean =>
+  entry.surface === 'site' &&
+  entry.config.policy === undefined &&
+  entry.config.prerender !== undefined;
+
+/**
+ * Each of `routes` that `asksPrerender`, enumerated in turn inside `scope` — the build's measuring
+ * scope, where a `prerender()` reading the app's own query is answered. A throw is the build's
+ * failure, exactly as it was when the sitemap made the call: a `prerender()` that cannot list its
+ * pages is the app's bug, never a page silently left out.
+ */
+export async function enumerateRoutes(
+  routes: readonly RouteEntry[],
+  scope: <T>(fn: () => Promise<T>) => Promise<T>,
+  before: () => Promise<void>,
+  enumerate: EnumerateRoute = enumeratePrerenderEntries,
+): Promise<RouteEntries> {
+  const asked = routes.filter(asksPrerender);
+  const entries = new Map<string, readonly PrerenderEntry[]>();
+  if (asked.length === 0) return entries;
+  await before();
+  for (const entry of asked) {
+    entries.set(entry.path, await scope(() => enumerate(entry)));
+  }
+  return entries;
+}

package/src/prerender-heaviest.ts

@@ -0,0 +1,27 @@
+// Single responsibility: name the heaviest thing a document boots by the source file an author can
+// open. Split from `prerender.ts`, which stands at its size ceiling.
+
+import type { IslandBundle } from './island-bundle';
+
+/**
+ * The heaviest thing the document actually boots, named by the source file an author can open.
+ * An island chunk is content-addressed, so its URL says nothing on its own — mapping it back
+ * through the bundle is what turns `X_BUDGET_EXCEEDED` from a number into an instruction.
+ */
+export function heaviestSource(
+  bundle: IslandBundle,
+  entries: readonly { readonly url: string; readonly bytes: number }[],
+): readonly string[] | undefined {
+  const heaviest = entries.reduce<{ url: string; bytes: number } | undefined>(
+    (max, entry) => (max === undefined || entry.bytes > max.bytes ? entry : max),
+    undefined,
+  );
+  if (heaviest === undefined) return undefined;
+  const chunk = bundle.chunkAt(heaviest.url);
+  if (chunk !== undefined) return [chunk.file];
+  // A shared chunk has no file of its own: the chain is an island on THIS page that imports it.
+  const importer = bundle.chunks.find(
+    (one) => one.imports.includes(heaviest.url) && entries.some((entry) => entry.url === one.url),
+  );
+  return importer === undefined ? [heaviest.url] : [importer.file, heaviest.url];
+}

package/src/prerender-preload.ts

@@ -0,0 +1,6 @@
+// Preloaded into `x build --target static`'s `bun run apps/web/prerender.ts`: installs the render
+// loader BEFORE Bun parses the script's import graph. A `.tsx` the script reaches statically (a
+// shared module that imports `@ultimat3/ui`) is parsed first, so a loader installed by evaluating
+// `@ultimat3/render` inside that graph arrives too late and Bun compiles the JSX to `jsxDEV`.
+
+import '@ultimat3/render/server';

package/src/prerender-report.ts

@@ -2,6 +2,8 @@
 // where the stats and the inventory landed. Split from `prerender.ts`, which decides what is
 // written; this file only names the shapes the report carries.
 
+import type { RouteEntries } from './prerender-entries';
+import type { LlmsPages } from './site-llms-pages';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 
 export interface PrerenderedPage {
@@ -55,4 +57,14 @@ export interface PrerenderReport {
   readonly warnings: readonly string[];
   /** The origin every absolute URL in the export was built against — hand it to `siteSeo`. */
   readonly origin: string;
+  /**
+   * Every page each public `site/` route's `prerender()` listed, enumerated once inside the build's
+   * scope — hand it to `siteSeo`, which then never asks `prerender()` after that scope is gone.
+   */
+  readonly entries: RouteEntries;
+  /**
+   * Every `llms.txt` page record whose `meta` needs its `load`, read inside the build's scope —
+   * hand it to `siteSeo` as `llmsPages`, which then never runs a `load` after that scope is gone.
+   */
+  readonly llmsPages: LlmsPages;
 }

package/src/prerender-seo-reads.ts

@@ -0,0 +1,38 @@
+// What `siteSeo` needs from the static build, read while its API scope and database are still open:
+// each `site/` route's `prerender()` entries and each `llms.txt` page's `load`. Asked after the
+// scope closes, a route that reads the app's own query fails the export.
+
+import { routeEntries } from '@ultimat3/render';
+import { type EnumerateRoute, enumerateRoutes, type RouteEntries } from './prerender-entries';
+import { loadSiteSettings } from './site-config';
+import { collectLlmsPages, type LlmsPages } from './site-llms-pages';
+
+export interface SeoReadsInput {
+  readonly root: string;
+  readonly origin: string;
+  readonly defaultLocale: string;
+  /** Runs one read inside the build's PUBLIC scope: its in-process API authenticates nobody. */
+  readonly scope: <T>(fn: () => Promise<T>) => Promise<T>;
+  /** Readies the build's database before the first read that needs it. */
+  readonly before: () => Promise<void>;
+  /** The build's one enumeration memo, so a route's `prerender()` runs once per build. */
+  readonly enumerate: EnumerateRoute;
+}
+
+export interface SeoReads {
+  readonly entries: RouteEntries;
+  readonly llmsPages: LlmsPages;
+}
+
+export async function collectSeoReads(input: SeoReadsInput): Promise<SeoReads> {
+  const entries = await enumerateRoutes(routeEntries(), input.scope, input.before, input.enumerate);
+  const llmsPages = await collectLlmsPages({
+    baseUrl: input.origin,
+    defaultLocale: input.defaultLocale,
+    enabled: (await loadSiteSettings(input.root)).llms,
+    entries,
+    scope: input.scope,
+    before: input.before,
+  });
+  return { entries, llmsPages };
+}

package/src/prerender-served.ts

@@ -9,14 +9,21 @@ import type { MeasureOptions } from './budgets';
 import type { IslandBundle } from './island-bundle';
 import { isRuntimeChunk } from './island-runtime';
 import { pageSync } from './page-sync';
+import type { VitalsBuild } from './prerender-vitals';
 import { realtimeConfigOf } from './runtime-realtime';
 import { PAGE_BOOT_BASE_PATH } from './worker-bundle';
+import { zoneBoot } from './zone-boot';
 
 /** What a served-document measurement adds: to the document's options, and to the measurer's. */
 export interface ServedMeasure {
   readonly document: {
     readonly sync?: ClientSyncHead;
     readonly persisted?: () => readonly string[];
+    /**
+     * `/x-client-vitals.js`, when `clientErrors.vitals` lists `app`, and the zone script when
+     * `time.detect` is on: served, so charged — both are the app's opt-in.
+     */
+    readonly appHead?: string;
   };
   readonly measure: MeasureOptions;
 }
@@ -24,25 +31,33 @@ export interface ServedMeasure {
 /**
  * `realtime.enabled: false` serves no sync head and no boot (`pageSync`), and then the measurement
  * adds nothing: such a page's realtime islands load the runtime chunk, and are charged for it.
+ *
+ * Real-user timings ride the same way: an `app/` document of an app that listed `app` names
+ * `/x-client-vitals.js`, which no artifact holds, so its bytes come from `vitals.script`. Charged,
+ * not exempted (`budgets.ts`' `FRAMEWORK_SCRIPTS`): the app opted in, and can opt out.
  */
 export async function servedMeasure(
   root: string,
   buildId: string,
   islands: IslandBundle,
+  vitals: VitalsBuild = {},
 ): Promise<ServedMeasure> {
-  const sync = await pageSync(
-    root,
-    process.env,
-    buildId,
-    realtimeConfigOf(await loadAppConfig(root)),
-  );
+  const config = await loadAppConfig(root);
+  const sync = await pageSync(root, process.env, buildId, realtimeConfigOf(config));
+  const appHead = (zoneBoot(config?.time)?.head ?? '') + (vitals.appHead ?? '');
   return {
     document: {
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
+      ...(appHead === '' ? {} : { appHead }),
     },
     measure: {
-      served: new Map(sync.scripts.map((script) => [script.url, script.code])),
+      served: new Map([
+        ...sync.scripts.map((script): [string, string] => [script.url, script.code]),
+        ...(vitals.appHead === undefined || vitals.script === undefined
+          ? []
+          : [[vitals.script.url, vitals.script.code] as [string, string]]),
+      ]),
       boot: {
         prefix: `${PAGE_BOOT_BASE_PATH}/`,
         supplies: new Set(islands.shared.map((one) => one.url).filter(isRuntimeChunk)),

package/src/prerender-vitals.ts

@@ -0,0 +1,42 @@
+// What the build adds for real-user timings (`clientErrors.vitals`): the head each surface's
+// documents carry and the script's bytes, so the budgets step weighs a page as it is SERVED. Off,
+// or a surface not listed, adds nothing — and a page that carries nothing is charged nothing.
+
+import type { ClientVitalsConfig } from '@ultimat3/core';
+import {
+  CLIENT_VITALS_PATH,
+  CLIENT_VITALS_SCRIPT_PATH,
+  clientVitalsHead,
+  clientVitalsScript,
+} from './client-vitals-script';
+
+export interface VitalsBuild {
+  /** For an `app/` document weighed as served. Absent unless `app` is listed. */
+  readonly appHead?: string;
+  /** For a `site/` document, exported and weighed. Absent unless `site` is listed. */
+  readonly siteHead?: string;
+  /** The bytes behind the head, keyed by the URL a document names. Absent when off. */
+  readonly script?: { readonly url: string; readonly code: string };
+}
+
+export function vitalsBuild(config: ClientVitalsConfig | undefined): VitalsBuild {
+  if (config?.enabled !== true) return {};
+  const head = clientVitalsHead();
+  return {
+    ...(config.surfaces.includes('app') ? { appHead: head } : {}),
+    ...(config.surfaces.includes('site') ? { siteHead: head } : {}),
+    script: { url: CLIENT_VITALS_SCRIPT_PATH, code: clientVitalsScript(config.sampleRate) },
+  };
+}
+
+/**
+ * A `site/` page exported with the script names a beacon route only a served process answers:
+ * on a static host the timings go nowhere. Said, never refused — the same export served by the
+ * container does land them, and the bytes are charged either way.
+ */
+export function clientVitalsStaticWarning(build: VitalsBuild): string[] {
+  if (build.siteHead === undefined) return [];
+  return [
+    `clientErrors.vitals.surfaces lists site, and a static host serves no ${CLIENT_VITALS_PATH} route — exported site/ pages carry ${CLIENT_VITALS_SCRIPT_PATH}, and their beacons land only where the app is served (x dev, or the container)`,
+  ];
+}