@ultimat3/cli 22.2.2 → 22.3.1

package/src/cmd-test.ts

@@ -17,7 +17,14 @@ import type { CommandResult, JsonValue } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
-import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
+import {
+  discoverTests,
+  missingSelection,
+  readFilters,
+  readSample,
+  readType,
+  sampleFiles,
+} from './test-select';
 import { runShards } from './test-shards';
 import { defaultWorkers, SERIAL_TYPES, WORKER_CEILING } from './test-workers';
 import type { TestType } from './verify-tests';
@@ -100,16 +107,37 @@ const withScope = (result: CommandResult, scope: AffectedScope): CommandResult =
   data: { ...asObject(result.data), affected: affectedScopeJson(scope) },
 });
 
+/** The selection that matched nothing, as one phrase for `cli.test.empty`. */
+const describeSelection = (missing: { type?: string; filter?: string }): string =>
+  [
+    missing.type === undefined ? undefined : `type ${missing.type}`,
+    missing.filter === undefined ? undefined : `"${missing.filter}"`,
+  ]
+    .filter((part) => part !== undefined)
+    .join(' and ') || 'the selection';
+
 export const testCommand: CliCommand = {
   spec: testSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const type = readOnlyType(ctx.args.positionals);
     const filter = flagString(ctx.args, 'filter');
+    const filters = readFilters(filter);
     const sample = readSample(ctx.args);
     const scope = await readAffectedScope(ctx);
-    const discovered = await discoverTests(ctx.cwd, filter, type);
+    const discovered = await discoverTests(ctx.cwd, filters, type);
     if (discovered.length === 0) {
-      throw new NoTestFilesError({ root: ctx.cwd, ...missingSelection(type, filter) });
+      const missing = missingSelection(type, filter);
+      // `--allow-empty` is for a caller that COMPUTED the selection — a scoped runner handing over
+      // the paths a diff touched, some of which hold no test yet. Green, spawning nothing, and
+      // never read as "the suite passed": the line names the selection that matched nothing and
+      // `data.files` is 0. Without the flag an empty selection stays X_TEST_NO_FILES, because a
+      // typo'd `--filter` typed by hand is exactly the run that must not pass.
+      if (flagBool(ctx.args, 'allow-empty')) {
+        return ok('test', msg('cli.test.empty', { selection: describeSelection(missing) }), {
+          data: { ...missing, files: 0, empty: true },
+        });
+      }
+      throw new NoTestFilesError({ root: ctx.cwd, ...missing });
     }
     const selected =
       scope === undefined

package/src/cmd-verify-spec.ts

@@ -7,22 +7,22 @@ import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-worke
 export const verifySpec: CommandSpec = {
   name: 'verify',
   summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
-  usage: 'x verify [--only <step>] [--workers N] [--json]',
+  usage: 'x verify [--only <step>[,<step>…]] [--workers N] [--json]',
   requiresApp: true,
   // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
-  // spread, never which steps run. `--only` runs one step and says so in both renderers —
+  // spread, never which steps run. `--only` runs the steps it names and says so in both renderers —
   // never silently, which is the whole of what makes it safe to have.
   flags: [
     {
       name: 'workers',
       type: 'string',
-      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to free memory; min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
     },
     {
       name: 'only',
       type: 'string',
       summary:
-        'run ONE step by name — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
+        'run the named step(s), comma-separated, in one process — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
     },
   ],
 };

package/src/cmd-verify.ts

@@ -2,12 +2,12 @@
 // same list in the terminal and in --json, and a non-zero exit if any step fails. Green means
 // shippable (axiom 5): one step list, no second checklist, no CI-only step.
 //
-// `--only <step>` is the ONE narrowing, decided as D6, and it does not weaken that: the GATE is
-// the no-flag run, and a narrowed run says `NOT A GATE RUN` in the summary and in `--json` so no
+// `--only <step>[,<step>…]` is the ONE narrowing, decided as D6, and it does not weaken that: the
+// GATE is the no-flag run, and a narrowed run says `NOT A GATE RUN` in the summary and in `--json` so no
 // reader of either can take it for one. `--skip` stays refused — it would let a caller drop the
 // step that was going to fail and still read the output as a whole-tree verdict.
 
-import { nearestName } from '@ultimat3/core';
+import { nearestName, renderFixShellArg } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -35,7 +35,7 @@ export const verifyCommand: CliCommand = {
     // Both readers before the run: an unrunnable flag must be refused in milliseconds, not after
     // `tsc -b` has spent fourteen seconds on a run the caller cannot use.
     const workers = readWorkers(ctx.args);
-    const only = readOnlyStep(ctx.args);
+    const only = readOnlySteps(ctx.args);
     return runVerify(VERIFY_STEPS, {
       root,
       runner: ctx.runner,
@@ -47,28 +47,43 @@ export const verifyCommand: CliCommand = {
 };
 
 /**
- * The step `--only` names, or nothing. Refused against `VERIFY_STEP_NAMES` — the same constant the
- * runner's list is built from — so a typo can never be read as "narrow to no steps at all", which
- * is a run that passes by checking nothing.
+ * The steps `--only` names, or nothing: one step (`--only lint`) or a comma-separated list
+ * (`--only typecheck,lint,boundaries`) run in ONE process, in the gate's declared order whatever
+ * order they were typed in. Refused against `VERIFY_STEP_NAMES` — the same constant the runner's
+ * list is built from — so a typo can never be read as "narrow to no steps at all", which is a run
+ * that passes by checking nothing. An empty item (`lint,,drift`, a trailing comma) is refused for
+ * the same reason.
  *
- * A near miss leads with the step it is near; a word near NOTHING gets the gate itself rather than
- * an invented lead, which is the rule `parse.ts` already follows for a command that resembles
- * none. Both arms are commands that run.
+ * A near miss leads with the list as it would be with each typo corrected; an item near NOTHING
+ * gets the gate itself rather than an invented lead, which is the rule `parse.ts` already follows
+ * for a command that resembles none. Both arms are commands that run.
  */
-export const readOnlyStep = (args: ParsedArgs): VerifyStepName | undefined => {
+export const readOnlySteps = (args: ParsedArgs): readonly VerifyStepName[] | undefined => {
   const raw = flagString(args, 'only');
   if (raw === undefined) return undefined;
-  const found = VERIFY_STEP_NAMES.find((name) => name === raw);
-  if (found !== undefined) return found;
-  const suggestion = nearestName(raw, VERIFY_STEP_NAMES);
+  const items = raw.split(',').map((item) => item.trim());
+  const unknown = items.filter((item) => !isStepName(item));
+  if (unknown.length === 0) {
+    return VERIFY_STEP_NAMES.filter((name) => items.includes(name));
+  }
+  const corrected = items.map((item) =>
+    isStepName(item) ? item : nearestName(item, VERIFY_STEP_NAMES),
+  );
+  const fix = corrected.every((item) => item !== undefined)
+    ? `x verify --only ${renderFixShellArg([...new Set(corrected)].join(','), '<step,step>')} --json`
+    : 'x verify --json';
+  const named = unknown.map((item) => (item === '' ? '(empty)' : `"${item}"`)).join(', ');
   throw new BadFlagError({
     flag: 'only',
     command: 'verify',
-    reason: `"${raw}" is not a gate step (${VERIFY_STEP_NAMES.join(', ')})`,
-    fix: suggestion === undefined ? 'x verify --json' : `x verify --only ${suggestion} --json`,
+    reason: `${named} ${unknown.length === 1 ? 'is not a gate step' : 'are not gate steps'} (${VERIFY_STEP_NAMES.join(', ')})`,
+    fix,
   });
 };
 
+const isStepName = (raw: string): raw is VerifyStepName =>
+  (VERIFY_STEP_NAMES as readonly string[]).includes(raw);
+
 /**
  * Both bounds are the constants the flag summary already names, so `x help verify` and the reader
  * cannot disagree. Exported for the test that pins them: the command's `run` reaches this only

package/src/dev-route-table.ts

@@ -21,6 +21,7 @@ import { assetRoutes } from './runtime-assets';
 import { appRoutes } from './runtime-render';
 import { servedStorage, storageRoutes } from './runtime-storage';
 import { seoRoutes } from './seo-routes';
+import { loadSiteSettings, publicOrigin } from './site-config';
 import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
@@ -55,6 +56,9 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // is mounted, and the 0kb baseline is not spent on a `<link>` to a file that does not exist.
   const pwa = await loadPwaArtifacts(input.root);
   const theme = themeBoot(await loadThemeMode(input.root));
+  // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
+  const site = await loadSiteSettings(input.root);
+  const origin = publicOrigin(input.env, site);
   // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
   const sync = await pageSync(input.root, input.env, input.buildId, input.realtime);
   const errorStyles = await errorPageStyleSources(input.root);
@@ -101,7 +105,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     // captured at boot would answer 404 for the href the document now carries.
     ...styleRoutes(() => styleBundle()),
     // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
-    ...seoRoutes({ env: input.env }),
+    ...seoRoutes({ env: input.env, site }),
     // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
     // lives here rather than in a second server because everything it needs is in THIS process:
     // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
@@ -119,6 +123,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
       themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
     }),
   ];

package/src/error-contract.ts

@@ -42,6 +42,11 @@ export const COMMAND_TOKENS: readonly RegExp[] = [
   // Built from `fix-path.ts`'s extension list, because the token that makes a fix count as an
   // instruction is exactly the token `citedPathProblem` then has to resolve.
   new RegExp(FILE_TOKEN_PATTERN),
+  // A repo script, run as written: `bin/check --full`, `./bin/probe`. An app's gate is `bin/check`,
+  // so without this the one command its fixes most often name read as the banned word "check".
+  // Anchored like `x` above — `/usr/bin/env` and `robin/check` are not the repo's scripts.
+  // (`scripts/<name>.ts` is already a file token.)
+  /(?:^|[\s;|&("'`])(?:\.\/)?bin\/[\w.-]+/,
   /\b(?:app\.config\.ts|package\.json|tsconfig\.json|bunfig\.toml|\.env(?:\.[\w.-]+)?)\b/,
 ];
 

package/src/index.ts

@@ -145,6 +145,8 @@ export {
   serveApp,
 } from './serve';
 export { quoteArg } from './shell-quote';
+export type { SiteSettings } from './site-config';
+export { loadSiteSettings, publicOrigin } from './site-config';
 export type { SiteSeo, SiteSeoOptions } from './site-seo';
 export { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 export { eachSourceFile, isGenerated, isTest, SOURCE_GLOBS } from './source-files';

package/src/messages.ts

@@ -189,6 +189,12 @@ const CATALOG = {
   'cli.shot.ok': '{route} clean — {islands} island(s) mounted, nothing logged and nothing threw',
   'cli.shot.errors': '{route}: {errors} console error(s) — verdict.json names each one',
   'cli.shot.redirected': '{route} redirected to {url} — the picture is not the route asked for',
+  // After the redirect and before everything else: a 404 page can be spotless, and a picture of
+  // "Not found" read as the route is the capture lying about its subject.
+  'cli.shot.status':
+    '{route} answered HTTP {status}, expected {expected} — the picture is that response, not the page',
+  'cli.shot.document': '  document HTTP {status}',
+  'cli.shot.documentUnknown': '  document status not seen — the driver recorded no response for it',
   'cli.shot.server.booted': '  server   booted for this shot on {url}',
   'cli.shot.server.reused': '  server   the x dev already running on {url}',
   'cli.shot.canvas': '  canvas   {width}x{height}',
@@ -257,6 +263,7 @@ const CATALOG = {
     '    the diff has moved under this thread — {line} is where the comment was written',
   'cli.test.fail': '{failed} of {workers} shard(s) failed',
   'cli.test.affected.none': 'nothing is affected by {base}...HEAD — 0 test file(s) ran',
+  'cli.test.empty': 'no test file matches {selection} — 0 test file(s) ran (--allow-empty)',
   'cli.test.pass': '{files} test file(s) on {workers} worker(s) passed in {ms}ms',
   'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
   'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',

package/src/prerender-locales.ts

@@ -0,0 +1,34 @@
+// One `site/` route's static artifacts in every routed locale. The default locale's pages keep the
+// paths and files `renderStatic` computed; every other locale's are served at `/<locale>/<path>`
+// and written to `<locale>/<file>` — the layout every static host resolves with no rewrite rule.
+
+import { localeSegment, localizedPath } from '@ultimat3/i18n';
+import type { StaticArtifact } from '@ultimat3/render/server';
+
+/** A `StaticArtifact` placed for one locale: its served path and its file under `<locale>/`. */
+export type LocalizedArtifact = StaticArtifact & { readonly locale: string };
+
+/** The default's artifacts first, so a report lists the unprefixed page before its translations. */
+export async function localizedArtifacts(
+  locales: readonly string[],
+  defaultLocale: string,
+  renderIn: (locale: string) => Promise<readonly StaticArtifact[]>,
+): Promise<readonly LocalizedArtifact[]> {
+  const out: LocalizedArtifact[] = [];
+  for (const locale of locales) {
+    const isDefault = locale === defaultLocale;
+    for (const artifact of await renderIn(locale)) {
+      out.push({
+        ...artifact,
+        locale,
+        path: isDefault ? artifact.path : localizedPath(artifact.path, locale, defaultLocale),
+        outputPath: isDefault
+          ? artifact.outputPath
+          : `${localeSegment(locale)}/${artifact.outputPath}`,
+      });
+    }
+    // A route with no pages writes none in any locale; asking again per locale is the same answer.
+    if (out.length === 0) break;
+  }
+  return out;
+}

package/src/prerender.ts

@@ -4,7 +4,15 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
-import { createContext, isUltimateError, renderThrowable, runWithContext } from '@ultimat3/core';
+import {
+  createContext,
+  DEFAULT_ENVIRONMENT,
+  isUltimateError,
+  renderThrowable,
+  runWithContext,
+  tryResolveEnvironment,
+} from '@ultimat3/core';
+import { localeConfig, localizedPath, routedLocales } from '@ultimat3/i18n';
 import type { RouteEntry } from '@ultimat3/render';
 import { describeRoutes, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
@@ -19,9 +27,12 @@ import { buildIslands, writeIslands } from './island-bundle';
 import { measureDatabase } from './measure-database';
 import { measurePaths } from './measure-paths';
 import { measureScope, withAppUrl } from './measure-scope';
+import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
 import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import { routeDocument } from './runtime-render';
+import { writeSiteAssets } from './site-assets';
+import { loadSiteSettings, originWarning, publicOrigin } from './site-config';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 import { styleBundle, writeStyles } from './style-bundle';
@@ -53,15 +64,22 @@ export const isPrerenderable = (entry: RouteEntry): boolean =>
 export interface PrerenderOptions {
   readonly root: string;
   readonly out: string;
-  /** Origin the rendered `<head>` builds canonical and og:url from. */
+  /**
+   * Origin the rendered `<head>` builds canonical, og:url and hreflang from. Absent: `APP_URL`,
+   * `SITE_ORIGIN`, then `site.origin` from `app.config.ts`, then `DEFAULT_ORIGIN` — with a warning
+   * on a production build, because a placeholder canonical is one a search engine indexes.
+   */
   readonly origin?: string;
 }
 
 export interface PrerenderedPage {
   /** The DECLARED route, `/blog/:slug` — one route can write many pages, and the report groups them. */
   readonly route: string;
+  /** The URL the page is served at — `/en/pricing` for a non-default locale. */
   readonly path: string;
-  /** Relative to `out`, POSIX, as `renderStatic` computed it. */
+  /** The locale the page was rendered in. */
+  readonly locale: string;
+  /** Relative to `out`, POSIX — under `<locale>/` for a non-default locale. */
   readonly file: string;
   readonly hash: string;
   readonly bytes: number;
@@ -101,6 +119,10 @@ export interface PrerenderReport {
    * has to reach the build's own report. Empty for an app with no service worker.
    */
   readonly serviceWorkerWarnings: readonly string[];
+  /** What this build could not get right on its own — today, a production build with no origin. */
+  readonly warnings: readonly string[];
+  /** The origin every absolute URL in the export was built against — hand it to `siteSeo`. */
+  readonly origin: string;
 }
 
 /**
@@ -149,7 +171,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   await clearPrerenderOut(options.out, options.root);
   await loadApp(options.root);
   const buildId = (await appManifest(options.root)).manifest.buildId;
-  const origin = options.origin ?? DEFAULT_ORIGIN;
+  const declaredOrigin =
+    options.origin ?? publicOrigin(process.env, await loadSiteSettings(options.root));
+  const origin = declaredOrigin ?? DEFAULT_ORIGIN;
+  // Written to stderr as well as returned: an app's `prerender.ts` prints its report as ONE JSON
+  // line on stdout, and a build that parses it must not meet a warning inside it.
+  const warnings = originWarning(tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT, declaredOrigin);
+  for (const warning of warnings) process.stderr.write(`warning: ${warning}\n`);
+  // After `loadApp`: `defineCatalogs()` configures the locales on the app's own import. The
+  // default first, so every other pass writes beside a tree that already holds the unprefixed one.
+  const locales = routedLocales();
+  const defaultLocale = localeConfig().fallback;
   const pages: PrerenderedPage[] = [];
   const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
@@ -171,6 +203,9 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // pages whose `<link>` names a file the artifact does not have.
   const styles = styleBundle();
   await writeStyles(styles, options.out);
+  // The hashed `site/assets/**` copies every document's `asset()` URL names — once, never per
+  // locale: an asset is the same bytes in every language, so `/en/` pages link the root's copy.
+  writeSiteAssets(options.root, options.out);
   // Same rule, one asset further: a browser asks for `/favicon.ico` on the first page it loads,
   // and a static export has no route to answer it — so the bytes the served surfaces would have
   // returned go into the artifact instead of leaving a 404 in every visitor's console.
@@ -230,7 +265,12 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // build. One context for the build, `role: 'web'` because that is the role serving these
   // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
   // with the id the report and the stats carry.
-  const ctx = createContext({ role: 'web', buildId });
+  // ONE PER LOCALE, and the locale is the context's: `createContext` defaults it to core's `en`, so a
+  // Spanish-default site was prerendered in English — `<html lang="en">` over English copy — while
+  // the served process answered Spanish. Each `site/` page is rendered once per routed locale.
+  const contexts = new Map(
+    locales.map((locale) => [locale, createContext({ role: 'web', buildId, locale })]),
+  );
   // A SECOND scope, for the branch below that renders only to weigh (`measure-scope.ts`): a
   // request context holding the app's measurement actor, with the app's own API answered in
   // process, because an `app/` page's `load` calls policy-guarded queries over its typed client
@@ -244,10 +284,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     routeDocument(entry, data, {
       resolveIsland: (file: string) => islands.resolverFor(file),
       themeHead: theme.head,
+      origin,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
     });
-  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
-    runWithContext(ctx, () => render(entry, data));
+  const document = (
+    locale: string,
+    entry: RouteEntry,
+    data: { url: string; params: Record<string, string> },
+  ) =>
+    runWithContext(contexts.get(locale) ?? createContext({ role: 'web', buildId, locale }), () =>
+      render(entry, data),
+    );
 
   try {
     for (const entry of routeEntries()) {
@@ -303,10 +350,16 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         }
         continue;
       }
-      const artifacts = await renderStatic(
-        entry,
-        ({ path, params }) => document(entry, { url: new URL(path, origin).href, params }),
-        { buildId },
+      const artifacts = await localizedArtifacts(locales, defaultLocale, (locale) =>
+        renderStatic(
+          entry,
+          ({ path, params }) =>
+            document(locale, entry, {
+              url: new URL(localizedPath(path, locale, defaultLocale), origin).href,
+              params,
+            }),
+          { buildId },
+        ),
       );
       // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
       // `render: 'static'` route with a param writes nothing and used to be reported NOWHERE — past
@@ -329,6 +382,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         pages.push({
           route: entry.path,
           path: artifact.path,
+          locale: artifact.locale,
           file: artifact.outputPath,
           hash: artifact.hash,
           bytes,
@@ -403,5 +457,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     islands: islands.chunks.map((chunk) => chunk.file),
     styles: styles.chunks.map((chunk) => chunk.url),
     serviceWorkerWarnings: serviceWorker?.warnings ?? [],
+    warnings,
+    origin,
   };
 }

package/src/runtime-assets.ts

@@ -26,13 +26,17 @@ import {
   authorizeStorageRead,
   STORAGE_READ_PERMISSION,
 } from './runtime-storage';
+import { siteAssetRoutes } from './site-asset-routes';
+import { siteAssetTable } from './site-assets';
 
 /**
  * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.
  * Guarded exactly as `/_storage` is — an object reachable through two URLs must not be reachable
  * on two different terms — so a `src` under this path needs a signed-in reader holding
- * `storage:read`. A genuinely public image belongs in `apps/web/site/`, which is served as a
- * static asset and never touches a disk holding another tenant's uploads.
+ * `storage:read`. A genuinely public image belongs in `apps/web/site/assets/`, named with
+ * `asset('assets/…')`: served below at a content-hashed `/assets/*` URL, copied into the static
+ * export under the same name (`site-assets.ts`), and never touching a disk that holds another
+ * tenant's uploads.
  */
 export const MEDIA_BASE_PATH = '/media';
 
@@ -222,6 +226,10 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
   // container is the dev/prod difference this package's own rule forbids. `favicon.ts` owns what
   // the answer IS — this file only says the app's asset surface is where it hangs.
   routes.push(faviconRoute(options.root));
+  // And every other public file of the site: `apps/web/site/assets/**` at the hashed URLs
+  // `asset()` mints, immutable. The same table `loadApp` installed for the renderer, so the URL a
+  // document names and the URL this answers are one computation.
+  routes.push(...siteAssetRoutes(siteAssetTable(options.root)));
   // Same rule one asset further along: the icons above are the ones this manifest NAMES, so the
   // two belong to one surface and cannot be mounted from two places without drifting apart.
   if (options.pwa !== undefined) routes.push(pwaManifestRoute(options.pwa));

package/src/runtime-render.ts

@@ -26,7 +26,7 @@ import type {
   RouteParams,
 } from '@ultimat3/http';
 import { asCtx, html, NO_STORE, redirect, stream, takeRedirect } from '@ultimat3/http';
-import { currentLocale } from '@ultimat3/i18n';
+import { currentLocale, localeConfig } from '@ultimat3/i18n';
 import type {
   ClientSyncHead,
   IslandCollector,
@@ -107,6 +107,12 @@ export interface DocumentOptions {
    * with no scope carries none.
    */
   readonly persisted?: () => readonly string[];
+  /**
+   * The public origin canonical, `og:url` and hreflang are absolute against — `publicOrigin()`
+   * from `site-config.ts`. Absent, the request's own origin: a relative canonical is one a crawler
+   * resolves against whatever host it happened to fetch from, a CDN's or a preview's.
+   */
+  readonly origin?: string;
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -142,24 +148,37 @@ const headFor = async (
   data: RouteData,
   options: DocumentOptions,
   scope?: string,
-): Promise<string> =>
-  renderHead(
-    headFromMeta(
-      await entry.config.meta(metaContextFor(ctx, data)),
-      seoRenderers({ path: new URL(ctx.url).pathname }),
-      [
-        ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
-        // The page boot rides the scope tag: its whole job — restoring a principal's persisted
-        // records and replaying its queued writes — is per principal, and a shareable document
-        // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
-        ...(scope === undefined
-          ? []
-          : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
-      ],
-    ),
-  ) +
-  (options.themeHead ?? '') +
-  (options.pwaHead ?? '');
+): Promise<string> => {
+  const meta = metaContextFor(ctx, data);
+  const url = new URL(ctx.url);
+  return (
+    renderHead(
+      headFromMeta(
+        await entry.config.meta(meta),
+        seoRenderers({
+          path: url.pathname,
+          baseUrl: options.origin ?? url.origin,
+          localization: {
+            locale: meta.locale,
+            defaultLocale: localeConfig().fallback,
+            alternates: meta.alternates,
+          },
+        }),
+        [
+          ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
+          // The page boot rides the scope tag: its whole job — restoring a principal's persisted
+          // records and replaying its queued writes — is per principal, and a shareable document
+          // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
+          ...(scope === undefined
+            ? []
+            : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
+        ],
+      ),
+    ) +
+    (options.themeHead ?? '') +
+    (options.pwaHead ?? '')
+  );
+};
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
@@ -409,6 +428,9 @@ const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
   auth: entry.config.policy === undefined ? 'public' : 'required',
   render: entry.config.render,
   tags: [entry.surface],
+  // A `site/` page is prerendered once per locale and served as files, so its locale is its URL's:
+  // the unprefixed path is the default, and the served process must answer what the file says.
+  localeSource: entry.surface === 'site' ? 'path' : 'request',
   ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
   // Projected so the router screens its ages at mount (`assertRouteCache`) and the `cache-headers`
   // stage applies it to a response that wrote none — a loader's redirect. The rendered document

package/src/seo-routes.ts

@@ -5,24 +5,22 @@
 import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
+import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
 import { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 
 export interface SeoRoutesOptions {
   readonly env: Readonly<Record<string, string | undefined>>;
+  /** `site.origin` and `seo.robots.disallow` from `app.config.ts` (`loadSiteSettings`). */
+  readonly site?: SiteSettings;
 }
 
 /**
- * The public origin: `APP_URL`, the one the framework's runtime already names for it (OAuth's
- * redirect, the sync node's admitted origin); else `SITE_ORIGIN`, the static build's; else the
+ * The public origin — `publicOrigin()`: `APP_URL`, `SITE_ORIGIN`, then `site.origin` — else the
  * request's own. A container behind an ingress sees its pod address as the request's host, which
  * is why the declared origin comes first — a sitemap of `http://10.0.0.7:3000/…` indexes nothing.
  */
-function originOf(env: SeoRoutesOptions['env'], request: UltimateRequest): string {
-  for (const key of ['APP_URL', 'SITE_ORIGIN']) {
-    const declared = env[key]?.trim() ?? '';
-    if (declared !== '') return declared.replace(/\/+$/, '');
-  }
-  return new URL(request.url).origin;
+function originOf(options: SeoRoutesOptions, request: UltimateRequest): string {
+  return publicOrigin(options.env, options.site ?? NO_SITE_SETTINGS) ?? new URL(request.url).origin;
 }
 
 /**
@@ -35,7 +33,11 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
   const environment: Environment =
     tryResolveEnvironment({ env: options.env }) ?? DEFAULT_ENVIRONMENT;
   const answer = async (request: UltimateRequest) =>
-    await siteSeo({ baseUrl: originOf(options.env, request), environment });
+    await siteSeo({
+      baseUrl: originOf(options, request),
+      environment,
+      disallow: options.site?.disallow ?? [],
+    });
 
   return [
     {

package/src/serve-boot.ts

@@ -29,6 +29,7 @@ import { seoRoutes } from './seo-routes';
 import { loadDrainConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
 import type { ServedApp, ServeOptions } from './serve-types';
+import { loadSiteSettings, publicOrigin } from './site-config';
 import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
@@ -138,6 +139,9 @@ async function webSurface(
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
   const theme = themeBoot(await loadThemeMode(options.root));
+  // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
+  const site = await loadSiteSettings(options.root);
+  const origin = publicOrigin(options.env, site);
   // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
   // Before the service worker, which precaches those scripts.
   const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
@@ -175,7 +179,7 @@ async function webSurface(
     // filled, so this process serves exactly the CSS it renders against.
     ...styleRoutes(() => styleBundle()),
     // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
-    ...seoRoutes({ env: options.env }),
+    ...seoRoutes({ env: options.env, site }),
     // The page's one socket: its worker script, served beside the islands for their reason.
     ...sync.routes,
     ...appRoutes({
@@ -184,6 +188,7 @@ async function webSurface(
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
       themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of