@ultimat3/cli 23.0.0 → 25.0.0

package/src/cmd-new.ts

@@ -3,9 +3,9 @@
 // Interactive-free: every choice is a flag with a default, because an agent cannot answer prompts.
 
 import { existsSync } from 'node:fs';
-import { chmod } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { AppNameInvalidError, appNameIssue } from './app-name';
 import { dedupe } from './cmd-generate';
 import { newSpec } from './cmd-new-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -18,7 +18,7 @@ import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
-import { appFiles, EXECUTABLE_FILES, names, repoFiles, resourceFiles } from './templates';
+import { appFiles, names, repoFiles, resourceFiles } from './templates';
 import { loadVersion } from './version-loader';
 
 export interface NewAppOptions {
@@ -102,6 +102,15 @@ export async function initRepository(runner: Runner, dir: string): Promise<Repos
   return { initialized: true, committed: true, problem: null };
 }
 
+/** `path` relative to `cwd` when it lies under it, else absolute — never a `../../` walk. */
+const displayPath = (cwd: string, path: string): string => {
+  const rel = relative(cwd, path);
+  return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? path : rel;
+};
+
+/** The `cd` operand of the next-steps line: the target as typed from `cwd`, pasteable verbatim. */
+const cdTarget = (cwd: string, target: string): string => quoteArg(displayPath(cwd, target));
+
 /** Pure: the complete file list for a new app, so `--dry-run` and the test see the same thing. */
 export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
   const app = names(options.name);
@@ -145,13 +154,12 @@ export interface WrittenApp {
  * a migration whose snapshot never existed is what made the app's first two database commands
  * refuse each other — `x db migrate` naming `x db gen`, and `x db gen` refusing a sidecar version
  * control never had. The consequence is deliberate: `x verify`'s `drift` step is red on a pristine
- * scaffold until `x db gen "initial"` runs — which `bin/setup` does, and which is what
+ * scaffold until `x db gen "initial"` runs — which `bun run setup` does, and which is what
  * `cli.new.done` tells the author to run.
  */
 export async function writeNewApp(target: string, options: NewAppOptions): Promise<WrittenApp> {
   const files = planNewApp(options);
   for (const file of files) await Bun.write(join(target, file.path), file.contents);
-  for (const path of EXECUTABLE_FILES) await chmod(join(target, path), 0o755);
   return { dir: target, files: files.map((file) => file.path) };
 }
 
@@ -210,6 +218,18 @@ export const newCommand: CliCommand = {
         flags: callerFlags(ctx),
       });
     }
+    // After the slug exists and before anything is planned: the slug is `app.config.ts`'s `name`,
+    // and a name core's `defineConfig` refuses is an app that throws at its own first import.
+    const issue = appNameIssue(app.kebab);
+    if (issue !== undefined) {
+      throw new AppNameInvalidError({
+        name: raw,
+        slug: app.kebab,
+        issue,
+        invocation: invocationOf(ctx, 'new'),
+        flags: callerFlags(ctx),
+      });
+    }
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
     const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
 
@@ -218,9 +238,17 @@ export const newCommand: CliCommand = {
       return {
         ok: true,
         command: 'new',
-        summary: msg('cli.new.done', { name: app.kebab }),
+        summary: msg('cli.new.dryRun', {
+          name: app.kebab,
+          dir: target,
+          cd: cdTarget(ctx.cwd, target),
+        }),
         data: { dir: target, files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => msg('cli.file.added', { path: `${app.kebab}/${file.path}` })),
+        // Where each file WOULD land, as the caller would reach it: relative to the cwd, `--dir`
+        // included — `${app.kebab}/…` named the wrong place whenever `--dir` was set.
+        lines: files.map((file) =>
+          msg('cli.file.added', { path: displayPath(ctx.cwd, join(target, file.path)) }),
+        ),
       };
     }
     if (existsSync(target) && !flagBool(ctx.args, 'force')) {
@@ -263,7 +291,7 @@ export const newCommand: CliCommand = {
     return {
       ok: true,
       command: 'new',
-      summary: msg('cli.new.done', { name: app.kebab }),
+      summary: msg('cli.new.done', { name: app.kebab, cd: cdTarget(ctx.cwd, target) }),
       data: { dir: written.dir, files: written.files, git },
       lines,
     };

package/src/cmd-planned.ts

@@ -3,8 +3,8 @@
 // does not exist", which is false and sends an agent looking for a typo. X_NOT_IMPLEMENTED plus a
 // fix naming the closest shipped command says the true thing, and `x help` lists them honestly.
 
+import { NotImplementedError } from '@ultimat3/core';
 import type { CliCommand } from './command';
-import { CliNotImplementedError } from './errors';
 import type { CommandResult } from './output';
 import type { CommandSpec } from './parse';
 
@@ -127,6 +127,15 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
     subcommand: 'studio',
     fix: 'x dev   # then the db panel at /_x: schema, rows, and a guarded SQL console',
   },
+  // Planned because Postgres is the one durable job driver: there is nowhere to drain to. The two
+  // `--to` values, `redis` and `nats`, were `X_NOT_IMPLEMENTED` stubs on every method, so a drain
+  // leased the production batch for five minutes, failed each enqueue and nacked it back. 25.0.0
+  // deleted both stubs and the unreachable drain body; a real second driver writes a new one.
+  {
+    command: 'jobs',
+    subcommand: 'drain',
+    fix: 'x jobs ls --json   # the queue as it stands; Postgres is the only durable driver, so there is nowhere to drain to',
+  },
 ];
 
 /**
@@ -134,18 +143,28 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
  * the error rather than throwing it, because a `run` that throws synchronously escapes the
  * promise its signature promises — the caller does `throw plannedSubcommand(...)`.
  */
-export function plannedSubcommand(command: string, subcommand: string): CliNotImplementedError {
+export function plannedSubcommand(command: string, subcommand: string): NotImplementedError {
   const planned = PLANNED_SUBCOMMANDS.find(
     (entry) => entry.command === command && entry.subcommand === subcommand,
   );
-  return new CliNotImplementedError({
-    feature: `x ${command} ${subcommand}`,
+  return new NotImplementedError({
+    cause: `x ${command} ${subcommand} is not implemented in this build`,
     // `x help <command>`, not `x <command> --help`: for a command that declares subcommands and no
     // default, the latter is refused by the parser before help is ever rendered.
     fix: planned?.fix ?? `x help ${command}`,
   });
 }
 
+/**
+ * What every invocation of a planned command answers — its `run`, and the dispatcher when the
+ * parser refused a flag before any `run` was reached. One builder, so the two cannot drift.
+ */
+export const plannedCommandError = (planned: PlannedCommand): NotImplementedError =>
+  new NotImplementedError({
+    cause: `x ${planned.name} is not implemented in this build`,
+    fix: planned.fix,
+  });
+
 const specFor = (planned: PlannedCommand): CommandSpec => ({
   name: planned.name,
   summary: `${planned.summary} (planned)`,
@@ -167,10 +186,7 @@ const toCommand = (planned: PlannedCommand): CliCommand => ({
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.
   async run(): Promise<CommandResult> {
-    throw new CliNotImplementedError({
-      feature: `x ${planned.name}`,
-      fix: planned.fix,
-    });
+    throw plannedCommandError(planned);
   },
 });
 

package/src/cmd-routes.ts

@@ -1,16 +1,16 @@
 // `x routes` — the route table as a table, or as JSON. Replaces grepping a router directory, which
 // is what an agent does when the framework has no answer to "what URLs exist".
 //
-// The rows are `@ultimat3/render`'s own `describeRoutes()`: the CLI prints the route table, it
+// The rows are `@ultimat3/render`'s own `describePages()`: the CLI prints the route table, it
 // does not keep a second one.
 
 import type { RouteDescriptor, Surface } from '@ultimat3/render';
-import { describeRoutes, SURFACES } from '@ultimat3/render';
+import { describePages, SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { routesSpec } from './cmd-routes-spec';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
@@ -52,7 +52,7 @@ const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
     render: route.mode,
     hydrate: route.hydrate,
     offline: route.offline,
-    budget: { js: route.budgetJs, lcp: route.budgetLcp },
+    budget: { js: route.budgetJs },
     // Absent on a file route, never `null`: only a mounted route has the fact.
     ...(route.mount === undefined
       ? {}
@@ -83,11 +83,21 @@ export const routesCommand: CliCommand = {
   spec: routesSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
+    // No positional: `x routes list --json` ran only because a stray word was ignored, which is
+    // how a retired spelling stayed in the route-miss fix lines. Refused before the app loads.
+    const stray = ctx.args.positionals[0];
+    if (stray !== undefined) {
+      throw new UnknownCommandError({
+        path: `routes ${stray}`,
+        known: ['routes'],
+        suggestion: 'routes --json',
+      });
+    }
     // Read before the app is loaded: a typo must not cost a boot to report, the rule `x mcp`'s
     // `--transport` already follows.
     const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));
     const { findings } = await loadApp(root);
-    const routes = describeRoutes().filter(
+    const routes = describePages().filter(
       (route) => surface === undefined || route.surface === surface,
     );
     return {

package/src/cmd-secrets.ts

@@ -25,6 +25,7 @@ import {
   SecretsPlaintextInvalidError,
   secretsFileExists,
   serializeSecretValues,
+  UltimateError,
   writeMasterKeyFile,
   writeSecretsFile,
 } from '@ultimat3/core';
@@ -33,12 +34,7 @@ import { requireAppRoot } from './app-root';
 import { appSecrets, dropRetired, retire, retiredKeyIds } from './cmd-secrets-ring';
 import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
-import {
-  MissingPositionalError,
-  SecretsEditFailedError,
-  SecretsEditorMissingError,
-  SecretsExistsError,
-} from './errors';
+import { MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
@@ -46,6 +42,51 @@ import { recoverRotation, rotateMasterKey } from './secrets-rotation';
 import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
 
+/**
+ * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
+ * guessing one and opening a decrypted file in it is the last place a surprise belongs.
+ */
+export class SecretsEditorMissingError extends UltimateError {
+  constructor(input: { vars: readonly string[] }) {
+    super({
+      code: 'X_SECRETS_EDITOR_MISSING',
+      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
+      fix: 'EDITOR=nano x secrets edit',
+    });
+  }
+}
+
+/**
+ * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
+ * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
+ * commit whatever half-written state the crash left behind.
+ */
+export class SecretsEditFailedError extends UltimateError {
+  constructor(input: { editor: string; code: number }) {
+    super({
+      code: 'X_SECRETS_EDIT_FAILED',
+      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
+      fix: 'x secrets edit',
+    });
+  }
+}
+
+/**
+ * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
+ * package's own code for exactly that, and a second name for "a generator would clobber something"
+ * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
+ * the committed file it opens is then ciphertext nobody can read again.
+ */
+export class SecretsExistsError extends UltimateError {
+  constructor(input: { path: string; fix: string }) {
+    super({
+      code: 'X_GENERATE_CONFLICT',
+      cause: `${input.path} already exists, and x secrets init would replace it`,
+      fix: input.fix,
+    });
+  }
+}
+
 export { SECRETS_SUBCOMMANDS } from './cmd-secrets-spec';
 
 /** In order of precedence. `VISUAL` outranks `EDITOR` by POSIX convention on an interactive tty. */

package/src/cmd-shot-matrix.ts

@@ -5,14 +5,17 @@
 
 // why: no Bun native joins a path.
 import { join, relative } from 'node:path';
+import { escapeHtml } from '@ultimat3/core';
 import { routeEntries } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import type { ShotRun } from './cmd-shot';
+import { BadFlagError } from './errors';
 import type { CommandResult } from './output';
 import { localizedShotPath } from './shot-locale';
 import type { ShotServer } from './shot-server';
 import { SHOT_DIR } from './shot-server';
 import type { ShotArtifacts } from './shot-verdict';
+import { viewportDir } from './shot-viewport';
 
 export const MATRIX_DIR = join(SHOT_DIR, 'matrix');
 export const MATRIX_INDEX = 'index.html';
@@ -20,7 +23,10 @@ export const MATRIX_INDEX = 'index.html';
 /** The two themes the boot honours from storage. */
 export const MATRIX_THEMES: readonly ('light' | 'dark')[] = ['light', 'dark'];
 
-/** A phone and a desktop, each with the height its class of device is photographed at. */
+/**
+ * A phone and a desktop, each with the height its class of device is photographed at. The default
+ * only: `x shot --matrix --viewport <w>x<h>[,…]` replaces the pair (`shot-viewport.ts`).
+ */
 export const MATRIX_VIEWPORTS: readonly { readonly width: number; readonly height: number }[] = [
   { width: 390, height: 844 },
   { width: 1440, height: 900 },
@@ -34,10 +40,20 @@ export interface MatrixCell {
   readonly viewport: { readonly width: number; readonly height: number };
   /** What the browser opens: the route, prefixed for a non-default locale. */
   readonly path: string;
-  /** Relative to the matrix directory: `<route-slug>/<locale>/<theme>-<width>`. */
+  /** Relative to the matrix directory: `<route-slug>/<locale>/<theme>-<width>x<height>`. */
   readonly dir: string;
 }
 
+/** The matrix photographs ROUTES; `--island`/`--all-islands` beside it is two subjects. */
+export function refuseMatrixWithComponent(): never {
+  throw new BadFlagError({
+    flag: 'matrix',
+    command: 'shot',
+    reason: 'photographs every site route; --island and --all-islands photograph components',
+    fix: 'x shot --matrix --json',
+  });
+}
+
 /** A route a matrix can photograph without inventing a parameter: no `:param`, no `*rest`. */
 export const isMatrixRoute = (path: string): boolean => !/[:*[]/.test(path);
 
@@ -78,7 +94,8 @@ export function planShotMatrix(input: MatrixPlanInput): readonly MatrixCell[] {
             theme,
             viewport,
             path: localizedShotPath(route, locale, input.defaultLocale),
-            dir: join(slug(route), locale, `${theme}-${String(viewport.width)}`),
+            // The whole size, never the width alone: `--viewport 390x844,390x664` is two pictures.
+            dir: join(slug(route), locale, `${theme}-${viewportDir(viewport)}`),
           });
         }
       }
@@ -94,9 +111,6 @@ export interface MatrixShot {
   readonly image: string;
 }
 
-const escapeHtml = (text: string): string =>
-  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-
 /**
  * The contact sheet. System colours only (`Canvas`, `CanvasText`, `Mark`): a generated review page
  * has no design tokens to read, and a literal colour would be the one this repo refuses.
@@ -108,7 +122,7 @@ export function contactSheet(shots: readonly MatrixShot[]): string {
       .filter((shot) => shot.cell.route === route)
       .map((shot) => {
         const { locale, theme, viewport, path } = shot.cell;
-        const label = `${locale} · ${theme} · ${String(viewport.width)}px${shot.ok ? '' : ' · FAILED'}`;
+        const label = `${locale} · ${theme} · ${viewportDir(viewport)}${shot.ok ? '' : ' · FAILED'}`;
         return (
           `<figure${shot.ok ? '' : ' class="failed"'}><a href="${escapeHtml(shot.image)}">` +
           `<img src="${escapeHtml(shot.image)}" alt="${escapeHtml(`${path} ${label}`)}" loading="lazy" ` +
@@ -193,6 +207,7 @@ export async function runShotMatrix(run: MatrixRun): Promise<CommandResult> {
         locale: shot.cell.locale,
         theme: shot.cell.theme,
         width: shot.cell.viewport.width,
+        height: shot.cell.viewport.height,
         image: shot.image,
         ok: shot.ok,
       })),

package/src/cmd-shot-spec.ts

@@ -7,7 +7,7 @@ export const shotSpec: CommandSpec = {
   name: 'shot',
   summary: 'photograph one route, one island in a state it declares, or every island in the app',
   usage:
-    'x shot <route> [--locale <l>] [--theme light|dark] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--cookie <name=value>] [--expect-status 404] [--port 0] [--out <dir>] [--settle 2000] [--json]',
+    'x shot <route> [--locale <l>] [--theme light|dark] [--viewport 390x844,1440x900] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--cookie <name=value>] [--expect-status 404] [--port 0] [--out <dir>] [--settle 2000] [--json]',
   requiresApp: true,
   flags: [
     { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
@@ -51,7 +51,15 @@ export const shotSpec: CommandSpec = {
       name: 'matrix',
       type: 'boolean',
       summary:
-        'every site route × locale × light/dark × 390/1440 px into .x/shot/matrix/, plus an index.html contact sheet',
+        'every site route × locale × light/dark × 390x844/1440x900 (or --viewport) into .x/shot/matrix/, plus an index.html contact sheet',
+    },
+    // One flag, read as a list, rather than a repeatable one: the parser keeps the last value of a
+    // repeated flag, so `--viewport a --viewport b` would photograph `b` alone and say nothing.
+    {
+      name: 'viewport',
+      type: 'string',
+      summary:
+        '<w>x<h>[,<w>x<h>] — a route once per size into <out>/<w>x<h>/; with --matrix, its sizes',
     },
     // A FLAG on `x shot` and never a second command: photographing a route and photographing a
     // component are one job with two subjects, and a parallel command would be the second path

package/src/cmd-shot.ts

@@ -8,6 +8,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { renderFixShellArg } from '@ultimat3/core';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -23,7 +24,13 @@ import {
   refuseSweepWithRoute,
   refuseSweepWithState,
 } from './cmd-shot-island';
-import { MATRIX_DIR, matrixRoutes, planShotMatrix, runShotMatrix } from './cmd-shot-matrix';
+import {
+  MATRIX_DIR,
+  matrixRoutes,
+  planShotMatrix,
+  refuseMatrixWithComponent,
+  runShotMatrix,
+} from './cmd-shot-matrix';
 import { shotSpec } from './cmd-shot-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
@@ -33,12 +40,7 @@ import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { shotBrowserChoice } from './shot-browser';
 import { readCookieFlag, type ShotCookiePair, shotCookies } from './shot-cookie';
-import {
-  acceptLanguageHeaders,
-  loadShotLocales,
-  localizedShotPath,
-  readLocaleFlag,
-} from './shot-locale';
+import { acceptLanguageHeaders, localizedShotPath, readLocaleFlag } from './shot-locale';
 import type { BootDevServer, ShotServer } from './shot-server';
 import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
@@ -53,21 +55,12 @@ import {
   shotSummary,
   verdictJson,
 } from './shot-verdict';
+import { parseViewports, refuseViewportWithComponent, runShotViewports } from './shot-viewport';
 
 /** Kernel-picked by default: :3000 is usually another project's dev server, not a free port. */
 const DEFAULT_PORT = 0;
 
-/**
- * How long the page is left alone after `load` before it is photographed: exactly the
- * `requestIdleCallback` deadline `@ultimat3/render`'s hydration runtime gives an `idle` island —
- * shoot sooner and the verdict reports `booted: 0` for a page that hydrates perfectly. READ from
- * that runtime rather than restated, because two copies of one number that must agree is the drift
- * axiom 2 refuses: the settle window is not "2 seconds", it is "the deadline the runtime uses".
- */
-export const DEFAULT_SETTLE_MS = IDLE_HYDRATE_TIMEOUT_MS;
-
-// Re-exported, not re-declared: `cmd-shot.test.ts` and the island path both name them, and a
-// second declaration of a path or an allow-list rule is a second answer.
+// Re-exported, not re-declared: a second declaration of a path or a host rule is a second answer.
 export type { BootDevServer, ShotServer };
 export { allowHostsFrom, devServerFor, SHOT_DIR };
 
@@ -339,6 +332,14 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
   }
 }
 
+/**
+ * Where the artifacts land. A relative `--out` is a path the caller typed from where they stand,
+ * so it resolves against the cwd — `x build --out`'s rule. Against the app root it landed
+ * somewhere else whenever `x shot` ran from `apps/web`.
+ */
+export const shotOutDir = (cwd: string, out: string | undefined, fallback: string): string =>
+  out === undefined ? fallback : resolve(cwd, out);
+
 export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
   ok: artifacts.verdict.ok,
   command: 'shot',
@@ -364,7 +365,8 @@ export const shotCommand: CliCommand = {
     const sweep = flagBool(ctx.args, 'all-islands');
     const matrix = flagBool(ctx.args, 'matrix');
     const cookies = readCookieFlag(flagString(ctx.args, 'cookie'));
-    const app = await loadShotLocales(root);
+    const viewports = parseViewports(flagString(ctx.args, 'viewport'));
+    const app = await appLocaleSet(root);
     const locale = readLocaleFlag(flagString(ctx.args, 'locale'), app);
     // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
     // subjects has a belief about which one runs, and half of them would be wrong.
@@ -377,14 +379,9 @@ export const shotCommand: CliCommand = {
     }
     const component = sweep || (island !== undefined && island !== '');
     // The matrix photographs ROUTES; a component beside it is two subjects.
-    if (matrix && component) {
-      throw new BadFlagError({
-        flag: 'matrix',
-        command: 'shot',
-        reason: 'photographs every site route; --island and --all-islands photograph components',
-        fix: 'x shot --matrix --json',
-      });
-    }
+    if (matrix && component) refuseMatrixWithComponent();
+    // An island state declares its own size, so a size asked for beside one is a second answer.
+    if (component && viewports !== undefined) refuseViewportWithComponent();
     // An island is photographed in BOTH themes by the harness, which owns its `data-theme` and
     // carries no boot script — so a theme asked for beside one is a request nothing could honour.
     if (component && locale !== undefined) {
@@ -406,7 +403,12 @@ export const shotCommand: CliCommand = {
     // `--matrix` alone is every site route; a route beside it narrows the matrix to that one.
     const route = component || (matrix && positional === undefined) ? '' : readRoute(positional);
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
-    const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
+    // How long the page is left alone after `load` before it is photographed: exactly the
+    // `requestIdleCallback` deadline `@ultimat3/render`'s hydration runtime gives an `idle` island —
+    // shoot sooner and the verdict reports `booted: 0` for a page that hydrates perfectly. The
+    // runtime's own constant, under its own name: the settle window is not "2 seconds", it is "the
+    // deadline the runtime uses", and a second name for it is a second import path.
+    const settleMs = intFlag(ctx.args, 'settle', 0, IDLE_HYDRATE_TIMEOUT_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
     // Read only when given: its absence means "any 2xx", which no single default number can say.
     const expectStatus =
@@ -426,7 +428,8 @@ export const shotCommand: CliCommand = {
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
     const shared = {
       root,
-      ...(out === undefined ? {} : { out }),
+      // Absolute here, so the island sweep's own `resolve(root, out)` keeps the caller's path.
+      ...(out === undefined ? {} : { out: shotOutDir(ctx.cwd, out, root) }),
       settleMs,
       timeoutMs,
       ...(executablePath === undefined ? {} : { executablePath }),
@@ -464,22 +467,24 @@ export const shotCommand: CliCommand = {
         locales: locale === undefined ? app.locales : [locale],
         defaultLocale: app.defaultLocale,
         ...(theme === undefined ? {} : { themes: [theme] }),
+        ...(viewports === undefined ? {} : { viewports }),
       });
-      const outDir = out === undefined ? join(root, MATRIX_DIR) : resolve(root, out);
+      const outDir = shotOutDir(ctx.cwd, out, join(root, MATRIX_DIR));
       return runShotMatrix({ cells, outDir, boot, shoot: runShot, base });
     }
     const shown = locale ?? app.defaultLocale;
     const path = localizedShotPath(route, shown, app.defaultLocale);
-    return shotResult(
-      await runShot({
-        ...base,
-        route: path,
-        outDir: out === undefined ? join(root, SHOT_DIR, shotSlug(path)) : resolve(root, out),
-        boot,
-        // Pinned whether or not `--locale` was given: the default locale, never the box's own.
-        acceptLanguage: shown,
-        ...(theme === undefined ? {} : { colorScheme: theme }),
-      }),
-    );
+    const single = {
+      ...base,
+      route: path,
+      // Pinned whether or not `--locale` was given: the default locale, never the box's own.
+      acceptLanguage: shown,
+      ...(theme === undefined ? {} : { colorScheme: theme }),
+    };
+    const outDir = shotOutDir(ctx.cwd, out, join(root, SHOT_DIR, shotSlug(path)));
+    if (viewports !== undefined) {
+      return runShotViewports({ viewports, outDir, boot, shoot: runShot, base: single });
+    }
+    return shotResult(await runShot({ ...single, outDir, boot }));
   },
 };

package/src/cmd-tasks.ts

@@ -7,6 +7,7 @@
 import { nearestName, systemClock } from '@ultimat3/core';
 import type { JobDriver, TaskFire, TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
+import { fromEpochMs, isoInZone } from '@ultimat3/time';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { tasksSpec } from './cmd-tasks-spec';
@@ -19,7 +20,6 @@ import { flagString } from './parse';
 import { renderTable } from './table';
 import {
   findTaskHandle,
-  isoInZone,
   knownTaskNames,
   listTaskFacts,
   parseCountFlag,
@@ -58,7 +58,7 @@ const lastFireOf = (fires: ReadonlyMap<string, TaskFire>, name: string, tz: stri
   if (fire === undefined) return NEVER_FIRED;
   return {
     lastMs: fire.occurrenceMs,
-    last: isoInZone(fire.occurrenceMs, tz),
+    last: isoInZone(fromEpochMs(fire.occurrenceMs), tz),
     lastFiredAtMs: fire.firedAt,
   };
 };

package/src/cmd-test-spec.ts

@@ -10,7 +10,7 @@ export const testSpec: CommandSpec = {
   name: 'test',
   summary:
     'run one test type — or the whole suite — across N workers, one isolated database per worker',
-  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--isolate] [--json] [-- <bun test flags>]`,
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--isolate] [--json] [-- <bun test flags>]`,
   positionalChoices: TEST_TYPES,
   // The one command that hands a tail to another tool — `bun test` — and the reason
   // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
@@ -28,12 +28,6 @@ export const testSpec: CommandSpec = {
       summary:
         'a fresh global per test file (bun test --isolate) — off by default since 22.7; x.verify.json "isolate": true makes it the repo default',
     },
-    {
-      name: 'worker',
-      type: 'string',
-      summary:
-        'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
-    },
     {
       name: 'filter',
       type: 'string',