@ultimat3/cli 22.10.0 → 22.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.10.0",
+  "version": "22.12.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.10.0",
-    "@ultimat3/admin": "22.10.0",
-    "@ultimat3/ai": "22.10.0",
-    "@ultimat3/auth": "22.10.0",
-    "@ultimat3/cache": "22.10.0",
-    "@ultimat3/core": "22.10.0",
-    "@ultimat3/db": "22.10.0",
-    "@ultimat3/entity": "22.10.0",
-    "@ultimat3/flags": "22.10.0",
-    "@ultimat3/http": "22.10.0",
-    "@ultimat3/i18n": "22.10.0",
-    "@ultimat3/jobs": "22.10.0",
-    "@ultimat3/mail": "22.10.0",
-    "@ultimat3/manifest": "22.10.0",
-    "@ultimat3/mcp": "22.10.0",
-    "@ultimat3/money": "22.10.0",
-    "@ultimat3/notify": "22.10.0",
-    "@ultimat3/policy": "22.10.0",
-    "@ultimat3/pwa": "22.10.0",
-    "@ultimat3/query": "22.10.0",
-    "@ultimat3/realtime": "22.10.0",
-    "@ultimat3/render": "22.10.0",
-    "@ultimat3/schema": "22.10.0",
-    "@ultimat3/seo": "22.10.0",
-    "@ultimat3/storage": "22.10.0",
-    "@ultimat3/testing": "22.10.0",
-    "@ultimat3/time": "22.10.0",
+    "@ultimat3/action": "22.12.0",
+    "@ultimat3/admin": "22.12.0",
+    "@ultimat3/ai": "22.12.0",
+    "@ultimat3/auth": "22.12.0",
+    "@ultimat3/cache": "22.12.0",
+    "@ultimat3/core": "22.12.0",
+    "@ultimat3/db": "22.12.0",
+    "@ultimat3/entity": "22.12.0",
+    "@ultimat3/flags": "22.12.0",
+    "@ultimat3/http": "22.12.0",
+    "@ultimat3/i18n": "22.12.0",
+    "@ultimat3/jobs": "22.12.0",
+    "@ultimat3/mail": "22.12.0",
+    "@ultimat3/manifest": "22.12.0",
+    "@ultimat3/mcp": "22.12.0",
+    "@ultimat3/money": "22.12.0",
+    "@ultimat3/notify": "22.12.0",
+    "@ultimat3/policy": "22.12.0",
+    "@ultimat3/pwa": "22.12.0",
+    "@ultimat3/query": "22.12.0",
+    "@ultimat3/realtime": "22.12.0",
+    "@ultimat3/render": "22.12.0",
+    "@ultimat3/schema": "22.12.0",
+    "@ultimat3/seo": "22.12.0",
+    "@ultimat3/storage": "22.12.0",
+    "@ultimat3/testing": "22.12.0",
+    "@ultimat3/time": "22.12.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-reload-graph.ts

@@ -16,7 +16,9 @@
 // A module that DEFINES a primitive is PINNED and never leaves the registry: its exports are held
 // by every importer and by a registry that refuses a second definition of one name (an entity is
 // `X_ENTITY_DUPLICATE`; a second action instance is a handler nobody routes to). The closure stops
-// at a pinned module, and an edit to one still needs a restart — exactly what it needed before.
+// at a pinned module — and RECORDS it (`takeStalePins`): a pinned module above a change still holds
+// the old instance of what changed (a slice's service under its query, an admin page's view under
+// `defineAdmin`), so only a new process serves the save. `x dev` restarts on it (`dev-supervisor.ts`).
 
 // why: Bun ships no path API; import specifiers resolve against the importing file's directory.
 import { dirname, resolve } from 'node:path';
@@ -37,6 +39,27 @@ const nodes = new Map<string, Node>();
 /** Reverse edges: file → the files that import it. */
 const importers = new Map<string, Set<string>>();
 const pinned = new Set<string>();
+
+/** A pinned module that still holds the old instance of `changed` — or IS `changed`. */
+export interface StalePin {
+  /** The saved file, absolute. */
+  readonly changed: string;
+  /** The module that defines a primitive and was not re-evaluated, absolute. */
+  readonly pinned: string;
+}
+
+/** What the last rescans' closures stopped at, until `takeStalePins` reads it. */
+let stale: StalePin[] = [];
+
+/**
+ * Every pinned module a rescan since the last call could not refresh, sorted by pinned path, and
+ * forgets them. Empty: everything the saves reached was re-evaluated and the process serves it.
+ */
+export function takeStalePins(): readonly StalePin[] {
+  const taken = stale;
+  stale = [];
+  return taken;
+}
 /**
  * Edges cost a transpile scan and a resolve per import (~300 ms over notificado.co's 1200 modules),
  * so only the one process that rescans pays it: `x dev` turns this on before its first scan. Off,
@@ -54,6 +77,7 @@ export function resetReloadGraph(): void {
   nodes.clear();
   importers.clear();
   pinned.clear();
+  stale = [];
 }
 
 /** Marks a module that defines a primitive: never evicted, and the closure stops at it. */
@@ -185,18 +209,36 @@ async function changedFiles(root: string): Promise<string[]> {
   return changed;
 }
 
-/** `changed` and everything above it, stopping at — and excluding — every pinned module. */
+/**
+ * `changed` and everything above it, stopping at — and excluding — every pinned module. Each
+ * pinned module a walk stopped at is recorded against the change that reached it, once.
+ */
 function closure(changed: readonly string[]): Set<string> {
   const dirty = new Set<string>();
-  const stack = changed.filter((path) => !pinned.has(path));
-  while (stack.length > 0) {
-    const path = stack.pop();
-    if (path === undefined || dirty.has(path)) continue;
-    dirty.add(path);
-    for (const importer of importers.get(path) ?? []) {
-      if (!pinned.has(importer)) stack.push(importer);
+  const reached = new Map<string, string>();
+  for (const origin of changed) {
+    if (pinned.has(origin)) {
+      if (!reached.has(origin)) reached.set(origin, origin);
+      continue;
+    }
+    const seen = new Set<string>();
+    const stack = [origin];
+    while (stack.length > 0) {
+      const path = stack.pop();
+      if (path === undefined || seen.has(path)) continue;
+      seen.add(path);
+      dirty.add(path);
+      for (const importer of importers.get(path) ?? []) {
+        if (!pinned.has(importer)) stack.push(importer);
+        else if (!reached.has(importer)) reached.set(importer, origin);
+      }
     }
   }
+  const held = new Set(stale.map((entry) => entry.pinned));
+  const found = [...reached]
+    .filter(([module]) => !held.has(module))
+    .map(([module, origin]) => ({ changed: origin, pinned: module }));
+  stale = [...stale, ...found].sort((a, b) => (a.pinned < b.pinned ? -1 : 1));
   return dirty;
 }
 

package/src/bin.ts

@@ -33,6 +33,20 @@ if (local !== undefined) {
   process.exit(await child.exited);
 }
 
+// `x dev` supervises a child that serves (`dev-supervisor.ts`): a save that reaches a module which
+// defines a primitive is a restart, since no re-import in one process can serve it. After the
+// handoff above, so the supervisor and its children are the app's own CLI.
+// Imported only for `dev`: every other command's process must not load, or register, anything more.
+if (Bun.argv[2] === 'dev') {
+  const { devSupervision, freeDevPort, superviseDev } = await import('./dev-supervisor');
+  const supervision = devSupervision(Bun.argv.slice(2), Bun.env, freeDevPort);
+  if (supervision !== undefined) {
+    process.exit(
+      await superviseDev({ bin: import.meta.path, argv: supervision.argv, env: Bun.env }),
+    );
+  }
+}
+
 const code = await dispatch({
   argv: Bun.argv.slice(2),
   cwd: process.cwd(),

package/src/browser-launcher-port.ts

@@ -152,6 +152,18 @@ export interface ShotSessionInit {
    * the locale asked for, never of whatever language the machine's Chrome happens to speak.
    */
   readonly headers?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Set in the browser before the first navigation, each for `url`'s origin — `x shot --cookie`, so
+   * a page is photographed with its consent (or any other cookie-held choice) already decided.
+   */
+  readonly cookies?: readonly ShotCookie[] | undefined;
+}
+
+/** One cookie for a shot session: `url` scopes it to the app under test, never another host. */
+export interface ShotCookie {
+  readonly name: string;
+  readonly value: string;
+  readonly url: string;
 }
 
 export interface ShotSession {

package/src/cdp-shot-driver.ts

@@ -139,6 +139,15 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
         if (init.headers !== undefined && Object.keys(init.headers).length > 0) {
           await on('Network.setExtraHTTPHeaders', { headers: init.headers });
         }
+        // `Network.setCookie` needs the Network domain on and precedes `goto` for the header's
+        // reason: a consent banner decided after the first paint is a picture of the banner.
+        for (const cookie of init.cookies ?? []) {
+          await on('Network.setCookie', {
+            name: cookie.name,
+            value: cookie.value,
+            url: cookie.url,
+          });
+        }
         const size = init.viewport ?? viewport;
         await on('Emulation.setDeviceMetricsOverride', {
           width: size.width,
@@ -146,7 +155,11 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
           deviceScaleFactor: 1,
           mobile: false,
         });
-        return { page: cdpShotPage({ connection, sessionId, init, watch }), close };
+        // A classic scrollbar takes ~15px of the layout, so a page "at 1440" was laid out at 1425 and
+        // a full-page capture came back 1425 wide. Hidden, the page is laid out at the width asked
+        // for, which is what a phone's overlay scrollbar and the reviewer's expectation both are.
+        await on('Emulation.setScrollbarsHidden', { hidden: true });
+        return { page: cdpShotPage({ connection, sessionId, init, watch, viewport: size }), close };
       } catch (error) {
         await close();
         throw error;

package/src/cdp-shot-page.ts

@@ -42,6 +42,8 @@ export interface CdpShotPageInput {
   readonly sessionId: string;
   readonly init: ShotSessionInit;
   readonly watch: PageWatch;
+  /** What the page is laid out in: a full-page capture is never narrower than it. */
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
 }
 
 export function cdpShotPage(input: CdpShotPageInput): ShotPage {
@@ -164,7 +166,7 @@ export function cdpShotPage(input: CdpShotPageInput): ShotPage {
       ),
     query,
     evaluate,
-    screenshot: (options?: ShotCapture) => capture(send, options ?? {}),
+    screenshot: (options?: ShotCapture) => capture(send, options ?? {}, input.viewport?.width ?? 0),
     async colorScheme(scheme: ShotColorScheme) {
       // An EMPTY list is CDP's reset; an explicit `no-preference` would be an override.
       const features =
@@ -191,7 +193,7 @@ type Send = (
  * PNG bytes of the viewport, the whole document, or one clip — never both of the last two, which
  * CDP would resolve silently in favour of one. A clip is CSS pixels in page coordinates.
  */
-async function capture(send: Send, framing: ShotCapture): Promise<Uint8Array> {
+async function capture(send: Send, framing: ShotCapture, minWidth: number): Promise<Uint8Array> {
   const clip = framing.clip;
   assert(
     !(framing.fullPage === true && clip !== undefined),
@@ -212,7 +214,14 @@ async function capture(send: Send, framing: ShotCapture): Promise<Uint8Array> {
     const width = metrics?.['width'];
     const height = metrics?.['height'];
     if (typeof width === 'number' && typeof height === 'number') {
-      region = { x: 0, y: 0, width: Math.ceil(width), height: Math.ceil(height) };
+      // Floored at the viewport: the content size is the LAYOUT width, which a scrollbar (or a
+      // document narrower than the window) makes smaller than the picture that was asked for.
+      region = {
+        x: 0,
+        y: 0,
+        width: Math.max(minWidth, Math.ceil(width)),
+        height: Math.ceil(height),
+      };
     }
   }
   const answer = await send('Page.captureScreenshot', {

package/src/cmd-dev.ts

@@ -16,7 +16,8 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { createIsrController } from '@ultimat3/render/server';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
-import { enableReloadTracking } from './app-reload-graph';
+import type { StalePin } from './app-reload-graph';
+import { enableReloadTracking, takeStalePins } from './app-reload-graph';
 import { requireAppRoot } from './app-root';
 import { loadAppRuntime } from './app-runtime';
 import { devSpec } from './cmd-dev-spec';
@@ -29,6 +30,7 @@ import { createStatementLedger } from './dev-n-plus-one';
 import { devPortFor } from './dev-port';
 import { coalesceReloads } from './dev-reload';
 import { devRouteTable } from './dev-route-table';
+import { childRestart, restartFinding } from './dev-supervisor';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
 import { holdUntilShutdown } from './hold';
@@ -108,6 +110,12 @@ export interface StartDevOptions {
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly roles?: readonly Role[];
   readonly onReload?: (file: string, durationMs: number) => void;
+  /**
+   * A save reached a module that defines a primitive, so this process cannot serve it
+   * (`takeStalePins`). Given, it is called INSTEAD of `onReload` — `x dev`'s child drains and exits
+   * for its supervisor to boot a fresh one. Absent, the save is `X_DEV_RESTART_REQUIRED` on `/_x`.
+   */
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
 }
 
 /**
@@ -294,8 +302,14 @@ async function bootDev(
       state.islands = islands;
       for (const path of isr.store().paths()) isr.store().delete(path);
       state.reloads += 1;
-      state.reloadFinding = undefined;
-      options.onReload?.(file, Math.round(performance.now() - started));
+      // Read on EVERY rebuild, so a pin one save reached is never reported against the next save.
+      const pins = takeStalePins();
+      state.reloadFinding =
+        pins.length > 0 && options.onRestart === undefined
+          ? restartFinding(options.root, pins)
+          : undefined;
+      if (pins.length > 0 && options.onRestart !== undefined) options.onRestart(pins);
+      else options.onReload?.(file, Math.round(performance.now() - started));
     },
     // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
     // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
@@ -375,6 +389,7 @@ export const devCommand: CliCommand = {
     // The directory is CLAIMED from here down, so a boot that throws has to give it back — the
     // `releaseBoot` shape, with one acquisition. Without it the first failed `x dev` in a shell
     // refuses every later one with a pid that is no longer running.
+    const restart = childRestart(root, ctx.env);
     const server = await startDev({
       root,
       port,
@@ -384,6 +399,8 @@ export const devCommand: CliCommand = {
         if (!ctx.args.json)
           process.stdout.write(`${msg('cli.dev.hmr', { file, ms: durationMs })}\n`);
       },
+      // Supervised, a save this process cannot serve is a drain and an exit for a fresh child.
+      ...restart.options,
     }).catch((error: unknown) => {
       release();
       throw error;
@@ -461,12 +478,17 @@ export const devCommand: CliCommand = {
     // directory locked by a process that no longer exists.
     return {
       ...result,
-      hold: holdUntilShutdown('dev', async () => {
-        // The lock first: a stop() that throws must not leave a file claiming this pid still owns
-        // the directory, because the next boot would then refuse for a process that is gone.
-        clearLock(services.stateDir);
-        await server.stop();
-      }),
+      hold: holdUntilShutdown(
+        'dev',
+        async () => {
+          // The lock first: a stop() that throws must not leave a file claiming this pid still owns
+          // the directory, because the next boot would then refuse for a process that is gone.
+          clearLock(services.stateDir);
+          await server.stop();
+        },
+        // Released — the port, the lock and the embedded database are free for the next child.
+        { exit: restart.exit },
+      ),
     };
   },
 };

package/src/cmd-shot-island.ts

@@ -26,6 +26,7 @@ import {
   islandVerdictJson,
 } from './island-verdict';
 import type { CommandResult } from './output';
+import type { ShotCookiePair } from './shot-cookie';
 import type { ShotServer } from './shot-server';
 import { SHOT_DIR } from './shot-server';
 
@@ -152,6 +153,8 @@ export interface IslandShotInput {
   readonly settleMs: number;
   readonly timeoutMs: number;
   readonly extraHosts?: string | undefined;
+  /** `--cookie`, set in every state's session for the harness's own origin. */
+  readonly cookies?: readonly ShotCookiePair[] | undefined;
   readonly executablePath?: string | undefined;
   /** A provider's session, or a sidecar. One attach per viewport, memoised like a launch. */
   readonly cdpUrl?: string | undefined;
@@ -195,6 +198,7 @@ export async function islandShot(input: IslandShotInput): Promise<IslandArtifact
     settleMs: input.settleMs,
     timeoutMs: input.timeoutMs,
     ...(input.extraHosts === undefined ? {} : { extraHosts: input.extraHosts }),
+    ...(input.cookies === undefined ? {} : { cookies: input.cookies }),
     ...(input.minBytes === undefined ? {} : { minBytes: input.minBytes }),
   });
 }
@@ -225,6 +229,7 @@ export async function islandSweep(input: IslandSweepInput): Promise<IslandSweepA
     settleMs: input.settleMs,
     timeoutMs: input.timeoutMs,
     ...(input.extraHosts === undefined ? {} : { extraHosts: input.extraHosts }),
+    ...(input.cookies === undefined ? {} : { cookies: input.cookies }),
     ...(input.minBytes === undefined ? {} : { minBytes: input.minBytes }),
   });
 }

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 [--expect-status 404] [--port 0] [--out <dir>] [--settle 2000] [--json]',
+    '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]',
   requiresApp: true,
   flags: [
     { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
@@ -28,6 +28,12 @@ export const shotSpec: CommandSpec = {
       summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
     },
     { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
+    {
+      name: 'cookie',
+      type: 'string',
+      summary:
+        'name=value[,name=value] set for the app before the first navigation (e.g. consent=granted)',
+    },
     {
       name: 'theme',
       type: 'string',

package/src/cmd-shot.ts

@@ -32,6 +32,7 @@ import type { CommandResult } from './output';
 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,
@@ -218,6 +219,11 @@ export interface ShotRun {
    * app's default locale — so a picture never depends on the language of the machine's Chrome.
    */
   readonly acceptLanguage?: string | undefined;
+  /**
+   * `--cookie`: set before the first navigation, each for the server's own URL once it is up —
+   * so a consent banner (or any cookie-held choice) is decided in the picture.
+   */
+  readonly cookies?: readonly ShotCookiePair[] | undefined;
   readonly now?: (() => Date) | undefined;
   /**
    * `--expect-status`: the document status this shot is ok with — `404` to photograph the not-found
@@ -263,6 +269,9 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       ...(options.acceptLanguage === undefined
         ? {}
         : { headers: acceptLanguageHeaders(options.acceptLanguage) }),
+      ...(options.cookies === undefined || options.cookies.length === 0
+        ? {}
+        : { cookies: shotCookies(options.cookies, new URL(server.url).toString()) }),
     });
     const page = session.page;
     if (options.colorScheme !== undefined) {
@@ -354,6 +363,7 @@ export const shotCommand: CliCommand = {
     const positional = ctx.args.positionals[0];
     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 locale = readLocaleFlag(flagString(ctx.args, 'locale'), app);
     // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
@@ -424,6 +434,7 @@ export const shotCommand: CliCommand = {
       ...(flagString(ctx.args, 'allow-hosts') === undefined
         ? {}
         : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
+      ...(cookies.length === 0 ? {} : { cookies }),
       boot,
     };
     if (sweep) return islandSweepResult(await islandSweep(shared));
@@ -444,6 +455,7 @@ export const shotCommand: CliCommand = {
       fullPage: flagBool(ctx.args, 'full'),
       extraHosts: flagString(ctx.args, 'allow-hosts'),
       ...(expectStatus === undefined ? {} : { expectStatus }),
+      ...(cookies.length === 0 ? {} : { cookies }),
     };
     if (matrix) {
       // `--locale` and `--theme` narrow the matrix to one value of their axis.

package/src/dev-port.ts

@@ -4,7 +4,7 @@
 
 import { PORT_RANGE, readIntFlag } from './flag-number';
 import type { ParsedArgs } from './parse';
-import { portFromEnv } from './serve';
+import { portFromEnv } from './serve-env';
 
 export const DEFAULT_DEV_PORT = 3000;
 

package/src/dev-supervisor.ts

@@ -0,0 +1,178 @@
+// `x dev` as two processes: this one supervises, a child serves. A save that reaches a module which
+// DEFINES a primitive (`app-reload-graph.ts`'s pinned modules — a query over a slice's service, an
+// admin page's view under `defineAdmin`) cannot be served by re-importing: the registries and the
+// route table hold that module's first instance. The child exits `DEV_RESTART_EXIT_CODE` instead
+// of logging "reloaded" over stale code, and this loop boots a fresh one on the same port. Every
+// other save stays the in-process reload it was — a restart is paid only where nothing else works.
+
+// why: Bun has no path API; the restart line names files relative to the app root.
+import { relative } from 'node:path';
+import { drain } from '@ultimat3/core';
+import type { StalePin } from './app-reload-graph';
+import { devSpec } from './cmd-dev-spec';
+import { devPortFor } from './dev-port';
+import { msg } from './messages';
+import type { Finding } from './output';
+import { parseArgs } from './parse';
+
+/** Set on the child: it serves, and a pinned save makes it exit for a restart. */
+export const DEV_CHILD_ENV = 'ULTIMATE_DEV_CHILD';
+/** `EX_TEMPFAIL`: "try again" — the one exit code the supervisor answers with a new child. */
+export const DEV_RESTART_EXIT_CODE = 75;
+
+/** What the supervisor runs the child with: the argv, its port pinned. */
+export interface DevSupervision {
+  readonly argv: readonly string[];
+}
+
+/**
+ * Whether this `x …` invocation is a supervised `x dev`, and with what child argv. Not for the
+ * child itself, `--once` (it boots, reports and exits — nothing to restart), `--help`, or an argv
+ * the parse refuses (`dispatch` reports that, in the child's place). `--port 0` is pinned to one
+ * free port here, so a restarted child binds the address the first one printed.
+ */
+export function devSupervision(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+  pickPort: () => number,
+): DevSupervision | undefined {
+  if (argv[0] !== 'dev' || env[DEV_CHILD_ENV] === '1') return undefined;
+  try {
+    const args = parseArgs(argv, [devSpec]);
+    if (args.help || args.flags.get('once') === true) return undefined;
+    return { argv: devPortFor(args, env) === 0 ? withPort(argv, pickPort()) : argv };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A port nothing holds right now, asked of the OS — what `--port 0` is pinned to. */
+export function freeDevPort(): number {
+  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
+  const port = probe.port ?? 0;
+  probe.stop(true);
+  return port;
+}
+
+/** `argv` with every `--port` removed and `--port <port>` appended. */
+function withPort(argv: readonly string[], port: number): readonly string[] {
+  const out: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] ?? '';
+    if (token === '--port') {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--port=')) continue;
+    out.push(token);
+  }
+  return [...out, '--port', String(port)];
+}
+
+/** The child as the loop sees it — `Bun.spawn`'s answer, narrowed so a test can hand one in. */
+export interface DevChild {
+  readonly exited: Promise<number>;
+  kill(signal: 'SIGINT' | 'SIGTERM'): void;
+}
+
+export interface SuperviseDevInput {
+  readonly bin: string;
+  readonly argv: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly spawn?: (
+    command: readonly string[],
+    env: Record<string, string | undefined>,
+  ) => DevChild;
+}
+
+const spawnInherited = (
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): DevChild =>
+  Bun.spawn([...command], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit', env });
+
+/**
+ * Runs children until one exits with anything but `DEV_RESTART_EXIT_CODE`, and answers that code.
+ * SIGINT and SIGTERM are forwarded — a terminal's Ctrl-C reaches the child on its own too, and its
+ * drain is idempotent — and once one arrived no child is started again: a Ctrl-C during a restart
+ * is a stop, never a respawn.
+ */
+export async function superviseDev(input: SuperviseDevInput): Promise<number> {
+  const spawn = input.spawn ?? spawnInherited;
+  let child: DevChild | undefined;
+  let stopping = false;
+  const forward = (signal: 'SIGINT' | 'SIGTERM') => (): void => {
+    stopping = true;
+    child?.kill(signal);
+  };
+  const onInt = forward('SIGINT');
+  const onTerm = forward('SIGTERM');
+  process.on('SIGINT', onInt);
+  process.on('SIGTERM', onTerm);
+  try {
+    for (;;) {
+      child = spawn([process.execPath, input.bin, ...input.argv], {
+        ...input.env,
+        [DEV_CHILD_ENV]: '1',
+      });
+      const code = await child.exited;
+      if (code !== DEV_RESTART_EXIT_CODE || stopping) return code;
+    }
+  } finally {
+    process.off('SIGINT', onInt);
+    process.off('SIGTERM', onTerm);
+  }
+}
+
+/** `apps/web/app/greet/service.ts under apps/web/app/greet/queries.ts`, one per pinned module. */
+export function restartReason(root: string, pins: readonly StalePin[]): string {
+  return pins
+    .map(({ changed, pinned }) =>
+      changed === pinned
+        ? relative(root, pinned)
+        : `${relative(root, changed)} under ${relative(root, pinned)}`,
+    )
+    .join(', ');
+}
+
+/** `/_x`'s finding for a process nothing supervises (an embedded `startDev()` with no `onRestart`). */
+export function restartFinding(root: string, pins: readonly StalePin[]): Finding {
+  const first = pins[0];
+  return {
+    code: 'X_DEV_RESTART_REQUIRED',
+    cause: `${restartReason(root, pins)} — a module that defines a primitive still holds the code before the save, and re-importing it would register a second definition`,
+    fix: 'restart x dev (a supervised `x dev` restarts itself; an embedded startDev() passes onRestart)',
+    at: first === undefined ? '' : relative(root, first.pinned),
+  };
+}
+
+/** The child's half: what `startDev` is handed, and what the hold calls once released. */
+export interface ChildRestart {
+  readonly options: { readonly onRestart?: (pins: readonly StalePin[]) => void };
+  readonly exit: (code: number) => void;
+}
+
+/**
+ * Only a supervised child restarts: it says why on stderr (fd 1 may be `--json`'s one document),
+ * starts core's drain — the hold then releases the lock, the port and the embedded database — and
+ * exits `DEV_RESTART_EXIT_CODE` once released. Anything else keeps the finding on `/_x`.
+ */
+export function childRestart(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+): ChildRestart {
+  if (env[DEV_CHILD_ENV] !== '1') return { options: {}, exit: () => undefined };
+  let restarting = false;
+  return {
+    options: {
+      onRestart: (pins) => {
+        process.stderr.write(`${msg('cli.dev.restart', { reason: restartReason(root, pins) })}\n`);
+        restarting = true;
+        void drain('restart');
+      },
+    },
+    exit: () => {
+      if (restarting) process.exit(DEV_RESTART_EXIT_CODE);
+    },
+  };
+}

package/src/error-codes.ts

@@ -203,6 +203,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_VERIFY_MERGE_INCOMPLETE',
   'X_VERIFY_MERGE_INPUT',
   'X_SITEMAP_EXTRA_INVALID',
+  'X_DEV_RESTART_REQUIRED',
 ] as const;
 
 /**
@@ -355,6 +356,8 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_VERIFY_MERGE_INCOMPLETE: 'x verify merge was handed parts that do not add up to the whole gate',
   X_VERIFY_MERGE_INPUT: 'a part handed to x verify merge is not an x verify --json document',
   X_SITEMAP_EXTRA_INVALID: 'a seo.sitemap.extra path names no public page',
+  X_DEV_RESTART_REQUIRED:
+    'a save reached a module that defines a primitive; only a new process serves it',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/island-capture.ts

@@ -14,6 +14,7 @@ import { readinessProbe } from './island-harness-script';
 import { IslandRequestUnstubbedError, IslandUnphotographableError } from './island-shot-errors';
 import type { IslandReadiness, IslandStateShot } from './island-verdict';
 import { parseReadiness } from './island-verdict';
+import { type ShotCookiePair, shotCookies } from './shot-cookie';
 import type { ShotServer } from './shot-server';
 import { allowHostsFrom } from './shot-server';
 import { SETTLE_POLL_MS, settleReadiness } from './shot-settle';
@@ -120,7 +121,8 @@ export function photographFault(
 }
 
 /**
- * The capture rectangle for a readiness answer, in PAGE coordinates: the crop target's own box,
+ * The capture rectangle for a readiness answer, in PAGE coordinates: the crop target's frame (its
+ * own box grown to every open popup),
  * translated out of the viewport coordinates `getBoundingClientRect()` answers in, then grown by
  * `margin` on every side and CLAMPED to the document.
  *
@@ -136,10 +138,13 @@ export function photographFault(
  * the parser's floor and not a second opinion.
  */
 export function clipFor(seen: IslandReadiness | null, margin: number): CaptureClip {
-  const x = (seen?.box.x ?? 0) + (seen?.scroll.x ?? 0);
-  const y = (seen?.box.y ?? 0) + (seen?.scroll.y ?? 0);
-  const width = seen?.box.width ?? 0;
-  const height = seen?.box.height ?? 0;
+  // The frame, not the box: an open listbox, menu or popover lies outside the island's own box,
+  // and cropping to the box photographed an `open` state closed. The frame always contains the box.
+  const framed = seen?.frame ?? seen?.box;
+  const x = (framed?.x ?? 0) + (seen?.scroll.x ?? 0);
+  const y = (framed?.y ?? 0) + (seen?.scroll.y ?? 0);
+  const width = framed?.width ?? 0;
+  const height = framed?.height ?? 0;
   const left = Math.max(0, x - margin);
   const top = Math.max(0, y - margin);
   const right = Math.min(seen?.page.width ?? x + width, x + width + margin);
@@ -159,6 +164,8 @@ export interface IslandCaptureRun {
   readonly timeoutMs: number;
   readonly extraHosts?: string | undefined;
   readonly cropMarginPx?: number | undefined;
+  /** `--cookie`, scoped to the harness's server once it is up. */
+  readonly cookies?: readonly ShotCookiePair[] | undefined;
 }
 
 const quietly = async (stop: () => Promise<void>): Promise<void> => {
@@ -189,6 +196,9 @@ export async function captureIslandState(
       rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
       clock: systemShotClock,
       timeoutMs: options.timeoutMs,
+      ...(options.cookies === undefined || options.cookies.length === 0
+        ? {}
+        : { cookies: shotCookies(options.cookies, new URL(server.url).toString()) }),
     });
     const page = session.page;
     // BEFORE the navigation, so the first paint already has it: `prefers-color-scheme` is a live

package/src/island-harness-script.ts

@@ -179,11 +179,28 @@ export function harnessScript(options: HarnessScriptOptions): string {
  *
  * `selector` is the crop target the manifest declared; the island's own host element when absent.
  */
+/**
+ * What an island shows OUTSIDE its own box while a state is open: a combobox's listbox, a menu, a
+ * popover or a dialog — often portalled to `<body>`, so no descendant walk would find it. The crop
+ * is the union of the target's box and every visible match, so an `open` state photographs open.
+ * `:popover-open` is last and dropped on an engine that cannot parse it.
+ */
+export const POPUP_SELECTOR =
+  '[role=listbox],[role=menu],[role=dialog],[role=alertdialog],[role=tooltip],dialog[open],:popover-open';
+
 export const readinessProbe = (selector: string): string =>
   `(function(){var W=window.${HARNESS_GLOBAL}||{};` +
   'var host=document.querySelector("[data-x-island]");' +
   `var box=document.querySelector(${JSON.stringify(selector)})||host;` +
   'var r=box?box.getBoundingClientRect():{width:0,height:0,x:0,y:0};' +
+  // The frame: the box grown to every open popup the page shows, in the same viewport coordinates.
+  'var fl=r.x,ft=r.y,fr=r.x+r.width,fb=r.y+r.height,ps=[];' +
+  `try{ps=document.querySelectorAll(${JSON.stringify(POPUP_SELECTOR)})}` +
+  `catch(e){ps=document.querySelectorAll(${JSON.stringify(POPUP_SELECTOR.replace(',:popover-open', ''))})}` +
+  'for(var i=0;box&&i<ps.length;i++){var s=getComputedStyle(ps[i]);' +
+  'if(s.display==="none"||s.visibility==="hidden")continue;var q=ps[i].getBoundingClientRect();' +
+  'if(q.width===0||q.height===0)continue;fl=Math.min(fl,q.x);ft=Math.min(ft,q.y);' +
+  'fr=Math.max(fr,q.x+q.width);fb=Math.max(fb,q.y+q.height)}' +
   'return{harness:W.harness===true,ready:W.ready===true,' +
   'unstubbed:(W.unstubbed||[]).slice(),' +
   // Recorded beside `unstubbed`, never merged into it: a socket a component opened and never
@@ -198,6 +215,7 @@ export const readinessProbe = (selector: string): string =>
   // 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)},' +
+  'frame:{x:Math.round(fl),y:Math.round(ft),width:Math.round(fr-fl),height:Math.round(fb-ft)},' +
   // 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

package/src/island-verdict.ts

@@ -67,6 +67,11 @@ export interface IslandReadiness {
   readonly filled: boolean;
   /** The crop target's rectangle in VIEWPORT coordinates, which is what the DOM answers. */
   readonly box: IslandBox;
+  /**
+   * `box` grown to every open popup the page shows (`POPUP_SELECTOR`), same coordinates: what the
+   * picture is cropped to, so a listbox or a portalled menu is in it. Absent: the box alone.
+   */
+  readonly frame?: IslandBox | undefined;
   /**
    * 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
@@ -99,6 +104,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 }),
+  frame: t.optional(t.object({ x: t.number, y: t.number, width: t.number, height: t.number })),
   scroll: t.object({ x: t.number, y: t.number }),
   overflow: t.object({ x: t.boolean, y: t.boolean }),
   page: t.object({ width: t.number, height: t.number }),

package/src/mcp-errors.ts

@@ -253,6 +253,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only budgets --json   # after moving each await in Page into export const load',
   X_SITEMAP_EXTRA_INVALID:
     'x routes --json   # then list in seo.sitemap.extra only a path a registered app/ route without a policy answers',
+  X_DEV_RESTART_REQUIRED:
+    'x dev --json   # a fresh process; the supervised x dev restarts itself on such a save',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -76,6 +76,7 @@ const CATALOG = {
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
+  'cli.dev.restart': 'restarting: {reason} — a module that defines a primitive holds the old code',
   // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
   // reader knows why the boot paused, and never a finding.
   'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',

package/src/shot-cookie.ts

@@ -0,0 +1,45 @@
+// `x shot --cookie name=value[,name=value]` — cookies set in the browser before the first
+// navigation, so a page is photographed with a cookie-held choice (consent, a dismissed banner)
+// already made. Read here, before anything boots; scoped to the app's own origin once it exists.
+
+import type { ShotCookie } from './browser-launcher-port';
+import { BadFlagError } from './errors';
+
+/** RFC 6265 `token` for a name; a value may not carry what ends or splits a Cookie header. */
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const COOKIE_VALUE = /^[^\s;,"\\]*$/;
+
+const FIX = 'x shot / --cookie consent=granted --json';
+
+export interface ShotCookiePair {
+  readonly name: string;
+  readonly value: string;
+}
+
+const refuse = (reason: string): never => {
+  throw new BadFlagError({ flag: 'cookie', command: 'shot', reason, fix: FIX });
+};
+
+/** The pairs `--cookie` names, in order; absent or empty is none. */
+export function readCookieFlag(raw: string | undefined): readonly ShotCookiePair[] {
+  if (raw === undefined || raw.trim() === '') return [];
+  return raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .map((pair) => {
+      const at = pair.indexOf('=');
+      if (at < 0) return refuse(`"${pair}" has no "=" — a cookie is name=value`);
+      const name = pair.slice(0, at).trim();
+      const value = pair.slice(at + 1).trim();
+      if (!COOKIE_NAME.test(name)) return refuse(`"${name}" is not a cookie name`);
+      if (!COOKIE_VALUE.test(value)) {
+        return refuse(`the value of "${name}" holds a space, ";", ",", a quote or a backslash`);
+      }
+      return { name, value };
+    });
+}
+
+/** Each pair for the app under test: the server's own URL, so no cookie reaches another host. */
+export const shotCookies = (pairs: readonly ShotCookiePair[], url: string): readonly ShotCookie[] =>
+  pairs.map((pair) => ({ ...pair, url }));