@ultimat3/cli 17.0.0 → 19.0.0

package/src/dev-purge.ts

@@ -1,5 +1,10 @@
-// The retention sweep this boot owns: the three framework tables that grow with traffic, the
-// `purge()` job that empties them and the `task` that fires it hourly.
+// The retention sweep this boot owns: the framework tables that grow with traffic, the `purge()`
+// job that empties them and the `task` that fires it hourly.
+//
+// FIVE TARGETS over six tables, `As of 2026-08-27` — `x_idempotency`, `x_rate_limit`, the two
+// `x_auth` tables under one target, `x_notify_deliveries` and `x_notify_inbox`. Counted nowhere in
+// prose but here: this header said "three" for two releases after the notify tables joined the
+// boot's DDL, which is how `x_notify_inbox` became the one framework table nothing swept.
 //
 // WHY here and not in the packages that own the tables: `postgresIdempotencyStore` (tier 3),
 // `postgresRateLimitStore` (tier 2) and `postgresAuthLimiter` (tier 2) cannot see each other and
@@ -17,6 +22,9 @@ import { purgeAuthLimits } from '@ultimat3/auth';
 import type { PostgresRateLimitStore } from '@ultimat3/http';
 import type { JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
 import { DEFAULT_PURGE_CRON, getJob, getTask, purge, task } from '@ultimat3/jobs';
+import { purgeNotifyDeliveries, purgeNotifyInbox } from '@ultimat3/notify';
+import type { InboxRetention } from './dev-notify-retention';
+import { NO_INBOX_RETENTION } from './dev-notify-retention';
 
 /** The durable queue key. Pinned, like every framework-owned job name — rows carry it. */
 export const PURGE_JOB_NAME = 'x.purge';
@@ -36,6 +44,42 @@ export const PURGE_TASK_NAME = 'x.purge.hourly';
 export interface RetentionStores {
   readonly idempotency: PostgresIdempotencyStore;
   readonly rateLimit: PostgresRateLimitStore;
+  /**
+   * The app's own answer to "how long is an unread message kept", loaded from `app.config.ts` by
+   * `loadInboxRetention`. Absent windows mean the inbox is never swept, which is the default and a
+   * decision rather than an oversight — see `NotifyConfig` in `@ultimat3/core`.
+   */
+  readonly inboxRetention?: InboxRetention | undefined;
+}
+
+/**
+ * The two notify tables, and neither store is in `RetentionStores` — deliberately, and for the
+ * reason `authTarget` is not either. `setNotifyStores` is an APP's boot line and runs when the
+ * app's modules import, which is AFTER this install; `framework-schema.ts` says so where it
+ * applies the DDL "whether or not this boot calls `setNotifyStores`". So the sweep can only ask,
+ * per attempt, what is installed now — `purgeNotifyInbox`/`purgeNotifyDeliveries` answer 0 for a
+ * memory store or none at all, which is a boot that made a decision, not a failure.
+ */
+function notifyTargets(retention: InboxRetention): readonly PurgeTarget[] {
+  return [
+    {
+      name: 'x_notify_deliveries',
+      // The job's clock, exactly as `x_rate_limit` below: `at` is written by whichever process took
+      // the delivery, so a cutoff computed inside Postgres measures the offset between two clocks
+      // rather than the age of the row. The WINDOW is the ledger's own, never named here — one
+      // number, beside the statement that reads it.
+      purgeExpired: (nowMs: number): Promise<number> => purgeNotifyDeliveries(nowMs),
+    },
+    {
+      name: 'x_notify_inbox',
+      purgeExpired: (nowMs: number): Promise<number> =>
+        purgeNotifyInbox({
+          read: retention.readMs === undefined ? undefined : new Date(nowMs - retention.readMs),
+          unread:
+            retention.unreadMs === undefined ? undefined : new Date(nowMs - retention.unreadMs),
+        }),
+    },
+  ];
 }
 
 /**
@@ -76,6 +120,7 @@ function retentionTargets(stores: RetentionStores): readonly PurgeTarget[] {
       purgeExpired: (nowMs: number): Promise<number> => stores.rateLimit.purgeExpired(nowMs),
     },
     authTarget,
+    ...notifyTargets(stores.inboxRetention ?? NO_INBOX_RETENTION),
   ];
 }
 

package/src/dev-render.ts

@@ -45,6 +45,17 @@ export type IslandResolver = (routeFile: string) => (src: string) => string;
 
 export interface DocumentOptions {
   readonly resolveIsland?: IslandResolver;
+  /**
+   * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
+   * from `pwa-artifacts.ts`, or absent when the app is not installable.
+   *
+   * A document-level string rather than something a route's `meta()` returns: it is the same three
+   * elements on every page of the app, an installable app is one whose EVERY page carries them
+   * (a browser offers the install on whichever page the visitor landed on), and `headFromMeta`
+   * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
+   * boot knows it, the renderer cannot ask.
+   */
+  readonly pwaHead?: string;
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -68,13 +79,18 @@ export interface DevRouteData extends Record<string, unknown> {
  */
 const lang = (): string => currentLocale();
 
-const headFor = async (entry: RouteEntry, ctx: DevRouteData, data: RouteData): Promise<string> =>
+const headFor = async (
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  options: DocumentOptions,
+): Promise<string> =>
   renderHead(
     headFromMeta(
       await entry.config.meta(metaContextFor(ctx, data)),
       seoRenderers({ path: new URL(ctx.url).pathname }),
     ),
-  );
+  ) + (options.pwaHead ?? '');
 
 /** `<style>` for the surface's own stylesheets, or nothing at all when the surface imports none. */
 const styleTag = (entry: RouteEntry): string => {
@@ -155,7 +171,7 @@ async function documentFrom(
 ): Promise<string> {
   const islands = collectorFor(entry, options);
   const [head, body] = await Promise.all([
-    headFor(entry, ctx, data),
+    headFor(entry, ctx, data, options),
     routeBody(entry, ctx, data, islands),
   ]);
   return (
@@ -203,7 +219,7 @@ async function resultFor(
       // correct output, no streaming benefit.
       const islands = collectorFor(entry, options);
       const [head, shell] = await Promise.all([
-        headFor(entry, request, data),
+        headFor(entry, request, data, options),
         routeBody(entry, request, data, islands),
       ]);
       return streamResult(

package/src/dev-replicator.ts

@@ -41,6 +41,24 @@ const embeddedRefusal = (): BadFlagError =>
     fix: 'DATABASE_URL=postgres://user:password@localhost:5432/app x dev --role replicator',
   });
 
+/**
+ * The relations the feed decodes: every registered entity's PHYSICAL TABLE, never its name.
+ *
+ * Both readers of this list are catalog readers. `PgReplicationStream` keeps a change only when
+ * `#entities.has(relation.name)`, and a pgoutput Relation message names the table; `warnPartialIdentity`
+ * matches the same list against `pg_class.relname`. An entity NAME is the framework's own registry
+ * key — what a cache tag, a policy and `x entities describe` are keyed by — and `entity('user',
+ * { table: 'users' })` makes the two different strings. Passing the name meant a renamed table
+ * matched nothing on either side: every change SKIPPED, and a replica-identity warning that could
+ * never fire. Latent wherever the two agree, which is every entity in `examples/dummy`.
+ *
+ * Deduplicated and sorted: two entities may share one table, and the same registry must hand the
+ * feed the same list whatever order it was registered in.
+ */
+export function replicatedRelations(): readonly string[] {
+  return [...new Set(describeEntities().map((entity) => entity.table))].sort();
+}
+
 /**
  * An entity list is the feed's filter, so an empty one is a replicator that decodes every change
  * and forwards none. Refused here rather than inside the feed: this is the layer that knows the
@@ -61,7 +79,7 @@ const noEntitiesRefusal = (): BadFlagError =>
  */
 export async function startReplicator(options: StartReplicatorOptions): Promise<RunningReplicator> {
   if (options.services.db.mode === 'embedded') throw embeddedRefusal();
-  const entities = describeEntities().map((entity) => entity.name);
+  const entities = replicatedRelations();
   if (entities.length === 0) throw noEntitiesRefusal();
 
   const selection = selectChangeFeed(options.env, { entities });

package/src/dev-runtime.ts

@@ -31,6 +31,7 @@ import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
 import { loadCacheTiers, startCacheTiers } from './dev-cache';
+import { loadInboxRetention } from './dev-notify-retention';
 import { installRetentionSweep } from './dev-purge';
 import type { DevDbClient } from './dev-queue';
 import { pgExecutorFor, startQueue } from './dev-queue';
@@ -327,11 +328,19 @@ export async function startServices(
       postgresAuthLimiter({ executor, clock: systemClock, policy }),
     );
     started.push(() => resetAuthLimiters());
-    // The hourly sweep over the three framework tables this boot is responsible for. Every one of
-    // them ships a `purgeExpired()` that nothing called, so every row written was a row kept —
+    // The hourly sweep over the framework tables this boot is responsible for. Every one of them
+    // ships a `purgeExpired()` that nothing called, so every row written was a row kept —
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
+    //
+    // `inboxRetention` is READ HERE and not defaulted in `dev-purge.ts`: the two windows are the
+    // app's, `startServices` holds no `AppConfig`, and a loader that silently answered "never
+    // sweep" from inside the sweep would be indistinguishable from an app that chose it.
     started.push(
-      installRetentionSweep({ idempotency: queue.idempotency, rateLimit: rateLimitStore }),
+      installRetentionSweep({
+        idempotency: queue.idempotency,
+        rateLimit: rateLimitStore,
+        inboxRetention: await loadInboxRetention(services.root),
+      }),
     );
     // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
     // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and

package/src/dev-services.ts

@@ -21,6 +21,13 @@ export interface DevServices {
   readonly events: ServiceBinding;
   readonly storage: ServiceBinding;
   readonly stateDir: string;
+  /**
+   * The app directory itself, carried rather than re-derived from `stateDir`. A boot that needs to
+   * read the app's own `app.config.ts` — `loadInboxRetention` does — otherwise has to undo the
+   * `join(root, '.x')` above, and a `dirname` that silently disagrees with this file's join is a
+   * path bug nothing would catch.
+   */
+  readonly root: string;
 }
 
 export type Env = Readonly<Record<string, string | undefined>>;
@@ -44,6 +51,7 @@ export function resolveServices(root: string, env: Env): DevServices {
     mkdirSync(stateDir, { recursive: true });
   }
   return {
+    root,
     stateDir,
     db:
       databaseUrl === undefined

package/src/e2e-driver.ts

@@ -11,34 +11,52 @@ import {
   unavailableFixture,
   useE2eDriver,
 } from '@ultimat3/testing';
-import type { E2ePageOptions } from './e2e-page';
+import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 
 export type E2eDriverOptions = E2ePageOptions;
 
 /**
- * The three `E2eFixtures` members this driver cannot build, and why each is a REFUSAL rather than
- * a no-op. A fixture that silently did nothing would make the assertion after it read as proof:
- * `offline()` followed by "the fallback rendered" is the app's ONLINE page passing an offline test.
- *
- * All three are genuinely out of reach of the shipped port, not merely unimplemented:
- * `CdpPageLike` (`packages/scraping/src/cdp-port.ts`) declares twelve methods and none of them is
- * `setOfflineMode`, and a new build id is a fact about the SERVER, which no page port has ever
- * been able to speak for.
+ * A member this driver cannot build is a REFUSAL, never a no-op. A fixture that silently did
+ * nothing would make the assertion after it read as proof: `offline()` followed by "the fallback
+ * rendered" is the app's ONLINE page passing an offline test.
  */
 const refuse =
   (name: string, needs: string): (() => Promise<void>) =>
   () =>
     Promise.reject(new FixtureUnavailableError({ name, needs }));
 
-/** What `e2eTest` hands its body: a real page, and three members that say what they are missing. */
-export const e2eFixtures = (page: PageLike): E2eFixtures => ({
+/**
+ * `offline()`/`online()` FORWARD, `As of 2026-08-27`. They refused until then on a reason the tree
+ * contradicted on the day it was written: this file said `CdpPageLike`
+ * (`packages/scraping/src/cdp-port.ts`) "declares twelve methods and none of them is
+ * `setOfflineMode`". It declares it at line 71 — optional, guarded, with a coded
+ * `X_NOT_IMPLEMENTED` in `cdp-target.ts` for a launcher that lacks it — and `page-over-target.ts`
+ * exposes it as `ScrapePage.offline()`. All of that landed in **the same commit as the comment**
+ * (#351), so the refusal was never true, and it is the reason issue #390 records a real browser
+ * check as out of reach.
+ *
+ * Optional on `E2eBrowserPage` rather than required, for the reason `CdpPageLike` gives about the
+ * same method: this port is the shape of somebody ELSE's object, and a six-line test double must
+ * still satisfy it. Absent, the refusal stands — and now it names the method the double is missing
+ * rather than a capability the framework does not have.
+ */
+const networkFixtures = (browser: E2eBrowserPage): Pick<E2eFixtures, 'offline' | 'online'> => {
+  const setOffline = browser.offline?.bind(browser);
+  if (setOffline === undefined) {
+    const needs =
+      "a page whose driver implements offline(enabled) — @ultimat3/scraping's ScrapePage does; a hand-rolled E2eBrowserPage may not";
+    return { offline: refuse('offline', needs), online: refuse('online', needs) };
+  }
+  return { offline: () => setOffline(true), online: () => setOffline(false) };
+};
+
+/** What `e2eTest` hands its body: a real page, the network condition, and one honest refusal. */
+export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixtures => ({
   page,
-  offline: refuse(
-    'offline',
-    "a CDP method for the browser's own network state — the shipped CdpPageLike has no setOfflineMode",
-  ),
-  online: refuse('online', 'the same CDP method offline() needs, in order to undo it'),
+  ...networkFixtures(browser),
+  // The one that is still genuinely out of reach, and it is not a port gap: a new build id is a
+  // fact about the SERVER, which no page port has ever been able to speak for.
   update: refuse(
     'update',
     'a second build served under a new immutable build id, which is a server fact',
@@ -65,7 +83,7 @@ export function installE2eDriver(options: E2eDriverOptions): () => void {
   const page = e2ePage(options);
   defineFixtures({ page: () => page });
   useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page)));
+    bunTest(name, () => body(e2eFixtures(page, options.page)));
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than

package/src/e2e-page.ts

@@ -10,15 +10,27 @@ import { e2eLocator } from './e2e-locator';
 import type { E2eSelection } from './e2e-selection';
 
 /**
- * What this adapter needs of a browser: four members, every one of them on `ScrapePage`. Declared
- * structurally rather than as `ScrapePage` so a test can stand one up in six lines — the same
- * bargain `cdp-port.ts` makes about puppeteer, one layer up.
+ * What this adapter needs of a browser: four required members, every one of them on `ScrapePage`.
+ * Declared structurally rather than as `ScrapePage` so a test can stand one up in six lines — the
+ * same bargain `cdp-port.ts` makes about puppeteer, one layer up.
  */
 export interface E2eBrowserPage {
   url(): string;
   goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<unknown>;
   evaluate(expression: string): Promise<unknown>;
   click(selector: string): Promise<void>;
+  /**
+   * The browser's own network condition, which `E2eFixtures.offline()`/`online()` forward to.
+   * `ScrapePage` has it (`page-over-target.ts`), reaching `CdpPageLike.setOfflineMode` through
+   * `cdp-target.ts`'s guard.
+   *
+   * OPTIONAL for the reason the four above are structural: this port is the shape of somebody
+   * ELSE's object, and requiring it would cost every six-line double a type error for a capability
+   * a test that never goes offline does not need. Absent, `e2e-driver.ts` keeps refusing by name —
+   * a coded refusal, never a silent no-op, because an `offline()` that did nothing would let the
+   * app's ONLINE page pass an offline test.
+   */
+  offline?(enabled: boolean): Promise<void>;
 }
 
 export interface E2ePageOptions {

package/src/error-codes.ts

@@ -108,6 +108,14 @@ export const CLI_OWNED_ERROR_CODES = [
   // code, because the only remedy available for all of them is a line in the migration file, and
   // where that file lives is this package's fact.
   'X_MIGRATION_UNGENERATABLE',
+  // The third `subscribes:` condition, and the only one neither @ultimat3/query nor
+  // @ultimat3/db can ask. Query owns X_QUERY_SUBSCRIBES_INVALID (a declaration that cannot
+  // be acted on) and X_QUERY_SUBSCRIBES_DRIFT (it disagrees with the resolved shape); db
+  // keeps only the declared names an entity's table matches and DROPS the rest, because it
+  // has no way to tell a typo from a table another migration owns. Neither package holds
+  // both registries, so a name matching nothing was granted REPLICA IDENTITY FULL on
+  // nothing while its author read the declaration as granted (#357).
+  'X_QUERY_SUBSCRIBES_UNKNOWN',
   'X_DB_MIGRATE_FAILED',
   'X_DB_BRANCH_FAILED',
   'X_DB_STUDIO_FAILED',
@@ -158,6 +166,13 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_E2E_LOCATOR_EMPTY',
   'X_E2E_LOCATOR_AMBIGUOUS',
   'X_E2E_SERVICE_WORKER_ABSENT',
+  // The raw-CDP browser under that driver — `cdp-launch.ts`, `cdp-connection.ts`,
+  // `cdp-e2e-page.ts`, `cdp-browser.ts`. Four codes and not one, because the four repairs differ:
+  // install a browser, read the browser's own stderr, look at the page, raise a deadline.
+  'X_CDP_BROWSER_MISSING',
+  'X_CDP_LAUNCH_FAILED',
+  'X_CDP_CALL_FAILED',
+  'X_CDP_TIMEOUT',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
@@ -258,6 +273,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_DB_SCHEMA_UNMIGRATED: 'an entity declaration no migration recorded',
   X_DB_SCHEMA_UNDECLARED: 'a migration records schema no entity declares',
   X_MIGRATION_UNGENERATABLE: 'this migration holds SQL no declaration carries and does not say so',
+  X_QUERY_SUBSCRIBES_UNKNOWN: 'a live query subscribes to a table no entity declares',
   X_DB_MIGRATE_FAILED: 'x db migrate failed',
   X_DB_BRANCH_FAILED: 'an x db branch step failed',
   X_DB_STUDIO_FAILED: 'x db studio failed',
@@ -285,6 +301,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
   X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
   X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
+  X_CDP_BROWSER_MISSING: 'no Chrome or Chromium is installed for the e2e driver to launch',
+  X_CDP_LAUNCH_FAILED: 'the browser started and never announced a DevTools endpoint',
+  X_CDP_CALL_FAILED: 'the browser refused a DevTools call',
+  X_CDP_TIMEOUT: 'a DevTools call did not answer inside its deadline',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',

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

@@ -25,6 +25,33 @@ export type { BoundaryCut, BoundarySplit } from './boundary-cuts';
 export { planBoundaryCuts } from './boundary-cuts';
 export type { BuildStats, RouteStats } from './budgets';
 export { BUILD_STATS_FILE, checkBudgets, readBuildStats } from './budgets';
+// The raw-CDP browser the driver above runs on. `openE2eBrowserIfAvailable()` is what an app's
+// test preload calls: it answers `undefined` on a machine with no Chrome, so the browser-backed
+// suite SKIPS rather than turning a gate red for a reason unrelated to the change.
+export type { E2eBrowser, OpenE2eBrowserOptions } from './cdp-browser';
+export {
+  DEFAULT_CDP_TIMEOUT_MS,
+  openE2eBrowser,
+  openE2eBrowserIfAvailable,
+} from './cdp-browser';
+export type { CdpConnection, CdpConnectionOptions, CdpResult } from './cdp-connection';
+export { cdpConnect } from './cdp-connection';
+export type { CdpE2ePageOptions } from './cdp-e2e-page';
+export { cdpE2ePage } from './cdp-e2e-page';
+export {
+  CdpBrowserMissingError,
+  CdpCallFailedError,
+  CdpLaunchFailedError,
+  CdpTimeoutError,
+} from './cdp-errors';
+export type { LaunchedBrowser, LaunchOptions } from './cdp-launch';
+export {
+  CHROME_CANDIDATES,
+  CHROME_PATH_ENV,
+  findChrome,
+  launchChrome,
+  launchFoundChrome,
+} from './cdp-launch';
 export type { BuildTarget } from './cmd-build';
 export {
   argsFor,
@@ -72,6 +99,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 +111,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 +262,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 +309,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 +365,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

@@ -6,7 +6,7 @@
 // why: no Bun native joins a path; `Bun.write` and `Bun.file` both take one already joined.
 import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
-import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
+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';
@@ -139,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)`;
 
@@ -171,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> =>
@@ -202,9 +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 });
+    // 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,