@ultimat3/cli 19.1.2 → 19.2.0

package/CLAUDE.md

@@ -156,6 +156,7 @@ them is answered by this table rather than by a second convention:
 | `x tasks` | `cmd-tasks.ts`, `tasks-facts.ts` | `registeredTasks()` + `@ultimat3/time`'s cron resolution |
 | `x policy` | `cmd-policy.ts`, `policy-facts.ts` | `@ultimat3/policy`'s `policyMatrix()` over the app's own `Policy` objects |
 | `x i18n` | `cmd-i18n.ts`, `i18n-audit.ts`, `i18n-registration.ts` | `@ultimat3/i18n`'s `extractFromFiles` + `auditCatalogs`, then the live catalog registry |
+| `x i18n check` and the `policy` step, before either registry | `duplicate-packages.ts` | `Bun.resolveSync` of `@ultimat3/i18n` / `@ultimat3/policy` / `@ultimat3/entity` from the app root, every workspace and the CLI's own directory, keyed by REALPATH. Two real directories is `X_PACKAGE_DUPLICATED`: a registry is per module instance, so the app registers into one copy and the CLI reads the other — `x i18n check` said "move `defineCatalogs()`" about a call that was already where it belongs (ai-maxxing, 2026-09-05), and the policy step was green over an undeclared grant. A workspace symlink to one checkout is one copy; two store entries at ONE version are two |
 
 Each pairs a `cmd-*.ts` of CLI wiring with a facts module that takes plain inputs and returns plain
 data, so the projection is testable without a `ParsedArgs` — the `cmd-jobs.ts` / `jobs-report.ts`
@@ -981,7 +982,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |
 | `dev-render.ts` | one HTTP route per registered `route`, through render's own mode function |
-| `style-csp.ts` | the `style-src` sha256 of every inline `<style>` the web role serves |
+| `style-csp.ts` | the `style-src` sha256 of every inline `<style>` the web role **still** serves — the app's own surface CSS is a file under `/styles/` (`style-bundle.ts`) admitted by `'self'`, so a production boot extends the directive with nothing |
 | `script-csp.ts` | the `script-src` sha256 of every inline `<script>` it serves — the hydration runtime, from `@ultimat3/render`'s own `HYDRATE_RUNTIME_BODIES` |
 | `dev-assets.ts` | the image pipeline's only HTTP surface: `/icons/*` and `/media/*` |
 | `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
@@ -995,6 +996,8 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `statement-loop.ts` | one verdict → the finding, the panel fact, the overlay notice and the log line |
 | `dev-policy.ts` | which actors to ask about, and which capability each policy gates |
 | `cmd-dev.ts` | boot order, mounting `/_x`, installing the span exporter, the file watcher |
+| `dev-watch.ts` | which writes under the app root are a source change. Seven directories are never one — `.x`, `node_modules`, `.git`, `.personal`, `.claude`, `dist`, `coverage` — and each is matched as a path SEGMENT: the rule was `filename.includes('.x/') \|\| filename.includes('node_modules')`, so `git status`, an agent's scratch file and a coverage run each ran a full `appManifest()` + `buildIslands()` (measured in ai-maxxing, which keeps two whole copies of the app under `.claude/worktrees/`), while a directory named `my-node_modules-notes/` got no reload at all |
+| `style-bundle.ts` / `style-routes.ts` | a surface's CSS as one content-hashed file under `/styles/`, served `immutable` — `island-bundle.ts` / `island-routes.ts`' shape one asset over. It was an inline `<style>` until 2026-09-06: 156,738 bytes, identical on every page, inside a `private, no-store` document. The URL is the hash alone, no surface in the name: a surface is not a property of the bytes, and an app whose only CSS is its global layer would otherwise write three identical files into its static export and three entries into a precache manifest that has a budget |
 | `mcp-host.ts` | the `DevCapabilities` half of `@ultimat3/mcp`'s `DevHost` — db, tests, logs, verify |
 | `mcp-db-target.ts` | which database the host is pointed at: whether it is a branch, and whether it is production |
 | `mcp-errors.ts` | `errors.explain`: one runnable command per code, typed over `CliErrorCode` |
@@ -1134,8 +1137,20 @@ island's `src` is a string, so no import edge reaches it and the page's graph st
 against bytes. Two islands that both import the same helper each carry a copy; that is the honest
 number for what booting either one costs.
 
-**The chunk URL is content-addressed with render's own `contentHash`** — the function that already
-stamps an ETag and a precache revision. One identity for a byte string, not a third.
+**The chunk URL is SOURCE-addressed, not byte-addressed, `As of 2026-09-06`.** `graphHash` hashes
+the build's inputs — the source map's `sourcesContent`, sorted, plus the entry's app-relative path,
+the framework version and `Bun.version` — with render's own `contentHash`, the function that already
+stamps an ETag and a precache revision. Hashing the OUTPUT is what it did, and `Bun.build` is not
+byte-deterministic under `minify`: measured on 1.4.0, one entry point, no source file touched, a
+131,589-byte island alternated between two outputs of identical length differing only in minified
+identifier names, roughly one build in ten. The URL then flapped — ten names in ten minutes in
+ai-maxxing — so the service worker precached a chunk that 404ed and the `immutable` cache never hit.
+The cost of the alternative was measured and refused: `minify: { identifiers: false }` IS
+deterministic and is +47% raw, +20% gzipped, on every island of every app. `sourcemap: 'external'`
+pays for the input list (277ms against 276ms) and its `//# debugId=` line is stripped, so the
+shipped bytes are unchanged. Two processes can therefore serve two byte strings at one URL — the
+same program under different local names — and a per-file cache keeps ONE process serving one.
+Delete `graphHash` the day `Bun.build` is deterministic.
 
 **`x dev`, the container and the static export all mount the same table.** `serve.ts` builds the
 islands at boot for the same reason it mounts `apiRoutes()`: a seam that works in dev and not in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.1.2",
+  "version": "19.2.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "19.1.2",
-    "@ultimat3/admin": "19.1.2",
-    "@ultimat3/ai": "19.1.2",
-    "@ultimat3/auth": "19.1.2",
-    "@ultimat3/cache": "19.1.2",
-    "@ultimat3/core": "19.1.2",
-    "@ultimat3/db": "19.1.2",
-    "@ultimat3/entity": "19.1.2",
-    "@ultimat3/flags": "19.1.2",
-    "@ultimat3/http": "19.1.2",
-    "@ultimat3/i18n": "19.1.2",
-    "@ultimat3/jobs": "19.1.2",
-    "@ultimat3/mail": "19.1.2",
-    "@ultimat3/manifest": "19.1.2",
-    "@ultimat3/mcp": "19.1.2",
-    "@ultimat3/money": "19.1.2",
-    "@ultimat3/notify": "19.1.2",
-    "@ultimat3/policy": "19.1.2",
-    "@ultimat3/pwa": "19.1.2",
-    "@ultimat3/query": "19.1.2",
-    "@ultimat3/realtime": "19.1.2",
-    "@ultimat3/render": "19.1.2",
-    "@ultimat3/schema": "19.1.2",
-    "@ultimat3/scraping": "19.1.2",
-    "@ultimat3/seo": "19.1.2",
-    "@ultimat3/storage": "19.1.2",
-    "@ultimat3/testing": "19.1.2",
-    "@ultimat3/time": "19.1.2",
+    "@ultimat3/action": "19.2.0",
+    "@ultimat3/admin": "19.2.0",
+    "@ultimat3/ai": "19.2.0",
+    "@ultimat3/auth": "19.2.0",
+    "@ultimat3/cache": "19.2.0",
+    "@ultimat3/core": "19.2.0",
+    "@ultimat3/db": "19.2.0",
+    "@ultimat3/entity": "19.2.0",
+    "@ultimat3/flags": "19.2.0",
+    "@ultimat3/http": "19.2.0",
+    "@ultimat3/i18n": "19.2.0",
+    "@ultimat3/jobs": "19.2.0",
+    "@ultimat3/mail": "19.2.0",
+    "@ultimat3/manifest": "19.2.0",
+    "@ultimat3/mcp": "19.2.0",
+    "@ultimat3/money": "19.2.0",
+    "@ultimat3/notify": "19.2.0",
+    "@ultimat3/policy": "19.2.0",
+    "@ultimat3/pwa": "19.2.0",
+    "@ultimat3/query": "19.2.0",
+    "@ultimat3/realtime": "19.2.0",
+    "@ultimat3/render": "19.2.0",
+    "@ultimat3/schema": "19.2.0",
+    "@ultimat3/scraping": "19.2.0",
+    "@ultimat3/seo": "19.2.0",
+    "@ultimat3/storage": "19.2.0",
+    "@ultimat3/testing": "19.2.0",
+    "@ultimat3/time": "19.2.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-openapi.ts

@@ -1,12 +1,20 @@
-// `openapi.json`, projected from the action registry by `@ultimat3/action`. The CLI writes the
-// file and compares the bytes; it does not know how an operation is shaped, which is why there
-// is no second OpenAPI builder to drift from the one the server serves.
+// `openapi.json`, projected from the two registries: the actions by `@ultimat3/action`'s
+// `buildOpenApi`, the queries by `@ultimat3/query`'s `queryOpenApiPaths`. The CLI merges the two
+// `paths` maps — those packages are one tier and cannot compose each other — writes the file and
+// compares the bytes; it does not know how an operation is shaped, which is why there is no third
+// OpenAPI builder to drift from the ones the packages serve. Until 2026-09 only the actions were
+// here, and every `GET /_x/query/<name>` the server mounted was a route the spec had never heard of.
 
 import { buildOpenApi, serializeOpenApi } from '@ultimat3/action';
 import type { Manifest } from '@ultimat3/manifest';
+import { queryOpenApiPaths } from '@ultimat3/query';
 
 export const OPENAPI_FILE = 'openapi.json';
 
 /** The exact bytes on disk — deterministic, so `x verify` can compare them literally. */
-export const openApiJson = (manifest: Manifest): string =>
-  serializeOpenApi(buildOpenApi({ title: manifest.app.name, version: manifest.app.version }));
+export const openApiJson = (manifest: Manifest): string => {
+  const document = buildOpenApi({ title: manifest.app.name, version: manifest.app.version });
+  // Action paths are `/api/...`, query paths `/_x/query/...`: disjoint by prefix, so the spread
+  // can never shadow one with the other. `serializeOpenApi` sorts the merged keys.
+  return serializeOpenApi({ ...document, paths: { ...document.paths, ...queryOpenApiPaths() } });
+};

package/src/browser-launcher.ts

@@ -13,6 +13,7 @@ import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
 import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
+import { CHROME_CANDIDATES } from './cdp-launch';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -56,6 +57,33 @@ export class ShotBrowserMissingError extends UltimateError {
   }
 }
 
+/**
+ * The OTHER half of "no browser": the library is installed and there is no Chrome for it to start.
+ *
+ * The same code as the class above because it is the same question to a reader — `x shot` has no
+ * browser — and a code is a stable public name, not a taxonomy. The cause and the fix are what
+ * differ, and they are the half that is acted on: `bun add -d puppeteer-core` cannot install
+ * Chrome, and `export CHROME_PATH=…` cannot install a client that speaks CDP.
+ *
+ * Raised BEFORE the dev server, which is the whole point of it: the launch that used to report this
+ * happens inside `driver.open()`, one embedded Postgres past the point where the answer was already
+ * decidable from the environment and the filesystem.
+ */
+export class ShotChromeMissingError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_SHOT_BROWSER_MISSING',
+      cause: `x shot launches a browser here and none was named or found — no ${BROWSER_PATH_VARS.join(' or ')} is set, and none of ${CHROME_CANDIDATES.join(', ')} is on disk`,
+      // One literal, for `fix-scan.ts`'s reason — the same rule the class above states. It names an
+      // export rather than an install because a path is the one repair that works whatever the
+      // browser is and wherever the distribution put it; `--cdp-url` is the answer for a box that
+      // will never have one, and it is a flag `x shot` already ships.
+      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome or Chromium binary; a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
+      meta: { tried: [...CHROME_CANDIDATES], vars: [...BROWSER_PATH_VARS] },
+    });
+  }
+}
+
 /**
  * Structural, because this is somebody else's module: a namespace object, a CJS `default`, or a
  * transpiled interop wrapper are all shapes `import()` legitimately hands back, and only one
@@ -99,22 +127,43 @@ export interface AppBrowserOptions {
   readonly load?: (path: string) => Promise<unknown>;
 }
 
-/** The path a run will launch, or `undefined` for "let the library find its own". */
+/** True when a named executable is really there — a bad `--browser` is refused before a boot. */
+export const browserBinaryExists = (path: string): boolean => existsSync(path);
+
+/**
+ * The path a run will launch, or `undefined` when this machine has no browser to launch.
+ *
+ * NOT "let the library find its own": `puppeteer-core` ships no browser and has no default, so a
+ * launch with no `executablePath` throws ``An `executablePath` or `channel` must be specified``
+ * from inside somebody else's library, one dev-server boot after the point where the answer was
+ * knowable. So the last step is a PROBE — the same four paths `cdp-launch.ts` already tries for the
+ * e2e driver, imported rather than restated, because two lists of Chrome locations that must agree
+ * is the drift axiom 2 refuses.
+ *
+ * A value NAMED in the flag or the environment is answered without touching the filesystem, even
+ * when nothing is there: an operator who typed a path has a belief about which binary runs, and
+ * silently substituting a probed one would photograph a page in a browser they did not choose.
+ * `shotBrowserChoice` reports that path as absent instead.
+ *
+ * `exists` is the injectable seam, so the probe is asserted the same way on a machine with Chrome
+ * and on one without.
+ */
 export const executablePathFrom = (
   flag: string | undefined,
   env: Readonly<Record<string, string | undefined>>,
+  exists: (path: string) => boolean = browserBinaryExists,
 ): string | undefined => {
   if (flag !== undefined && flag.length > 0) return flag;
   for (const name of BROWSER_PATH_VARS) {
     const value = env[name];
     if (value !== undefined && value.length > 0) return value;
   }
+  for (const candidate of CHROME_CANDIDATES) {
+    if (exists(candidate)) return candidate;
+  }
   return undefined;
 };
 
-/** True when a named executable is really there — a bad `--browser` is refused before a boot. */
-export const browserBinaryExists = (path: string): boolean => existsSync(path);
-
 /** The endpoint a run will attach to, or `undefined` for "launch one here". */
 export const cdpUrlFrom = (
   flag: string | undefined,

package/src/budgets.ts

@@ -12,6 +12,7 @@ import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import { formatBytes, parseByteBudget } from '@ultimat3/render';
 import type { Finding } from './output';
+import type { UnmeasuredRoute } from './static-report';
 
 export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 
@@ -87,14 +88,52 @@ function unmeasuredFinding(url: string, declared: string, built: boolean): Findi
   };
 }
 
+/**
+ * The ONE code a failed measurement is reported under by its own name rather than as
+ * `X_BUDGET_UNMEASURED`. Its cause is complete — the island, the prop, its bytes, the cap — and
+ * its fix is an edit to the page, so the step's own "run x build and read the list" would put a
+ * second command between the author and a sentence the build had already composed. Every other
+ * render failure keeps the generic finding: a `TypeError` from a `load` that wanted a request is
+ * a reason to read the report, not an instruction.
+ *
+ * ONE code and not "any coded error", deliberately. `X_NO_CONTEXT`, `X_UNAUTHENTICATED` and
+ * `X_DB_UNAVAILABLE` from a measurement render are facts about the BUILD's environment, and
+ * reporting them under their own codes would tell the author to fix a database the gate never
+ * had. The list grows by a decision, per code, here.
+ */
+const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set(['X_ISLAND_PROPS_INVALID']);
+
+/**
+ * The build's own finding for a route it could not weigh, when that failure is an instruction.
+ * Read off the static report's `unmeasured` list — the same list `X_BUDGET_UNMEASURED`'s `fix:`
+ * sends its reader to, now read by the step itself for the one code it can act on.
+ */
+function ownCodeFinding(url: string, unmeasured: readonly UnmeasuredRoute[]): Finding | undefined {
+  const entry = unmeasured.find((one) => one.path === url);
+  if (entry?.code === undefined || !REPORTED_BY_OWN_CODE.has(entry.code)) return undefined;
+  return {
+    code: entry.code,
+    cause: entry.cause ?? entry.reason,
+    fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
+    docs: ERROR_DOCS_URL,
+    at: url,
+  };
+}
+
 /**
  * `undefined` stats means no build has run; `{ routes: [] }` means one ran and emitted nothing.
  * The parameter is widened rather than defaulted, because collapsing the two here is exactly the
  * distinction the finding above exists to make.
+ *
+ * `unmeasured` is the static report's list of routes the build rendered and could not weigh, with
+ * each failure's code when it had one. Optional because the report is written beside the stats
+ * and can be absent for the same reason; with it, a route whose measurement failed on a code in
+ * `REPORTED_BY_OWN_CODE` is reported under that code, with the build's own cause and fix.
  */
 export function checkBudgets(
   manifest: Manifest,
   stats: BuildStats | undefined,
+  unmeasured: readonly UnmeasuredRoute[] = [],
 ): readonly Finding[] {
   const byPath = new Map((stats?.routes ?? []).map((route) => [route.path, route]));
   const findings: Finding[] = [];
@@ -104,7 +143,10 @@ export function checkBudgets(
     const lcp = route.budget?.lcp;
     if (measured === undefined) {
       if (js !== null || lcp !== undefined) {
-        findings.push(unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined));
+        findings.push(
+          ownCodeFinding(route.url, unmeasured) ??
+            unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined),
+        );
       }
       continue;
     }

package/src/cmd-dev.ts

@@ -39,10 +39,12 @@ import type { DevServices } from './dev-services';
 import { describeServices, reportedUrls, resolveServices } from './dev-services';
 import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
+import { isIgnoredPath } from './dev-watch';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands } from './island-bundle';
+import { FRAME_STYLE } from './island-harness';
 import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
@@ -53,6 +55,8 @@ import { flagString } from './parse';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 
@@ -92,12 +96,16 @@ interface DevState {
   islands: IslandBundle;
 }
 
-/** Debounced: a save that touches five files is one reload, not five. */
+/**
+ * Debounced: a save that touches five files is one reload, not five. What counts as a save at all
+ * is `dev-watch.ts` — a reload is a full `appManifest()` plus a `buildIslands()` over every island,
+ * so a write this cannot rule out is the most expensive no-op the dev loop has.
+ */
 function watchApp(root: string, onChange: (file: string) => void): () => void {
   let timer: ReturnType<typeof setTimeout> | undefined;
   let last = '';
   const watcher = watch(root, { recursive: true }, (_event, filename) => {
-    if (filename === null || filename.includes('.x/') || filename.includes('node_modules')) return;
+    if (filename === null || isIgnoredPath(filename)) return;
     last = filename;
     if (timer !== undefined) clearTimeout(timer);
     timer = setTimeout(() => onChange(last), 30);
@@ -191,7 +199,13 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   const serviceWorker =
     pwa === undefined
       ? undefined
-      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands: state.islands });
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands: state.islands,
+          styles: styleBundle(),
+        });
 
   // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
   // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
@@ -215,6 +229,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // The chunks the documents below name. Mounted before the app's routes for the reason
     // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
     ...islandRoutes(() => state.islands),
+    // And the stylesheet every one of those documents links. Read through the getter for the
+    // reason the islands are: a rebuilt island registers CSS, which mints a new URL, and a table
+    // captured at boot would answer 404 for the href the document now carries.
+    ...styleRoutes(() => styleBundle()),
     // `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
@@ -258,10 +276,12 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // The same seam `serve.ts` passes: the app's own error page is a FILE, so the root is what
     // `startWeb` needs to find one.
     root: options.root,
-    // The one document this process serves that the app did not write; `startRoles` covers the
-    // app's own surfaces itself. `x dev` sends the policy report-only, so an uncovered `<style>`
-    // here is a console report rather than a blank page — which is how this reached production.
-    inlineStyles: [await devShellStyle()],
+    // The documents this process serves that the app did not write — the `/_x` shell and the
+    // screenshot harness's frame. The app's OWN surfaces need no entry any more: their CSS is a
+    // content-hashed file `'self'` already admits (`style-bundle.ts`). `x dev` sends the policy
+    // report-only, so an uncovered `<style>` here is a console report rather than a blank page —
+    // which is how this reached production.
+    inlineStyles: [await devShellStyle(), FRAME_STYLE],
     // The fourth surface, and the only one an author sees without leaving the page they broke:
     // the overlay renders this request's own loops under the error it is already showing.
     // `serve.ts` boots through the same `startRoles` and passes nothing, so production has no

package/src/cmd-shot.ts

@@ -322,7 +322,9 @@ export const shotCommand: CliCommand = {
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
     // Which browser this run gets — start one here, or attach to one somebody else is running.
     // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
-    // provider session exists to pay for a typo.
+    // provider session exists to pay for a typo. It also PROBES for an installed Chrome and refuses
+    // when there is none: `puppeteer-core` bundles no browser, so a missing one used to surface as
+    // a library throw one embedded Postgres later.
     const { cdpUrl, executablePath } = shotBrowserChoice({
       cdpFlag: flagString(ctx.args, 'cdp-url'),
       browserFlag: flagString(ctx.args, 'browser'),

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-sync.ts

@@ -18,6 +18,7 @@ import type { StartRolesOptions } from './dev-roles';
 import { neighbouringPort, PORT_RANGE } 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 —
@@ -177,7 +178,12 @@ 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;
+    const listener = listenSyncNode(node, { port, hostname: binding.hostname });
     return {
       url: listener.url,
       registry,

package/src/dev-watch.ts

@@ -0,0 +1,53 @@
+// Which writes under the app root are a source change, and which are noise. Split out of
+// `cmd-dev.ts` because it is a rule with cases rather than four lines of glue, and because the
+// answer needs a test of its own: a watcher that reloads on the wrong write is invisible — the
+// dev server stays correct and merely does the most expensive thing it can do, repeatedly.
+//
+// What it was: `filename.includes('.x/') || filename.includes('node_modules')`. Measured against
+// ai-maxxing, whose checkout carries `.git/`, `.personal/`, `.claude/worktrees/` (two FULL copies
+// of the app) and `coverage/`, every write under any of them ran a whole `appManifest()` plus a
+// `buildIslands()` over ten islands. `git status`, an agent's scratch file and a coverage run each
+// cost a full rebuild, and each rebuild re-minted every island chunk.
+//
+// `includes` was also the wrong operator, not just the wrong list: a directory legitimately named
+// `my-node_modules-notes/` was excluded from the dev loop for a substring, and `notes/.xyz/` for
+// another. The match is on a PATH SEGMENT, so only the directory itself is ever ignored.
+
+/**
+ * Directories whose writes are never an app source change.
+ *
+ * Every entry earns its line and none is a guess:
+ * - `.x` — the framework's own state directory: PGlite's data, the dev lock, the static export,
+ *   `build-stats.json`. `x build` writes here, which made a build trigger reloads of the process
+ *   that was running it.
+ * - `node_modules` — an install, not an edit. `x dev` does not reload for a dependency change
+ *   because it cannot: the modules are already in this process's cache.
+ * - `.git` — the reason this list exists. `git status`, `git fetch` and every commit rewrite index
+ *   and ref files continuously, and none of them is a source edit; a checkout of a branch IS one,
+ *   but it also writes the source files themselves, which this list does not touch.
+ * - `.personal` — an app's uncommitted local state (ai-maxxing's fleet file, its inventory, its
+ *   credentials). 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`, `coverage` — build and test output. Both are written by commands an author runs
+ *   BESIDE `x dev`, which is exactly when a spurious rebuild costs the most.
+ */
+export const IGNORED_DIRECTORIES: readonly string[] = [
+  '.x',
+  'node_modules',
+  '.git',
+  '.personal',
+  '.claude',
+  'dist',
+  'coverage',
+];
+
+/**
+ * A path segment, never a substring. `filename` arrives from `node:fs`'s watcher root-relative and
+ * with the platform's separator, so both are normalised before the split — a rule that reads
+ * `foo/node_modules/bar` and not `foo\\node_modules\\bar` is a rule that does not exist on Windows.
+ */
+export function isIgnoredPath(filename: string): boolean {
+  const segments = filename.replaceAll('\\', '/').split('/');
+  return segments.some((segment) => IGNORED_DIRECTORIES.includes(segment));
+}