@ultimat3/cli 23.0.0 → 25.0.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.
@@ -31,19 +40,52 @@ image:
 
 # Non-secret configuration. Secrets come from an existing Secret, never from this file:
 #   kubectl create secret generic ${app.kebab}-secrets --from-literal=DATABASE_URL=...
+#
+# APP_URL — the pages' public origin — is what the sync node admits a websocket from. With the
+# ingress below enabled the chart SETS it on the sync role from ingress.host (https when
+# ingress.tls), because an undeclared node behind a TLS ingress also admits the plain-http page.
+# Set it here when the pages are served from another host or port than that (a CDN domain, a
+# SYNC_URL of its own): this value wins, and without it every websocket from those pages is
+# 403 X_SOCKET_ORIGIN_REFUSED.
 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
+# schema-owning DATABASE_URL need not sit on a web pod.
+
+# The /tmp every pod mounts (the root filesystem is read-only), bounded: past this the kubelet
+# evicts the pod that filled it, never its neighbours for node disk pressure.
+tmp:
+  sizeLimit: 512Mi
+
+# One NetworkPolicy per serving role (templates/networkpolicy.yaml): \`http\` from httpFrom,
+# \`metrics\` from metricsFrom, nothing else. Inert on a CNI that does not enforce NetworkPolicy.
+#   httpFrom     empty = any source; narrow it to your ingress controller's namespace, e.g.
+#                [{ namespaceSelector: { matchLabels: { kubernetes.io/metadata.name: ingress-nginx } } }]
+#   metricsFrom  default: any pod in the cluster and no address outside it
+#   egress       OFF while empty; a list turns on egress filtering with exactly those rules —
+#                the database, NATS, the object store and DNS are your addresses, so list all of them
+networkPolicy:
+  enabled: true
+  httpFrom: []
+  metricsFrom:
+    - namespaceSelector: {}
+  egress: []
 
 # The scrape listener every serving role opens, on its own port and never the app's: the ingress
 # routes / to web, so /metrics beside /healthz on 3000 is /metrics on the internet. This is
 # 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:
@@ -52,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:
@@ -112,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 }
@@ -153,7 +210,7 @@ ingress:
 `;
 
 /**
- * The chart for a new app: five kinds of object, all of them core Kubernetes. A ServiceMonitor and
+ * The chart for a new app: six kinds of object, all of them core Kubernetes. A ServiceMonitor and
  * a PodDisruptionBudget are deliberately absent — the first needs a CRD `helm install` fails on
  * where no Prometheus operator is installed, and both are cluster policy rather than app topology.
  */

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
@@ -41,10 +43,18 @@ const BIOME_VERSION = '2.5.8';
  */
 const TYPESCRIPT_VERSION = '^7.0.2';
 
+/**
+ * The Solid runtime every island and `@ultimat3/ui` component renders with, exact for the reason
+ * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.15`, and a scaffold
+ * that installed an older runtime than the compiler targets drifted as a buried literal (1.9.14
+ * beside the repository's 1.9.15). `scaffold-repo.test.ts` holds it equal to the root manifest's.
+ */
+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.
@@ -62,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 .",
@@ -82,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}",
@@ -99,7 +110,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/schema": "^${version}",
     "@ultimat3/seo": "^${version}",
     "@ultimat3/ui": "^${version}",
-    "solid-js": "1.9.14"
+    "solid-js": "${SOLID_VERSION}"
   },
   "engines": {
     "bun": ">=${REQUIRED_BUN}"
@@ -176,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.
@@ -195,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
@@ -215,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: {
@@ -227,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 } },
 });
 
 /**
@@ -287,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": {
@@ -356,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',
@@ -462,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);
@@ -272,17 +286,11 @@ const toggleIsland =
 // browser downloads. Named by SPECIFIER from the page, never by import:
 //   const ThemeSwitch = island({ src: '../../shared/theme-toggle.island.tsx', props: ['locale'] });
 //
-// The control itself is the catalog's \`ThemeToggle\`; this file is the runtime it needs and the
-// one decision the framework cannot make for it — see \`bootedEnv\` below.
+// The control itself is the catalog's \`ThemeToggle\`; this file is only the runtime it needs. It
+// reads the browser on its own: the theme the boot stamped on \`<html>\`, then \`theme.defaultMode\`
+// (stamped beside it), then the OS.
 
-import {
-  browserThemeEnv,
-  setSolidRuntime,
-  THEME_ATTRIBUTE,
-  type ThemeEnv,
-  ThemeToggle,
-  UiProvider,
-} from '@ultimat3/ui';
+import { setSolidRuntime, ThemeToggle, UiProvider } from '@ultimat3/ui';
 import {
   createContext,
   createEffect,
@@ -298,17 +306,6 @@ export interface ThemeToggleIslandProps {
   readonly locale: string;
 }
 
-/**
- * With no stored choice the catalog's \`resolveTheme\` asks the OS — but the document already wears
- * the theme the framework's boot script stamped from \`theme.defaultMode\` (dark, in this app), so
- * a toggle that asked the OS would show one theme while the page wore another. The boot's verdict
- * is on \`<html>\` before this runs: read it once, and let a stored choice win as it does there.
- */
-export const bootedEnv = (): ThemeEnv => {
-  const booted = document.documentElement.getAttribute(THEME_ATTRIBUTE) === 'dark';
-  return { ...browserThemeEnv(), prefersDark: () => booted };
-};
-
 /**
  * The one export the hydration runtime calls. \`setSolidRuntime\` comes FIRST and is not optional:
  * \`@ultimat3/ui\` imports types from solid-js and never a runtime, so the reactive graph a
@@ -318,12 +315,11 @@ export const bootedEnv = (): ThemeEnv => {
  */
 export function mount(el: HTMLElement, props: ThemeToggleIslandProps): void {
   setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
-  const env = bootedEnv();
   el.textContent = '';
   render(
     () => (
       <UiProvider locale={props.locale}>
-        <ThemeToggle mode="toggle" env={env} />
+        <ThemeToggle mode="toggle" />
       </UiProvider>
     ),
     el,
@@ -353,15 +349,14 @@ export const themeToggleStates = defineIslandStates({
 
 const toggleTest =
   (): string => `// The toggle the browser actually runs: built with the same \`buildIslands\` as \`x build\`, mounted
-// against a DOM small enough to read, and clicked. What it pins is the one decision this island
-// makes — the boot's verdict on \`<html>\` is what the control starts from, and a click writes the
-// key the boot script reads back on the next load.
+// against a DOM small enough to read, and clicked. What it pins: the boot's verdict on \`<html>\` is
+// what the control starts from, and a click writes the key the boot script reads back next load.
 
 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_STORAGE_KEY } from '@ultimat3/ui';
-import { bootedEnv } from './theme-toggle.island';
+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. */
@@ -371,11 +366,19 @@ const localStorage = {
   setItem: (key: string, value: string): void => void stored.set(key, value),
   removeItem: (key: string): void => void stored.delete(key),
 };
+/** One OS query, shared by every \`matchMedia\` call: \`flipOs\` changes it and tells the listeners. */
+const os = { dark: false, listeners: new Set<() => void>() };
 const matchMedia = (): Record<string, unknown> => ({
-  matches: false,
-  addEventListener: () => {},
-  removeEventListener: () => {},
+  get matches(): boolean {
+    return os.dark;
+  },
+  addEventListener: (_type: string, listener: () => void) => void os.listeners.add(listener),
+  removeEventListener: (_type: string, listener: () => void) => void os.listeners.delete(listener),
 });
+const flipOs = (dark: boolean): void => {
+  os.dark = dark;
+  for (const listener of os.listeners) listener();
+};
 
 // The state \`x shot --island theme-toggle\` photographs is the state this mounts: one manifest,
 // so the picture and the assertion cannot be of two different components.
@@ -404,12 +407,27 @@ describeIslandState(themeToggleStates, 'default', island, (mounted) => {
     expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
   });
 
-  test('the env the island builds starts from the theme stamped on <html>', () => {
-    // The fake document is still installed here, so this reads exactly what \`mount\` read.
+  test('with nothing stored, a click flips the theme the boot stamped — not the OS', () => {
+    // The OS fake says light. The boot stamped this app's \`defaultMode\`, dark, so the visible
+    // theme is dark and the first click must go light; a toggle that asked the OS would write the
+    // dark already on screen and look dead.
+    stored.clear();
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'dark');
     mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'dark');
-    expect(bootedEnv().prefersDark()).toBe(true);
-    mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'light');
-    expect(bootedEnv().prefersDark()).toBe(false);
+    expect(mounted().fire('button', 'click')).toBe(true);
+    expect(stored.get(THEME_STORAGE_KEY)).toBe('light');
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('light');
+  });
+
+  test("an OS flip is followed while nothing is stored and the app's default is 'system'", () => {
+    stored.clear();
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'system');
+    flipOs(true);
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
+    // A fixed default is the app's own opinion: the OS does not override it.
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'dark');
+    flipOs(false);
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
   });
 });
 `;

package/src/test-counts.ts

@@ -5,6 +5,8 @@
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
 import { parseBunTest } from './mcp-test-output';
+// One reader of bun's `N errors` line, shared with MCP `tests.run` — never a second regex.
+import { errorsIn } from './mcp-test-run';
 
 export interface TestCounts {
   /** Tests that executed — passed plus failed. A failed test is a test that ran. */
@@ -20,12 +22,6 @@ export interface TestCounts {
   readonly errors?: number;
 }
 
-/** Bun's own `N error` / `N errors` summary line: the last one, as `parseBunTest` reads the rest. */
-const errorsIn = (output: string): number => {
-  const last = [...output.matchAll(/^\s*(\d+)\s+errors?\s*$/gm)].at(-1);
-  return last === undefined ? 0 : Number.parseInt(last[1] ?? '0', 10);
-};
-
 /**
  * Summed across every process the step spawned, because a step is one line in the gate whether it
  * ran on one worker or eight.

package/src/test-ignores.ts

@@ -0,0 +1,25 @@
+// The ONE policy for which paths are never a test the gate runs here, projected twice: the path
+// predicate `discoverTests` filters by and the `--path-ignore-patterns` the serial steps pass to
+// `bun test`. A leaf, so `test-select.ts` and `verify-tests.ts` (which import each other) share it.
+
+/** Build output and installed packages: never a test, at ANY depth — a workspace's `dist/` too. */
+const IGNORED_ANYWHERE = ['dist', 'node_modules'] as const;
+
+/**
+ * Nested projects with their own gate (`examples/`, `dummy/`, run by
+ * `scripts/reference-app-gate.ts`) and the root `build/` — skipped AT THE ROOT only. Matched at any
+ * depth they swallowed an app's own slice: `x g resource build` lost 14 of its 16 test files and
+ * `x g resource example` its `examples/` page tests, from `x test` and the gate alike.
+ */
+const IGNORED_AT_ROOT = ['build', 'examples', 'dummy'] as const;
+
+/** Whether a root-relative POSIX path is excluded from every test selection. */
+export const isIgnoredTestPath = (path: string): boolean =>
+  IGNORED_ANYWHERE.some((dir) => `/${path}`.includes(`/${dir}/`)) ||
+  IGNORED_AT_ROOT.some((dir) => path.startsWith(`${dir}/`));
+
+/** The same policy as `bun test --path-ignore-patterns` globs, relative to the run's root. */
+export const IGNORED_TEST_PATTERNS: readonly string[] = [
+  ...IGNORED_ANYWHERE.map((dir) => `**/${dir}/**`),
+  ...IGNORED_AT_ROOT.map((dir) => `${dir}/**`),
+];