@domandigital/craft 0.19.3 → 0.20.0

package/dist/phone.d.cts

@@ -1,3 +1,9 @@
+interface SourceFile {
+    /** Repo-relative path. The extension decides how the file is read. */
+    path: string;
+    text: string;
+}
+
 /**
  * The in-page half of the phone-first gate.
  *
@@ -18,20 +24,25 @@ interface PhoneFloors {
     fieldFontPx: number;
     textPx: number;
 }
-type PhoneCheck = "scroll" | "target" | "field" | "text" | "title";
+/**
+ * What a measure can find. The first five are the 375px floors (DOM-775); the
+ * rest are the every-viewport and phone-optimisation checks (DOM-787).
+ */
+type PhoneCheck = "scroll" | "target" | "field" | "text" | "title" | "overlap" | "action" | "layers" | "landscape" | "image" | "input" | "autocomplete" | "tel" | "linelength";
 interface RawPhoneFinding {
     check: PhoneCheck;
     /** `<tag> "text"`: what a person looks for on the page. */
     element: string;
     detail: string;
 }
-declare function measurePhoneInPage(floors: PhoneFloors): RawPhoneFinding[];
-
-interface SourceFile {
-    /** Repo-relative path. The extension decides how the file is read. */
-    path: string;
-    text: string;
-}
+/**
+ * `floors.only` narrows the measure to some checks, for the viewports where
+ * only some apply (text at every width, targets and fields at phone widths).
+ * Left out, all five run, as they always did.
+ */
+declare function measurePhoneInPage(floors: PhoneFloors & {
+    only?: PhoneCheck[];
+}): RawPhoneFinding[];
 
 /**
  * The judging half of the phone-first gate: pure text work, tested without a
@@ -68,6 +79,8 @@ interface MeasuredRoute {
         width: number;
         height: number;
     };
+    /** Set by the every-viewport measure: the viewports and widths the findings were gathered across, phone first. */
+    viewports?: string[];
     findings: RawPhoneFinding[];
 }
 interface Baseline {
@@ -117,6 +130,242 @@ declare function judgeMeasured(routes: MeasuredRoute[], baseline: Baseline): Jud
 /** The baseline that makes this run pass: what is there now, counted. */
 declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[], note?: string): Baseline;
 
+/**
+ * What "every viewport" means (STANDARD.md section 10, DOM-787): the ladder
+ * the page is measured at, the five bands it is designed in, the width sweep
+ * between the rungs, and the thresholds the checks judge by. Pure data and
+ * text work, so it is tested without a browser.
+ */
+
+type Band = "phone" | "large-phone" | "tablet" | "laptop" | "wide";
+/** The five bands every page is designed in. A width belongs to exactly one. */
+declare const BANDS: {
+    band: Band;
+    from: number;
+    to: number | null;
+}[];
+declare const bandOf: (width: number) => Band;
+interface Viewport {
+    /** The label a report uses: `375`, or `844x390` for a landscape phone. */
+    name: string;
+    width: number;
+    height: number;
+    /** A phone held either way up: the touch floors (targets, fields) apply. */
+    phone: boolean;
+    landscape?: boolean;
+}
+/**
+ * The ladder, phone first in order and in every report. Heights are the
+ * phones' own; 375 x 812 stays the house phone (`PHONE`), so a baseline made
+ * at 375 means the same thing here.
+ */
+declare const LADDER: Viewport[];
+/** The short phone the first screen is judged on: an iPhone SE, the least height a visitor has. */
+declare const SHORT_PHONE: Viewport;
+/** Widths where body line length and wide-screen image scaling are judged. */
+declare const WIDE_WIDTHS: number[];
+interface Sweep {
+    from: number;
+    to: number;
+    /** Step below `wideFrom`, where layouts change most. */
+    step: number;
+    /** Step from `wideFrom` up. */
+    wideStep: number;
+    wideFrom: number;
+    /** The height every swept width is laid out at. */
+    height: number;
+}
+declare const DEFAULT_SWEEP: Sweep;
+/** 320, 336 ... 1024, 1056 ... 1920. */
+declare function sweepWidths(sweep?: Sweep): number[];
+/** House defaults for the checks. Each can be overridden per site or portal; the defaults are what the standard says. */
+interface Thresholds {
+    /** Fixed and sticky layers together cover at most this share of a short phone's screen. */
+    maxLayerShare: number;
+    /** In landscape, header and fixed layers leave at least this share of the height: they cover at most 1 minus it. */
+    landscapeMaxLayerShare: number;
+    /** An image whose file is more than this many times its displayed width is oversized (at DPR 2 it needs 2; the rest is slack). */
+    oversizeRatio: number;
+    /** An image whose file is narrower than this many times its displayed width is upscaled. */
+    upscaleRatio: number;
+    /** Body text lines at 1440 and 1920 are at most this many characters (`ch` of the computed font). */
+    maxLineCh: number;
+    /** Two pieces of visible text overlap when the overlap is this share of the shorter one's height and at least 3px wide. */
+    overlapShare: number;
+    /** Image files under this displayed width (CSS px) are icons and marks: not judged. */
+    minImagePx: number;
+}
+declare const DEFAULT_THRESHOLDS: Thresholds;
+/** The main action, as a selector: one for the whole site, or one per route (`*` is the fallback). */
+type MainAction = string | Record<string, string>;
+declare const mainActionFor: (config: MainAction | undefined, route: string) => string | undefined;
+/**
+ * Widths as a person reads them: `320-352, 400, 1440`. A run is consecutive
+ * tested widths that all fail. A landscape or short-phone name (`844x390`)
+ * stands alone.
+ */
+declare function formatWidths(failing: string[], tested: string[]): string;
+/**
+ * One finding per element and check across every viewport, so the baseline
+ * counts what is on the page and not how many widths it was seen at. The count
+ * is the most seen at any single viewport; the detail names every viewport it
+ * failed at, as ranges.
+ */
+declare function mergeViewportFindings(perViewport: {
+    viewport: string;
+    findings: RawPhoneFinding[];
+}[], tested: string[]): RawPhoneFinding[];
+
+/**
+ * The in-page half of the every-viewport measure (DOM-787).
+ *
+ * `measureViewportInPage` runs inside the browser through `page.evaluate`, so
+ * like `measurePhoneInPage` it must be self-contained: no imports, nothing
+ * from outside its own body. The caller has set the viewport, waited for the
+ * page to settle and scrolled to the top; the function judges the page as it
+ * stands, for whichever groups of checks it is asked for:
+ *
+ * - `sweep`: at any width, the page does not scroll sideways, no visible text
+ *   sits on other visible text, and no page title is cut off.
+ * - `optimise`: on the short phone (375 x 667), the main action is on the
+ *   first screen or pinned, fixed and sticky layers leave the screen to the
+ *   page, images are sized for the phone, fields use the right keyboard and
+ *   carry autocomplete, and phone numbers in the text dial.
+ * - `landscape`: on a phone held sideways, the header and fixed layers leave
+ *   at least half the height.
+ * - `wide`: at 1440 and above, body text keeps a readable line length and no
+ *   image is stretched past its file.
+ */
+
+type InPageGroup = "sweep" | "optimise" | "landscape" | "wide";
+interface ViewportArg {
+    groups: InPageGroup[];
+    thresholds: Thresholds;
+    /** CSS selector for the page's main action. Absent: the action check is not run. */
+    mainAction?: string;
+    /** Also fail a page with no width=device-width viewport meta, which a phone lays out at 980px. Meaningful at phone widths. */
+    metaViewport?: boolean;
+}
+declare function measureViewportInPage(arg: ViewportArg): RawPhoneFinding[];
+
+/** What the phone measures share: the house phone, the house floors, where results go. */
+
+/**
+ * The phone every surface is designed at (STANDARD.md section 10): 375 x 812,
+ * touch, at 2x. Spread into Playwright's `test.use` or `browser.newContext`.
+ */
+declare const PHONE: {
+    readonly viewport: {
+        readonly width: 375;
+        readonly height: 812;
+    };
+    readonly deviceScaleFactor: 2;
+    readonly isMobile: true;
+    readonly hasTouch: true;
+};
+/** The house floors at phone width. Not per-repo settings. */
+declare const PHONE_FLOORS: PhoneFloors;
+/** Where `measurePhone` writes and `craft phone-first --measured` reads, unless told otherwise. */
+declare const DEFAULT_MEASURED_DIR = "phone-first/measured";
+/** A route as a file name: `/portal/invoices` is `portal-invoices.json`, `/` is `home.json`. */
+declare const routeFile: (route: string) => string;
+
+/**
+ * The runner for the every-viewport measure (DOM-787): drives a page through
+ * the ladder and the width sweep and hands each stop to the in-page checks.
+ *
+ * Two entries:
+ *
+ * - `measureViewports(page, options)` resizes the page it is given, in place.
+ *   A portal's Playwright suite owns the sign-in and the fixture data, so it
+ *   opens the route and calls this.
+ * - `measureSite(browser, options)` opens each route itself, once in a phone
+ *   context (touch, 2x, mobile viewport handling) for everything under 768 and
+ *   once in a desktop context for the rest: what create-site's measure.mjs and
+ *   `craft viewports` use for a page anyone can open.
+ *
+ * Neither imports Playwright: the caller drives the browser.
+ */
+
+interface ViewportPage {
+    evaluate<R, A>(fn: (arg: A) => R, arg: A): Promise<R>;
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+interface MeasureViewportsOptions {
+    /** The route as the baseline names it, without host or query: `/portal/invoices`. */
+    route: string;
+    /** The folder to write `<route>.json` into. Default `phone-first/measured`. `false` writes nothing. */
+    out?: string | false;
+    /**
+     * Which half to run on this page. `all` (default) runs everything on the one
+     * page; `phone` stops below 768 and adds the short phone and landscape;
+     * `wide` runs 768 and up. A page in a desktop browser context has no business
+     * judging a phone, and the other way round: `measureSite` runs each half in
+     * the context it belongs to.
+     */
+    scope?: "all" | "phone" | "wide";
+    /** Override house thresholds. */
+    thresholds?: Partial<Thresholds>;
+    /** Override the 12 / 16 / 44px floors. The defaults are the house standard; a site may set `textPx` higher. */
+    floors?: Partial<PhoneFloors>;
+    /** The main action's selector: one for all routes, or per route with `*` as the fallback. Absent: not checked. */
+    mainAction?: MainAction;
+    /** The width sweep, or `false` to measure the ladder only. */
+    sweep?: Partial<Sweep> | false;
+    /** Replace the ladder. */
+    ladder?: Viewport[];
+    /** Called at each ladder viewport once the page has settled, for captures. */
+    onViewport?: (page: ViewportPage, viewport: Viewport, route: string) => Promise<void>;
+}
+interface ViewportsResult extends MeasuredRoute {
+    viewports: string[];
+    /** What each viewport found before the merge, in the order measured. */
+    perViewport: {
+        viewport: string;
+        findings: RawPhoneFinding[];
+    }[];
+}
+/**
+ * Measure the page the caller has opened at every viewport, resizing it in
+ * place: the ladder, the width sweep, the short phone, landscape and the wide
+ * checks. Writes the merged result for `craft phone-first --measured`. Does
+ * not judge or throw on a finding: the baseline decides.
+ */
+declare function measureViewports(page: ViewportPage, options: MeasureViewportsOptions): Promise<ViewportsResult>;
+interface SitePage extends ViewportPage {
+    goto(url: string): Promise<{
+        ok(): boolean;
+        status(): number | string;
+    } | null>;
+}
+interface SiteBrowser {
+    newContext(options: Record<string, unknown>): Promise<{
+        newPage(): Promise<SitePage>;
+        close(): Promise<void>;
+    }>;
+}
+interface MeasureSiteOptions extends Omit<MeasureViewportsOptions, "route" | "scope"> {
+    /** The running site, without a trailing slash. */
+    base: string;
+    routes: string[];
+}
+interface SiteResult {
+    routes: ViewportsResult[];
+    /** Routes that did not answer, with why. Not measured, and not passed. */
+    errors: {
+        route: string;
+        error: string;
+    }[];
+}
+/**
+ * Open every route on a running site and measure it: the phone half in a
+ * phone context, the wide half in a desktop one, merged per route.
+ */
+declare function measureSite(browser: SiteBrowser, options: MeasureSiteOptions): Promise<SiteResult>;
+
 /**
  * `@domandigital/craft/phone`: the phone-first gate for an app behind a
  * sign-in, such as a client portal (DOM-775).
@@ -140,26 +389,16 @@ declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[
  *       });
  *     }
  *
+ * `measureViewports` (DOM-787) is the same for every viewport: it resizes the
+ * page the suite opened through the ladder and the width sweep, and adds the
+ * phone-optimisation and wide-screen checks. `measureSite` opens a running
+ * site's routes itself, and `craft viewports` is that on the command line.
+ * Both write the same measured files, so `craft phone-first --measured` judges
+ * them against the same baseline.
+ *
  * Nothing here imports Playwright: the page is whatever the caller drives.
  */
 
-/**
- * The phone every surface is designed at (STANDARD.md section 10): 375 x 812,
- * touch, at 2x. Spread into Playwright's `test.use` or `browser.newContext`.
- */
-declare const PHONE: {
-    readonly viewport: {
-        readonly width: 375;
-        readonly height: 812;
-    };
-    readonly deviceScaleFactor: 2;
-    readonly isMobile: true;
-    readonly hasTouch: true;
-};
-/** The house floors at phone width. Not per-repo settings. */
-declare const PHONE_FLOORS: PhoneFloors;
-/** Where `measurePhone` writes and `craft phone-first --measured` reads, unless told otherwise. */
-declare const DEFAULT_MEASURED_DIR = "phone-first/measured";
 interface MinimalPage {
     evaluate<R, A>(fn: (arg: A) => R, arg: A): Promise<R>;
     viewportSize?(): {
@@ -173,8 +412,6 @@ interface MeasurePhoneOptions {
     /** The folder to write `<route>.json` into. Default `phone-first/measured`, from the working directory. */
     out?: string;
 }
-/** A route as a file name: `/portal/invoices` is `portal-invoices.json`, `/` is `home.json`. */
-declare const routeFile: (route: string) => string;
 /**
  * Measure the page as it is now and write the result for `craft phone-first`.
  * Waits for web fonts first, so text is measured in the face it is set in.
@@ -182,4 +419,4 @@ declare const routeFile: (route: string) => string;
  */
 declare function measurePhone(page: MinimalPage, options: MeasurePhoneOptions): Promise<MeasuredRoute>;
 
-export { type Baseline, DEFAULT_MEASURED_DIR, EMPTY_BASELINE, type FileException, type Judgement, type MeasurePhoneOptions, type MeasuredRoute, PHONE, PHONE_FLOORS, type PhoneCheck, type PhoneFloors, type RawPhoneFinding, type StaticFinding, checkExceptions, judgeMeasured, judgeStatic, measurePhone, measurePhoneInPage, normaliseElement, reasonOf, routeFile, scanPhoneFirst, writeBaseline };
+export { BANDS, type Band, type Baseline, DEFAULT_MEASURED_DIR, DEFAULT_SWEEP, DEFAULT_THRESHOLDS, EMPTY_BASELINE, type FileException, type InPageGroup, type Judgement, LADDER, type MainAction, type MeasurePhoneOptions, type MeasureSiteOptions, type MeasureViewportsOptions, type MeasuredRoute, PHONE, PHONE_FLOORS, type PhoneCheck, type PhoneFloors, type RawPhoneFinding, SHORT_PHONE, type SiteBrowser, type SitePage, type SiteResult, type StaticFinding, type Sweep, type Thresholds, type Viewport, type ViewportArg, type ViewportPage, type ViewportsResult, WIDE_WIDTHS, bandOf, checkExceptions, formatWidths, judgeMeasured, judgeStatic, mainActionFor, measurePhone, measurePhoneInPage, measureSite, measureViewportInPage, measureViewports, mergeViewportFindings, normaliseElement, reasonOf, routeFile, scanPhoneFirst, sweepWidths, writeBaseline };

package/dist/phone.d.ts

@@ -1,3 +1,9 @@
+interface SourceFile {
+    /** Repo-relative path. The extension decides how the file is read. */
+    path: string;
+    text: string;
+}
+
 /**
  * The in-page half of the phone-first gate.
  *
@@ -18,20 +24,25 @@ interface PhoneFloors {
     fieldFontPx: number;
     textPx: number;
 }
-type PhoneCheck = "scroll" | "target" | "field" | "text" | "title";
+/**
+ * What a measure can find. The first five are the 375px floors (DOM-775); the
+ * rest are the every-viewport and phone-optimisation checks (DOM-787).
+ */
+type PhoneCheck = "scroll" | "target" | "field" | "text" | "title" | "overlap" | "action" | "layers" | "landscape" | "image" | "input" | "autocomplete" | "tel" | "linelength";
 interface RawPhoneFinding {
     check: PhoneCheck;
     /** `<tag> "text"`: what a person looks for on the page. */
     element: string;
     detail: string;
 }
-declare function measurePhoneInPage(floors: PhoneFloors): RawPhoneFinding[];
-
-interface SourceFile {
-    /** Repo-relative path. The extension decides how the file is read. */
-    path: string;
-    text: string;
-}
+/**
+ * `floors.only` narrows the measure to some checks, for the viewports where
+ * only some apply (text at every width, targets and fields at phone widths).
+ * Left out, all five run, as they always did.
+ */
+declare function measurePhoneInPage(floors: PhoneFloors & {
+    only?: PhoneCheck[];
+}): RawPhoneFinding[];
 
 /**
  * The judging half of the phone-first gate: pure text work, tested without a
@@ -68,6 +79,8 @@ interface MeasuredRoute {
         width: number;
         height: number;
     };
+    /** Set by the every-viewport measure: the viewports and widths the findings were gathered across, phone first. */
+    viewports?: string[];
     findings: RawPhoneFinding[];
 }
 interface Baseline {
@@ -117,6 +130,242 @@ declare function judgeMeasured(routes: MeasuredRoute[], baseline: Baseline): Jud
 /** The baseline that makes this run pass: what is there now, counted. */
 declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[], note?: string): Baseline;
 
+/**
+ * What "every viewport" means (STANDARD.md section 10, DOM-787): the ladder
+ * the page is measured at, the five bands it is designed in, the width sweep
+ * between the rungs, and the thresholds the checks judge by. Pure data and
+ * text work, so it is tested without a browser.
+ */
+
+type Band = "phone" | "large-phone" | "tablet" | "laptop" | "wide";
+/** The five bands every page is designed in. A width belongs to exactly one. */
+declare const BANDS: {
+    band: Band;
+    from: number;
+    to: number | null;
+}[];
+declare const bandOf: (width: number) => Band;
+interface Viewport {
+    /** The label a report uses: `375`, or `844x390` for a landscape phone. */
+    name: string;
+    width: number;
+    height: number;
+    /** A phone held either way up: the touch floors (targets, fields) apply. */
+    phone: boolean;
+    landscape?: boolean;
+}
+/**
+ * The ladder, phone first in order and in every report. Heights are the
+ * phones' own; 375 x 812 stays the house phone (`PHONE`), so a baseline made
+ * at 375 means the same thing here.
+ */
+declare const LADDER: Viewport[];
+/** The short phone the first screen is judged on: an iPhone SE, the least height a visitor has. */
+declare const SHORT_PHONE: Viewport;
+/** Widths where body line length and wide-screen image scaling are judged. */
+declare const WIDE_WIDTHS: number[];
+interface Sweep {
+    from: number;
+    to: number;
+    /** Step below `wideFrom`, where layouts change most. */
+    step: number;
+    /** Step from `wideFrom` up. */
+    wideStep: number;
+    wideFrom: number;
+    /** The height every swept width is laid out at. */
+    height: number;
+}
+declare const DEFAULT_SWEEP: Sweep;
+/** 320, 336 ... 1024, 1056 ... 1920. */
+declare function sweepWidths(sweep?: Sweep): number[];
+/** House defaults for the checks. Each can be overridden per site or portal; the defaults are what the standard says. */
+interface Thresholds {
+    /** Fixed and sticky layers together cover at most this share of a short phone's screen. */
+    maxLayerShare: number;
+    /** In landscape, header and fixed layers leave at least this share of the height: they cover at most 1 minus it. */
+    landscapeMaxLayerShare: number;
+    /** An image whose file is more than this many times its displayed width is oversized (at DPR 2 it needs 2; the rest is slack). */
+    oversizeRatio: number;
+    /** An image whose file is narrower than this many times its displayed width is upscaled. */
+    upscaleRatio: number;
+    /** Body text lines at 1440 and 1920 are at most this many characters (`ch` of the computed font). */
+    maxLineCh: number;
+    /** Two pieces of visible text overlap when the overlap is this share of the shorter one's height and at least 3px wide. */
+    overlapShare: number;
+    /** Image files under this displayed width (CSS px) are icons and marks: not judged. */
+    minImagePx: number;
+}
+declare const DEFAULT_THRESHOLDS: Thresholds;
+/** The main action, as a selector: one for the whole site, or one per route (`*` is the fallback). */
+type MainAction = string | Record<string, string>;
+declare const mainActionFor: (config: MainAction | undefined, route: string) => string | undefined;
+/**
+ * Widths as a person reads them: `320-352, 400, 1440`. A run is consecutive
+ * tested widths that all fail. A landscape or short-phone name (`844x390`)
+ * stands alone.
+ */
+declare function formatWidths(failing: string[], tested: string[]): string;
+/**
+ * One finding per element and check across every viewport, so the baseline
+ * counts what is on the page and not how many widths it was seen at. The count
+ * is the most seen at any single viewport; the detail names every viewport it
+ * failed at, as ranges.
+ */
+declare function mergeViewportFindings(perViewport: {
+    viewport: string;
+    findings: RawPhoneFinding[];
+}[], tested: string[]): RawPhoneFinding[];
+
+/**
+ * The in-page half of the every-viewport measure (DOM-787).
+ *
+ * `measureViewportInPage` runs inside the browser through `page.evaluate`, so
+ * like `measurePhoneInPage` it must be self-contained: no imports, nothing
+ * from outside its own body. The caller has set the viewport, waited for the
+ * page to settle and scrolled to the top; the function judges the page as it
+ * stands, for whichever groups of checks it is asked for:
+ *
+ * - `sweep`: at any width, the page does not scroll sideways, no visible text
+ *   sits on other visible text, and no page title is cut off.
+ * - `optimise`: on the short phone (375 x 667), the main action is on the
+ *   first screen or pinned, fixed and sticky layers leave the screen to the
+ *   page, images are sized for the phone, fields use the right keyboard and
+ *   carry autocomplete, and phone numbers in the text dial.
+ * - `landscape`: on a phone held sideways, the header and fixed layers leave
+ *   at least half the height.
+ * - `wide`: at 1440 and above, body text keeps a readable line length and no
+ *   image is stretched past its file.
+ */
+
+type InPageGroup = "sweep" | "optimise" | "landscape" | "wide";
+interface ViewportArg {
+    groups: InPageGroup[];
+    thresholds: Thresholds;
+    /** CSS selector for the page's main action. Absent: the action check is not run. */
+    mainAction?: string;
+    /** Also fail a page with no width=device-width viewport meta, which a phone lays out at 980px. Meaningful at phone widths. */
+    metaViewport?: boolean;
+}
+declare function measureViewportInPage(arg: ViewportArg): RawPhoneFinding[];
+
+/** What the phone measures share: the house phone, the house floors, where results go. */
+
+/**
+ * The phone every surface is designed at (STANDARD.md section 10): 375 x 812,
+ * touch, at 2x. Spread into Playwright's `test.use` or `browser.newContext`.
+ */
+declare const PHONE: {
+    readonly viewport: {
+        readonly width: 375;
+        readonly height: 812;
+    };
+    readonly deviceScaleFactor: 2;
+    readonly isMobile: true;
+    readonly hasTouch: true;
+};
+/** The house floors at phone width. Not per-repo settings. */
+declare const PHONE_FLOORS: PhoneFloors;
+/** Where `measurePhone` writes and `craft phone-first --measured` reads, unless told otherwise. */
+declare const DEFAULT_MEASURED_DIR = "phone-first/measured";
+/** A route as a file name: `/portal/invoices` is `portal-invoices.json`, `/` is `home.json`. */
+declare const routeFile: (route: string) => string;
+
+/**
+ * The runner for the every-viewport measure (DOM-787): drives a page through
+ * the ladder and the width sweep and hands each stop to the in-page checks.
+ *
+ * Two entries:
+ *
+ * - `measureViewports(page, options)` resizes the page it is given, in place.
+ *   A portal's Playwright suite owns the sign-in and the fixture data, so it
+ *   opens the route and calls this.
+ * - `measureSite(browser, options)` opens each route itself, once in a phone
+ *   context (touch, 2x, mobile viewport handling) for everything under 768 and
+ *   once in a desktop context for the rest: what create-site's measure.mjs and
+ *   `craft viewports` use for a page anyone can open.
+ *
+ * Neither imports Playwright: the caller drives the browser.
+ */
+
+interface ViewportPage {
+    evaluate<R, A>(fn: (arg: A) => R, arg: A): Promise<R>;
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+interface MeasureViewportsOptions {
+    /** The route as the baseline names it, without host or query: `/portal/invoices`. */
+    route: string;
+    /** The folder to write `<route>.json` into. Default `phone-first/measured`. `false` writes nothing. */
+    out?: string | false;
+    /**
+     * Which half to run on this page. `all` (default) runs everything on the one
+     * page; `phone` stops below 768 and adds the short phone and landscape;
+     * `wide` runs 768 and up. A page in a desktop browser context has no business
+     * judging a phone, and the other way round: `measureSite` runs each half in
+     * the context it belongs to.
+     */
+    scope?: "all" | "phone" | "wide";
+    /** Override house thresholds. */
+    thresholds?: Partial<Thresholds>;
+    /** Override the 12 / 16 / 44px floors. The defaults are the house standard; a site may set `textPx` higher. */
+    floors?: Partial<PhoneFloors>;
+    /** The main action's selector: one for all routes, or per route with `*` as the fallback. Absent: not checked. */
+    mainAction?: MainAction;
+    /** The width sweep, or `false` to measure the ladder only. */
+    sweep?: Partial<Sweep> | false;
+    /** Replace the ladder. */
+    ladder?: Viewport[];
+    /** Called at each ladder viewport once the page has settled, for captures. */
+    onViewport?: (page: ViewportPage, viewport: Viewport, route: string) => Promise<void>;
+}
+interface ViewportsResult extends MeasuredRoute {
+    viewports: string[];
+    /** What each viewport found before the merge, in the order measured. */
+    perViewport: {
+        viewport: string;
+        findings: RawPhoneFinding[];
+    }[];
+}
+/**
+ * Measure the page the caller has opened at every viewport, resizing it in
+ * place: the ladder, the width sweep, the short phone, landscape and the wide
+ * checks. Writes the merged result for `craft phone-first --measured`. Does
+ * not judge or throw on a finding: the baseline decides.
+ */
+declare function measureViewports(page: ViewportPage, options: MeasureViewportsOptions): Promise<ViewportsResult>;
+interface SitePage extends ViewportPage {
+    goto(url: string): Promise<{
+        ok(): boolean;
+        status(): number | string;
+    } | null>;
+}
+interface SiteBrowser {
+    newContext(options: Record<string, unknown>): Promise<{
+        newPage(): Promise<SitePage>;
+        close(): Promise<void>;
+    }>;
+}
+interface MeasureSiteOptions extends Omit<MeasureViewportsOptions, "route" | "scope"> {
+    /** The running site, without a trailing slash. */
+    base: string;
+    routes: string[];
+}
+interface SiteResult {
+    routes: ViewportsResult[];
+    /** Routes that did not answer, with why. Not measured, and not passed. */
+    errors: {
+        route: string;
+        error: string;
+    }[];
+}
+/**
+ * Open every route on a running site and measure it: the phone half in a
+ * phone context, the wide half in a desktop one, merged per route.
+ */
+declare function measureSite(browser: SiteBrowser, options: MeasureSiteOptions): Promise<SiteResult>;
+
 /**
  * `@domandigital/craft/phone`: the phone-first gate for an app behind a
  * sign-in, such as a client portal (DOM-775).
@@ -140,26 +389,16 @@ declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[
  *       });
  *     }
  *
+ * `measureViewports` (DOM-787) is the same for every viewport: it resizes the
+ * page the suite opened through the ladder and the width sweep, and adds the
+ * phone-optimisation and wide-screen checks. `measureSite` opens a running
+ * site's routes itself, and `craft viewports` is that on the command line.
+ * Both write the same measured files, so `craft phone-first --measured` judges
+ * them against the same baseline.
+ *
  * Nothing here imports Playwright: the page is whatever the caller drives.
  */
 
-/**
- * The phone every surface is designed at (STANDARD.md section 10): 375 x 812,
- * touch, at 2x. Spread into Playwright's `test.use` or `browser.newContext`.
- */
-declare const PHONE: {
-    readonly viewport: {
-        readonly width: 375;
-        readonly height: 812;
-    };
-    readonly deviceScaleFactor: 2;
-    readonly isMobile: true;
-    readonly hasTouch: true;
-};
-/** The house floors at phone width. Not per-repo settings. */
-declare const PHONE_FLOORS: PhoneFloors;
-/** Where `measurePhone` writes and `craft phone-first --measured` reads, unless told otherwise. */
-declare const DEFAULT_MEASURED_DIR = "phone-first/measured";
 interface MinimalPage {
     evaluate<R, A>(fn: (arg: A) => R, arg: A): Promise<R>;
     viewportSize?(): {
@@ -173,8 +412,6 @@ interface MeasurePhoneOptions {
     /** The folder to write `<route>.json` into. Default `phone-first/measured`, from the working directory. */
     out?: string;
 }
-/** A route as a file name: `/portal/invoices` is `portal-invoices.json`, `/` is `home.json`. */
-declare const routeFile: (route: string) => string;
 /**
  * Measure the page as it is now and write the result for `craft phone-first`.
  * Waits for web fonts first, so text is measured in the face it is set in.
@@ -182,4 +419,4 @@ declare const routeFile: (route: string) => string;
  */
 declare function measurePhone(page: MinimalPage, options: MeasurePhoneOptions): Promise<MeasuredRoute>;
 
-export { type Baseline, DEFAULT_MEASURED_DIR, EMPTY_BASELINE, type FileException, type Judgement, type MeasurePhoneOptions, type MeasuredRoute, PHONE, PHONE_FLOORS, type PhoneCheck, type PhoneFloors, type RawPhoneFinding, type StaticFinding, checkExceptions, judgeMeasured, judgeStatic, measurePhone, measurePhoneInPage, normaliseElement, reasonOf, routeFile, scanPhoneFirst, writeBaseline };
+export { BANDS, type Band, type Baseline, DEFAULT_MEASURED_DIR, DEFAULT_SWEEP, DEFAULT_THRESHOLDS, EMPTY_BASELINE, type FileException, type InPageGroup, type Judgement, LADDER, type MainAction, type MeasurePhoneOptions, type MeasureSiteOptions, type MeasureViewportsOptions, type MeasuredRoute, PHONE, PHONE_FLOORS, type PhoneCheck, type PhoneFloors, type RawPhoneFinding, SHORT_PHONE, type SiteBrowser, type SitePage, type SiteResult, type StaticFinding, type Sweep, type Thresholds, type Viewport, type ViewportArg, type ViewportPage, type ViewportsResult, WIDE_WIDTHS, bandOf, checkExceptions, formatWidths, judgeMeasured, judgeStatic, mainActionFor, measurePhone, measurePhoneInPage, measureSite, measureViewportInPage, measureViewports, mergeViewportFindings, normaliseElement, reasonOf, routeFile, scanPhoneFirst, sweepWidths, writeBaseline };