@ultimat3/cli 16.0.0 → 18.0.0

package/src/icon-assets.ts

@@ -0,0 +1,74 @@
+// Single responsibility: the one source image every generated icon derives from, where the matrix
+// is served, and the renderer that turns one into the other. Its own module so the two things that
+// need it — `dev-assets.ts`, which SERVES the matrix, and `pwa-artifacts.ts`, which NAMES it in the
+// web manifest — can share it without importing each other.
+
+// why: Bun exposes no path-join primitive, and `ICON_SOURCE` is app-root-relative, so resolving it
+// against the root is string work no `Bun.file` overload does.
+import { join } from 'node:path';
+import type { IconPlan } from '@ultimat3/pwa';
+import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
+
+/**
+ * The one source image every generated icon derives from. `x new` scaffolds it, `x doctor` checks
+ * it and this file reads it — one constant, because a second spelling is an app that passes the
+ * diagnostic and still serves no icons. PNG, not SVG: core's pipeline decodes PNG and JPEG only.
+ */
+export const ICON_SOURCE = 'apps/web/site/icon.png';
+
+/** Where `planIcons` writes, and therefore the paths the generated web manifest names. */
+export const ICON_BASE_PATH = '/icons';
+
+/**
+ * The matrix's whole plan, off one constant pair. One call, so the icons `/icons/*` serves and the
+ * icons `manifest.webmanifest` names can never be two different lists.
+ */
+export const iconPlan = (): IconPlan =>
+  planIcons({ sourceIcon: ICON_SOURCE, outDir: ICON_BASE_PATH });
+
+/**
+ * Whether the app committed the one file the whole matrix derives from. Read where the answer
+ * changes what is EMITTED — a manifest naming twelve icons an app has no source for is twelve 404s
+ * in an install prompt, which is the promise-nothing-keeps shape this module's callers exist to
+ * close. `x doctor` owns the diagnostic and reports the same condition with `X_PWA_ICON_MISSING`.
+ */
+export const hasSourceIcon = (root: string): Promise<boolean> =>
+  Bun.file(join(root, ICON_SOURCE)).exists();
+
+/**
+ * Rendered once per process, not per request: the fourteen matrix entries are pure functions of
+ * one source file, and re-encoding a 512px PNG on every hit would be work no caller can observe.
+ */
+export function iconRenderer(root: string): (plan: IconPlan, path: string) => Promise<Uint8Array> {
+  const pipeline = new BuiltinImagePipeline();
+  const rendered = new Map<string, Promise<Uint8Array>>();
+  const sourceBytes = async (): Promise<Uint8Array> => {
+    const file = Bun.file(join(root, ICON_SOURCE));
+    if (!(await file.exists())) {
+      throw new PwaIconMissingError(
+        `${ICON_SOURCE} does not exist, so every icon the web manifest declares is unbacked and ` +
+          'the app is not installable',
+        // The same edit `x doctor` reports for the same condition, in `@ultimat3/pwa`'s own words.
+        // `x new` was here and takes an app name, so it could never run inside the broken app.
+        `add a 1024x1024 square PNG at ${ICON_SOURCE}`,
+      );
+    }
+    return file.bytes();
+  };
+  return async (plan, path) => {
+    const entry = plan.entries.find((candidate) => candidate.outputPath === path);
+    if (entry === undefined) {
+      throw new PwaIconMissingError(
+        `${path} is not in the icon matrix, so no transform describes it`,
+        `request one of ${plan.entries.map((one) => one.outputPath).join(', ')}`,
+      );
+    }
+    const existing = rendered.get(path);
+    if (existing !== undefined) return existing;
+    const bytes = sourceBytes().then((source) => pipeline.resize(source, entry.transform));
+    rendered.set(path, bytes);
+    // A failed render must not be remembered — the next request comes after the source was added.
+    bytes.catch(() => rendered.delete(path));
+    return bytes;
+  };
+}

package/src/index.ts

@@ -72,6 +72,7 @@ export { testCommand } from './cmd-test';
 export { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
 export type { CliCommand, CommandContext } from './command';
 export { failed, ok } from './command';
+export { acceptCreatedTables, createdTables } from './db-accept-created';
 export type { BranchRow, BranchSubcommand } from './db-branch';
 export {
   BRANCH_SUBCOMMANDS,
@@ -83,11 +84,11 @@ export {
 } from './db-branch';
 export type { GeneratedFiles, GenerateMigrationOptions, GenerateOutcome } from './db-generate';
 export { generateAppMigration, migrationSql } from './db-generate';
+export type { SubscribingQuery } from './db-subscribes';
+export { QuerySubscribesUnknownError, replicaIdentityTables } from './db-subscribes';
 export type { AssetRoutesOptions } from './dev-assets';
 export {
   assetRoutes,
-  ICON_BASE_PATH,
-  ICON_SOURCE,
   MEDIA_BASE_PATH,
 } from './dev-assets';
 export type { DevDashboardInput, DevStatus } from './dev-dashboard';
@@ -234,6 +235,13 @@ export {
 } from './framework-schema';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
+export {
+  hasSourceIcon,
+  ICON_BASE_PATH,
+  ICON_SOURCE,
+  iconPlan,
+  iconRenderer,
+} from './icon-assets';
 // The island bundler, and only its entry point. An island is the one module Ultimate ships to a
 // browser, so an app has to be able to build one to TEST one — `mountIsland` from
 // `@ultimat3/testing` takes this function as its `build` parameter (issue #260). `discoverIslands`,
@@ -274,6 +282,13 @@ export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
 export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
+export type { PwaArtifacts } from './pwa-artifacts';
+export {
+  loadPwaArtifacts,
+  pwaManifestRoute,
+  WEB_MANIFEST_PATH,
+  writePwaIcons,
+} from './pwa-artifacts';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
 export type { SchemaDifference, SchemaDirection, SchemaPart } from './schema-diff';
 export { diffDeclaredSchema } from './schema-diff';
@@ -323,8 +338,8 @@ export type { TestCounts } from './test-counts';
 export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';
 export { belongsToType, discoverTests, sampleFiles } from './test-select';
-export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
-export { planShards, reproduceFor, runShards, shardArgs } from './test-shards';
+export type { ReproduceOptions, RunShardsOptions } from './test-shards';
+export { filesIn, reproduceFor, runShards, testArgs } from './test-shards';
 export { availableCpus, defaultWorkers, WORKER_CEILING } from './test-workers';
 export type {
   CodeFixSite,

package/src/island-harness-script.ts

@@ -144,4 +144,11 @@ export const readinessProbe = (selector: string): string =>
   // Children OR text: a component that renders one text node has painted, and one that mounted
   // and rendered nothing is the silence a non-zero box would otherwise read as success.
   'filled:box?(box.children.length>0||(box.textContent||"").trim().length>0):false,' +
-  'box:{x:Math.round(r.x),y:Math.round(r.y),width:Math.round(r.width),height:Math.round(r.height)}};})()';
+  'box:{x:Math.round(r.x),y:Math.round(r.y),width:Math.round(r.width),height:Math.round(r.height)},' +
+  // The box is VIEWPORT coordinates — what `getBoundingClientRect()` answers — and a capture clip
+  // is PAGE coordinates. They agree only while the page is at the origin, which is the one case a
+  // harness happens to be in and is not a rule anything enforces: a state whose component sits
+  // below the fold scrolls, and a clip taken from the raw rect then crops the wrong band with
+  // nothing to report it. The offset is returned rather than added here so `box` keeps meaning
+  // exactly what the verdict already publishes.
+  'scroll:{x:Math.round(window.scrollX||0),y:Math.round(window.scrollY||0)}};})()';

package/src/island-shot.ts

@@ -5,7 +5,8 @@
 
 // why: no Bun native joins a path; `Bun.write` and `Bun.file` both take one already joined.
 import { join } from 'node:path';
-import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
+import { finiteCount } from '@ultimat3/core';
+import type { CaptureClip, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { systemScrapeClock } from '@ultimat3/scraping';
 import type { IslandShotTarget, IslandStatesManifest, IslandViewport } from '@ultimat3/testing';
 import { islandShotTargets, islandStatesFile } from '@ultimat3/testing';
@@ -138,6 +139,21 @@ export function photographFault(
   return undefined;
 }
 
+/**
+ * The capture rectangle for a readiness answer, in PAGE coordinates.
+ *
+ * `seen` is non-null and its box has area by the time this is reached — `photographFault` refuses
+ * both above, and it refuses them BEFORE the shutter for exactly this reason: a zero-area clip is
+ * `X_SCRAPE_CAPTURE_CLIP_EMPTY` from the port, which is a worse report of the same fault than
+ * "rendered nothing". The `?? 0` pair is the parser's floor and not a second opinion.
+ */
+const clipFor = (seen: IslandReadiness | null): CaptureClip => ({
+  x: (seen?.box.x ?? 0) + (seen?.scroll.x ?? 0),
+  y: (seen?.box.y ?? 0) + (seen?.scroll.y ?? 0),
+  width: seen?.box.width ?? 0,
+  height: seen?.box.height ?? 0,
+});
+
 const hostFix = (target: IslandShotTarget): string =>
   `in ${islandStatesFile(target.island)} set island to a path that exports mount(el, props)`;
 
@@ -157,6 +173,7 @@ async function captureOne(
   options: IslandShotRun,
   server: ShotServer,
   target: IslandShotTarget,
+  floor: number,
 ): Promise<IslandStateShot> {
   const url = new URL(`${ISLAND_HARNESS_PATH}${target.query}`, server.url).toString();
   let session: ScrapeSession | undefined;
@@ -169,6 +186,17 @@ async function captureOne(
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
+    // BEFORE the navigation, so the first paint already has it: `prefers-color-scheme` is a live
+    // media query, and the theme a component resolves on mount is the one it will keep.
+    //
+    // This is the INPUT and the harness's `data-theme` attribute is the OUTCOME, and both are set
+    // deliberately. The attribute is right for a component that READS a theme it does not own; the
+    // preference is the only thing that reaches one that RESOLVES its own. `examples/dummy`'s
+    // settings island is the second kind — its state's `theme` prop is `'system'`, so on mount it
+    // DELETES the attribute the harness set, both pictures fall through to `:root`, and the two
+    // came back byte-identical with the same md5 (issue #338). Re-setting the attribute after
+    // readiness is not the repair: it photographs a state the component would never reach.
+    await page.colorScheme(target.theme);
     await page.goto(url, { timeout: options.timeoutMs });
     const expression = readinessProbe(target.target ?? '[data-x-island]');
     const probe = (): Promise<IslandReadiness | null> =>
@@ -200,10 +228,16 @@ async function captureOne(
         ...fault,
       });
     }
-    // Never `fullPage`: the frame is the state's own declared viewport, and a full-page capture
-    // would grow with whatever the component scrolled.
-    const bytes = await page.screenshot({ fullPage: false });
-    const floor = options.minBytes ?? MIN_SHOT_BYTES;
+    // The COMPONENT, not the viewport it happens to sit in — the crop this feature was designed
+    // around, and which nothing passed until 2026-08-26 (issue #338). The rectangle is the
+    // readiness probe's own box, which is the crop target the manifest declared, translated from
+    // the DOM's viewport coordinates into the page coordinates a capture clip is in.
+    //
+    // The clip ALONE. `fullPage: false` beside it is accepted — `assertCaptureFraming` refuses only
+    // `=== true`, and `cdp-target.ts` sends `{ clip }` and nothing else either way, so all four
+    // pictures really were written with the pair — but it is a field that says nothing: the two
+    // are exclusive, and spelling out the default of the one you did not ask for reads as a choice.
+    const bytes = await page.screenshot({ clip: clipFor(seen) });
     if (bytes.byteLength < floor) {
       throw new IslandUnphotographableError({
         island: target.island,
@@ -257,6 +291,11 @@ export async function runIslandShot(options: IslandShotRun): Promise<IslandArtif
   const targets = islandShotTargets(options.manifest).filter(
     (target) => chosen === null || chosen.has(target.state),
   );
+  // Before the boot, and before a browser: `bytes.byteLength < NaN` is false for every picture, so
+  // an unchecked floor does not lower the backstop — it removes it, and "produced nothing and
+  // exited 0" is the one outcome a reader cannot tell from success. 0 stays legal and is what
+  // `island-shot.test.ts` passes: the fake driver answers an 8-byte PNG signature.
+  const floor = finiteCount('runIslandShot', 'minBytes', options.minBytes ?? MIN_SHOT_BYTES);
   const server = await options.boot();
   const shots: IslandStateShot[] = [];
   const failures: unknown[] = [];
@@ -266,7 +305,7 @@ export async function runIslandShot(options: IslandShotRun): Promise<IslandArtif
       // the app CAN produce plus a named reason for each one it cannot, and the missing-shot gate
       // below is what turns those reasons into a non-zero exit.
       try {
-        shots.push(await captureOne(options, server, target));
+        shots.push(await captureOne(options, server, target, floor));
       } catch (error) {
         failures.push(error);
       }

package/src/island-verdict.ts

@@ -27,10 +27,13 @@ export const ISLAND_SHOT_MESSAGE_KEYS = [
  * this tool cannot support — and both are properties of the port rather than of a run, which is
  * why they are a constant and not a per-run list.
  *
- * The crop one is the honest limit of the shipped browser port: `CaptureRequest` is `fullPage`
- * alone (`packages/scraping/src/page.ts`), so a picture is the VIEWPORT and the framing knob is the
- * state's own `viewport`, not a clip rectangle. The locale one is the reach of a page-side clock
- * patch: `date.toLocaleString()` resolves the zone inside the engine and never through the patched
+ * The crop one is what a rectangle still cannot see: the picture IS the component's own box now
+ * (`clipFor`, `island-shot.ts`), so what a reader loses is the surroundings — a component that
+ * overflows its box, or one whose fault is the space around it, is outside the frame. It said the
+ * opposite until 2026-08-26 — "the browser port takes no clip rectangle" — which stopped being
+ * true when the port gained `CaptureClip`, and a blind spot that names a capability the tool has
+ * is the same lie as one that hides a gap. The locale one is the reach of a page-side clock patch:
+ * `date.toLocaleString()` resolves the zone inside the engine and never through the patched
  * `Intl.DateTimeFormat`.
  */
 export const ISLAND_BLIND_SPOTS = [
@@ -54,7 +57,15 @@ export interface IslandReadiness {
   readonly mounted: boolean;
   readonly failed: string | null;
   readonly filled: boolean;
+  /** The crop target's rectangle in VIEWPORT coordinates, which is what the DOM answers. */
   readonly box: IslandBox;
+  /**
+   * The page's scroll offset at the moment the box was measured. A capture clip is in PAGE
+   * coordinates, so this is what turns one into the other — and it is a separate field rather than
+   * an addition inside the probe because `box` is published in the verdict and means the DOM's own
+   * answer there.
+   */
+  readonly scroll: { readonly x: number; readonly y: number };
 }
 
 const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
@@ -66,6 +77,7 @@ const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
   failed: t.nullable(t.string),
   filled: t.boolean,
   box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
+  scroll: t.object({ x: t.number, y: t.number }),
 }) as unknown as StandardSchemaV1<unknown, IslandReadiness>;
 
 /**

package/src/mcp-errors.ts

@@ -168,6 +168,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // reproduces the finding, and the finding names the file and the header line to add.
   X_MIGRATION_UNGENERATABLE:
     'x verify --only drift --json   # then add the `-- ungeneratable: <n>` header line the finding names',
+  // The edit comes first and the command re-runs it, exactly as the two schema codes above do:
+  // the cause names the query and the name that matched nothing, and `subscribes:` is a field in
+  // that query's own file. Regenerating is safe here — this refusal happens BEFORE anything is
+  // written, so there is no half-generated migration to undo.
+  X_QUERY_SUBSCRIBES_UNKNOWN:
+    'x db gen "retry after fixing subscribes" --json   # first edit subscribes: on the query the cause names',
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',

package/src/messages.ts

@@ -212,7 +212,7 @@ const CATALOG = {
   'cli.shot.island.picture': '  pictures {path}',
   'cli.shot.island.verdict': '  verdict  {path}',
   'cli.shot.island.blind.crop':
-    'the picture is the viewport, not a crop — the browser port takes no clip rectangle, so a state sizes its own frame with viewport',
+    'the picture is the crop target and nothing around it — a component that overflows its own box, or whose fault is the space beside it, is outside the frame',
   'cli.shot.island.blind.locale':
     'toLocaleString() on a Date resolves its zone inside the engine — only an explicit timeZone is pinned by this harness',
   'cli.ci.failed':

package/src/metrics-endpoint.ts

@@ -3,6 +3,7 @@
 // `docker/helm`'s HPAs read a number instead of `<unknown>`.
 
 import {
+  finiteCount,
   logger,
   METRICS_CONTENT_TYPE,
   METRICS_PATH,
@@ -78,7 +79,11 @@ export interface MetricsEndpoint {
  * signal at the moment of load is worse than no autoscaler.
  */
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
-  const port = options.port ?? DEFAULT_METRICS_PORT;
+  // Screened here rather than left to `Bun.serve`, which refuses a `NaN` with a bare `RangeError`
+  // — no code, no `fix:` — at exactly the boot path the refusal below exists to stop reporting
+  // that way. Floor 0, because 0 asks the kernel for a free port and `dev-roles.ts` passes it for
+  // an ephemeral boot; the ceiling stays Bun's, which names the range it refuses.
+  const port = finiteCount('startMetricsEndpoint', 'port', options.port ?? DEFAULT_METRICS_PORT);
   // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
   // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
   // The return type is inferred, keeping `Bun.serve`'s own shape stated once.

package/src/prerender.ts

@@ -17,6 +17,7 @@ import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
+import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 
@@ -147,6 +148,20 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     join(options.out, STATIC_ERROR_PAGE),
     await errorPageDocument(options.root, NOT_FOUND_STATUS),
   );
+  // And the file every document above is about to name. A static export is served with no process
+  // behind it, so `<link rel="manifest">` resolves to a 404 unless the bytes are in the artifact —
+  // an installable app that is installable only under `x dev` is the dev/prod split this whole
+  // wiring exists to close. `undefined` when the app is not installable, and then no document
+  // names it either.
+  const pwa = await loadPwaArtifacts(options.root);
+  if (pwa !== undefined) {
+    await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
+    // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
+    // `/icons/*` entry would be a 404 in the install prompt — the manifest half of the same
+    // promise `favicon.ico` above keeps. Nothing when the app committed no source icon, which is
+    // also when the manifest names no icon.
+    await writePwaIcons(options.root, options.out);
+  }
 
   // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
   // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
@@ -161,6 +176,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(ctx, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
+        ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
       }),
     );
 

package/src/pwa-artifacts.ts

@@ -0,0 +1,188 @@
+// The web manifest an installable app promises, and that no build had ever produced.
+//
+// `pwa.enabled` was a switch with no reader anywhere in the tree (issue #362, and
+// `scripts/lib/config-reader-pins.ts` pinned it as a `jobs.driver` candidate). `@ultimat3/pwa` has
+// shipped `generateWebManifest`, `renderThemeColorMeta`, `planIcons` and `appleTouchLinks` since it
+// existed and NOTHING called them, so every Ultimate app served a `<head>` with no
+// `<link rel="manifest">`, no `theme-color` and no apple-touch icon — and no browser has ever
+// offered to install one, however the config was written.
+//
+// WHY HERE. `dev-assets.ts`'s reason exactly: three packages declare what an installable app is and
+// none of them can read a config file off disk. This one composes tier 0's `pwa` block with tier
+// 4's generator and hands both served surfaces and the static export the same two strings.
+//
+// WHAT IT DOES NOT DO: emit a service worker. `offline`, `backgroundSync` and `push` still have no
+// build behind them — `wiki/PWA-And-Offline.md` says so — and a bad `sw.js` is sticky in a way a
+// manifest is not, so the worker lands behind a real browser check rather than beside this.
+
+// why: Bun exposes no synchronous file-existence primitive, and this read is the same one
+// `app-auth.ts` and `dev-cache.ts` each make before importing an app's config — a root with no
+// `app.config.ts` is an ordinary answer here (a scratch root, `x build` outside an app).
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join primitive, and `APP_CONFIG_FILE` is app-root-relative — the same
+// necessity `favicon.ts` and `dev-assets.ts` each record for their own root-relative constant.
+import { join } from 'node:path';
+import type { PwaColors } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+import {
+  appleTouchLinks,
+  generateWebManifest,
+  renderThemeColorMeta,
+  serializeWebManifest,
+} from '@ultimat3/pwa';
+import { escapeAttribute } from '@ultimat3/seo';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
+
+/** What a browser fetches from `<link rel="manifest">`. The spec's own extension, not `.json`. */
+export const WEB_MANIFEST_PATH = '/manifest.webmanifest';
+
+/**
+ * Short, never immutable. The path carries no content hash, so an app that changed its install
+ * title must be able to publish it — an hour is `favicon.ts`'s number, for the same asset class.
+ */
+const MANIFEST_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/** The two strings every surface needs: the file's bytes, and what `<head>` must carry to name it. */
+export interface PwaArtifacts {
+  /** `manifest.webmanifest`, serialized. */
+  readonly body: string;
+  /**
+   * `<link rel="manifest">`, both `theme-color` metas, and every apple-touch icon link. One string
+   * because a document either carries all of it or none: a manifest link with no theme colour
+   * installs an app whose status bar flashes white on every launch, and an apple-touch link with
+   * no manifest is an iOS icon for an app iOS will not add.
+   */
+  readonly head: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() !== '' ? value : undefined;
+
+/**
+ * `colors` read structurally, for `loadSignInPath`'s reason: `defineConfig` returns a plain object
+ * and a config resolved through an older core simply has no such key. `validate()` already refused
+ * a blank one an `await import` above this line, so anything this rejects is a hand-written config
+ * object — and the honest answer for one is no manifest at all, never a colour we invented.
+ */
+function colorsOf(value: unknown): PwaColors | undefined {
+  if (!isRecord(value)) return undefined;
+  const light = isRecord(value['light']) ? value['light'] : undefined;
+  const dark = isRecord(value['dark']) ? value['dark'] : undefined;
+  if (light === undefined || dark === undefined) return undefined;
+  const [lt, lb, dt, db] = [
+    text(light['themeColor']),
+    text(light['backgroundColor']),
+    text(dark['themeColor']),
+    text(dark['backgroundColor']),
+  ];
+  if (lt === undefined || lb === undefined || dt === undefined || db === undefined)
+    return undefined;
+  return {
+    light: { themeColor: lt, backgroundColor: lb },
+    dark: { themeColor: dt, backgroundColor: db },
+  };
+}
+
+/** The `pwa` block, as much of it as this file needs, or `undefined` when the app declares none. */
+interface InstallableApp {
+  readonly name: string;
+  readonly colors: PwaColors;
+}
+
+async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!existsSync(configPath)) return undefined;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return undefined;
+  const pwa = config['pwa'];
+  // `pwa.enabled`, read. Not a truthiness test: `enabled` is the key this whole file exists to
+  // give a reader, and `=== true` is what makes a hand-written `enabled: 'yes'` produce no
+  // manifest rather than one nobody asked for.
+  if (!isRecord(pwa) || pwa['enabled'] !== true) return undefined;
+  const name = text(pwa['name']);
+  const colors = colorsOf(pwa['colors']);
+  if (name === undefined || colors === undefined) return undefined;
+  return { name, colors };
+}
+
+/**
+ * Resolved ONCE at boot, like `loadSignInPath` and `loadCacheTiers` and unlike `faviconBytes`:
+ * `await import` caches the module, so re-reading per request would answer the same object at a
+ * per-request cost, and the head string has to be available synchronously while a document renders.
+ */
+export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | undefined> {
+  const app = await loadInstallable(root);
+  if (app === undefined) return undefined;
+  // The icons the manifest promises are exactly the ones `/icons/*` serves and `x build` writes —
+  // ONE plan, so no surface can name a size another will not produce.
+  //
+  // AND ONLY WHEN THE APP HAS A SOURCE FOR THEM. `planIcons` answers the same fourteen entries
+  // whether `apps/web/site/icon.png` exists or not, so a manifest built off it unconditionally
+  // promises twelve icons and three apple-touch links that are twelve 404s in an install prompt —
+  // the promise-nothing-keeps shape this whole module exists to close, one level down.
+  // `examples/dummy` is exactly that app: it declares `pwa.enabled: true` and commits no icon.
+  // A missing source is NOT reported here — `x doctor` already refuses it by name with
+  // `X_PWA_ICON_MISSING`, and a second reporter of one condition is the duplication this package's
+  // own rule forbids. Read at boot, like the rest of this function: adding the file takes effect
+  // on the next start, because the manifest is generated once and served as bytes.
+  const icons = (await hasSourceIcon(root)) ? iconPlan() : undefined;
+  const result = generateWebManifest({
+    name: app.name,
+    tokens: app.colors,
+    icons: icons?.manifestIcons ?? [],
+  });
+  return {
+    body: serializeWebManifest(result.manifest),
+    head:
+      `<link rel="manifest" href="${escapeAttribute(WEB_MANIFEST_PATH)}">` +
+      renderThemeColorMeta(result.themeColorMeta) +
+      (icons === undefined ? '' : appleTouchLinks(icons)),
+  };
+}
+
+/**
+ * The icon bytes a STATIC export has to carry, written under `out`. Answers the paths it wrote.
+ *
+ * A static host runs no `assetRoutes()`, so every `/icons/*` entry the manifest names is a 404
+ * unless the bytes are in the artifact — the same rule `prerenderSite` already applies to
+ * `favicon.ico` and `404.html`, one asset class further along. Nothing when the app has no source
+ * icon, which is also when the manifest names none.
+ */
+export async function writePwaIcons(root: string, out: string): Promise<readonly string[]> {
+  if (!(await hasSourceIcon(root))) return [];
+  const plan = iconPlan();
+  const render = iconRenderer(root);
+  const written: string[] = [];
+  for (const entry of plan.entries) {
+    // `outputPath` is `/icons/<file>`; `out` is the export root, so the leading slash goes.
+    await Bun.write(join(out, entry.outputPath.slice(1)), await render(plan, entry.outputPath));
+    written.push(entry.outputPath);
+  }
+  return written;
+}
+
+/**
+ * Mounted through `assetRoutes`, so `x dev` and the container serve it from one place — a surface
+ * that answers in dev and not in the image is the failure that file's own header names.
+ * Public: a browser fetches a manifest before anyone has signed in, and an installable app that
+ * needs a session to describe itself is not installable.
+ */
+export const pwaManifestRoute = (artifacts: PwaArtifacts): Route => ({
+  method: 'GET',
+  path: WEB_MANIFEST_PATH,
+  meta: { name: 'assets.manifest', auth: 'public', cache: MANIFEST_CACHE, tags: ['assets'] },
+  handler: async (_request: UltimateRequest): Promise<Response> =>
+    applyCacheHeaders(
+      new Response(artifacts.body, {
+        headers: { 'content-type': 'application/manifest+json; charset=utf-8' },
+      }),
+      MANIFEST_CACHE,
+    ),
+});

package/src/serve.ts

@@ -25,6 +25,7 @@ import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
+import { acceptCreatedTables } from './db-accept-created';
 import { assetRoutes } from './dev-assets';
 import { startQueue } from './dev-queue';
 import { appRoutes } from './dev-render';
@@ -43,6 +44,7 @@ import { islandRoutes } from './island-routes';
 import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
+import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
 
 export const DEFAULT_PORT = 3000;
@@ -200,7 +202,11 @@ export async function runMigrations(options: ServeOptions): Promise<MigratedApp>
       available: migrations.length,
       appVersion: report.appVersion,
     });
-    const drift = await checkDrift({ migrations });
+    // Every migration above has just been applied, so a `create table` in one of them is proof
+    // the app owns that relation — and a snapshot records only what ENTITIES declare, so without
+    // this a hand-written table is `unexpected-table` on this deploy and on every deploy after it
+    // (issue #345). Only that one difference, only for a name a migration's SQL creates.
+    const drift = acceptCreatedTables(await checkDrift({ migrations }), migrations);
     // Logged with the first difference, not just a count: a release phase's log is the only place
     // an operator sees this, and "3 differences" names nothing to act on.
     if (!drift.ok) {
@@ -293,18 +299,24 @@ async function bootRoles(boot: {
   // does from the same source — the alternative is a second bundler invocation in the image build
   // whose output nothing compares against the one the dev loop proved.
   const islands = await buildIslands(options.root);
+  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
+  // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
+  // prevent, and it is the one an operator cannot see without installing the app.
+  const pwa = await loadPwaArtifacts(options.root);
   const routes: readonly Route[] = [
     ...apiRoutes(),
     ...assetRoutes({
       root: options.root,
       storage: runtime.storage,
       ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
     }),
     ...storageRoutes({ storage: runtime.storage }),
     ...islandRoutes(() => islands),
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
       // the fleet while the other eleven keep serving the page it just invalidated.

package/src/sync-authenticator.ts

@@ -5,7 +5,7 @@
 // by wiring, not by design.
 
 import type { Actor, Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { finiteCount, systemClock } from '@ultimat3/core';
 import type { HttpConfig } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -102,7 +102,13 @@ export function syncAuthenticator(
   // this per connection otherwise.
   const config = upgradeConfig(buildId);
   const clock = options.clock ?? systemClock;
-  const ttlMs = options.ttlMs ?? SYNC_GRANT_TTL_MS;
+  // A credential lifetime, screened where it is declared. `expiresAt` is `now + ttlMs`, and
+  // `GrantBook.expired()` asks `expiresAt <= now` — false for every `now` when the sum is `NaN`,
+  // so the grant never reaches a sweep and the socket keeps a revoked actor's authority for as
+  // long as the tab is open. That is the hole this whole file was written to close, and a `??`
+  // does not close it: `NaN` is not nullish. At least 1ms — a window that has already shut when
+  // the grant is minted is not a window.
+  const ttlMs = finiteCount('syncAuthenticator', 'ttlMs', options.ttlMs ?? SYNC_GRANT_TTL_MS, 1);
 
   const resolve = async (credential: Credential): Promise<SyncGrant | null> => {
     const request = new Request(credential.url, {