@ultimat3/cli 24.0.0 → 25.1.0

package/src/templates/scaffold-helm.ts

@@ -8,6 +8,15 @@
 import type { GeneratedFile, NameSet } from './naming';
 import { helmTemplateFiles } from './scaffold-helm-templates';
 
+/**
+ * The uid AND gid the app's process runs as, in the image and in every pod: the `bun` user of the
+ * `oven/bun:1.4-alpine` base the scaffolded Dockerfile pins (`id bun` → `uid=1000 gid=1000`). One
+ * number, read by both templates, because two of them drifted — the chart ran distroless'
+ * `nonroot` (65532), a uid that image does not have. Pinned to the measurement by
+ * `scaffold-container.test.ts`.
+ */
+export const RUNTIME_UID = 1000;
+
 /**
  * `appVersion` is the default image tag (`image.tag: ""` below), so it must name a tag that can
  * exist. `x deploy --image <ref>` overrides both keys, which is the path that actually ships.
@@ -41,7 +50,7 @@ image:
 env:
   NODE_ENV: production
 
-existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET, ULTIMATE_CURSOR_SECRET
+existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET, and .env.example's Framework section
 
 # The release-wide Secret above is every role's DEFAULT: \`existingSecret\` under a role
 # (roles.web.existingSecret, migrate.existingSecret) names that role's own, so the migrate Job's
@@ -71,9 +80,12 @@ networkPolicy:
 # METRICS_PORT in the container; move one and the other follows.
 metricsPort: 9090
 
+# The image's \`bun\` user, the same uid as the Dockerfile's USER: move one and the other follows.
 podSecurityContext:
   runAsNonRoot: true
-  runAsUser: 65532
+  runAsUser: ${RUNTIME_UID}
+  runAsGroup: ${RUNTIME_UID}
+  fsGroup: ${RUNTIME_UID}
   seccompProfile: { type: RuntimeDefault }
 
 securityContext:
@@ -82,10 +94,20 @@ securityContext:
   capabilities: { drop: [ALL] }
 
 # The stop sequence: out of the Service, then this preStop sleep (Kubernetes 1.30+ only), then
-# SIGTERM, then the framework's readiness grace and drain. terminationGracePeriodSeconds in
-# templates/deployments.yaml is sized to all three, so move them together.
+# SIGTERM, then the framework's readiness grace and drain. Each Deployment's
+# terminationGracePeriodSeconds is DERIVED from this block per role — never set it by hand.
+#   readinessGraceSeconds  app.config.ts drain.readinessGraceMs / 1000 (web and sync only)
+#   deadlineSeconds        app.config.ts drain.deadlineMs / 1000 — x deploy --method helm sets
+#                          both from app.config.ts, so a raised budget raises the grace with it
+#   teardownMarginSeconds  the release after the drain, the telemetry flush, the pool close
 drain:
   preStopSleepSeconds: 5
+  readinessGraceSeconds: 5
+  deadlineSeconds: 25
+  teardownMarginSeconds: 10
+
+# How long a new pod must stay Ready before a rollout counts it and stops an old one.
+minReadySeconds: 10
 
 # The release phase. Runs to completion before any serving role starts.
 migrate:
@@ -142,6 +164,11 @@ roles:
   worker:
     enabled: true
     replicas: 2
+    # The retire, OFF at 0. Set to the longest a held job may run, in seconds, and the worker's
+    # preStop sends its PID 1 SIGUSR2: stop claiming, finish every held job, abort nothing, exit 0
+    # — for a job whose side effect must happen at most once and may outlast drain.deadlineSeconds.
+    # Added to this role's terminationGracePeriodSeconds, which the kubelet counts the preStop against.
+    retireSeconds: 0
     resources:
       requests: { cpu: 200m, memory: 256Mi }
       limits: { memory: 1Gi }

package/src/templates/scaffold-http.ts

@@ -13,7 +13,7 @@ const httpConfig = (
   app: NameSet,
 ): string => `// What this app declares about HTTP. Module scope IS the wiring: the boot scan imports every
 // module under \`apps/*\` before a listener binds, and \`x dev\` and the container both read the
-// configured value back at start — the same seam \`app/auth/dev-actor.ts\` installs through.
+// configured value back at start — the same seam \`app/auth/authenticator.ts\` installs through.
 //
 // The BOOT lays its own facts over whatever this says: \`port\`, \`hostname\`, \`dev\`, \`buildId\`,
 // \`signInPath\`, \`trustProxy\`, \`trustedProxyHops\` and \`rateLimit.scope\` are all facts about the

package/src/templates/scaffold-i18n.ts

@@ -2,6 +2,7 @@
 // blessed typed-catalog shape (modelled on examples/dummy/packages/i18n/src/index.ts) — split out
 // of scaffold-repo.ts to stay under the file-size ceiling.
 
+import { APP_CATALOGS_PATH } from '@ultimat3/i18n/app-catalogs';
 import { catalogJson } from './catalog-json';
 import type { GeneratedFile, NameSet } from './naming';
 import { camel } from './naming';
@@ -121,7 +122,7 @@ const i18nCatalog = (app: NameSet): string =>
     'site.home.secondary': 'Open the admin',
     'site.home.f1Title': 'One command to a running app',
     'site.home.f1Body':
-      'bin/setup installs, migrates and seeds; bin/dev runs every role in one process.',
+      'bun run setup installs, migrates and seeds; bun run dev runs every role in one process.',
     'site.home.f2Title': 'Policies, not flags',
     'site.home.f2Body':
       'Every route, action and query declares who may call it, and one system decides.',
@@ -149,6 +150,18 @@ const i18nCatalog = (app: NameSet): string =>
     'app.dashboard.columnTitle': 'Title',
     'app.dashboard.columnCreated': 'Created',
     'app.dashboard.emptyTitle': 'No posts yet',
+    'app.dashboard.statPaid': 'Paid posts',
+    'app.dashboard.hintPaid': 'priced above zero',
+    'app.dashboard.chartKey': 'Day',
+    'app.dashboard.chartSeries': 'Posts',
+    'app.dashboard.mixTitle': 'Free and paid',
+    'app.dashboard.mixLabel': 'Posts by price, free against paid',
+    'app.dashboard.mixFree': 'Free',
+    'app.dashboard.mixPaid': 'Paid',
+    'app.dashboard.mixTotal': 'posts',
+    'app.dashboard.mixKey': 'Price',
+    'app.dashboard.gaugeLabel': 'Created this week, of all posts',
+    'app.dashboard.columnPrice': 'Price',
     'app.dashboard.statRoutes': 'Routes',
     'app.dashboard.hintRoutes': 'registered at boot',
     'app.dashboard.statLocales': 'Locales',
@@ -203,7 +216,7 @@ export function i18nFiles(app: NameSet, version: string): readonly GeneratedFile
       '**/*.ts',
       'catalogs/**/*',
     ]),
-    { path: 'packages/i18n/src/index.ts', contents: i18nIndex(['en']) },
+    { path: APP_CATALOGS_PATH, contents: i18nIndex(['en']) },
     { path: 'packages/i18n/src/index.test.ts', contents: i18nTest() },
     { path: 'packages/i18n/catalogs/en.json', contents: i18nCatalog(app), merge: 'json' },
   ];

package/src/templates/scaffold-icon.ts

@@ -4,7 +4,7 @@
 // never turn it into the fourteen `ICON_MATRIX` PNGs the generated web manifest declares.
 
 import type { Raster } from '@ultimat3/core';
-import { createRaster, encodeImage } from '@ultimat3/core';
+import { blankRaster, encodeImage } from '@ultimat3/core';
 
 /** `@ultimat3/pwa`'s own contract (`requireSourceIcon`'s fix line): square, 1024 or larger. */
 const ICON_SIZE = 1024;
@@ -48,7 +48,7 @@ function paintMark(raster: Raster, inset: number): void {
  * so `x new` output never depends on run order or the clock.
  */
 export function icon(): Uint8Array {
-  const raster = createRaster(ICON_SIZE, ICON_SIZE, 'scaffold-icon');
+  const raster = blankRaster(ICON_SIZE, ICON_SIZE, 'scaffold-icon');
   paintMark(raster, Math.round(ICON_SIZE * MASKABLE_PADDING));
   return encodeImage(raster, 'png');
 }

package/src/templates/scaffold-repo.ts

@@ -12,11 +12,13 @@ import { VERIFY_FLOOR_FILE } from '../verify-floor';
 import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
 import { titleCase } from './naming';
+import { BIN_SCRIPTS, binScript } from './scaffold-bin';
 import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
 import { envExampleSource, envSchemaSource } from './scaffold-env';
 import { PWA_COLORS } from './scaffold-errors';
+import { rootGitattributesFile } from './scaffold-gitattributes';
 import { scaffoldGuardFiles } from './scaffold-guards';
 import { i18nFiles } from './scaffold-i18n';
 import { mcpPackageFiles } from './scaffold-mcp-package';
@@ -28,7 +30,7 @@ import { uiPackageFiles } from './scaffold-ui-package';
  * config as out of date on every `bun run lint`. A formatter is a build input — a range that floats
  * is a `lint` step whose verdict depends on the day the app was installed.
  */
-const BIOME_VERSION = '2.5.8';
+const BIOME_VERSION = '2.5.15';
 
 /**
  * The checker a scaffolded app typechecks with, and it must not lag the one the FRAMEWORK is built
@@ -52,7 +54,7 @@ const SOLID_VERSION = '1.9.15';
 // `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
 // (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor
 // BELOW the CLI the app then runs, so on a box with Bun 1.3.x `bun install` succeeded and the very
-// next line of `bin/setup` died `X_BUN_VERSION: Bun 1.3.14 is older than the required 1.4.0` — a
+// next line of `bun run setup` died `X_BUN_VERSION: Bun 1.3.14 is older than the required 1.4.0` — a
 // floor admitting a runtime the app's own first command refuses. Interpolated, the two cannot
 // disagree; `scripts/bun-pin.test.ts` reads the emitted string as one more pin site, and
 // `github/ci.yml.ts` pins the workflow's Bun to the same constant.
@@ -70,9 +72,9 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "packages/*"
   ],
   "scripts": {
-    "setup": "bin/setup",
+    "setup": "${binScript(BIN_SCRIPTS.setup)}",
     "dev": "x dev",
-    "check": "bin/check",
+    "check": "${binScript(BIN_SCRIPTS.check)}",
     "verify": "x verify",
     "typecheck": "tsc -p . --pretty",
     "lint": "biome check .",
@@ -90,6 +92,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
   "dependencies": {
     "@ultimat3/action": "^${version}",
     "@ultimat3/admin": "^${version}",
+    "@ultimat3/auth": "^${version}",
     "@ultimat3/cache": "^${version}",
     "@ultimat3/cli": "^${version}",
     "@ultimat3/core": "^${version}",
@@ -184,9 +187,8 @@ export const env = defineEnv(envSchema);`;
  * author has no use for a comment about keys their config does not name.
  *
  * `tier` is the one that got through, and it says what the list was worth. It accepted
- * `'channels' | 'live-queries' | 'local-first'`, so `'local-first'` read as a durable client store
- * that does not exist (`createOpfsLocalStore` throws `X_NOT_IMPLEMENTED`) — silent, and shaped like
- * a capability. Which realtime tier an app is on is decided by what it DECLARES: a `channel()`
+ * `'channels' | 'live-queries' | 'local-first'`, and nothing read the value — silent, and shaped
+ * like a capability. Which realtime tier an app is on is decided by what it DECLARES: a `channel()`
  * topic, a `live: true` query, a local store. `scaffold-config.test.ts` no longer holds a list of
  * dead names to remember; it resolves every key path this literal writes against what `defineConfig`
  * really returns, so the fourteenth deletion fails there with no edit here.
@@ -203,10 +205,8 @@ ${envDeclaration()}
 
 export const config = defineConfig({
   name: '${app.kebab}',
-  locales: ['en'],
-  defaultLocale: 'en',
-  defaultTimeZone: 'UTC',
-  defaultCurrency: 'USD',
+  // Locales are declared by the catalogs (\`defineCatalogs\` in \`packages/i18n/src/index.ts\`); no
+  // zone or currency default exists — every format call names its zone, every \`Money\` its currency.
   // Env KEYS, never the value: the same image deploys to every environment. The database is
   // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
   // The tiers ARE the cache selection: add 'redis' to build the shared rung, which reads
@@ -223,7 +223,7 @@ export const config = defineConfig({
     enabled: true,
     // The document an offline navigation gets when the cache has no answer, and the path
     // \`apps/web/site/offline/page.tsx\` serves. Required once \`enabled\` is true: an installable
-    // app that shows the browser's error page offline is the failure the block exists to prevent.
+    // app that shows the browser error page offline is the failure the block exists to prevent.
     offline: { fallback: '/offline' },
     name: '${titleCase(app.raw)}',
     colors: {
@@ -235,7 +235,7 @@ export const config = defineConfig({
   // it, and a choice stored by the theme toggle wins over it on every later visit; 'system' follows
   // the OS.
   theme: { defaultMode: 'dark' },
-  ai: { mcp: { expose: true, path: '/mcp' } },
+  ai: { mcp: { expose: true } },
 });
 
 /**
@@ -295,7 +295,8 @@ const biome = (): string => `{
     "rules": {
       "preset": "recommended",
       "suspicious": { "noExplicitAny": "error" },
-      "correctness": { "noUnusedVariables": "error", "noUnusedImports": "error" }
+      "correctness": { "noUnusedVariables": "error", "noUnusedImports": "error" },
+      "style": { "useNodejsImportProtocol": "error" }
     }
   },
   "javascript": {
@@ -364,7 +365,7 @@ export const SCAFFOLD_COVERAGE_EXCLUDE: readonly CoverageExclude[] = [
   },
   {
     glob: 'apps/*/server.ts',
-    why: 'the container entry point: it boots the roles and lives as long as the process — bin/dev and the image exercise it',
+    why: 'the container entry point: it boots the roles and lives as long as the process — bun run dev and the image exercise it',
   },
   {
     glob: 'apps/*/prerender.ts',
@@ -470,6 +471,8 @@ export function repoFiles(
     { path: VERIFY_FLOOR_FILE, contents: verifyFloor(example) },
     { path: 'types/scss.d.ts', contents: scssTypes() },
     { path: '.gitignore', contents: gitignore() },
+    // Every text file LF whatever `core.autocrlf` says — a Windows checkout is otherwise CRLF.
+    rootGitattributesFile(),
     { path: '.env.development', contents: envDevelopment() },
     // Committed, and generated: `x env example` rewrites this file from `envSchema`, and the
     // gate's `manifest` step fails with X_ENV_EXAMPLE_DRIFT when the two stop agreeing. A

package/src/templates/scaffold-shell.ts

@@ -90,7 +90,7 @@ export function Shell(props: ShellProps): JSX.Element {
                 <span class={styles.env}>
                   {/* The pulse is a CSS opacity animation: alive without a byte of script. */}
                   <span class={styles.envDot} aria-hidden="true" />
-                  {environment}
+                  <span class={styles.envLabel}>{environment}</span>
                 </span>
               )}
               {props.actions}
@@ -125,9 +125,13 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
   justify-content: space-between;
   gap: tokens.space(4);
   inline-size: 100%;
+  // Free to shrink below its content: on a 390px phone the brand gives way, never the page.
+  min-inline-size: 0;
 }
 
+// The controls keep their size; the brand is what truncates.
 .end {
+  flex: none;
   display: inline-flex;
   align-items: center;
   gap: tokens.space(3);
@@ -136,6 +140,7 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 .brand {
   display: inline-flex;
   align-items: center;
+  min-inline-size: 0;
   gap: tokens.space(3);
   color: tokens.role('fg-strong');
 
@@ -146,6 +151,7 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 // One accent tile. The only saturated surface in the chrome, so the eye has exactly one anchor.
 .mark {
+  flex: none;
   display: inline-grid;
   place-items: center;
   inline-size: tokens.space(8);
@@ -159,6 +165,7 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .wordmark {
   @include tokens.data-text;
+  @include tokens.truncate;
 
   font-size: tokens.text('sm');
   font-weight: tokens.weight('medium');
@@ -178,6 +185,13 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
   font-size: tokens.text('xs');
 }
 
+// Below sm the pill is its dot: the word stays readable to assistive tech, not to the layout.
+.envLabel {
+  @include tokens.respond-down(sm) {
+    @include tokens.visually-hidden;
+  }
+}
+
 .envDot {
   inline-size: tokens.space(2);
   block-size: tokens.space(2);
@@ -340,8 +354,9 @@ const toggleTest =
 
 import { join } from 'node:path';
 import { buildIslands } from '@ultimat3/cli';
+import { THEME_STORAGE_KEY } from '@ultimat3/core';
 import { describeIslandState, expect, test } from '@ultimat3/testing';
-import { THEME_ATTRIBUTE, THEME_DEFAULT_ATTRIBUTE, THEME_STORAGE_KEY } from '@ultimat3/ui';
+import { THEME_ATTRIBUTE, THEME_DEFAULT_ATTRIBUTE } from '@ultimat3/ui';
 import { themeToggleStates } from './theme-toggle.island.states';
 
 /** What the island reads through \`browserThemeEnv\`: storage and the OS query, both fakes. */

package/src/test-only-shipped.ts

@@ -0,0 +1,193 @@
+// `package-shape`'s third rule of "test code does not ship": a `src/` module only tests (and
+// fixtures) import is test code under a name `files` cannot see. The tarball excludes `*.test.ts`
+// and `*-fixture.ts`, so a fake, a probe or a `bun:test` helper named anything else rode into
+// every install — 20 of them across eleven packages until 2026-10. The defect is the name.
+
+import { ERROR_DOCS_URL, renderFixShellArg } from '@ultimat3/core';
+import type { ClosureHost } from './import-closure';
+import { resolveSpec } from './import-closure';
+import type { Finding } from './output';
+import { FIXTURE_SUFFIX } from './publish-closure';
+import { eachSourceFile, isGenerated, isTest } from './source-files';
+
+/** A published package: its directory under `packages/` and the files its manifest names. */
+export interface ShippedPackage {
+  readonly dir: string;
+  /** Package-relative (`src/index.ts`), and may be a glob (`src/icons/glyphs/*.ts`). */
+  readonly entries: readonly string[];
+}
+
+export interface TestOnlyModule {
+  readonly path: string;
+  /** Every file that imports or names it — all of them tests, fixtures or test-only modules. */
+  readonly importers: readonly string[];
+}
+
+/**
+ * Every `src/` file a manifest names anywhere — `exports`, `bin`, the `browser` map, a `scripts`
+ * command (`bun run src/icons/build-icons.ts`). Read off the whole document rather than field by
+ * field: a module the manifest names is shipped on purpose, whichever field names it.
+ */
+export function entryPatternsOf(manifest: unknown): readonly string[] {
+  const text = JSON.stringify(manifest ?? null);
+  const found = [...text.matchAll(/(?:\.\/)?(src\/[\w./*-]+?\.tsx?)(?![\w.])/g)];
+  return [...new Set(found.map((match) => match[1] ?? ''))].sort();
+}
+
+// Type-only imports count: the package ships `.ts` source, so a consumer's `tsc` opens the file a
+// shipped `import type` names. One pattern for `from '.'`, `import('.')` and `import '.'`, relative
+// specifiers only: over-matching an importer only ever clears a module, never flags one.
+const RELATIVE = /(?:\bfrom|\bimport)\s*\(?\s*(['"])(\.\.?\/[^'"]*)\1/g;
+/**
+ * A template-literal `import(\`./drivers/${n}\`)`: the static head up to the first `${` names a
+ * DIRECTORY prefix, and any module under it may be the one loaded. With no `${` the closing
+ * backtick ends it and it is an ordinary specifier.
+ */
+const TEMPLATE = /\bimport\s*\(\s*`(\.\.?\/[^`$]*)(\$\{|`)/g;
+/** A file named in a string — `join(import.meta.dir, 'probe.ts')`, `new URL('./worker.ts', …)`. */
+const NAMED = /['"`/]([\w.-]+\.tsx?)['"`]/g;
+
+/**
+ * Whether the match at `index` sits on a line that IS a comment — `//`, a doc comment's `*`, a
+ * `/*` opener. Line-wise and not core's `stripComments`, which is exact and costs ~1.1 s over the
+ * repo's 6,000 files (measured 2026-10-05); asked only of a match, never of every line. The lines
+ * this skips are where a commented-out or quoted-in-prose import lives, and one it keeps can only
+ * clear a module, never flag one.
+ */
+function onCommentLine(text: string, index: number): boolean {
+  let at = text.lastIndexOf('\n', index - 1) + 1;
+  while (text[at] === ' ' || text[at] === '\t') at += 1;
+  const head = text.slice(at, at + 2);
+  return head === '//' || head === '/*' || head.startsWith('*');
+}
+
+/** `from`'s directory joined with a relative `head`, `.` and `..` folded; a trailing `/` kept. */
+function prefixFrom(from: string, head: string): string {
+  const parts = from.split('/').slice(0, -1);
+  const segments = head.split('/');
+  const last = segments.pop() ?? '';
+  for (const segment of segments) {
+    if (segment === '..') parts.pop();
+    else if (segment !== '.' && segment !== '') parts.push(segment);
+  }
+  return `${parts.join('/')}/${last}`;
+}
+
+const isFixture = (path: string): boolean => path.endsWith(FIXTURE_SUFFIX);
+const baseName = (path: string): string => path.slice(path.lastIndexOf('/') + 1);
+
+const add = (map: Map<string, Set<string>>, key: string, value: string): void => {
+  const set = map.get(key);
+  if (set === undefined) map.set(key, new Set([value]));
+  else set.add(value);
+};
+
+/** Who imports each file, and which files name each basename in a string. One pass per file. */
+function referrersOf(sources: ReadonlyMap<string, string>): {
+  readonly imports: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly named: ReadonlyMap<string, ReadonlySet<string>>;
+} {
+  const host: ClosureHost = { read: (path) => sources.get(path), alias: () => undefined };
+  const imports = new Map<string, Set<string>>();
+  const named = new Map<string, Set<string>>();
+  const prefixes: { readonly prefix: string; readonly from: string }[] = [];
+  for (const [from, text] of sources) {
+    for (const match of text.matchAll(RELATIVE)) {
+      if (onCommentLine(text, match.index)) continue;
+      const target = resolveSpec(host, from, match[2] ?? '');
+      if (target !== undefined && target !== from) add(imports, target, from);
+    }
+    for (const match of text.matchAll(TEMPLATE)) {
+      if (onCommentLine(text, match.index)) continue;
+      const head = match[1] ?? '';
+      if (match[2] === '`') {
+        const target = resolveSpec(host, from, head);
+        if (target !== undefined && target !== from) add(imports, target, from);
+      } else prefixes.push({ prefix: prefixFrom(from, head), from });
+    }
+    for (const match of text.matchAll(NAMED)) {
+      if (!onCommentLine(text, match.index)) add(named, match[1] ?? '', from);
+    }
+  }
+  // Few computed imports in any repo, so a scan of every path per prefix costs nothing measurable.
+  for (const { prefix, from } of prefixes) {
+    for (const path of sources.keys()) {
+      if (path !== from && path.startsWith(prefix)) add(imports, path, from);
+    }
+  }
+  return { imports, named };
+}
+
+/**
+ * The shipped `.ts` modules of the given packages whose every importer is a test, a fixture or
+ * another such module — a greatest fixed point, so a helper only a fake imports is caught with the
+ * fake. A module nobody references is not this rule's question, and an entry point is shipped by
+ * definition. `.tsx` is not judged: `FIXTURE_EXCLUSION` matches `-fixture.ts` alone.
+ */
+export function testOnlyModules(
+  sources: ReadonlyMap<string, string>,
+  packages: readonly ShippedPackage[],
+): readonly TestOnlyModule[] {
+  const { imports, named } = referrersOf(sources);
+  const entryGlobs = new Map(
+    packages.map((pkg) => [
+      pkg.dir,
+      pkg.entries.map((entry) => new Bun.Glob(`packages/${pkg.dir}/${entry}`)),
+    ]),
+  );
+  const referrers = new Map<string, ReadonlySet<string>>();
+  for (const path of sources.keys()) {
+    const dir = /^packages\/([^/]+)\/src\//.exec(path)?.[1];
+    const globs = dir === undefined ? undefined : entryGlobs.get(dir);
+    if (globs === undefined || !path.endsWith('.ts') || isGenerated(path)) continue;
+    if (isTest(path) || isFixture(path) || globs.some((glob) => glob.match(path))) continue;
+    const from = new Set([...(imports.get(path) ?? []), ...(named.get(baseName(path)) ?? [])]);
+    from.delete(path);
+    if (from.size > 0) referrers.set(path, from);
+  }
+  const testOnly = new Set(referrers.keys());
+  const live = (path: string): boolean => !isTest(path) && !isFixture(path) && !testOnly.has(path);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const path of testOnly) {
+      if (![...(referrers.get(path) ?? [])].some(live)) continue;
+      testOnly.delete(path);
+      changed = true;
+    }
+  }
+  return [...testOnly].sort().map((path) => ({
+    path,
+    importers: [...(referrers.get(path) ?? [])].sort(),
+  }));
+}
+
+/** `X_PACKAGE_TEST_ONLY_SHIPPED`, its fix the registered rename with the real paths in it. */
+export const testOnlyShippedFinding = (module: TestOnlyModule): Finding => {
+  const shown = module.importers.slice(0, 3).join(', ');
+  const more = module.importers.length > 3 ? ` and ${module.importers.length - 3} more` : '';
+  return {
+    code: 'X_PACKAGE_TEST_ONLY_SHIPPED',
+    cause: `${module.path} is imported only by tests and fixtures (${shown}${more}), and "files" publishes it — test scaffolding in every install`,
+    fix: `git mv ${renderFixShellArg(module.path, '<the module above>')} ${renderFixShellArg(module.path.replace(/\.ts$/, FIXTURE_SUFFIX), '<its name>-fixture.ts')}   # and update its importers`,
+    docs: ERROR_DOCS_URL,
+    at: module.path,
+    meta: { importers: [...module.importers] },
+  };
+};
+
+/**
+ * The rule over a repo on disk. Every source file is a possible importer — a script reading a
+ * package's module by relative path is a shipped use of it — so the walk is the gate's own
+ * (`eachSourceFile`), tests included. A repo with no published package reads nothing.
+ */
+export async function checkTestOnlyShipped(
+  root: string,
+  packages: readonly ShippedPackage[],
+): Promise<readonly Finding[]> {
+  if (packages.length === 0) return [];
+  const paths: string[] = [];
+  for await (const path of eachSourceFile(root)) if (!isGenerated(path)) paths.push(path);
+  const texts = await Promise.all(paths.map((path) => Bun.file(`${root}/${path}`).text()));
+  const sources = new Map(paths.map((path, index) => [path, texts[index] ?? '']));
+  return testOnlyModules(sources, packages).map(testOnlyShippedFinding);
+}

package/src/test-select.ts

@@ -6,12 +6,13 @@ import { join } from 'node:path';
 // Bun ships no equivalent: `join` builds the host-separator path from the scan root to a hit.
 // Sizing is Bun's own (`Bun.file().size`), so nothing here reaches for `node:fs`.
 import { nearestName, renderFixShellArg } from '@ultimat3/core';
+import { TEST_TYPES } from '@ultimat3/testing';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
 import { isIgnoredTestPath } from './test-ignores';
 import type { TestType } from './verify-tests';
-import { ownerOf, TEST_TYPES } from './verify-tests';
+import { ownerOf } from './verify-tests';
 
 export interface TestFile {
   readonly path: string;

package/src/test-shards.ts

@@ -52,9 +52,6 @@ import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
 import { testEnvOverrides } from './test-dotenv';
 
-/** `@ultimat3/testing`'s `ISOLATED_ENV` — the one spelling, which that package's preload reads. */
-export const ISOLATED_TEST_ENV = ISOLATED_ENV;
-
 /** Bun's per-file durations, cached under the run's root and refreshed by every parallel run. */
 export const TEST_TIMINGS_FILE = '.x/test-timings.json';
 
@@ -258,7 +255,7 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
     // Only an isolated run: the preload clears `Bun.plugin` handlers after each file, which in a
     // shared global would leave the next `.tsx` compiling with Bun's classic factory.
-    ...(isolatedRun(options) ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(isolatedRun(options) ? { [ISOLATED_ENV]: '1' } : {}),
   };
   const passthrough = options.passthrough ?? [];
   const watching = passthrough.includes('--watch');

package/src/theme-boot.ts

@@ -22,8 +22,8 @@ export interface ThemeBoot {
 /**
  * Tag and hash from ONE body: `themeScriptBody` is what `themeScript` inlines, so a policy hashed
  * here admits the script the document carries and not a restatement of it. The storage key is
- * render's `THEME_STORAGE_KEY`, which `theme-boot.test.ts` pins equal to `@ultimat3/ui`'s — the
- * toggle writes the key the boot reads.
+ * `@ultimat3/core`'s `THEME_STORAGE_KEY`, the one `@ultimat3/ui`'s toggle writes — so the toggle
+ * writes the key the boot reads.
  */
 export function themeBoot(mode: ThemeMode): ThemeBoot {
   const options = { fallback: mode };

package/src/theme-brand.ts

@@ -0,0 +1,66 @@
+// The app's brand, declared once as `export const brand = defineTheme(…)` in
+// `apps/web/shared/theme.ts`, read here and nowhere else: the `<style>` every document the boot
+// renders carries after its stylesheet, and the body `style-src` admits. No module, no brand: an
+// unthemed app emits no tag and extends no policy.
+
+// why: Bun exposes no path-join primitive, and the module path is app-root-relative.
+import { join } from 'node:path';
+import { ConfigInvalidError, describeValue } from '@ultimat3/core';
+import { renderHead } from '@ultimat3/render';
+
+/** The conventional module, beside `shared/global.ts` — one fixed path, as `API_INDEX` is. */
+export const APP_THEME_MODULE = 'apps/web/shared/theme.ts';
+/** The named export the module declares — `@ultimat3/ui`'s README spells it `brand`. */
+export const APP_THEME_EXPORT = 'brand';
+
+export interface ThemeBrand {
+  /** The rendered `<style>`, for `DocumentOptions.brandHead`. */
+  readonly head: string;
+  /** Exactly the text between the tags — the body a boot hands `inlineStyleSources`. */
+  readonly style: string;
+}
+
+/** Code to paste, as `loadAppConfig`'s is: the module path is already in the cause. */
+const FIX = `export const ${APP_THEME_EXPORT} = defineTheme({ preset: 'scifi' });`;
+
+/**
+ * `undefined` when the app has no theme module or its brand renders no CSS. A module that will not
+ * import throws as it did, so a palette `defineTheme()` refuses fails the boot with
+ * `X_UI_CONTRAST_INSUFFICIENT` (or its token code) and not a rewording of it.
+ */
+export async function loadThemeBrand(root: string): Promise<ThemeBrand | undefined> {
+  const path = join(root, APP_THEME_MODULE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  const css = brandCss(path, module);
+  if (css.length === 0) return undefined;
+  // `renderHead` escapes `</` in a style body, which would make the tag's text differ from the
+  // hashed one — so a body that needs escaping is refused above rather than escaped here.
+  return { head: renderHead([{ kind: 'style', key: 'style:brand', content: css }]), style: css };
+}
+
+/**
+ * The brand's stylesheet, read structurally: `@ultimat3/ui` is a tier below and this package does
+ * not import it, so a `Brand` is `{ css: string }`. `defineTheme()` never emits `<` — its values
+ * are validated against grammars that exclude it — so one here came from a hand-built object, and
+ * it is the one character that could end the element and start markup.
+ */
+function brandCss(path: string, module: Record<string, unknown>): string {
+  const brand = Object.hasOwn(module, APP_THEME_EXPORT) ? module[APP_THEME_EXPORT] : undefined;
+  const css = typeof brand === 'object' && brand !== null && 'css' in brand ? brand.css : undefined;
+  if (typeof css !== 'string') {
+    throw new ConfigInvalidError({
+      cause: `${path} exports no ${APP_THEME_EXPORT} built by defineTheme() (${describeValue(brand)}), so no document can carry the app's theme — declare it with defineTheme from @ultimat3/ui`,
+      fix: FIX,
+      meta: { key: APP_THEME_EXPORT },
+    });
+  }
+  if (css.includes('<')) {
+    throw new ConfigInvalidError({
+      cause: `${path}'s ${APP_THEME_EXPORT}.css contains "<", which defineTheme() never emits and which could close the <style> element it is inlined in`,
+      fix: FIX,
+      meta: { key: APP_THEME_EXPORT },
+    });
+  }
+  return css;
+}