@domandigital/craft 0.19.0 → 0.19.2

package/dist/phone.cjs

@@ -0,0 +1,275 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/phone/index.ts
+var phone_exports = {};
+__export(phone_exports, {
+  DEFAULT_MEASURED_DIR: () => DEFAULT_MEASURED_DIR,
+  EMPTY_BASELINE: () => EMPTY_BASELINE,
+  PHONE: () => PHONE,
+  PHONE_FLOORS: () => PHONE_FLOORS,
+  checkExceptions: () => checkExceptions,
+  judgeMeasured: () => judgeMeasured,
+  judgeStatic: () => judgeStatic,
+  measurePhone: () => measurePhone,
+  measurePhoneInPage: () => measurePhoneInPage,
+  normaliseElement: () => normaliseElement,
+  reasonOf: () => reasonOf,
+  routeFile: () => routeFile,
+  scanPhoneFirst: () => scanPhoneFirst,
+  writeBaseline: () => writeBaseline
+});
+module.exports = __toCommonJS(phone_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/phone/measure-in-page.ts
+function measurePhoneInPage(floors) {
+  const out = [];
+  const vw = document.documentElement.clientWidth;
+  const shown = (e) => {
+    const s = getComputedStyle(e);
+    return s.display !== "none" && s.visibility !== "hidden" && e.getClientRects().length > 0;
+  };
+  const offPage = (e) => {
+    const r = e.getBoundingClientRect();
+    return r.right <= 0 || r.bottom + window.scrollY <= 0 || r.left >= vw;
+  };
+  const quiet = (e) => !!e.closest("[aria-hidden='true'], .sr-only, .visually-hidden, [hidden]") || offPage(e);
+  const describe = (e) => {
+    const text = (e.textContent ?? "").replace(/\s+/g, " ").trim() || e.getAttribute("aria-label") || e.getAttribute("name") || e.getAttribute("placeholder") || "";
+    return `<${e.tagName.toLowerCase()}>${text ? ` "${text.slice(0, 40)}"` : ""}`;
+  };
+  if (vw > window.screen.width + 1) {
+    out.push({ check: "scroll", element: "<meta name=viewport>", detail: `the page lays out at ${vw}px on a ${window.screen.width}px phone: no width=device-width viewport meta` });
+  } else if (document.documentElement.scrollWidth > vw + 1) {
+    const wide = Array.from(document.body.querySelectorAll("*")).filter((e) => shown(e) && e.getBoundingClientRect().right > vw + 1).filter((e, _, all) => !all.some((o) => o !== e && o.contains(e))).slice(0, 3).map(describe);
+    out.push({ check: "scroll", element: "<html>", detail: `the page is ${document.documentElement.scrollWidth}px wide at ${vw}px${wide.length ? `; widest: ${wide.join(", ")}` : ""}` });
+  }
+  const inline = (e) => {
+    if (e.tagName !== "A" || getComputedStyle(e).display !== "inline") return false;
+    const block = e.parentElement?.closest("p, li, dd, td, th, blockquote, figcaption, address");
+    return !!block && (block.textContent ?? "").trim().length > (e.textContent ?? "").trim().length;
+  };
+  const targets = Array.from(document.querySelectorAll("a[href], button, input:not([type='hidden']), select, textarea, [role='button'], [role='tab'], [role='menuitem'], summary")).filter(shown);
+  for (const e of targets) {
+    const r = e.getBoundingClientRect();
+    if (quiet(e) || inline(e) || r.width <= 1 || r.height <= 1) continue;
+    const labels = "labels" in e && e.labels ? Array.from(e.labels).filter(shown) : [];
+    const boxes = [r, ...labels.map((l) => l.getBoundingClientRect())];
+    const w = Math.round(Math.max(...boxes.map((b) => b.width)));
+    const h = Math.round(Math.max(...boxes.map((b) => b.height)));
+    if (w < floors.targetPx || h < floors.targetPx) out.push({ check: "target", element: describe(e), detail: `${w}x${h}px, under ${floors.targetPx}x${floors.targetPx}` });
+  }
+  const NOT_TEXT = /* @__PURE__ */ new Set(["checkbox", "radio", "range", "color", "file", "submit", "reset", "button", "image"]);
+  for (const e of Array.from(document.querySelectorAll("input:not([type='hidden']), select, textarea"))) {
+    if (!shown(e) || quiet(e) || e.tagName === "INPUT" && NOT_TEXT.has(e.type)) continue;
+    const px = parseFloat(getComputedStyle(e).fontSize);
+    if (px < floors.fieldFontPx) out.push({ check: "field", element: describe(e), detail: `set at ${px}px, under ${floors.fieldFontPx}px, so Safari on iOS zooms on focus` });
+  }
+  for (const e of Array.from(document.body.querySelectorAll("*"))) {
+    if (!shown(e) || quiet(e) || ["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE"].includes(e.tagName)) continue;
+    const own = Array.from(e.childNodes).filter((n) => n.nodeType === 3).map((n) => n.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
+    if (!own) continue;
+    const px = parseFloat(getComputedStyle(e).fontSize);
+    if (px < floors.textPx) out.push({ check: "text", element: `<${e.tagName.toLowerCase()}> "${own.slice(0, 40)}"`, detail: `${px}px, under ${floors.textPx}px` });
+  }
+  for (const e of Array.from(document.querySelectorAll("h1"))) {
+    if (!shown(e) || quiet(e)) continue;
+    const s = getComputedStyle(e);
+    const clipsX = e.scrollWidth > e.clientWidth + 1 && s.overflowX !== "visible";
+    const clipsY = e.scrollHeight > e.clientHeight + 1 && s.overflowY !== "visible";
+    if (clipsX || clipsY) out.push({ check: "title", element: describe(e), detail: "the page title is cut off" });
+  }
+  return out;
+}
+
+// src/phone/judge.ts
+var EMPTY_BASELINE = { static: [], measured: [] };
+var MEDIA = /@(?:custom-)?media\b([^{;]*)/g;
+var CAPS_WIDTH = /\bmax-(?:device-)?width\s*:|\bwidth\s*<|>=?\s*(?:device-)?width\b/i;
+var VARIANT = /(?<![\w@-])max-(\[[^\]\s]+\]|[a-z0-9]+):/g;
+var NOT_VARIANTS = /* @__PURE__ */ new Set(["width", "height", "lines", "resolution", "zoom", "inline-size", "block-size"]);
+var OK = /mobile-first-ok\b:?(.*)/;
+function reasonOf(line) {
+  const m = line?.match(OK);
+  return m ? m[1].replace(/\*\/|-->|[{}]/g, "").trim() : null;
+}
+function scanPhoneFirst(files, exceptions = []) {
+  const excusedFiles = new Set(exceptions.filter((e) => e.reason?.trim()).map((e) => e.file));
+  const findings = [];
+  let excused = 0;
+  for (const { path, text } of files) {
+    if (excusedFiles.has(path)) continue;
+    const lines = text.split("\n");
+    const lineOf = (index) => text.slice(0, index).split("\n").length;
+    const found = [];
+    for (const m of text.matchAll(MEDIA)) {
+      if (CAPS_WIDTH.test(m[1])) found.push({ line: lineOf(m.index), what: `${m[0].slice(0, m[0].length - m[1].length)}${m[1].replace(/\s+/g, " ").trimEnd()}` });
+    }
+    for (const m of text.matchAll(VARIANT)) {
+      if (!NOT_VARIANTS.has(m[1])) found.push({ line: lineOf(m.index), what: m[0] });
+    }
+    for (const { line, what } of found.sort((a, b) => a.line - b.line)) {
+      const here = reasonOf(lines[line - 1]);
+      const above = reasonOf(lines[line - 2]);
+      if (here || above) {
+        excused++;
+        continue;
+      }
+      findings.push({ file: path, line, what: here === "" || above === "" ? `${what} (mobile-first-ok with no reason)` : what });
+    }
+  }
+  return { findings, excused };
+}
+function checkExceptions(exceptions, exists) {
+  const problems = [];
+  exceptions.forEach((e, i) => {
+    const at = `exceptions[${i}]`;
+    const x = e;
+    if (typeof x?.file !== "string" || !x.file.trim()) problems.push(`${at}: names no file`);
+    else if (typeof x.reason !== "string" || !x.reason.trim()) problems.push(`${at} (${x.file}): no reason. Say why this file needs a max-width query, or remove the exception.`);
+    else if (!exists(x.file)) problems.push(`${at}: ${x.file} is not there. Remove the exception.`);
+  });
+  return problems;
+}
+var normaliseElement = (element) => element.replace(/\d+/g, "#");
+var tally = (items, key) => {
+  const m = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const k = key(item);
+    const had = m.get(k);
+    if (had) had.count++;
+    else m.set(k, { item, count: 1 });
+  }
+  return m;
+};
+function judgeStatic(findings, baseline) {
+  const byFile = tally(findings, (f) => f.file);
+  const allowed = new Map(baseline.static.map((b) => [b.file, b.count]));
+  const fresh = [];
+  const stale = [];
+  let known = 0;
+  for (const [file, { count }] of byFile) {
+    const allow = allowed.get(file) ?? 0;
+    known += Math.min(count, allow);
+    if (count > allow) {
+      const here = findings.filter((f) => f.file === file);
+      const lead = allow ? `${file}: ${count} desktop-first rules, the baseline allows ${allow}. One of these is new:` : `${file}:`;
+      fresh.push(`${lead}
+${here.map((f) => `    line ${f.line}: ${f.what}`).join("\n")}`);
+    }
+  }
+  for (const { file, count } of baseline.static) {
+    const now = byFile.get(file)?.count ?? 0;
+    if (now < count) stale.push(`${file}: the baseline allows ${count}, there ${now === 1 ? "is" : "are"} ${now} now. Lower it to ${now}${now ? "" : " (remove the line)"}.`);
+  }
+  return { fresh, stale, known };
+}
+var measuredKey = (route, check, element) => `${route}\0${check}\0${element}`;
+function judgeMeasured(routes, baseline) {
+  const fresh = [];
+  const stale = [];
+  let known = 0;
+  const allowed = new Map(baseline.measured.map((b) => [measuredKey(b.route, b.check, b.element), b.count]));
+  const seen = /* @__PURE__ */ new Map();
+  const measured = new Set(routes.map((r) => r.route));
+  for (const { route, findings } of routes) {
+    const counted = tally(findings, (f) => measuredKey(route, f.check, normaliseElement(f.element)));
+    for (const [key, { item, count }] of counted) {
+      seen.set(key, count);
+      const allow = allowed.get(key) ?? 0;
+      known += Math.min(count, allow);
+      if (count > allow) {
+        const times = count - allow > 1 ? ` (${count - allow} more than the baseline's ${allow})` : allow ? ` (the baseline allows ${allow})` : "";
+        fresh.push(`${route}: ${LABEL[item.check]} ${item.element}: ${item.detail}${times}`);
+      }
+    }
+  }
+  const missing = /* @__PURE__ */ new Set();
+  for (const b of baseline.measured) {
+    const key = measuredKey(b.route, b.check, b.element);
+    if (!measured.has(b.route)) {
+      if (!missing.has(b.route)) stale.push(`${b.route}: in the baseline but not measured this run. Measure it, or remove its lines.`);
+      missing.add(b.route);
+      continue;
+    }
+    const now = seen.get(key) ?? 0;
+    if (now < b.count) stale.push(`${b.route}: ${LABEL[b.check]} ${b.element}: the baseline allows ${b.count}, ${now} found. Lower it to ${now}${now ? "" : " (remove the line)"}.`);
+  }
+  return { fresh, stale, known };
+}
+var LABEL = {
+  scroll: "scrolls sideways",
+  target: "small target",
+  field: "small field",
+  text: "small text",
+  title: "title cut off"
+};
+function writeBaseline(findings, routes, note) {
+  const byFile = tally(findings, (f) => f.file);
+  const measured = routes.flatMap(
+    ({ route, findings: findings2 }) => [...tally(findings2, (f) => measuredKey(route, f.check, normaliseElement(f.element))).values()].map(({ item, count }) => ({ route, check: item.check, element: normaliseElement(item.element), count }))
+  );
+  return {
+    ...note ? { note } : {},
+    static: [...byFile.values()].map(({ item, count }) => ({ file: item.file, count, found: findings.filter((f) => f.file === item.file).map((f) => f.what) })).sort((a, b) => a.file.localeCompare(b.file)),
+    measured: measured.sort((a, b) => a.route.localeCompare(b.route) || a.check.localeCompare(b.check) || a.element.localeCompare(b.element))
+  };
+}
+
+// src/phone/index.ts
+var PHONE = {
+  viewport: { width: 375, height: 812 },
+  deviceScaleFactor: 2,
+  isMobile: true,
+  hasTouch: true
+};
+var PHONE_FLOORS = { targetPx: 44, fieldFontPx: 16, textPx: 12 };
+var DEFAULT_MEASURED_DIR = "phone-first/measured";
+var routeFile = (route) => `${route === "/" ? "home" : route.replace(/^\/+|\/+$/g, "").replace(/[^\w.-]+/g, "-")}.json`;
+async function measurePhone(page, options) {
+  if (!options.route.startsWith("/")) throw new Error(`measurePhone: route "${options.route}" should start with /`);
+  await page.evaluate(() => document.fonts?.ready.then(() => void 0), void 0);
+  const findings = await page.evaluate(measurePhoneInPage, PHONE_FLOORS);
+  const viewport = page.viewportSize?.() ?? void 0;
+  const result = { route: options.route, ...viewport ? { viewport } : {}, findings };
+  const dir = options.out ?? DEFAULT_MEASURED_DIR;
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  (0, import_node_fs.writeFileSync)((0, import_node_path.join)(dir, routeFile(options.route)), `${JSON.stringify(result, null, 1)}
+`);
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_MEASURED_DIR,
+  EMPTY_BASELINE,
+  PHONE,
+  PHONE_FLOORS,
+  checkExceptions,
+  judgeMeasured,
+  judgeStatic,
+  measurePhone,
+  measurePhoneInPage,
+  normaliseElement,
+  reasonOf,
+  routeFile,
+  scanPhoneFirst,
+  writeBaseline
+});

package/dist/phone.d.cts

@@ -0,0 +1,185 @@
+/**
+ * The in-page half of the phone-first gate.
+ *
+ * `measurePhoneInPage` runs inside the browser through `page.evaluate`, so it
+ * must be self-contained: no imports, no references to anything outside its
+ * own body. It measures the page as it stands at whatever viewport the
+ * browser has; the caller sets 375 x 812 (`PHONE` in ./index.ts).
+ *
+ * The floors are STANDARD.md section 10 and portal standard rule 10: nothing
+ * scrolls sideways, every target a thumb has to hit is at least 44 x 44 CSS
+ * px, every text field is set at 16px or more so Safari on iOS does not zoom
+ * on focus, no visible text is under 12px, and no page title is cut off.
+ * Lifted from create-site's measure.mjs (DOM-774) so a site and a portal are
+ * measured the same way.
+ */
+interface PhoneFloors {
+    targetPx: number;
+    fieldFontPx: number;
+    textPx: number;
+}
+type PhoneCheck = "scroll" | "target" | "field" | "text" | "title";
+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;
+}
+
+/**
+ * The judging half of the phone-first gate: pure text work, tested without a
+ * browser or a disk.
+ *
+ * Two kinds of breach, one baseline:
+ *
+ * - **Static.** A `max-width` media query (`max-width:`, or the range syntax
+ *   `width <`, `width <=`, `600px > width`) or a Tailwind `max-*` variant
+ *   (`max-sm:`, `max-[40rem]:`) in source. Base styles are the phone; wider
+ *   layouts are added with `min-width`. The same patterns as create-site's
+ *   mobile-first.mjs (DOM-774).
+ * - **Measured.** What `measurePhone` found on a rendered route at 375px.
+ *
+ * A repo that already breaks the rule records what it breaks in a baseline,
+ * counted per file and per route, so the gate blocks every new breach from
+ * the day it goes in while the existing ones stay listed in the open. The
+ * baseline only shrinks: a count higher than what is found fails as well
+ * ("lower the baseline"), so a fix cannot leave room for the next breach.
+ */
+
+interface StaticFinding {
+    file: string;
+    line: number;
+    what: string;
+}
+interface FileException {
+    file: string;
+    reason: string;
+}
+interface MeasuredRoute {
+    route: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    findings: RawPhoneFinding[];
+}
+interface Baseline {
+    /** Why the baseline exists and which issue burns it down. Free text, for a person. */
+    note?: string;
+    static: {
+        file: string;
+        count: number;
+        found?: string[];
+    }[];
+    measured: {
+        route: string;
+        check: PhoneCheck;
+        element: string;
+        count: number;
+    }[];
+}
+declare const EMPTY_BASELINE: Baseline;
+/** The reason in a `mobile-first-ok: <reason>` comment, "" for the marker with no reason, null for none. */
+declare function reasonOf(line: string | undefined): string | null;
+/**
+ * Every desktop-first rule in the files that is not excused. An excuse is
+ * `mobile-first-ok: <reason>` on the line or the line above, or the whole file
+ * in `exceptions` with a reason. A marker with no reason is itself a finding.
+ */
+declare function scanPhoneFirst(files: SourceFile[], exceptions?: FileException[]): {
+    findings: StaticFinding[];
+    excused: number;
+};
+/** Problems with the exceptions themselves: no file, no reason, or a file that is not there. */
+declare function checkExceptions(exceptions: unknown[], exists: (file: string) => boolean): string[];
+/**
+ * Digits become `#`, so a date or an amount in fixture data does not make the
+ * same button a different one.
+ */
+declare const normaliseElement: (element: string) => string;
+interface Judgement {
+    /** Breaches the baseline does not cover: the gate fails on these. */
+    fresh: string[];
+    /** Baseline lines that claim more than is there now: the gate fails on these too, so the baseline only shrinks. */
+    stale: string[];
+    /** How many breaches the baseline covers. Printed every run, so the debt stays in sight. */
+    known: number;
+}
+declare function judgeStatic(findings: StaticFinding[], baseline: Baseline): Judgement;
+declare function judgeMeasured(routes: MeasuredRoute[], baseline: Baseline): Judgement;
+/** The baseline that makes this run pass: what is there now, counted. */
+declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[], note?: string): Baseline;
+
+/**
+ * `@domandigital/craft/phone`: the phone-first gate for an app behind a
+ * sign-in, such as a client portal (DOM-775).
+ *
+ * A site is measured by create-site's measure.mjs, which can open any page.
+ * A portal's pages need a signed-in user and fixture data, which only the
+ * portal's own Playwright suite knows how to set up. So the portal's suite
+ * opens each key route at `PHONE` and calls `measurePhone`, which measures
+ * the page and writes what it found; `craft phone-first --measured <dir>`
+ * then judges every route against the repo's baseline in one place, with the
+ * static check for max-width rules.
+ *
+ *     import { test } from "@playwright/test";
+ *     import { PHONE, measurePhone } from "@domandigital/craft/phone";
+ *
+ *     test.use(PHONE);
+ *     for (const route of ["/portal", "/portal/invoices"]) {
+ *       test(`phone first: ${route}`, async ({ page }) => {
+ *         await page.goto(route);
+ *         await measurePhone(page, { route });
+ *       });
+ *     }
+ *
+ * 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?(): {
+        width: number;
+        height: number;
+    } | null;
+}
+interface MeasurePhoneOptions {
+    /** 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`, 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.
+ * Does not judge or throw on a finding: the baseline decides.
+ */
+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 };

package/dist/phone.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The in-page half of the phone-first gate.
+ *
+ * `measurePhoneInPage` runs inside the browser through `page.evaluate`, so it
+ * must be self-contained: no imports, no references to anything outside its
+ * own body. It measures the page as it stands at whatever viewport the
+ * browser has; the caller sets 375 x 812 (`PHONE` in ./index.ts).
+ *
+ * The floors are STANDARD.md section 10 and portal standard rule 10: nothing
+ * scrolls sideways, every target a thumb has to hit is at least 44 x 44 CSS
+ * px, every text field is set at 16px or more so Safari on iOS does not zoom
+ * on focus, no visible text is under 12px, and no page title is cut off.
+ * Lifted from create-site's measure.mjs (DOM-774) so a site and a portal are
+ * measured the same way.
+ */
+interface PhoneFloors {
+    targetPx: number;
+    fieldFontPx: number;
+    textPx: number;
+}
+type PhoneCheck = "scroll" | "target" | "field" | "text" | "title";
+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;
+}
+
+/**
+ * The judging half of the phone-first gate: pure text work, tested without a
+ * browser or a disk.
+ *
+ * Two kinds of breach, one baseline:
+ *
+ * - **Static.** A `max-width` media query (`max-width:`, or the range syntax
+ *   `width <`, `width <=`, `600px > width`) or a Tailwind `max-*` variant
+ *   (`max-sm:`, `max-[40rem]:`) in source. Base styles are the phone; wider
+ *   layouts are added with `min-width`. The same patterns as create-site's
+ *   mobile-first.mjs (DOM-774).
+ * - **Measured.** What `measurePhone` found on a rendered route at 375px.
+ *
+ * A repo that already breaks the rule records what it breaks in a baseline,
+ * counted per file and per route, so the gate blocks every new breach from
+ * the day it goes in while the existing ones stay listed in the open. The
+ * baseline only shrinks: a count higher than what is found fails as well
+ * ("lower the baseline"), so a fix cannot leave room for the next breach.
+ */
+
+interface StaticFinding {
+    file: string;
+    line: number;
+    what: string;
+}
+interface FileException {
+    file: string;
+    reason: string;
+}
+interface MeasuredRoute {
+    route: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    findings: RawPhoneFinding[];
+}
+interface Baseline {
+    /** Why the baseline exists and which issue burns it down. Free text, for a person. */
+    note?: string;
+    static: {
+        file: string;
+        count: number;
+        found?: string[];
+    }[];
+    measured: {
+        route: string;
+        check: PhoneCheck;
+        element: string;
+        count: number;
+    }[];
+}
+declare const EMPTY_BASELINE: Baseline;
+/** The reason in a `mobile-first-ok: <reason>` comment, "" for the marker with no reason, null for none. */
+declare function reasonOf(line: string | undefined): string | null;
+/**
+ * Every desktop-first rule in the files that is not excused. An excuse is
+ * `mobile-first-ok: <reason>` on the line or the line above, or the whole file
+ * in `exceptions` with a reason. A marker with no reason is itself a finding.
+ */
+declare function scanPhoneFirst(files: SourceFile[], exceptions?: FileException[]): {
+    findings: StaticFinding[];
+    excused: number;
+};
+/** Problems with the exceptions themselves: no file, no reason, or a file that is not there. */
+declare function checkExceptions(exceptions: unknown[], exists: (file: string) => boolean): string[];
+/**
+ * Digits become `#`, so a date or an amount in fixture data does not make the
+ * same button a different one.
+ */
+declare const normaliseElement: (element: string) => string;
+interface Judgement {
+    /** Breaches the baseline does not cover: the gate fails on these. */
+    fresh: string[];
+    /** Baseline lines that claim more than is there now: the gate fails on these too, so the baseline only shrinks. */
+    stale: string[];
+    /** How many breaches the baseline covers. Printed every run, so the debt stays in sight. */
+    known: number;
+}
+declare function judgeStatic(findings: StaticFinding[], baseline: Baseline): Judgement;
+declare function judgeMeasured(routes: MeasuredRoute[], baseline: Baseline): Judgement;
+/** The baseline that makes this run pass: what is there now, counted. */
+declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[], note?: string): Baseline;
+
+/**
+ * `@domandigital/craft/phone`: the phone-first gate for an app behind a
+ * sign-in, such as a client portal (DOM-775).
+ *
+ * A site is measured by create-site's measure.mjs, which can open any page.
+ * A portal's pages need a signed-in user and fixture data, which only the
+ * portal's own Playwright suite knows how to set up. So the portal's suite
+ * opens each key route at `PHONE` and calls `measurePhone`, which measures
+ * the page and writes what it found; `craft phone-first --measured <dir>`
+ * then judges every route against the repo's baseline in one place, with the
+ * static check for max-width rules.
+ *
+ *     import { test } from "@playwright/test";
+ *     import { PHONE, measurePhone } from "@domandigital/craft/phone";
+ *
+ *     test.use(PHONE);
+ *     for (const route of ["/portal", "/portal/invoices"]) {
+ *       test(`phone first: ${route}`, async ({ page }) => {
+ *         await page.goto(route);
+ *         await measurePhone(page, { route });
+ *       });
+ *     }
+ *
+ * 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?(): {
+        width: number;
+        height: number;
+    } | null;
+}
+interface MeasurePhoneOptions {
+    /** 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`, 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.
+ * Does not judge or throw on a finding: the baseline decides.
+ */
+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 };