@ultimat3/cli 22.10.0 → 22.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.10.0",
+  "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.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.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/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/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 }));