@ultimat3/cli 22.2.2 → 22.3.1

package/src/shot-locale.ts

@@ -0,0 +1,67 @@
+// Which locale a picture is of. `x shot` pins `Accept-Language` on every capture — to `--locale`
+// when one is asked for and to the app's DEFAULT locale otherwise — so a screenshot never depends
+// on the language of the machine's Chrome. A non-default locale is also a URL prefix (`/en/…`),
+// because on a `site/` route the unprefixed path is always the default locale whatever the header.
+
+import { join } from 'node:path'; // why: Bun ships no path join.
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+import { BadFlagError } from './errors';
+
+export interface ShotLocales {
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+}
+
+/** An app that declares nothing is `en` only — the framework's own default. */
+export const FALLBACK_SHOT_LOCALES: ShotLocales = { locales: ['en'], defaultLocale: 'en' };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/** `app.config.ts`'s `locales` and `defaultLocale`, read the way `loadThemeMode` reads `theme`. */
+export async function loadShotLocales(root: string): Promise<ShotLocales> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return FALLBACK_SHOT_LOCALES;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return FALLBACK_SHOT_LOCALES;
+  const declared = config['locales'];
+  const locales = Array.isArray(declared)
+    ? declared.filter((locale): locale is string => typeof locale === 'string')
+    : [];
+  const fallback = config['defaultLocale'];
+  const defaultLocale =
+    typeof fallback === 'string' && fallback !== '' ? fallback : (locales[0] ?? 'en');
+  return {
+    locales: locales.length === 0 ? [defaultLocale] : locales,
+    defaultLocale,
+  };
+}
+
+/** `--locale <l>`, refused by name when the app does not declare it — a typo costs no browser. */
+export function readLocaleFlag(value: string | undefined, app: ShotLocales): string | undefined {
+  if (value === undefined) return undefined;
+  if (app.locales.includes(value)) return value;
+  throw new BadFlagError({
+    flag: 'locale',
+    command: 'shot',
+    reason: `"${value}" is not one of the app's locales (${app.locales.join(', ')})`,
+    fix: `x shot / --locale ${app.defaultLocale} --json`,
+  });
+}
+
+/**
+ * The path a visitor in `locale` opens: unchanged for the default locale, `/<locale>/…` for any
+ * other. The root keeps its trailing slash (`/en/`), which is the directory a static export writes
+ * the prefixed home page to.
+ */
+export function localizedShotPath(route: string, locale: string, defaultLocale: string): string {
+  if (locale === defaultLocale) return route;
+  return route === '/' ? `/${locale}/` : `/${locale}${route}`;
+}
+
+/** The header every capture sends. One key, lower-case, as CDP forwards it verbatim. */
+export const acceptLanguageHeaders = (locale: string): Readonly<Record<string, string>> => ({
+  'accept-language': locale,
+});

package/src/shot-verdict.ts

@@ -25,6 +25,9 @@ export const SHOT_MESSAGE_KEYS = [
   'cli.shot.ok',
   'cli.shot.errors',
   'cli.shot.redirected',
+  'cli.shot.status',
+  'cli.shot.document',
+  'cli.shot.documentUnknown',
   'cli.shot.picture',
   'cli.shot.verdict',
   'cli.shot.server.booted',
@@ -146,6 +149,13 @@ export interface ShotInput {
   readonly networkDropped: number;
   /** `null` when the probe could not run or did not parse. Never a zero standing in for unknown. */
   readonly islands: IslandCount | null;
+  /**
+   * The document's status as read right after navigation. Only a fallback: the network ring is
+   * bounded, so on a page of a few hundred requests the document entry may be gone by capture time.
+   */
+  readonly landedStatus?: number | null | undefined;
+  /** `--expect-status`: the one status this shot is ok with. Absent means any 2xx. */
+  readonly expectStatus?: number | undefined;
 }
 
 export interface ShotVerdict extends ShotInput {
@@ -161,10 +171,44 @@ export interface ShotVerdict extends ShotInput {
    * gating, like a console warning: a missing favicon would otherwise fail every shot of every app.
    */
   readonly failed: number;
+  /**
+   * The HTTP status of the document photographed. `null` when no driver response carried one —
+   * "not seen" never gates, like an uncounted island, and is never reported as a 200.
+   */
+  readonly status: number | null;
+  /** The status asked for with `--expect-status`, or `null` for "any 2xx". */
+  readonly expectedStatus: number | null;
   /** What this verdict cannot see, stated every time — a `0` whose blind spots are named. */
   readonly blind: readonly string[];
 }
 
+const withoutFragment = (url: string): string => {
+  const hash = url.indexOf('#');
+  return hash === -1 ? url : url.slice(0, hash);
+};
+
+/**
+ * The status of the LAST document response at `url` — the last, because a reload or a redirect
+ * back re-requests it and the picture is of the latest. The fragment is dropped: `location.href`
+ * keeps it and no request ever carries one.
+ */
+export function documentStatus(network: readonly NetworkEntry[], url: string): number | null {
+  const target = withoutFragment(url);
+  for (let index = network.length - 1; index >= 0; index -= 1) {
+    const entry = network[index];
+    if (entry === undefined || entry.resourceType !== 'document') continue;
+    if (withoutFragment(entry.url) !== target) continue;
+    if (entry.status !== undefined) return entry.status;
+  }
+  return null;
+}
+
+/** ok for a status: the one expected, or any 2xx when none was. Unseen is not a failure. */
+const statusOk = (status: number | null, expected: number | null): boolean => {
+  if (expected !== null) return status === expected;
+  return status === null || (status >= 200 && status < 300);
+};
+
 /**
  * What a shot is blind to, each naming the mechanism rather than apologising. Constant because
  * these are properties of the browser port, not of a run — and in the artifact because `errors: 0`
@@ -183,7 +227,7 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
   lines.filter((line) => line.level === level).length;
 
 /**
- * `ok` is four conditions, and every one is something a picture cannot show: nothing on the page
+ * `ok` is five conditions, and every one is something a picture cannot show: nothing on the page
  * logged an error, nothing THREW, no island's `mount()` REJECTED, and the document photographed is
  * the route that was asked for.
  *
@@ -195,16 +239,23 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
  * an uncounted probe (`null`) out of the verdict — "not counted" is not "none failed".
  * A redirect is a failure of the CAPTURE rather than of the app: an agent that
  * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
+ * A fifth (`As of 2026-09-26`): the document answered 2xx, or exactly `--expect-status`. A 404
+ * page is clean by every other clause, and `x shot /typo` reported it ok.
  */
 export function buildVerdict(input: ShotInput): ShotVerdict {
   const errors = levelCount(input.console, 'error');
+  const status = documentStatus(input.network, input.finalUrl) ?? input.landedStatus ?? null;
+  const expectedStatus = input.expectStatus ?? null;
   return {
     ...input,
     ok:
       errors === 0 &&
       input.pageErrors.length === 0 &&
       (input.islands?.failed ?? 0) === 0 &&
-      input.requestedUrl === input.finalUrl,
+      input.requestedUrl === input.finalUrl &&
+      statusOk(status, expectedStatus),
+    status,
+    expectedStatus,
     redirected: input.requestedUrl !== input.finalUrl,
     errors,
     warnings: levelCount(input.console, 'warn'),
@@ -241,6 +292,8 @@ export function verdictJson(verdict: ShotVerdict): JsonValue {
     requestedUrl: verdict.requestedUrl,
     finalUrl: verdict.finalUrl,
     redirected: verdict.redirected,
+    status: verdict.status,
+    expectedStatus: verdict.expectedStatus,
     server: verdict.server,
     capturedAt: verdict.capturedAt,
     screenshot: verdict.screenshot,
@@ -301,6 +354,9 @@ export function shotLines(artifacts: ShotArtifacts): readonly string[] {
   const canvas = verdict.canvas;
   return [
     msg(`cli.shot.server.${verdict.server}`, { url: verdict.finalUrl }),
+    verdict.status === null
+      ? msg('cli.shot.documentUnknown')
+      : msg('cli.shot.document', { status: verdict.status }),
     canvas === null
       ? msg('cli.shot.canvasUnreadable', { bytes: verdict.bytes.byteLength })
       : msg('cli.shot.canvas', { width: canvas.width, height: canvas.height }),
@@ -338,6 +394,13 @@ export const shotSummary = (verdict: ShotVerdict): string => {
   if (verdict.redirected) {
     return msg('cli.shot.redirected', { route: verdict.route, url: verdict.finalUrl });
   }
+  if (!statusOk(verdict.status, verdict.expectedStatus)) {
+    return msg('cli.shot.status', {
+      route: verdict.route,
+      status: verdict.status ?? 'unseen',
+      expected: verdict.expectedStatus ?? '2xx',
+    });
+  }
   // Ahead of the console count, because a throw is the more severe fact AND the quieter one: an
   // island that died can log nothing at all, so `errors` would report a clean page.
   if (verdict.pageErrors.length > 0) {

package/src/site-asset-routes.ts

@@ -0,0 +1,106 @@
+// Serving `apps/web/site/assets/**` at the hashed URLs `asset()` mints. Mounted by `assetRoutes`,
+// which both `x dev` and the container compose, so a picture that paints on a laptop paints in the
+// image. Byte ranges are answered because Safari will not play an `<video>` from a server that
+// ignores `Range`, and a film that plays everywhere but an iPhone is not a film that ships.
+
+import { isUltimateError } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import type { SiteAsset, SiteAssetTable } from './site-assets';
+import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
+
+/** The URL is the content, so the answer is `public, max-age=31536000, immutable`. */
+export const SITE_ASSET_CACHE: CacheHint = { mode: 'immutable' };
+
+const notFound = (code: string, cause: string, fix: string): Response =>
+  json({ ok: false, error: { code, cause, fix } }, { status: 404 });
+
+/** One `bytes=` range, resolved against the file's size; `null` when it cannot be satisfied. */
+export function byteRange(
+  header: string | null,
+  size: number,
+): { readonly start: number; readonly end: number } | null | undefined {
+  if (header === null) return undefined;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  // A multi-range or a unit we do not speak: RFC 9110 lets a server ignore Range and send it all.
+  if (match === null) return undefined;
+  const [, from = '', to = ''] = match;
+  if (from === '' && to === '') return null;
+  if (from === '') {
+    const suffix = Number(to);
+    if (suffix === 0) return null;
+    return { start: Math.max(0, size - suffix), end: size - 1 };
+  }
+  const start = Number(from);
+  const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);
+  if (start >= size || end < start) return null;
+  return { start, end };
+}
+
+function assetResponse(asset: SiteAsset, range: string | null): Response {
+  const file = Bun.file(asset.file);
+  const headers: Record<string, string> = {
+    'content-type': asset.contentType,
+    'accept-ranges': 'bytes',
+  };
+  const wanted = byteRange(range, asset.bytes);
+  if (wanted === null) {
+    return new Response(null, {
+      status: 416,
+      headers: { ...headers, 'content-range': `bytes */${String(asset.bytes)}` },
+    });
+  }
+  if (wanted === undefined) {
+    return applyCacheHeaders(new Response(file, { headers }), SITE_ASSET_CACHE);
+  }
+  return applyCacheHeaders(
+    new Response(file.slice(wanted.start, wanted.end + 1), {
+      status: 206,
+      headers: {
+        ...headers,
+        'content-range': `bytes ${String(wanted.start)}-${String(wanted.end)}/${String(asset.bytes)}`,
+      },
+    }),
+    SITE_ASSET_CACHE,
+  );
+}
+
+/**
+ * Only the HASHED name is served, and only while the bytes still hash to it: an immutable answer
+ * under a URL whose bytes changed would be cached for a year by every CDN that saw it. A stale
+ * hash is a document from an earlier build, and says so.
+ */
+export function siteAssetRoutes(table: SiteAssetTable): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${SITE_ASSET_BASE_PATH}/*file`,
+      meta: { name: 'assets.site', auth: 'public', tags: ['assets'] },
+      handler: (request: UltimateRequest): Response => {
+        const named = parseHashedAssetUrl(request.pathname);
+        if (named === undefined) {
+          return notFound(
+            'X_ROUTE_NOT_FOUND',
+            `${request.pathname} is not a hashed site asset URL`,
+            "name the file with asset('assets/…') in the page, which returns the URL this route serves",
+          );
+        }
+        let asset: SiteAsset;
+        try {
+          asset = table.resolve(named.path);
+        } catch (error) {
+          if (!isUltimateError(error)) throw error;
+          return notFound(error.code, error.cause, error.fix);
+        }
+        if (asset.hash !== named.hash) {
+          return notFound(
+            'X_ROUTE_NOT_FOUND',
+            `${named.path} is at ${asset.url} now — the document asking for ${request.pathname} was rendered against earlier bytes`,
+            'reload the page; it names the current URL',
+          );
+        }
+        return assetResponse(asset, request.headers.get('range'));
+      },
+    },
+  ];
+}

package/src/site-assets.ts

@@ -0,0 +1,177 @@
+// The site asset table: every file under `apps/web/site/assets/`, named by a content-hashed URL.
+// One table per app root answers all three questions — the URL `asset()` returns while a page
+// renders, the file `/assets/*` serves, and the copy `x build --target static` writes — so the
+// page, the container and the CDN can never name one file three ways.
+
+// why: `asset()` is called from a synchronous render, so the table answers synchronously — and Bun
+// ships no sync stat or sync read; `join`/`relative` because Bun ships no path API either.
+import { copyFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path'; // why: Bun ships no path API.
+import type { AssetExtension, AssetPath } from '@ultimat3/render';
+import { ASSET_DIR, AssetMissingError, assetPathProblem } from '@ultimat3/render';
+
+/** App-root-relative, beside `favicon.ico`: `apps/web/site/` is where an app's public files live. */
+export const SITE_ASSETS_SOURCE = `apps/web/site/${ASSET_DIR}`;
+
+/** The URL prefix every hashed asset is served under, and the export directory it is copied to. */
+export const SITE_ASSET_BASE_PATH = `/${ASSET_DIR}`;
+
+/** What each served extension IS. `vtt` carries a charset: captions are text a player decodes. */
+export const ASSET_CONTENT_TYPES: Readonly<Record<AssetExtension, string>> = {
+  avif: 'image/avif',
+  webp: 'image/webp',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  woff2: 'font/woff2',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  vtt: 'text/vtt; charset=utf-8',
+};
+
+export interface SiteAsset {
+  /** As `asset()` names it: `assets/brand/logo.svg`. */
+  readonly path: AssetPath;
+  /** Absolute path on disk. */
+  readonly file: string;
+  /** xxHash32 of the bytes, 8 hex characters — the algorithm `contentHash` uses for CSS. */
+  readonly hash: string;
+  /** `/assets/brand/logo.<hash>.svg`. */
+  readonly url: string;
+  readonly contentType: string;
+  readonly bytes: number;
+}
+
+const splitExtension = (path: string): { readonly stem: string; readonly extension: string } => {
+  const dot = path.lastIndexOf('.');
+  return { stem: path.slice(0, dot), extension: path.slice(dot + 1) };
+};
+
+/** The hash goes before the extension, so a static host still infers the type from the name. */
+export function hashedAssetUrl(path: AssetPath, hash: string): string {
+  const { stem, extension } = splitExtension(path);
+  return `/${stem}.${hash}.${extension}`;
+}
+
+const HASHED = /^\/(assets\/.+)\.([0-9a-f]{8})\.([a-z0-9]+)$/i;
+
+/** The inverse of `hashedAssetUrl`: which asset a request names, and at which content. */
+export function parseHashedAssetUrl(
+  pathname: string,
+): { readonly path: AssetPath; readonly hash: string } | undefined {
+  const match = HASHED.exec(pathname);
+  if (match === null) return undefined;
+  const path = `${match[1] ?? ''}.${match[3] ?? ''}`;
+  if (assetPathProblem(path) !== undefined) return undefined;
+  return { path: path as AssetPath, hash: match[2] ?? '' };
+}
+
+const hashBytes = (bytes: Uint8Array): string =>
+  Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0');
+
+export interface SiteAssetTable {
+  /** The asset `asset()` named, hashed as the bytes are NOW. Throws `X_ASSET_MISSING`. */
+  resolve(path: AssetPath): SiteAsset;
+  /** Every servable file under the source directory, sorted by path. */
+  all(): readonly SiteAsset[];
+}
+
+const missing = (path: string, cause: string): AssetMissingError =>
+  new AssetMissingError(
+    `asset(${JSON.stringify(path)}): ${cause}`,
+    `add the file at ${SITE_ASSETS_SOURCE}/${path.slice(ASSET_DIR.length + 1)}, or correct the path passed to asset(), then x build --target static --json`,
+  );
+
+/**
+ * A stat per call, a read only when the file changed: `x dev` sees an edited image under a new URL
+ * on the next render with no watcher, and the container — whose files never change — pays one
+ * `stat` per `asset()` call and nothing else. One behaviour in both, never a dev-only rescan.
+ */
+export function createSiteAssetTable(root: string): SiteAssetTable {
+  const source = join(root, SITE_ASSETS_SOURCE);
+  const cache = new Map<string, { readonly stamp: string; readonly asset: SiteAsset }>();
+
+  const resolve = (path: AssetPath): SiteAsset => {
+    const problem = assetPathProblem(path);
+    if (problem !== undefined) throw missing(path, problem);
+    const file = join(source, path.slice(ASSET_DIR.length + 1));
+    let stamp: string;
+    try {
+      const stat = statSync(file);
+      if (!stat.isFile()) throw missing(path, `${file} is not a file`);
+      stamp = `${String(stat.mtimeMs)}:${String(stat.size)}`;
+    } catch (error) {
+      if (error instanceof AssetMissingError) throw error;
+      throw missing(path, `no file at ${SITE_ASSETS_SOURCE}/${path.slice(ASSET_DIR.length + 1)}`);
+    }
+    const cached = cache.get(path);
+    if (cached !== undefined && cached.stamp === stamp) return cached.asset;
+    const bytes = readFileSync(file);
+    const hash = hashBytes(bytes);
+    // `assetPathProblem` already refused an unknown extension; the guard keeps `constructor` from
+    // ever answering an `Object` member if that check is loosened.
+    const extension = splitExtension(path).extension.toLowerCase();
+    const asset: SiteAsset = {
+      path,
+      file,
+      hash,
+      url: hashedAssetUrl(path, hash),
+      contentType: Object.hasOwn(ASSET_CONTENT_TYPES, extension)
+        ? ASSET_CONTENT_TYPES[extension as AssetExtension]
+        : 'application/octet-stream',
+      bytes: bytes.byteLength,
+    };
+    cache.set(path, { stamp, asset });
+    return asset;
+  };
+
+  const all = (): readonly SiteAsset[] => {
+    const found: SiteAsset[] = [];
+    let files: string[];
+    try {
+      files = [...new Bun.Glob('**/*').scanSync({ cwd: source, onlyFiles: true })];
+    } catch {
+      // No `assets/` directory is an app with no assets, not an error.
+      return [];
+    }
+    for (const relativePath of files.sort()) {
+      const path = `${ASSET_DIR}/${relativePath.split('\\').join('/')}`;
+      // A source file beside its renditions (a `.psd`, a `README.md`) is not a served asset.
+      if (assetPathProblem(path) !== undefined) continue;
+      found.push(resolve(path as AssetPath));
+    }
+    return found;
+  };
+
+  return { resolve, all };
+}
+
+/** One table per root, so the renderer and the route read the same cache. */
+const tables = new Map<string, SiteAssetTable>();
+
+export function siteAssetTable(root: string): SiteAssetTable {
+  let table = tables.get(root);
+  if (table === undefined) {
+    table = createSiteAssetTable(root);
+    tables.set(root, table);
+  }
+  return table;
+}
+
+/**
+ * Every asset, copied into the static export under its hashed URL — a static host serves with no
+ * process behind it, so the artifact carries every byte a document names. Returns the URLs written.
+ */
+export function writeSiteAssets(root: string, out: string): readonly string[] {
+  const written: string[] = [];
+  for (const asset of siteAssetTable(root).all()) {
+    const target = join(out, asset.url.slice(1));
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(asset.file, target);
+    written.push(asset.url);
+  }
+  return written;
+}

package/src/site-config.ts

@@ -0,0 +1,79 @@
+// The public origin and the crawler rules out of `app.config.ts` — `site.origin` and
+// `seo.robots.disallow` — and the one resolution of "which origin is this site served on" every
+// absolute URL a document, a sitemap or a robots file carries is built against. Sibling of
+// `app-auth.ts`'s `loadSignInPath`, and it imports the config for the same reason.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
+import { join } from 'node:path';
+import type { AppConfig, Environment } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+export interface SiteSettings {
+  /** `site.origin`, trailing slash removed; `null` when the app declares none. */
+  readonly origin: string | null;
+  /** `seo.robots.disallow` — the paths a production `robots.txt` keeps crawlers out of. */
+  readonly disallow: readonly string[];
+}
+
+export const NO_SITE_SETTINGS: SiteSettings = { origin: null, disallow: [] };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Structural, never `instanceof`, for `loadSignInPath`'s reason: a config that resolved through an
+ * older core simply has no `site` section, and that is the "not declared" answer, not a crash.
+ */
+const hasSiteSections = (value: unknown): value is Pick<AppConfig, 'site' | 'seo'> =>
+  isRecord(value) &&
+  isRecord(value['site']) &&
+  isRecord(value['seo']) &&
+  isRecord(value['seo']['robots']);
+
+const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
+
+export async function loadSiteSettings(root: string): Promise<SiteSettings> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return NO_SITE_SETTINGS;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!hasSiteSections(config)) return NO_SITE_SETTINGS;
+  const origin = config.site.origin;
+  return {
+    origin: typeof origin === 'string' && origin !== '' ? trimSlash(origin) : null,
+    disallow: [...config.seo.robots.disallow],
+  };
+}
+
+/**
+ * The declared public origin: `APP_URL` (what the runtime already names it — OAuth's redirect, the
+ * sync node's admitted origin), then `SITE_ORIGIN` (the static build's), then `site.origin`.
+ * The environment first because one image is deployed to staging and production under two
+ * origins; the config line is what a deploy that sets neither falls back to. `undefined` when
+ * nothing names one — the caller decides whether the request's own origin will do.
+ */
+export function publicOrigin(
+  env: Readonly<Record<string, string | undefined>>,
+  site: SiteSettings,
+): string | undefined {
+  for (const key of ['APP_URL', 'SITE_ORIGIN']) {
+    const declared = env[key]?.trim() ?? '';
+    if (declared !== '') return trimSlash(declared);
+  }
+  return site.origin ?? undefined;
+}
+
+/**
+ * The sentence a production build prints when no origin was declared. Every canonical, `og:url`,
+ * hreflang and sitemap `<loc>` is then built against a placeholder, and a search engine indexes a
+ * page whose canonical names a host the site is not on. A warning, not a refusal: a production
+ * build on a laptop is how a deploy is rehearsed.
+ */
+export function originWarning(environment: Environment, declared: string | undefined): string[] {
+  if (environment !== 'production' || declared !== undefined) return [];
+  return [
+    'no public origin: set APP_URL (or SITE_ORIGIN) or `site: { origin }` in app.config.ts — ' +
+      'canonical, og:url, hreflang and the sitemap are absolute against a placeholder',
+  ];
+}

package/src/site-seo.ts

@@ -3,6 +3,7 @@
 // serves it), so a crawler reads the same two files from a CDN and from a container.
 
 import type { Environment } from '@ultimat3/core';
+import { localeConfig, localizedPath, routedLocales, unlocalizedPath } from '@ultimat3/i18n';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { enumeratePrerender, fillPath } from '@ultimat3/render/server';
@@ -24,6 +25,11 @@ export interface SiteSeoOptions {
    * the same list, enumerated by the same function the prerenderer calls.
    */
   readonly pagesFor?: ((routePath: string) => readonly string[]) | undefined;
+  /**
+   * `seo.robots.disallow` from `app.config.ts` (`loadSiteSettings`). Added to the production
+   * `User-agent: *` group; a non-production `robots.txt` still disallows everything.
+   */
+  readonly disallow?: readonly string[] | undefined;
 }
 
 export interface SiteSeo {
@@ -36,8 +42,15 @@ export interface SiteSeo {
 const isPublicSite = (entry: RouteEntry): boolean =>
   entry.surface === 'site' && entry.config.policy === undefined;
 
+/**
+ * A dynamic route's pages, UNPREFIXED and once each. A static export's report lists every locale's
+ * copy (`/blog/a` and `/en/blog/a`), and the sitemap localizes each page itself — reading the
+ * prefixed copies back as pages of their own listed `/en/en/blog/a`.
+ */
 const pagesOf = async (entry: RouteEntry, options: SiteSeoOptions): Promise<readonly string[]> => {
-  if (options.pagesFor !== undefined) return options.pagesFor(entry.path);
+  if (options.pagesFor !== undefined) {
+    return [...new Set(options.pagesFor(entry.path).map((path) => unlocalizedPath(path)))];
+  }
   const params = await enumeratePrerender(entry);
   return params.map((set) => fillPath(entry.pattern.source, set));
 };
@@ -65,13 +78,29 @@ async function publicSiteRoutes(options: SiteSeoOptions): Promise<readonly Route
 }
 
 export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
-  const sitemap = await buildSitemap(await publicSiteRoutes(options), { baseUrl: options.baseUrl });
+  // Every routed locale, with `xhtml:link` alternates: one `<url>` per page per locale, each
+  // naming the whole cluster and `x-default`. A single-locale app passes none and gets the plain
+  // urlset it always had — an alternates cluster of one is noise.
+  const locales = routedLocales();
+  const defaultLocale = localeConfig().fallback;
+  const sitemap = await buildSitemap(await publicSiteRoutes(options), {
+    baseUrl: options.baseUrl,
+    ...(locales.length < 2
+      ? {}
+      : {
+          locales,
+          defaultLocale,
+          localizePath: (path: string, locale: string) =>
+            localizedPath(path, locale, defaultLocale),
+        }),
+  });
   // Past 50,000 URLs `files` are `/sitemap-N.xml` and the index is `/sitemap.xml`; below it,
   // `files` is that one file and there is no index.
   const sitemaps = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
   const robots = buildRobots({
     baseUrl: options.baseUrl,
     sitemaps: [SITEMAP_PATH],
+    ...(options.disallow === undefined ? {} : { disallow: options.disallow }),
     ...(options.environment === undefined ? {} : { environment: options.environment }),
   });
   return { robots, sitemaps };

package/src/templates/scaffold-entries.ts

@@ -65,7 +65,7 @@ const prerender =
 // landed on disk — which is what \`x build --target static --json\` reads back.
 
 import { join } from 'node:path';
-import { DEFAULT_ORIGIN, type PrerenderReport, prerenderSite, siteSeo } from '@ultimat3/cli';
+import { loadSiteSettings, type PrerenderReport, prerenderSite, siteSeo } from '@ultimat3/cli';
 
 const root = join(import.meta.dir, '..', '..');
 const flag = Bun.argv.indexOf('--out');
@@ -90,9 +90,11 @@ const origin = Bun.env.SITE_ORIGIN;
  * \`robots.txt\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
  * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
  */
-async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<readonly string[]> {
+async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]> {
   const seo = await siteSeo({
-    baseUrl,
+    // The origin the pages were built against, so the sitemap and every canonical agree.
+    baseUrl: report.origin,
+    disallow: (await loadSiteSettings(root)).disallow,
     pagesFor: (route) =>
       report.pages.filter((page) => page.route === route).map((page) => page.path),
   });
@@ -103,7 +105,7 @@ async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<
 
 if (import.meta.main) {
   const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
-  const seo = await writeSeoFiles(report, origin ?? DEFAULT_ORIGIN);
+  const seo = await writeSeoFiles(report);
   await Bun.stdout.write(
     \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report, seo })}\\n\`,
   );