@ultimat3/cli 22.9.1 → 22.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.9.1",
+  "version": "22.11.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.9.1",
-    "@ultimat3/admin": "22.9.1",
-    "@ultimat3/ai": "22.9.1",
-    "@ultimat3/auth": "22.9.1",
-    "@ultimat3/cache": "22.9.1",
-    "@ultimat3/core": "22.9.1",
-    "@ultimat3/db": "22.9.1",
-    "@ultimat3/entity": "22.9.1",
-    "@ultimat3/flags": "22.9.1",
-    "@ultimat3/http": "22.9.1",
-    "@ultimat3/i18n": "22.9.1",
-    "@ultimat3/jobs": "22.9.1",
-    "@ultimat3/mail": "22.9.1",
-    "@ultimat3/manifest": "22.9.1",
-    "@ultimat3/mcp": "22.9.1",
-    "@ultimat3/money": "22.9.1",
-    "@ultimat3/notify": "22.9.1",
-    "@ultimat3/policy": "22.9.1",
-    "@ultimat3/pwa": "22.9.1",
-    "@ultimat3/query": "22.9.1",
-    "@ultimat3/realtime": "22.9.1",
-    "@ultimat3/render": "22.9.1",
-    "@ultimat3/schema": "22.9.1",
-    "@ultimat3/seo": "22.9.1",
-    "@ultimat3/storage": "22.9.1",
-    "@ultimat3/testing": "22.9.1",
-    "@ultimat3/time": "22.9.1",
+    "@ultimat3/action": "22.11.0",
+    "@ultimat3/admin": "22.11.0",
+    "@ultimat3/ai": "22.11.0",
+    "@ultimat3/auth": "22.11.0",
+    "@ultimat3/cache": "22.11.0",
+    "@ultimat3/core": "22.11.0",
+    "@ultimat3/db": "22.11.0",
+    "@ultimat3/entity": "22.11.0",
+    "@ultimat3/flags": "22.11.0",
+    "@ultimat3/http": "22.11.0",
+    "@ultimat3/i18n": "22.11.0",
+    "@ultimat3/jobs": "22.11.0",
+    "@ultimat3/mail": "22.11.0",
+    "@ultimat3/manifest": "22.11.0",
+    "@ultimat3/mcp": "22.11.0",
+    "@ultimat3/money": "22.11.0",
+    "@ultimat3/notify": "22.11.0",
+    "@ultimat3/policy": "22.11.0",
+    "@ultimat3/pwa": "22.11.0",
+    "@ultimat3/query": "22.11.0",
+    "@ultimat3/realtime": "22.11.0",
+    "@ultimat3/render": "22.11.0",
+    "@ultimat3/schema": "22.11.0",
+    "@ultimat3/seo": "22.11.0",
+    "@ultimat3/storage": "22.11.0",
+    "@ultimat3/testing": "22.11.0",
+    "@ultimat3/time": "22.11.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

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-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-route-table.ts

@@ -127,7 +127,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     // captured at boot would answer 404 for the href the document now carries.
     ...styleRoutes(() => styleBundle()),
     // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
-    ...seoRoutes({ env: input.env, site }),
+    ...seoRoutes({ env: input.env, site, root: input.root }),
     // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
     // lives here rather than in a second server because everything it needs is in THIS process:
     // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout

package/src/error-codes.ts

@@ -202,6 +202,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_VERIFY_SHARD_INVALID',
   'X_VERIFY_MERGE_INCOMPLETE',
   'X_VERIFY_MERGE_INPUT',
+  'X_SITEMAP_EXTRA_INVALID',
 ] as const;
 
 /**
@@ -353,6 +354,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_VERIFY_SHARD_INVALID: 'x verify --shard was given a spec or a step list it cannot split',
   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',
 };
 
 // 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

@@ -251,6 +251,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x build --target static --json   # after adding prerender() with one real path to the route',
   X_ROUTE_ASYNC_PAGE:
     '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',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/seo-routes.ts

@@ -10,8 +10,10 @@ import { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 
 export interface SeoRoutesOptions {
   readonly env: Readonly<Record<string, string | undefined>>;
-  /** `site.origin` and `seo.robots.disallow` from `app.config.ts` (`loadSiteSettings`). */
+  /** `site.origin`, `seo.robots.disallow` and `seo.sitemap` from `app.config.ts` (`loadSiteSettings`). */
   readonly site?: SiteSettings;
+  /** The app root route files are relative to — `seo.sitemap.lastmod: 'git' | 'mtime'` reads them. */
+  readonly root?: string;
 }
 
 /**
@@ -37,6 +39,8 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
       baseUrl: originOf(options, request),
       environment,
       disallow: options.site?.disallow ?? [],
+      ...(options.site === undefined ? {} : { sitemap: options.site.sitemap }),
+      ...(options.root === undefined ? {} : { root: options.root }),
     });
 
   return [

package/src/serve-boot.ts

@@ -198,7 +198,7 @@ async function webSurface(
     // filled, so this process serves exactly the CSS it renders against.
     ...styleRoutes(() => styleBundle()),
     // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
-    ...seoRoutes({ env: options.env, site }),
+    ...seoRoutes({ env: options.env, site, root: options.root }),
     // The page's one socket: its worker script, served beside the islands for their reason.
     ...sync.routes,
     ...navigation.routes,

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 }));

package/src/site-config.ts

@@ -5,7 +5,8 @@
 
 // why: Bun exposes no path-join primitive, and the config path is app-root-relative.
 import { join } from 'node:path';
-import type { AppConfig, Environment } from '@ultimat3/core';
+import type { AppConfig, Environment, SeoSitemapConfig, SitemapLastmod } from '@ultimat3/core';
+import { SITEMAP_LASTMOD_SOURCES } from '@ultimat3/core';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 
@@ -14,9 +15,15 @@ export interface SiteSettings {
   readonly origin: string | null;
   /** `seo.robots.disallow` — the paths a production `robots.txt` keeps crawlers out of. */
   readonly disallow: readonly string[];
+  /** `seo.sitemap` — public `app/` pages to list, and where `<lastmod>` comes from. */
+  readonly sitemap: SeoSitemapConfig;
 }
 
-export const NO_SITE_SETTINGS: SiteSettings = { origin: null, disallow: [] };
+export const NO_SITE_SETTINGS: SiteSettings = {
+  origin: null,
+  disallow: [],
+  sitemap: { extra: [], lastmod: 'none' },
+};
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
@@ -43,6 +50,26 @@ export async function loadSiteSettings(root: string): Promise<SiteSettings> {
   return {
     origin: typeof origin === 'string' && origin !== '' ? trimSlash(origin) : null,
     disallow: [...config.seo.robots.disallow],
+    sitemap: sitemapOf(config.seo),
+  };
+}
+
+/**
+ * Structural for `hasSiteSections`' reason: a config resolved through a core older than
+ * `seo.sitemap` has no such key, and that is the default, not a crash.
+ */
+function sitemapOf(seo: unknown): SeoSitemapConfig {
+  const declared = isRecord(seo) ? seo['sitemap'] : undefined;
+  if (!isRecord(declared)) return NO_SITE_SETTINGS.sitemap;
+  const extra = declared['extra'];
+  const lastmod = declared['lastmod'];
+  return {
+    extra: Array.isArray(extra)
+      ? extra.filter((path): path is string => typeof path === 'string')
+      : [],
+    lastmod: SITEMAP_LASTMOD_SOURCES.includes(lastmod as SitemapLastmod)
+      ? (lastmod as SitemapLastmod)
+      : 'none',
   };
 }
 

package/src/site-seo.ts

@@ -2,7 +2,8 @@
 // (`apps/web/prerender.ts` writes it into the artifact) and the running web role (`seo-routes.ts`
 // serves it), so a crawler reads the same two files from a CDN and from a container.
 
-import type { Environment } from '@ultimat3/core';
+import type { Environment, SeoSitemapConfig } from '@ultimat3/core';
+import { UltimateError } from '@ultimat3/core';
 import { localeConfig, localizedPath, routedLocales, unlocalizedPath } from '@ultimat3/i18n';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
@@ -10,6 +11,7 @@ import { enumeratePrerender, fillPath } from '@ultimat3/render/server';
 import type { RouteRecord, SitemapFile } from '@ultimat3/seo';
 import { buildRobots, buildSitemap, isDynamic } from '@ultimat3/seo';
 import { readSiteMeta } from './seo-meta';
+import { lastmodOf } from './sitemap-lastmod';
 
 export const ROBOTS_PATH = '/robots.txt';
 export const SITEMAP_PATH = '/sitemap.xml';
@@ -30,6 +32,27 @@ export interface SiteSeoOptions {
    * `User-agent: *` group; a non-production `robots.txt` still disallows everything.
    */
   readonly disallow?: readonly string[] | undefined;
+  /**
+   * `seo.sitemap` from `app.config.ts` (`loadSiteSettings`): the public `app/` pages to list beside
+   * the `site/` ones, and where each `<lastmod>` comes from. Omitted: `site/` pages, no `<lastmod>`.
+   */
+  readonly sitemap?: SeoSitemapConfig | undefined;
+  /** The app root the route files are relative to — read for `lastmod: 'git' | 'mtime'`. */
+  readonly root?: string | undefined;
+}
+
+const NO_SITEMAP_SETTINGS: SeoSitemapConfig = { extra: [], lastmod: 'none' };
+
+/** A `seo.sitemap.extra` path that names no public page outside `site/`. */
+export class SitemapExtraInvalidError extends UltimateError {
+  constructor(path: string, reason: string) {
+    super({
+      code: 'X_SITEMAP_EXTRA_INVALID',
+      cause: `seo.sitemap.extra lists "${path}", which ${reason}`,
+      fix: 'x routes --json   # then list in seo.sitemap.extra only a path a registered app/ route without a policy answers',
+      meta: { path },
+    });
+  }
 }
 
 export interface SiteSeo {
@@ -60,7 +83,10 @@ const pagesOf = async (entry: RouteEntry, options: SiteSeoOptions): Promise<read
  * without a request (`readSiteMeta`), which is what lets a page's own `robots: { index: false }`
  * keep it out of the sitemap — a page that asks crawlers to stay away must not be listed for them.
  */
-async function publicSiteRoutes(options: SiteSeoOptions): Promise<readonly RouteRecord[]> {
+async function publicSiteRoutes(
+  options: SiteSeoOptions,
+  stamp: Stamp,
+): Promise<readonly RouteRecord[]> {
   const metaByPath = new Map((await readSiteMeta()).records.map((r) => [r.path, r.meta]));
   return routeEntries()
     .filter(isPublicSite)
@@ -73,17 +99,70 @@ async function publicSiteRoutes(options: SiteSeoOptions): Promise<readonly Route
         render: entry.config.render,
         ...(meta === undefined ? {} : { meta }),
         ...(isDynamic(entry.path) ? { prerender: () => pagesOf(entry, options) } : {}),
+        ...stamp(entry.file),
       };
     });
 }
 
+type Stamp = (file: string) => { readonly lastmod?: string };
+
+/**
+ * The app's `seo.sitemap.extra` paths as records, each resolved to the route that answers it — the
+ * most specific match, the router's own tie-break. REFUSED, never skipped, when it names no route,
+ * an `api/` route, a gated one or a `site/` page (listed already): a sitemap missing a page its
+ * author listed is the silent drop, and a gated page in it is a URL a crawler cannot open.
+ */
+function extraRoutes(extra: readonly string[], stamp: Stamp): readonly RouteRecord[] {
+  const entries = routeEntries();
+  return [...new Set(extra)].map((path) => {
+    const entry = entries
+      .filter((candidate) => candidate.pattern.regex.test(path))
+      .sort((a, b) => b.pattern.specificity - a.pattern.specificity)[0];
+    if (entry === undefined)
+      throw new SitemapExtraInvalidError(path, 'no registered route answers');
+    if (entry.surface === 'api') {
+      throw new SitemapExtraInvalidError(path, `is the api/ route ${entry.file}, not a page`);
+    }
+    if (entry.surface === 'site') {
+      throw new SitemapExtraInvalidError(
+        path,
+        `is the site/ page ${entry.file} — every public site/ page is listed already`,
+      );
+    }
+    if (entry.config.policy !== undefined) {
+      throw new SitemapExtraInvalidError(
+        path,
+        `is answered by ${entry.file}, which declares a policy — a crawler cannot open it`,
+      );
+    }
+    return {
+      path,
+      file: entry.file,
+      surface: 'app' as const,
+      render: entry.config.render,
+      sitemap: true,
+      ...stamp(entry.file),
+    };
+  });
+}
+
 export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
   // Every routed locale, with `xhtml:link` alternates: one `<url>` per page per locale, each
   // naming the whole cluster and `x-default`. A single-locale app passes none and gets the plain
   // urlset it always had — an alternates cluster of one is noise.
   const locales = routedLocales();
   const defaultLocale = localeConfig().fallback;
-  const sitemap = await buildSitemap(await publicSiteRoutes(options), {
+  const settings = options.sitemap ?? NO_SITEMAP_SETTINGS;
+  const root = options.root ?? process.cwd();
+  const stamp: Stamp = (file) => {
+    const lastmod = lastmodOf(file, settings.lastmod, root);
+    return lastmod === undefined ? {} : { lastmod };
+  };
+  const routes = [
+    ...(await publicSiteRoutes(options, stamp)),
+    ...extraRoutes(settings.extra, stamp),
+  ];
+  const sitemap = await buildSitemap(routes, {
     baseUrl: options.baseUrl,
     ...(locales.length < 2
       ? {}

package/src/sitemap-lastmod.ts

@@ -0,0 +1,73 @@
+// A sitemap `<lastmod>` per route source file — `seo.sitemap.lastmod` in `app.config.ts`. Read once
+// per file per process: the running web role answers `/sitemap.xml` per request, and a `git log`
+// per route per request is a subprocess per crawler hit for a date that changes on deploy.
+
+// why: Bun has no synchronous stat, and `Bun.file(missing).lastModified` answers a garbage date
+// (measured: year 144683) instead of refusing — the sitemap is built synchronously per route.
+import { statSync } from 'node:fs';
+// why: Bun exposes no path-join primitive, and the route file is app-root-relative.
+import { join } from 'node:path';
+import type { SitemapLastmod } from '@ultimat3/core';
+
+/** The moment this process first built a sitemap — `'build'`'s one timestamp for every URL. */
+let builtAt: string | undefined;
+
+const cache = new Map<string, string | undefined>();
+
+/**
+ * The `<lastmod>` for one route file, W3C Datetime (ISO 8601, UTC), or `undefined` when the source
+ * yields none — a sitemap entry without `<lastmod>` is valid, a wrong one misleads a crawler.
+ *
+ * `'git'` falls back to the file's mtime where there is no work tree (a container image): the
+ * image's copy of the file was written by the build, which is the honest "last changed" there.
+ */
+export function lastmodOf(file: string, mode: SitemapLastmod, root: string): string | undefined {
+  if (mode === 'none') return undefined;
+  if (mode === 'build') {
+    builtAt ??= new Date().toISOString();
+    return builtAt;
+  }
+  const key = `${mode}\u0000${root}\u0000${file}`;
+  if (cache.has(key)) return cache.get(key);
+  const value = (mode === 'git' ? gitDate(file, root) : undefined) ?? mtimeOf(join(root, file));
+  cache.set(key, value);
+  return value;
+}
+
+/** Test seam: forget every date read, so a test can move a file's clock. */
+export function resetLastmodCache(): void {
+  cache.clear();
+  builtAt = undefined;
+}
+
+function gitDate(file: string, root: string): string | undefined {
+  try {
+    const run = Bun.spawnSync(['git', 'log', '-1', '--format=%cI', '--', file], {
+      cwd: root,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    if (run.exitCode !== 0) return undefined;
+    return isoOf(run.stdout.toString().trim());
+  } catch {
+    // No `git` binary on PATH: the fallback, never a sitemap that cannot be served.
+    return undefined;
+  }
+}
+
+function mtimeOf(path: string): string | undefined {
+  try {
+    const modified = statSync(path, { throwIfNoEntry: false })?.mtimeMs;
+    return modified !== undefined && Number.isFinite(modified) && modified > 0
+      ? new Date(modified).toISOString()
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isoOf(text: string): string | undefined {
+  if (text === '') return undefined;
+  const time = Date.parse(text);
+  return Number.isFinite(time) ? new Date(time).toISOString() : undefined;
+}

package/src/templates/scaffold-entries.ts

@@ -91,10 +91,15 @@ const origin = Bun.env.SITE_ORIGIN;
  * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
  */
 async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]> {
+  // The same disallow list and sitemap settings the running server answers with
+  // (app.config.ts seo.robots.disallow and seo.sitemap).
+  const settings = await loadSiteSettings(root);
   const seo = await siteSeo({
     // The origin the pages were built against, so the sitemap and every canonical agree.
     baseUrl: report.origin,
-    disallow: (await loadSiteSettings(root)).disallow,
+    disallow: settings.disallow,
+    sitemap: settings.sitemap,
+    root,
     pagesFor: (route) =>
       report.pages.filter((page) => page.route === route).map((page) => page.path),
   });