@ultimat3/cli 22.15.0 → 24.0.0

package/src/output.ts

@@ -29,6 +29,12 @@ export interface Finding {
    * and must never be run as this CLI's own instruction.
    */
   readonly source?: 'ci-log';
+  /**
+   * Structured facts behind `cause`, for a `--json` reader that would otherwise parse the sentence:
+   * `X_VERIFY_STEP_TIMEOUT` carries the processes it killed and the files still in flight. Never
+   * the only home of a fact — the human render prints `cause` and `fix`, and both already say it.
+   */
+  readonly meta?: { readonly [key: string]: JsonValue };
 }
 
 export interface StepResult {
@@ -37,7 +43,12 @@ export interface StepResult {
   readonly durationMs: number;
   readonly skipped?: boolean;
   readonly findings: readonly Finding[];
-  /** Captured stdout/stderr, shown on failure or with --verbose. */
+  /**
+   * Captured stdout/stderr, for a reader working out what a step DID — carried by both renderers
+   * on failure or with `--verbose`, and by neither on a quiet green run. Never the home of a fact:
+   * a number a passing step must report by default goes in `CommandResult.data` (the `unit` step's
+   * coverage is `data.coverage.unit`), where `--json` and the terminal both always have it.
+   */
   readonly output?: string;
   /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
   readonly workers?: number;
@@ -208,6 +219,10 @@ const why = (step: StepResult): string => {
   return `  ${msg('cli.verify.allSkipped', { skipped: tests.skipped })}`;
 };
 
+/** The one rule for a step's captured output, so the two renderers cannot answer differently. */
+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 {
   const out: string[] = [];
   for (const step of result.steps ?? []) {
@@ -218,8 +233,8 @@ export function renderHuman(result: CommandResult, verbose = false): string {
     // NOT escaped, and that is the one exception: `output` is this process's own captured
     // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
     // already split on its real newlines rather than carrying them inside one entry.
-    if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
-      for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
+    if (showsOutput(step, verbose)) {
+      for (const line of (step.output ?? '').trimEnd().split('\n')) out.push(`      | ${line}`);
     }
   }
   // Every free-text line through the SAME `singleLine` the 3-line format runs, because this is
@@ -234,7 +249,7 @@ export function renderHuman(result: CommandResult, verbose = false): string {
   return out.join('\n');
 }
 
-export function renderJson(result: CommandResult): string {
+export function renderJson(result: CommandResult, verbose = false): string {
   const steps = (result.steps ?? []).map((step) => ({
     name: step.name,
     ok: step.ok,
@@ -261,10 +276,10 @@ export function renderJson(result: CommandResult): string {
     // fix line — the failing test's name and its assertion diff existed and were thrown away, so
     // the only way to learn what broke was to re-run it somewhere else. CI output is a prompt:
     // whoever reads it next, agent or human, must be able to act without reproducing first.
-    // Success stays quiet (`--verbose` is the human's opt-in) so a green run is not a wall of text.
-    ...(step.ok || step.output === undefined || step.output.length === 0
-      ? {}
-      : { output: step.output }),
+    // Success stays quiet so a green run is not a wall of text — unless `--verbose` asked, which
+    // is the same opt-in the terminal honours: a green step's output used to be reachable from the
+    // human render and from nowhere under `--json`.
+    ...(showsOutput(step, verbose) ? { output: step.output } : {}),
   }));
   const payload = {
     ok: result.ok,
@@ -278,7 +293,7 @@ export function renderJson(result: CommandResult): string {
 }
 
 export function render(result: CommandResult, json: boolean, verbose = false): string {
-  return json ? renderJson(result) : renderHuman(result, verbose);
+  return json ? renderJson(result, verbose) : renderHuman(result, verbose);
 }
 
 export function exitCodeFor(result: CommandResult): number {

package/src/page-navigation.ts

@@ -6,12 +6,9 @@
 // check a soft visit gets before `load`. No surface opted in: nothing is built, served or named — a
 // `site/` page that did not ask stays 0kb (axiom 6).
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
-// necessity `theme-boot.ts` records.
-import { join } from 'node:path';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx, NavigationSurface } from '@ultimat3/core';
-import { CLIENT_NAVIGATION_SCOPE_HEADER, NAVIGATION_SURFACES } from '@ultimat3/core';
+import { CLIENT_NAVIGATION_SCOPE_HEADER } from '@ultimat3/core';
 import type { Route, RouteNavigation, UltimateRequest } from '@ultimat3/http';
 import { locationFor, navigationPurpose, relocate } from '@ultimat3/http';
 import type { ClientNavigationHead, HeadTag, RouteEntry } from '@ultimat3/render';
@@ -22,8 +19,7 @@ import {
   routeEntries,
 } from '@ultimat3/render';
 import { ssrHeaders } from '@ultimat3/render/server';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { FrameworkScriptBuildFailedError } from './errors';
 import {
   buildNavigationScript,
@@ -56,26 +52,14 @@ export interface NavigationDeclaration {
   readonly surfaces: readonly NavigationSurface[];
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const isSurface = (value: unknown): value is NavigationSurface =>
-  NAVIGATION_SURFACES.some((surface) => surface === value);
-
 /**
- * `navigation.client` and `name`, as `defineConfig` validated them — no surfaces when the app says
- * nothing or has no config file. Structural, never `instanceof`, for `loadThemeMode`'s reason.
+ * `navigation.client` and `name`, off the one loader (`app-config-load.ts`) — no surfaces, and the
+ * app called `app`, for a root with no config file.
  */
 export async function loadNavigation(root: string): Promise<NavigationDeclaration> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return { app: 'app', surfaces: [] };
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return { app: 'app', surfaces: [] };
-  const app = typeof config['name'] === 'string' ? config['name'] : 'app';
-  const navigation = config['navigation'];
-  const client = isRecord(navigation) ? navigation['client'] : undefined;
-  return { app, surfaces: Array.isArray(client) ? client.filter(isSurface) : [] };
+  const config = await loadAppConfig(root);
+  if (config === undefined) return { app: 'app', surfaces: [] };
+  return { app: config.name, surfaces: config.navigation.client };
 }
 
 /**

package/src/page-speculation.ts

@@ -5,11 +5,8 @@
 // the next page's document on pointer rest, so a full-page navigation between prerendered pages
 // paints from memory — and the page still ships 0kb of JavaScript (axiom 6).
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
-// necessity `theme-boot.ts` records.
-import { join } from 'node:path';
 import type { NavigationSurface, SpeculationConfig } from '@ultimat3/core';
-import { DEFAULT_SPECULATION, localeSegment, resolveSpeculation } from '@ultimat3/core';
+import { DEFAULT_SPECULATION, localeSegment } from '@ultimat3/core';
 import { cspHashSource } from '@ultimat3/http';
 import { localeConfig, routedLocales } from '@ultimat3/i18n';
 import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
@@ -21,26 +18,14 @@ import {
   speculationRulesBody,
   speculationRulesTag,
 } from '@ultimat3/render';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
+import { loadAppConfig } from './app-config-load';
 
 /**
- * `navigation.speculation` — the default (on, `'moderate'`) when the app says nothing or has no
- * config file. Structural, for `loadThemeMode`'s reason, and so possibly NOT what `defineConfig`
- * validated: what it finds goes through core's `resolveSpeculation`, the one validator, which
- * REFUSES (`X_CONFIG_INVALID`) a value `defineConfig` would refuse. Never coerced: an `'eager'`
- * quietly served as `'moderate'` is a rule the app did not write.
+ * `navigation.speculation` off the one loader (`app-config-load.ts`), which holds it to core's
+ * `resolveSpeculation` — the default (on, `'moderate'`) for a root with no config file.
  */
 export async function loadSpeculation(root: string): Promise<SpeculationConfig> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return DEFAULT_SPECULATION;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const navigation = isRecord(config) ? config['navigation'] : undefined;
-  return resolveSpeculation(isRecord(navigation) ? navigation['speculation'] : undefined);
+  return (await loadAppConfig(root))?.navigation.speculation ?? DEFAULT_SPECULATION;
 }
 
 /**

package/src/permission-grants.ts

@@ -1,5 +1,5 @@
-// The `policy` step's second question: every permission an action, a query or a route REQUIRES is
-// one some role GRANTS. `x g resource customer` declared `customer:read`/`customer:write`, the
+// The `policy` step's second question: every permission an action, a query, a route or a MOUNTED
+// screen (the admin's) REQUIRES is one some role GRANTS. `x g resource customer` declared `customer:read`/`customer:write`, the
 // actions required them, no role held them, and `x verify` was green over an app whose every
 // generated endpoint answered 403 to the dev actor (plan 101 slice 11 a).
 
@@ -7,14 +7,14 @@ import { listActions } from '@ultimat3/action';
 import type { Policy } from '@ultimat3/policy';
 import { roleDefinitions, rolesGranting } from '@ultimat3/policy';
 import { listQueries } from '@ultimat3/query';
-import { routeEntries } from '@ultimat3/render';
+import { describeRoutes, routeEntries } from '@ultimat3/render';
 import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
 /** One rule that cannot pass for any actor the role map mints. */
 export interface UngrantedRequirement {
   readonly permission: string;
-  /** `action createCustomer`, `query customerList`, or the route file. */
+  /** `action createCustomer`, `query customerList`, the route file, or a mounted route's URL. */
   readonly by: string;
 }
 
@@ -43,6 +43,28 @@ export function requirements(): readonly UngrantedRequirement[] {
     const permission = entry.config.policy?.permission;
     if (permission !== undefined) rules.push({ permission, by: entry.file });
   }
+  // A route a package MOUNTED — the admin's — is in no file and so in no `routeEntries()` row. Its
+  // screen decides on every permission of the mount, not only the coarse gate its route config
+  // carries, so each one is a requirement: a hand-written entity nobody granted `<table>:read`
+  // for was a green gate and a 403 on its first open. `describeRoutes()` is memoized by the
+  // registry, so this loop reads a list every other step already built.
+  // One requirement per permission per mount, naming the first route that asks it: `posts:write`
+  // gates the create form and the edit form, and one missing grant is one finding.
+  const asked = new Map<string, { permission: string; by: string; first: string; more: number }>();
+  for (const route of describeRoutes()) {
+    if (route.mount === undefined) continue;
+    for (const permission of route.mount.permissions) {
+      const key = `${route.mount.by} ${permission}`;
+      const held = asked.get(key);
+      if (held === undefined) {
+        asked.set(key, { permission, by: route.mount.by, first: route.path, more: 0 });
+      } else held.more += 1;
+    }
+  }
+  for (const { permission, by, first, more } of asked.values()) {
+    const rest = more === 0 ? '' : `, and ${String(more)} more of its routes`;
+    rules.push({ permission, by: `${first} (mounted by ${by}${rest})` });
+  }
   return rules;
 }
 
@@ -73,14 +95,24 @@ export function ungrantedRequirements(
     );
 }
 
-/** Where the scaffold keeps the role map — the file `x g policy` and `x g resource` edit. */
+/**
+ * Where the SCAFFOLD keeps the role map — the file `x g policy` and `x g resource` edit. Never what
+ * a finding names: an app may declare its roles anywhere (the reference app's are in
+ * `shared/policies.ts`), so `ungrantedFinding` takes the file the role map was declared in.
+ */
 export const ROLES_FILE = 'apps/web/shared/roles.ts';
 
-export function ungrantedFinding(rule: UngrantedRequirement): Finding {
-  return {
+/**
+ * `rolesAt` is the app-relative file `defineRoles` ran in (`app-permissions.ts`'s `roleMapFile`),
+ * or `undefined` when no site under the app root can be read — then the fix names the call, not a
+ * path this function would have to guess.
+ */
+export function ungrantedFinding(rule: UngrantedRequirement, rolesAt: string | undefined): Finding {
+  const where = rolesAt ?? 'the module that calls defineRoles({ ... })';
+  const finding: Finding = {
     code: 'X_PERMISSION_UNGRANTED',
     cause: `${rule.by} requires ${quoteArg(rule.permission)}, and no role in the app's role map grants it — no actor a role mints can ever pass`,
-    fix: `add '${rule.permission}' to the grants of a role in ${ROLES_FILE}, then x verify --only policy`,
-    at: ROLES_FILE,
+    fix: `add '${rule.permission}' to the grants of a role in ${where}, then x verify --only policy`,
   };
+  return rolesAt === undefined ? finding : { ...finding, at: rolesAt };
 }

package/src/prerender-out.ts

@@ -1,25 +1,52 @@
 // The export directory is the build's own, and emptied before every build: `prerenderSite` only
 // ever ADDED files, so a route deleted from the app kept shipping its last HTML from `.x/static`.
-// Refused when `out` is the app root or above it — an `rm -rf` there deletes the app.
+// Emptied only when it is provably the build's: absent, empty, or marked by an earlier build —
+// `--out apps` deleted the app's pages and `--out .x` its embedded dev database.
 
-import { rm } from 'node:fs/promises'; // why: Bun has no recursive directory delete.
-import { isAbsolute, relative, resolve, sep } from 'node:path'; // why: Bun ships no path resolve/relative.
+import { lstat, readdir, rm } from 'node:fs/promises'; // why: Bun has no recursive delete or readdir.
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'; // why: Bun ships no path resolve/relative.
 import { UltimateError } from '@ultimat3/core';
 
+/** Written into every export directory a build empties: the proof the next build may empty it. */
+export const EXPORT_MARKER = '.x-export';
+
+/**
+ * The export directory `x build --target static` chooses itself. Exempt from the marker: a build
+ * from before the marker existed left it full and unmarked, and the build owns this path by name.
+ */
+const DEFAULT_EXPORT = join('.x', 'static');
+
+const MARKER_TEXT =
+  'Written by x build --target static. This directory is emptied before every static build.\n';
+
 /** True when `dir` is `root` itself or one of its ancestors. */
 const containsRoot = (dir: string, root: string): boolean => {
   const up = relative(resolve(dir), resolve(root));
   return up === '' || (up !== '..' && !up.startsWith(`..${sep}`) && !isAbsolute(up));
 };
 
-/** Empties `out` for a fresh export, or refuses a directory that holds the app. */
+/** Why `out` is not the build's to empty, or `undefined` when it is. */
+async function unsafeReason(out: string, root: string): Promise<string | undefined> {
+  if (containsRoot(out, root)) return 'is the app root or holds it';
+  const stat = await lstat(out).catch(() => undefined);
+  if (stat === undefined) return undefined;
+  if (!stat.isDirectory()) return 'is not a directory';
+  const entries = await readdir(out);
+  if (entries.length === 0 || entries.includes(EXPORT_MARKER)) return undefined;
+  if (resolve(out) === resolve(root, DEFAULT_EXPORT)) return undefined;
+  return `already holds ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} and no ${EXPORT_MARKER} a previous build wrote`;
+}
+
+/** Empties `out` for a fresh export and marks it, or refuses a directory the build did not write. */
 export async function clearPrerenderOut(out: string, root: string): Promise<void> {
-  if (containsRoot(out, root)) {
+  const reason = await unsafeReason(out, root);
+  if (reason !== undefined) {
     throw new UltimateError({
-      code: 'X_CLI_BAD_FLAG',
-      cause: `the static export directory ${resolve(out)} is the app root or holds it, and every build empties its export directory first`,
+      code: 'X_BUILD_OUT_UNSAFE',
+      cause: `the static export directory ${resolve(out)} ${reason}, and every build empties its export directory first`,
       fix: 'x build --target static --out .x/static --json',
     });
   }
   await rm(out, { recursive: true, force: true });
+  await Bun.write(join(out, EXPORT_MARKER), MARKER_TEXT);
 }

package/src/prerender.ts

@@ -21,6 +21,7 @@ import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
 import { measureDocumentJs, writeBuildStats } from './budgets';
 import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
+import { PrerenderLoadFailedError } from './errors';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
@@ -168,15 +169,17 @@ const NOT_FOUND_STATUS = 404;
  */
 const declaresBudget = (entry: RouteEntry): boolean => {
   const budget = entry.config.budget;
-  return budget !== undefined && (budget.js !== undefined || budget.lcp !== undefined);
+  return budget?.js !== undefined;
 };
 
 export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
-  // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
-  // route registry, so there is no route table to prerender before this runs.
-  // Emptied FIRST: the export only ever gained files, so a deleted route's HTML kept shipping.
+  // The load `x dev` and `x manifest` perform: importing the app's modules fills the route registry.
+  // A module that would not import registered nothing, so its page would vanish from the export
+  // under a green build — refused BEFORE the export is emptied, so the last good artifact survives.
+  const loaded = await loadApp(options.root);
+  if (loaded.findings.length > 0) throw new PrerenderLoadFailedError(loaded.findings);
+  // Emptied before anything is written: a deleted route's HTML kept shipping when it only grew.
   await clearPrerenderOut(options.out, options.root);
-  await loadApp(options.root);
   const buildId = (await appManifest(options.root)).manifest.buildId;
   const declaredOrigin =
     options.origin ?? publicOrigin(process.env, await loadSiteSettings(options.root));

package/src/publish-closure.ts

@@ -0,0 +1,101 @@
+// `package-shape`'s other half of "a fixture does not ship": what a published package's ENTRY
+// POINTS can load, held against the files its tarball leaves out. `files` negates
+// `src/**/*-fixture.ts`, so a module an entry reaches under that suffix is a published package
+// that fails on import — and the defect is the name, not the exclusion.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { ClosureHost } from './import-closure';
+import { importClosure } from './import-closure';
+import type { Finding } from './output';
+
+/** The suffix `FIXTURE_EXCLUSION` removes from a tarball. */
+export const FIXTURE_SUFFIX = '-fixture.ts';
+
+/** A package directory, read by package-relative POSIX path. */
+export type PackageReader = Pick<ClosureHost, 'read'>;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null;
+
+/** Every string under `exports` / `bin`, whatever the nesting: a condition map is still a file. */
+const targetsOf = (value: unknown): readonly string[] => {
+  if (typeof value === 'string') return [value];
+  return isRecord(value) ? Object.values(value).flatMap(targetsOf) : [];
+};
+
+/**
+ * The modules a consumer can import or run: `exports` and `bin`, package-relative. A subpath
+ * pattern (`./icons/*`) names no one file and a stylesheet is not a module, so neither is an
+ * entry to walk from.
+ */
+export function entryFilesOf(manifest: unknown): readonly string[] {
+  if (!isRecord(manifest)) return [];
+  const targets = [...targetsOf(manifest['exports']), ...targetsOf(manifest['bin'])];
+  const files = targets
+    .map((target) => target.replace(/^\.\//, ''))
+    .filter((target) => /\.tsx?$/.test(target) && !target.includes('*'));
+  return [...new Set(files)].sort();
+}
+
+/**
+ * Every `*-fixture.ts` whose body an entry can run. Bare specifiers end the walk: another package
+ * is that package's tarball, held by its own run of this rule.
+ */
+export function fixturesReachedFrom(
+  reader: PackageReader,
+  entries: readonly string[],
+): readonly string[] {
+  const host: ClosureHost = { read: reader.read, alias: () => undefined };
+  return importClosure(host, entries).filter((path) => path.endsWith(FIXTURE_SUFFIX));
+}
+
+/** `src/a/driver-fixture.ts` → `driver-fixture`; an `index.ts` is named by its directory. */
+const stemOf = (path: string): string => {
+  const parts = path.replace(/\.tsx?$/, '').split('/');
+  const last = parts.at(-1) ?? '';
+  return last === 'index' ? (parts.at(-2) ?? last) : last;
+};
+
+const escaped = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The cheap question, asked before the walk: COULD an entry reach a fixture? Backwards from each
+ * fixture, by the last segment of a relative specifier, over text alone — so it over-answers (a
+ * type-only import, two files of one name) and never under-answers. `false` is final; `true`
+ * earns the real closure. Measured 2026-10: the closure alone was ~650 ms across the 12 packages
+ * that hold a fixture, and all but one of them are answered here.
+ */
+export function mayReachFixture(
+  sources: ReadonlyMap<string, string>,
+  entries: readonly string[],
+): boolean {
+  const entrySet = new Set(entries);
+  const seen = new Set<string>();
+  let frontier = [...sources.keys()].filter((path) => path.endsWith(FIXTURE_SUFFIX));
+  while (frontier.length > 0) {
+    const names = new RegExp(
+      `/(?:${frontier.map(stemOf).map(escaped).join('|')})(?:\\.[jt]sx?)?['"]`,
+    );
+    const next: string[] = [];
+    for (const [path, text] of sources) {
+      if (seen.has(path) || path.endsWith(FIXTURE_SUFFIX) || !names.test(text)) continue;
+      if (entrySet.has(path)) return true;
+      seen.add(path);
+      next.push(path);
+    }
+    frontier = next;
+  }
+  return false;
+}
+
+export const fixtureReachFinding = (
+  dir: string,
+  fixture: string,
+  entries: readonly string[],
+): Finding => ({
+  code: 'X_PACKAGE_SHAPE',
+  cause: `packages/${dir}/${fixture} is loaded from the package's entry points (${entries.join(', ')}), and "files" leaves every *${FIXTURE_SUFFIX} out of the tarball — the published package would fail on import`,
+  fix: `rename packages/${dir}/${fixture} so it does not end in ${FIXTURE_SUFFIX} — it is shipped source, not test code — and update the imports that name it`,
+  docs: ERROR_DOCS_URL,
+  at: `packages/${dir}/${fixture}`,
+});

package/src/pwa-artifacts.ts

@@ -15,15 +15,10 @@
 // build behind them — `wiki/PWA-And-Offline.md` says so — and a bad `sw.js` is sticky in a way a
 // manifest is not, so the worker lands behind a real browser check rather than beside this.
 
-// why: Bun exposes no synchronous file-existence primitive, and this read is the same one
-// `app-auth.ts` and `runtime-cache.ts` each make before importing an app's config — a root with no
-// `app.config.ts` is an ordinary answer here (a scratch root, `x build` outside an app).
-import { existsSync } from 'node:fs';
-// why: Bun exposes no path-join primitive, and `APP_CONFIG_FILE` is app-root-relative — the same
-// necessity `favicon.ts` and `runtime-assets.ts` each record for their own root-relative constant.
+// why: Bun exposes no path-join primitive, and the export writes each icon under an out directory.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
-import { localeSegment } from '@ultimat3/core';
+import { escapeHtml, localeSegment } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import {
@@ -34,9 +29,7 @@ import {
 } from '@ultimat3/pwa';
 import type { AssetPath } from '@ultimat3/render';
 import { assetPathProblem } from '@ultimat3/render';
-import { escapeAttribute } from '@ultimat3/seo';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
 import type { AppLocales } from './pwa-manifest-locales';
 import { appLocales, localeMembers, spellIn } from './pwa-manifest-locales';
@@ -80,47 +73,14 @@ export interface PwaArtifacts {
   /** The `<head>` for a document in `locale` — it links that locale's manifest. */
   headFor(locale: string): string;
   /**
-   * The three `pwa` keys the SERVICE WORKER needs, carried here because this is the one module
-   * that reads an app's config file — `sw-artifacts.ts` needs the route table and the island
-   * bundle as well, and a second `await import` of `app.config.ts` would be a second answer to
-   * "what did this app declare".
+   * The three `pwa` keys the SERVICE WORKER needs, carried here so `sw-artifacts.ts` — which needs
+   * the route table and the island bundle as well — reads them off the same resolved block.
    */
   readonly offline: PwaOfflineConfig;
   readonly backgroundSync: boolean;
   readonly push: boolean;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const text = (value: unknown): string | undefined =>
-  typeof value === 'string' && value.trim() !== '' ? value : undefined;
-
-/**
- * `colors` read structurally, for `loadSignInPath`'s reason: `defineConfig` returns a plain object
- * and a config resolved through an older core simply has no such key. `validate()` already refused
- * a blank one an `await import` above this line, so anything this rejects is a hand-written config
- * object — and the honest answer for one is no manifest at all, never a colour we invented.
- */
-function colorsOf(value: unknown): PwaColors | undefined {
-  if (!isRecord(value)) return undefined;
-  const light = isRecord(value['light']) ? value['light'] : undefined;
-  const dark = isRecord(value['dark']) ? value['dark'] : undefined;
-  if (light === undefined || dark === undefined) return undefined;
-  const [lt, lb, dt, db] = [
-    text(light['themeColor']),
-    text(light['backgroundColor']),
-    text(dark['themeColor']),
-    text(dark['backgroundColor']),
-  ];
-  if (lt === undefined || lb === undefined || dt === undefined || db === undefined)
-    return undefined;
-  return {
-    light: { themeColor: lt, backgroundColor: lb },
-    dark: { themeColor: dt, backgroundColor: db },
-  };
-}
-
 /** The `pwa` block, as much of it as this file needs, or `undefined` when the app declares none. */
 interface InstallableApp {
   readonly name: string;
@@ -133,60 +93,30 @@ interface InstallableApp {
   readonly push: boolean;
 }
 
-async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return undefined;
-  const pwa = config['pwa'];
-  // `pwa.enabled`, read. Not a truthiness test: `enabled` is the key this whole file exists to
-  // give a reader, and `=== true` is what makes a hand-written `enabled: 'yes'` produce no
-  // manifest rather than one nobody asked for.
-  if (!isRecord(pwa) || pwa['enabled'] !== true) return undefined;
-  const name = text(pwa['name']);
-  const colors = colorsOf(pwa['colors']);
-  if (name === undefined || colors === undefined) return undefined;
-  return {
-    name,
-    colors,
-    block: pwa,
-    locales: appLocales(config),
-    offline: offlineOf(pwa['offline']),
-    ...flags(pwa),
-  };
-}
-
 /**
- * The offline block, read structurally for `colorsOf`'s reason: `defineConfig` refuses
- * `enabled: true` without an absolute `offline.fallback`, but a HAND-WRITTEN config object never
- * passed through it. A missing or relative fallback answers `null`, and `serviceWorkerArtifacts`
- * then emits no worker at all — never a path the framework invented, which offline would be a
- * cached 404 answering every navigation.
+ * `pwa.enabled`, read, off the one loader (`app-config-load.ts`). Core's validator refuses an
+ * enabled block without a name, both colour schemes or an absolute `offline.fallback`, so nothing
+ * here invents a colour or a fallback route; `colors` is optional only in the type.
  */
-function offlineOf(value: unknown): PwaOfflineConfig {
-  const block = isRecord(value) ? value : {};
-  const fallback = text(block['fallback']);
-  const patterns = block['neverCache'];
+async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
+  const config = await loadAppConfig(root);
+  const pwa = config?.pwa;
+  if (config === undefined || pwa === undefined || !pwa.enabled || pwa.colors === undefined) {
+    return undefined;
+  }
   return {
-    fallback: fallback?.startsWith('/') === true ? fallback : null,
-    image: text(block['image']) ?? null,
-    font: text(block['font']) ?? null,
-    neverCache: Array.isArray(patterns)
-      ? patterns.filter((entry): entry is string => typeof entry === 'string')
-      : [],
-    personalPages: block['personalPages'] === 'last-member' ? 'last-member' : 'never',
+    name: pwa.name,
+    colors: pwa.colors,
+    block: { ...pwa },
+    locales: appLocales({ locales: config.locales, defaultLocale: config.defaultLocale }),
+    offline: pwa.offline,
+    backgroundSync: pwa.backgroundSync,
+    push: pwa.push,
   };
 }
 
-/** `=== true` for `enabled`'s reason: a hand-written `backgroundSync: 'yes'` wires nothing. */
-const flags = (pwa: Record<string, unknown>): { backgroundSync: boolean; push: boolean } => ({
-  backgroundSync: pwa['backgroundSync'] === true,
-  push: pwa['push'] === true,
-});
-
 /**
- * Resolved ONCE at boot, like `loadSignInPath` and `loadCacheTiers` and unlike `faviconBytes`:
+ * Resolved ONCE at boot, like `loadSignInPath` and unlike `faviconBytes`: the loader's
  * `await import` caches the module, so re-reading per request would answer the same object at a
  * per-request cost, and the head string has to be available synchronously while a document renders.
  */
@@ -219,7 +149,7 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
       path,
       body: serializeWebManifest(result.manifest),
       head:
-        `<link rel="manifest" href="${escapeAttribute(path)}">` +
+        `<link rel="manifest" href="${escapeHtml(path)}">` +
         renderThemeColorMeta(result.themeColorMeta) +
         (icons === undefined ? '' : appleTouchLinks(icons)),
     };
@@ -244,7 +174,9 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
  * `asset()` does in a page. The site serves an asset ONLY at its hashed URL, and the manifest took
  * `src` verbatim, so an app had to hash its own screenshots to avoid shipping a 404 in the install
  * sheet (notificado.co's `pwa-install.ts`). A missing file is `X_ASSET_MISSING` at boot, never a
- * broken image in an install prompt; any other `src` (absolute, already hashed) passes untouched.
+ * broken image in an install prompt; any other `src` passes untouched — an absolute path outside
+ * `/assets/`, an already hashed one, or a shortcut icon's off-site URL (core screens screenshots and
+ * shortcut urls to absolute paths, not icon sources).
  */
 function withHashedAssets<M extends ReturnType<typeof localeMembers>>(members: M, root: string): M {
   const resolve = (src: string): string => {