@ultimat3/cli 19.1.3 → 19.3.1

package/src/dev-reload.ts

@@ -0,0 +1,46 @@
+// One rebuild at a time. A reload is a full `appManifest()` plus a `buildIslands()` over every
+// island, and the watcher had no in-flight guard: a 45ms drip of writes — a slow `git checkout`, a
+// formatter walking the tree, `x db gen` — started one per file, 40 for 40 files, each assigning
+// the same two state slots in COMPLETION order. So a slower earlier rebuild could land on top of a
+// newer one, and the dev server then served a manifest built from source that had already changed.
+
+/** What a tick does while a rebuild is already running: nothing, except become the next one. */
+export type ReloadTrigger = (file: string) => void;
+
+/**
+ * Serialise `run`, keeping only the LAST tick that arrived while it was busy. N ticks during one
+ * rebuild are exactly one more rebuild, for the newest file — never N queued ones, and never a
+ * dropped tick, which would leave the process serving the state before the author's last save.
+ *
+ * `onError` defaults to swallowing, because the caller that cares reports its own failure as a
+ * finding; a rejection escaping here would be an unhandled rejection that takes `x dev` down.
+ */
+export function coalesceReloads(
+  run: (file: string) => Promise<void> | void,
+  onError: (error: unknown, file: string) => void = () => undefined,
+): ReloadTrigger {
+  let running = false;
+  let pending: string | undefined;
+
+  const start = (file: string): void => {
+    running = true;
+    // `Promise.resolve().then` rather than a bare call: a SYNCHRONOUS throw from `run` would
+    // otherwise escape the fs callback that triggered it, where nothing is listening.
+    void (async () => await run(file))()
+      .catch((error: unknown) => onError(error, file))
+      .finally(() => {
+        running = false;
+        const next = pending;
+        pending = undefined;
+        if (next !== undefined) start(next);
+      });
+  };
+
+  return (file: string): void => {
+    if (running) {
+      pending = file;
+      return;
+    }
+    start(file);
+  };
+}

package/src/dev-render.ts

@@ -3,9 +3,16 @@
 // document, it never decides what a mode means or what headers it earns.
 //
 // The document is head + the route's own component, rendered by `@ultimat3/render`'s server JSX
-// writer, with the surface's compiled CSS inlined. Inlined rather than linked because a `site/`
-// page is a 0kb-JS artifact a CDN serves as one file: a stylesheet link would add a round trip to
-// the render path the mode exists to make cheap, and a static export would need a second file.
+// writer, with the surface's compiled CSS LINKED — one content-hashed file per surface
+// (`style-bundle.ts`), served `immutable`.
+//
+// It was inlined until 2026-09-06, on the argument that a `site/` page is a 0kb-JS artifact a CDN
+// serves as one file and a link would add a round trip. The round trip is real and it is paid
+// once: measured against ai-maxxing, every `app/` document carried the SAME 156,738-byte `<style>`
+// block — 92% of the dashboard document — inside a response the pipeline sends
+// `Cache-Control: private, no-store`, so the trip that argument saved was re-paid in full on every
+// navigation, with a re-parse on top. The static export writes the file (`writeStyles`), so the
+// "second file" cost is one `Bun.write`.
 
 import type { Ctx } from '@ultimat3/core';
 import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
@@ -32,8 +39,8 @@ import {
   renderSsr,
   staticHeaders,
   streamResult,
-  stylesFor,
 } from '@ultimat3/render/server';
+import { styleBundle } from './style-bundle';
 
 /**
  * Specifier → built chunk URL, bound to the route file the specifier is written relative to.
@@ -92,10 +99,24 @@ const headFor = async (
     ),
   ) + (options.pwaHead ?? '');
 
-/** `<style>` for the surface's own stylesheets, or nothing at all when the surface imports none. */
+/**
+ * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
+ * imports none.
+ *
+ * In `<head>`, which is what keeps this a swap and not a regression: a `<link rel="stylesheet">`
+ * there is render-blocking in every browser, exactly as the inline block was, so there is no
+ * window in which the document paints unstyled. Moving it to the body, or deferring it, is what
+ * would introduce a flash — never do that here.
+ *
+ * Read through `styleBundle()` rather than passed in through `DocumentOptions`: the registry it
+ * derives from is process-global (importing the app IS what fills it), so a caller that forgot to
+ * thread a resolver would serve a document with no CSS at all — and `appRoutes` is on this
+ * package's public surface, called as `appRoutes({ buildId })` by both tracked apps' contract
+ * tests. One reader, and it is the same one `styleRoutes` serves from.
+ */
 const styleTag = (entry: RouteEntry): string => {
-  const css = stylesFor(entry.surface);
-  return css.length === 0 ? '' : `<style>${css}</style>`;
+  const href = styleBundle().hrefFor(entry.surface);
+  return href === undefined ? '' : `<link rel="stylesheet" href="${href}">`;
 };
 
 /**

package/src/dev-roles.ts

@@ -43,6 +43,7 @@ import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
+import { DEV_BINDING, type WebBinding } from './web-binding';
 
 /** The roles `x dev` starts when `--role` names none, in boot order. */
 export const DEV_ROLES: readonly Role[] = ['web', 'sync', 'worker', 'scheduler'];
@@ -113,13 +114,9 @@ export interface StartRolesOptions {
   readonly overrides?: RuntimeOverrides;
 }
 
-export interface WebBinding {
-  readonly dev: boolean;
-  readonly hostname: string;
-}
-
-/** Loopback and dev-mode. What `x dev` means, and what a container must override. */
-export const DEV_BINDING: WebBinding = { dev: true, hostname: 'localhost' };
+// Re-exported, not re-declared: `web-binding.ts` is a leaf so `dev-sync` can read the default
+// without importing this module, which imports it.
+export { DEV_BINDING, type WebBinding } from './web-binding';
 
 export interface RunningRoles {
   readonly roles: readonly Role[];
@@ -366,9 +363,13 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // First, and for every role rather than only the two that open an HTTP socket: `worker` and
     // `sync` are precisely the roles whose HPAs read a series the process itself has to publish,
     // and a `worker` container with no listener is an HPA pinned at `<unknown>` forever.
+    // `?? DEV_BINDING`, not "omit the key when `options.http` is undefined". The old spread left
+    // the metrics endpoint on Bun's `0.0.0.0` for exactly the caller that asked for loopback —
+    // `x dev`, which passes no `http` at all — so the same gap the sync node had was here too.
+    const binding = options.http ?? DEV_BINDING;
     const metrics = startMetricsEndpoint({
       port: options.metricsPort ?? (options.port === 0 ? 0 : DEFAULT_METRICS_PORT),
-      ...(options.http === undefined ? {} : { hostname: options.http.hostname }),
+      hostname: binding.hostname,
     });
     started.push(async () => metrics.stop());
 

package/src/dev-runtime.ts

@@ -299,7 +299,10 @@ export async function startServices(
   // `@ultimat3/realtime`'s decision, and it is the same call a `ROLE=sync` container makes, so this
   // process cannot resolve the bus differently from the container it stands in for.
   const bus: TransportSelection = selectTransport(env);
-  const queue = await startQueue(services, overrides);
+  // `env`, not the ambient one: this function is HANDED the boot's environment and every other
+  // reader here already uses it, so a queue that asked `process.env` would decide the standby from
+  // a different answer than the middleware that routes to it.
+  const queue = await startQueue(services, overrides, env);
   const { db, jobs, outbox, events } = queue;
   // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
   // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is

package/src/dev-sync.ts

@@ -15,9 +15,10 @@ import {
   SocketRegistry,
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
-import { neighbouringPort, PORT_RANGE } from './flag-number';
+import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import { syncAuthenticator } from './sync-authenticator';
+import { DEV_BINDING } from './web-binding';
 
 /**
  * Beside its one thrower rather than in `errors.ts`, which is at 461 of the 500-line ceiling —
@@ -52,7 +53,11 @@ class SyncPortInUseError extends UltimateError {
     super({
       code: 'X_PORT_IN_USE',
       cause: `the sync role binds PORT + 1, so \`x dev --port ${input.webPort}\` needs port ${input.port} and something is already listening on it`,
-      fix: `x dev --port ${neighbouringPort(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
+      // `portPairAfter`, never `neighbouringPort`: `x dev` binds a PAIR, so the neighbour of the
+      // web port IS the sync port this refusal is about — the fix said `x dev --port 4000` for a
+      // run that had just died on 4000, and a test named "its fix is a command that ends the
+      // failure" pinned it.
+      fix: `x dev --port ${portPairAfter(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
       meta: { port: input.port, webPort: input.webPort },
     });
   }
@@ -177,7 +182,16 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   await node.start();
   const port = syncPortFor(options.port);
   try {
-    const listener = listenSyncNode(node, { port });
+    // The SAME interface the web role binds, resolved from the same option and the same default.
+    // Without this the sync node took Bun's `0.0.0.0` while `x dev`'s web role took `localhost`,
+    // so the one socket that streams live database patches was the one socket on every
+    // interface — and `WebBinding`'s own docstring is about not serving a laptop's app to a café.
+    const binding = options.http ?? DEV_BINDING;
+    // No drain grace: there is one node here and it is the one going away. Its clients reconnect
+    // to it when `x dev` is back, and a grace that kept their patches flowing meanwhile was five
+    // seconds of every Ctrl-C (measured 2026-09-06, 5.0s of 5.1s) spent on a reconnect frame
+    // whose target does not exist yet.
+    const listener = listenSyncNode(node, { port, hostname: binding.hostname, drainGraceMs: 0 });
     return {
       url: listener.url,
       registry,

package/src/dev-watch-tree.ts

@@ -0,0 +1,226 @@
+// The app root watched one directory at a time, because the watch SET is a registration decision
+// and not a filter. `watch(root, { recursive: true })` takes an inotify descriptor per directory
+// in the tree — including every directory the dev loop then discards events from — so `.git/`,
+// `node_modules/` and `.x/` (which this very process writes to, continuously) each cost a
+// descriptor, a kernel queue entry and a JS callback per write, against a per-user descriptor
+// budget of 8192 on many distributions. Bun 1.4.0's `fs.watch` takes no ignore option, so the
+// only place the answer can be given early is at registration.
+
+// why: Bun exposes no filesystem watcher, no directory listing and no synchronous stat —
+// `Bun.file().exists()` is async and answers false for a DIRECTORY, which is the one thing this
+// module has to decide. Delete each when Bun ships an equivalent.
+import type { Dirent } from 'node:fs';
+import { readdirSync, statSync, watch } from 'node:fs';
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import { finiteCount, logger } from '@ultimat3/core';
+import type { DevIgnore } from './dev-watch';
+import { devIgnore } from './dev-watch';
+import { pathSegments } from './path-segments';
+
+/** What `node:fs`'s watcher hands a listener — `filename` is optional in fact, not only in type. */
+export type WatchListener = (event: string, filename: string | Buffer | null | undefined) => void;
+
+/** The one thing this module needs of a watcher, so a test can stand one up in four lines. */
+export interface DirectoryWatcher {
+  close(): void;
+}
+
+export type WatchDirectory = (directory: string, listener: WatchListener) => DirectoryWatcher;
+
+export interface WatchTreeOptions {
+  readonly root: string;
+  /** A source change, app-root-relative and POSIX-separated. Debounced. */
+  readonly onChange: (file: string) => void;
+  /** Trailing debounce. A save touching five files is one reload, not five. Default 30ms. */
+  readonly debounceMs?: number;
+  /** Test seam: the default is `node:fs`'s `watch(dir, { recursive: false })`. */
+  readonly watchDirectory?: WatchDirectory;
+}
+
+export interface WatchTree {
+  /** Directories holding a descriptor right now, app-root-relative; `''` is the app root. */
+  directories(): readonly string[];
+  close(): void;
+}
+
+const DEFAULT_DEBOUNCE_MS = 30;
+
+/**
+ * Every directory under `root` an event could be a source change in, `''` first. Ignored
+ * directories are not descended, so a `node_modules` tree costs one `readdir` and nothing else.
+ * A symlinked directory is deliberately not followed: `Dirent.isDirectory()` is false for one, and
+ * a workspace symlink pointing back into the checkout would otherwise be walked twice.
+ */
+export function admittedDirectories(root: string, ignore: DevIgnore): readonly string[] {
+  const admitted: string[] = [''];
+  const pending: string[] = [''];
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    for (const entry of childrenOf(join(root, next))) {
+      if (!entry.isDirectory()) continue;
+      const child = next === '' ? entry.name : `${next}/${entry.name}`;
+      if (ignore.ignores(child, true)) continue;
+      admitted.push(child);
+      pending.push(child);
+    }
+  }
+  return admitted.sort();
+}
+
+/**
+ * One directory's entries, or none. A directory removed between the listing above and this read, or
+ * one this user may not open, is neither a source change nor a finding anyone can act on.
+ */
+function childrenOf(path: string): readonly Dirent[] {
+  try {
+    return readdirSync(path, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+const nodeWatch: WatchDirectory = (directory, listener) =>
+  watch(directory, { recursive: false }, listener);
+
+/** Whether the path is a directory right now — the question a `rename` event does not answer. */
+function isDirectoryAt(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function watchTree(options: WatchTreeOptions): WatchTree {
+  const { root, onChange } = options;
+  // Screened before a single descriptor is taken. `??` guards NULLISH and `NaN` is not nullish, so
+  // an unparsed value walks past the default into `setTimeout(fn, NaN)`, which coerces to **0**:
+  // the debounce reads as installed and every keystroke runs a full `appManifest()` plus
+  // `buildIslands()`. `0` is admitted — "rebuild on the next tick" is a decision — and `Infinity`
+  // is not, because a reload that never fires is the same defect facing the other way.
+  const debounceMs = finiteCount(
+    'watchTree',
+    'debounceMs',
+    options.debounceMs ?? DEFAULT_DEBOUNCE_MS,
+  );
+  const open = new WatchDirectoryMap(options.watchDirectory ?? nodeWatch, root);
+  let ignore = devIgnore(root);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let last = '';
+  let warned = false;
+
+  const schedule = (file: string): void => {
+    last = file;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => onChange(last), debounceMs);
+  };
+
+  const listen = (directory: string): void => {
+    open.add(directory, (event, filename) => {
+      if (typeof filename !== 'string' && !(filename instanceof Buffer)) {
+        // Bun's watcher delivers no filename when the WATCHED directory itself moves or is removed
+        // — `mv myapp myapp2`, a re-clone, a volume remount. Once, because the same rename can
+        // arrive on every descriptor at the same instant.
+        if (!warned) logger.warn('dev.watch.unnamed_event', { directory: directory || '.' });
+        warned = true;
+        return;
+      }
+      const name = pathSegments(filename.toString()).join('/');
+      const file = directory === '' ? name : `${directory}/${name}`;
+      // Asked of the DISK, once, because every trailing-slash rule in a `.gitignore` turns on it
+      // and a `rename` says only that something moved. One stat against a whole rebuild.
+      const isDirectory = open.has(file) || isDirectoryAt(join(root, file));
+      if (event === 'rename') follow(file, isDirectory);
+      if (file === '.gitignore') {
+        // The ignore set is the app's own, so an edit to it changes which directories are watched
+        // at all. Not a source change: rebuilding the manifest for it would be a reload the author
+        // did not ask for on the one file whose whole job is saying what to leave alone.
+        ignore = devIgnore(root);
+        reconcile();
+        return;
+      }
+      if (ignore.ignores(file, isDirectory)) return;
+      schedule(file);
+    });
+  };
+
+  /** A `rename` created or removed something: keep the descriptor set honest either way. */
+  const follow = (file: string, isDirectory: boolean): void => {
+    if (isDirectory && isDirectoryAt(join(root, file))) {
+      if (ignore.ignores(file, true)) return;
+      if (!open.has(file)) for (const found of subtree(file)) listen(found);
+      return;
+    }
+    if (open.has(file)) open.remove(file);
+  };
+
+  /** The admitted directories at or under `directory`, discovered rather than assumed. */
+  const subtree = (directory: string): readonly string[] =>
+    admittedDirectories(join(root, directory), ignore).map((found) =>
+      found === '' ? directory : `${directory}/${found}`,
+    );
+
+  /** The whole set, re-derived: a directory the author just ignored gives its descriptor back. */
+  const reconcile = (): void => {
+    const admitted = new Set(admittedDirectories(root, ignore));
+    for (const held of open.directories()) if (!admitted.has(held)) open.remove(held);
+    for (const directory of admitted) if (!open.has(directory)) listen(directory);
+  };
+
+  for (const directory of admittedDirectories(root, ignore)) listen(directory);
+
+  return {
+    directories: () => open.directories(),
+    close(): void {
+      if (timer !== undefined) clearTimeout(timer);
+      open.closeAll();
+    },
+  };
+}
+
+/**
+ * The descriptors this watcher holds, keyed by app-root-relative directory. Its own type because
+ * removing one means removing everything under it: a deleted directory takes its children's
+ * descriptors with it, and a `Map` iterated by the caller would leak every one of them.
+ */
+class WatchDirectoryMap {
+  readonly #watchers = new Map<string, DirectoryWatcher>();
+  readonly #watch: WatchDirectory;
+  readonly #root: string;
+
+  constructor(watchDirectory: WatchDirectory, root: string) {
+    this.#watch = watchDirectory;
+    this.#root = root;
+  }
+
+  add(directory: string, listener: WatchListener): void {
+    if (this.#watchers.has(directory)) return;
+    try {
+      this.#watchers.set(directory, this.#watch(join(this.#root, directory), listener));
+    } catch {
+      // A directory that vanished between the walk and the registration. The parent's own
+      // descriptor still reports anything that reappears there.
+    }
+  }
+
+  has(directory: string): boolean {
+    return this.#watchers.has(directory);
+  }
+
+  directories(): readonly string[] {
+    return [...this.#watchers.keys()].sort();
+  }
+
+  remove(directory: string): void {
+    for (const held of this.#watchers.keys()) {
+      if (held !== directory && !held.startsWith(`${directory}/`)) continue;
+      this.#watchers.get(held)?.close();
+      this.#watchers.delete(held);
+    }
+  }
+
+  closeAll(): void {
+    for (const watcher of this.#watchers.values()) watcher.close();
+    this.#watchers.clear();
+  }
+}

package/src/dev-watch.ts

@@ -0,0 +1,75 @@
+// Which paths under the app root `x dev` must not watch, and the rule is REGISTRATION rather than
+// filtering: `watch(root, { recursive: true })` takes one inotify descriptor per directory before
+// any filter runs, so an answer given after the event has already cost the kernel queue, a JS
+// callback and a slot out of `max_user_watches`. Measured on a monorepo root: 1901 descriptors,
+// 1490 of them under `.git/` and `node_modules/`, and one `git status` delivering 5 events.
+//
+// The ignore set is the app's own `.gitignore`, read with git's own anchoring (`gitignore.ts`),
+// plus a floor of directory names an ignore file need not name. It was seven hand-listed names,
+// and both halves of that were wrong: nothing read `.gitignore`, so `tsconfig.tsbuildinfo` —
+// rewritten by every `bun run typecheck` — ran a full `appManifest()` plus `buildIslands()`; and
+// `dist` and `coverage` were matched at ANY depth, so an app's own `/dist` or `/coverage` route
+// never reloaded at all, silently.
+
+// why: Bun exposes no path-join primitive. The same necessity `fix-path.ts` already records.
+import { join } from 'node:path';
+import type { IgnoreScope } from './gitignore';
+import { ignoreScopes, isGitIgnored } from './gitignore';
+import { pathSegments } from './path-segments';
+
+/**
+ * Directory names no `.gitignore` can be relied on to carry, matched as a path SEGMENT at any
+ * depth. Every entry earns its line, and every one is either dotted or `node_modules` — which is
+ * what makes the any-depth match safe: a `site/` subtree is a URL tree, and neither a dot-directory
+ * nor an install is ever a route.
+ *
+ * - `.git` — git never names its own directory in an ignore file, and `git status`, `git fetch` and
+ *   every commit rewrite index and ref files continuously. The reason this list exists.
+ * - `.x` — the framework's own state: PGlite's data directory (which THIS process writes
+ *   continuously), the dev lock, the static export, `build-stats.json`.
+ * - `node_modules` — an install, not an edit. `x dev` cannot reload for a dependency change: the
+ *   modules are already in this process's cache.
+ * - `.personal` — an app's uncommitted local state, written by scripts while the dev server runs.
+ * - `.claude` — agent scratch, session logs and worktrees. ai-maxxing keeps two entire copies of
+ *   the app under `.claude/worktrees/`, so a second agent's edit rebuilt the first agent's islands.
+ *
+ * `dist` and `coverage` were here and are deliberately not: both are ordinary build output that
+ * every ignore file already names, and hand-listing them cost an app its own routes.
+ */
+export const ALWAYS_IGNORED_DIRECTORIES: readonly string[] = [
+  '.git',
+  '.x',
+  'node_modules',
+  '.personal',
+  '.claude',
+];
+
+/** The ignore set as one question, so the walk and the event filter cannot disagree. */
+export interface DevIgnore {
+  /** `path` is app-root-relative; `isDirectory` decides every trailing-slash rule git holds. */
+  ignores(path: string, isDirectory: boolean): boolean;
+  /** The `.gitignore` files this set was built from, outermost first — what `--json` can report. */
+  readonly scopes: readonly IgnoreScope[];
+}
+
+/**
+ * Read once, at boot and again on every write that names `.gitignore`. A snapshot rather than a
+ * live reader: the watcher rebuilds the whole set and re-walks, so a directory the author just
+ * ignored drops its descriptor instead of keeping one nothing will ever read an event from.
+ *
+ * Two limits, both deliberate. An ANCESTOR ignore file is read at boot and is not watched — it sits
+ * outside the app root, so `x dev` has no descriptor there and a restart is the way to pick up an
+ * edit to it. A NESTED one (`apps/web/.gitignore`) is not read at all: `ignoreScopes` walks upward
+ * only, and watching for one would mean a scope per directory in the tree.
+ */
+export function devIgnore(root: string): DevIgnore {
+  const scopes = ignoreScopes(root);
+  return {
+    scopes,
+    ignores(path: string, isDirectory: boolean): boolean {
+      const segments = pathSegments(path);
+      if (segments.some((segment) => ALWAYS_IGNORED_DIRECTORIES.includes(segment))) return true;
+      return isGitIgnored(scopes, join(root, ...segments), isDirectory);
+    },
+  };
+}

package/src/doctor-offline.ts

@@ -0,0 +1,122 @@
+// `x doctor`'s offline-fallback check: the path the app DECLARED, against the routes it really
+// serves. Its own file because answering it needs the app's config and its route table, and
+// `cmd-doctor.ts`'s job is the probe rather than the loading — the `db-backfill.ts` split, one
+// diagnostic over.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { describeRoutes } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { loadPwaArtifacts } from './pwa-artifacts';
+
+/** A route as this check reads one: the URL it answers, and the surface that answers it. */
+export interface NavigableRoute {
+  readonly path: string;
+  readonly surface: string;
+}
+
+export interface OfflineFallbackFact {
+  /**
+   * `pwa.offline.fallback` as `loadPwaArtifacts` read it, or `null` — which is both "this app
+   * declares no PWA" and "it declares one with no fallback". Either way no service worker is
+   * emitted at all (`serviceWorkerArtifacts` answers `undefined`), so the two share one remedy.
+   */
+  readonly fallback: string | null;
+  /**
+   * Every registered route, or `undefined` when the app would not load. `appEntities`' rule
+   * (`schema-drift.ts`) one registry over: a module that will not import leaves the registry
+   * short, and a short registry reads as "no route serves it" — a generator handed out for a route
+   * the app already has, over one file's syntax error.
+   */
+  readonly routes: readonly NavigableRoute[] | undefined;
+}
+
+/**
+ * The one surface an OFFLINE navigation can land on. `api/` answers a JSON document and `shared/`
+ * is not a URL at all — the pair `sw-artifacts.ts` excludes for the same reason — and `app/` is
+ * excluded for a third: `SURFACE_SPECS` allows it `stream | ssr` and nothing else, only a `static`
+ * route is prerendered, and the service worker precaches a rendered DOCUMENT
+ * (`serviceWorkerArtifacts` reads `documents.get(fallback)`). So an `app/` fallback has nothing
+ * to precache and the offline navigation it is supposed to answer reaches the network and fails —
+ * this check passing for it is the false green it exists to prevent.
+ *
+ * It accepted `app` until 2026-09, on the argument that both surfaces answer the same URL and it
+ * is the FIX that is opinionated. True about URLs and wrong about offline: the fix's own comment
+ * below already refuses `--surface app`, so the check and the remedy disagreed about one code.
+ *
+ * Residual, and NOT closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
+ * either. `NavigableRoute` carries no render mode, and `describeRoutes()` has one — the narrower
+ * check belongs with it.
+ */
+const NAVIGABLE: ReadonlySet<string> = new Set(['site']);
+
+/**
+ * A fallback `x g route <name> --surface site` can actually create: ONE path segment, which is
+ * what the generator turns into `apps/<app>/site/<name>/page.tsx` and therefore into `/<name>`. A
+ * nested or punctuated path would be slugified into a DIFFERENT url (`/support/offline` →
+ * `/support-offline`), so offering the command there is a fix that runs and leaves the finding
+ * exactly where it was.
+ *
+ * `--surface site`, and never `app`: the document that answers a lost network must render with no
+ * network, no session and no database, which `app/` (`ssr | stream`) cannot promise — the reason
+ * `x new` scaffolds it under `site/` (`wiki/Upgrading.md`) — and it is the line `@ultimat3/pwa`'s
+ * own `X_PWA_NO_OFFLINE_FALLBACK` hands out. Two fixes for one code are two answers.
+ */
+const GENERATABLE = /^\/([a-z][a-z0-9-]*)$/;
+
+const finding = (cause: string, fix: string): Finding => ({
+  code: 'X_PWA_NO_OFFLINE_FALLBACK',
+  cause,
+  fix,
+  docs: ERROR_DOCS_URL,
+  at: APP_CONFIG_FILE,
+});
+
+/**
+ * The declared fallback, judged against the route table — never against a filename.
+ *
+ * It WAS a filename: the literal `apps/web/app/offline.tsx`, which `assertRouteFilename` refuses
+ * outright (the directory is the URL, so a page is `page.tsx`), while `x new` scaffolds
+ * `apps/web/site/offline/page.tsx` and this finding's own `fix:` writes
+ * `apps/web/app/offline/page.tsx`. Every one of the three is a different path, so the check was
+ * red for every app the framework has ever produced and no invocation could clear it — the shape
+ * `budgets.ts` calls a false green read backwards, and the reason a diagnostic is held to being
+ * closable by its own fix.
+ */
+export function offlineFallbackFinding(fact: OfflineFallbackFact): Finding | undefined {
+  if (fact.routes === undefined) return undefined;
+  const fallback = fact.fallback;
+  if (fallback === null) {
+    return finding(
+      'no pwa.offline.fallback is declared, so no service worker is emitted and an offline navigation falls back to the browser error page',
+      `set pwa: { offline: { fallback: '/offline' } } in ${APP_CONFIG_FILE}`,
+    );
+  }
+  if (fact.routes.some((route) => route.path === fallback && NAVIGABLE.has(route.surface))) {
+    return undefined;
+  }
+  const cause = `pwa.offline.fallback is "${fallback}" and no site/ route serves it, so an offline navigation falls back to the browser error page`;
+  const name = GENERATABLE.exec(fallback)?.[1];
+  return name === undefined
+    ? finding(cause, `set pwa.offline.fallback in ${APP_CONFIG_FILE} to a path a route serves`)
+    : finding(cause, `x g route ${name} --surface site`);
+}
+
+/**
+ * The fact, read off a real app root. Both halves come from the framework's own answers — the
+ * config through `loadPwaArtifacts` (the one reader of that file) and the routes through
+ * `describeRoutes()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
+ * built from), so this check and the service worker cannot disagree about which routes exist.
+ */
+export async function offlineFallbackProbe(root: string): Promise<OfflineFallbackFact> {
+  const pwa = await loadPwaArtifacts(root);
+  const app = await loadApp(root);
+  return {
+    fallback: pwa?.offline.fallback ?? null,
+    routes:
+      app.findings.length > 0
+        ? undefined
+        : describeRoutes().map((route) => ({ path: route.path, surface: route.surface })),
+  };
+}