@domandigital/craft 0.20.5 → 0.22.0

package/dist/phone.cjs

@@ -33,8 +33,15 @@ __export(phone_exports, {
   WIDE_WIDTHS: () => WIDE_WIDTHS,
   bandOf: () => bandOf,
   checkExceptions: () => checkExceptions,
+  checkScreenBudgets: () => checkScreenBudgets,
+  cleanRoute: () => cleanRoute,
+  formatScreens: () => formatScreens,
   formatWidths: () => formatWidths,
+  hasReason: () => hasReason,
+  hasUnexcusedEntries: () => hasUnexcusedEntries,
+  judgeGrowth: () => judgeGrowth,
   judgeMeasured: () => judgeMeasured,
+  judgeRoutes: () => judgeRoutes,
   judgeStatic: () => judgeStatic,
   mainActionFor: () => mainActionFor,
   measurePhone: () => measurePhone,
@@ -45,9 +52,14 @@ __export(phone_exports, {
   measureViewports: () => measureViewports,
   mergeViewportFindings: () => mergeViewportFindings,
   normaliseElement: () => normaliseElement,
+  parseBaseline: () => parseBaseline,
   reasonOf: () => reasonOf,
   routeFile: () => routeFile,
+  routeMatches: () => routeMatches,
+  routesFromManifest: () => routesFromManifest,
+  routesFromPages: () => routesFromPages,
   scanPhoneFirst: () => scanPhoneFirst,
+  screenBudgetFor: () => screenBudgetFor,
   sweepWidths: () => sweepWidths,
   writeBaseline: () => writeBaseline
 });
@@ -62,13 +74,14 @@ var PHONE = {
   isMobile: true,
   hasTouch: true
 };
-var PHONE_FLOORS = { targetPx: 44, fieldFontPx: 16, textPx: 12 };
+var PHONE_FLOORS = { targetPx: 44, fieldFontPx: 16, textPx: 12, fieldHeightPx: 48 };
 var DEFAULT_MEASURED_DIR = "phone-first/measured";
 var routeFile = (route) => `${route === "/" ? "home" : route.replace(/^\/+|\/+$/g, "").replace(/[^\w.-]+/g, "-")}.json`;
 
 // src/phone/measure-in-page.ts
 function measurePhoneInPage(floors) {
   const out = [];
+  const fieldHeightPx = floors.fieldHeightPx ?? 48;
   const only = floors.only;
   const on = (c) => !only || only.includes(c);
   const vw = document.documentElement.clientWidth;
@@ -112,6 +125,9 @@ function measurePhoneInPage(floors) {
     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` });
+    const box = e.getBoundingClientRect();
+    const height = Math.round(box.height);
+    if (box.width > 1 && height > 1 && height < fieldHeightPx) out.push({ check: "field", element: describe(e), detail: `${height}px tall, under ${fieldHeightPx}px (use min-h-12)` });
   }
   for (const e of on("text") ? Array.from(document.body.querySelectorAll("*")) : []) {
     if (!shown(e) || quiet(e) || ["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE"].includes(e.tagName)) continue;
@@ -419,17 +435,26 @@ function measureViewportInPage(arg) {
 }
 
 // src/phone/judge.ts
+var hasReason = (entry) => typeof entry.reason === "string" && entry.reason.trim() !== "";
+function parseBaseline(raw, where) {
+  const b = raw ?? {};
+  const entries = [...b.static ?? [], ...b.measured ?? []];
+  const bad = entries.find((e) => e.reason !== void 0 && typeof e.reason !== "string");
+  if (bad) throw new Error(`${where}: an entry has a "reason" that is not text: ${JSON.stringify(bad)}`);
+  return { ...b.note ? { note: b.note } : {}, static: b.static ?? [], measured: b.measured ?? [] };
+}
 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:?(.*)/;
+var VAR_OPACITY = /[^\s"'`]*var\([^)]*\)\]\/[0-9]+/g;
 function reasonOf(line) {
   const m = line?.match(OK);
   return m ? m[1].replace(/\*\/|-->|[{}]/g, "").trim() : null;
 }
-function scanPhoneFirst(files, exceptions = []) {
+function scanPhoneFirst(files, exceptions = [], options = {}) {
   const excusedFiles = new Set(exceptions.filter((e) => e.reason?.trim()).map((e) => e.file));
   const findings = [];
   let excused = 0;
@@ -444,7 +469,18 @@ function scanPhoneFirst(files, exceptions = []) {
     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 silent = /* @__PURE__ */ new Set();
+    if (options.tailwind3?.(path)) {
+      for (const m of text.matchAll(VAR_OPACITY)) {
+        silent.add(found.push({ line: lineOf(m.index), what: `${m[0]} (Tailwind 3 emits no CSS for opacity on a var() colour)` }) - 1);
+      }
+    }
+    const order = found.map((f, i) => ({ ...f, silent: silent.has(i) })).sort((a, b) => a.line - b.line);
+    for (const { line, what, silent: cannotExcuse } of order) {
+      if (cannotExcuse) {
+        findings.push({ file: path, line, what });
+        continue;
+      }
       const here = reasonOf(lines[line - 1]);
       const above = reasonOf(lines[line - 2]);
       if (here || above) {
@@ -547,19 +583,104 @@ var LABEL = {
   input: "wrong keyboard",
   autocomplete: "field the phone cannot fill in",
   tel: "phone number is not a link",
-  linelength: "line too long"
+  linelength: "line too long",
+  screens: "page too long for a phone"
 };
-function writeBaseline(findings, routes, note) {
+function writeBaseline(findings, routes, note, previous) {
   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 }))
   );
+  const staticReasons = new Map((previous?.static ?? []).filter(hasReason).map((b) => [b.file, b.reason]));
+  const measuredReasons = new Map((previous?.measured ?? []).filter(hasReason).map((b) => [measuredKey(b.route, b.check, b.element), b.reason]));
   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))
+    static: [...byFile.values()].map(({ item, count }) => ({ file: item.file, count, found: findings.filter((f) => f.file === item.file).map((f) => f.what), ...staticReasons.has(item.file) ? { reason: staticReasons.get(item.file) } : {} })).sort((a, b) => a.file.localeCompare(b.file)),
+    measured: measured.map((m) => measuredReasons.has(measuredKey(m.route, m.check, m.element)) ? { ...m, reason: measuredReasons.get(measuredKey(m.route, m.check, m.element)) } : m).sort((a, b) => a.route.localeCompare(b.route) || a.check.localeCompare(b.check) || a.element.localeCompare(b.element))
   };
 }
+function judgeGrowth(current, base, baseName = "main") {
+  const out = [];
+  const baseStatic = new Map(base.static.map((b) => [b.file, b.count]));
+  for (const b of current.static) {
+    const was = baseStatic.get(b.file) ?? 0;
+    if (b.count > was && !hasReason(b)) out.push(`${b.file}: ${was ? `${b.count} desktop-first rules, ${baseName} allows ${was}` : `${b.count} desktop-first rule${b.count === 1 ? "" : "s"} added to the baseline`}`);
+  }
+  const baseMeasured = new Map(base.measured.map((b) => [measuredKey(b.route, b.check, b.element), b.count]));
+  for (const b of current.measured) {
+    const was = baseMeasured.get(measuredKey(b.route, b.check, b.element)) ?? 0;
+    if (b.count > was && !hasReason(b)) out.push(`${b.route}: ${LABEL[b.check]} ${b.element}: ${was ? `${b.count} in the baseline, ${baseName} allows ${was}` : `added to the baseline (${b.count})`}`);
+  }
+  return out;
+}
+var hasUnexcusedEntries = (b) => [...b.static, ...b.measured].some((e) => !hasReason(e));
+var PAGE_FILE = /(?:^|\/)page\.(?:tsx|ts|jsx|js|mdx)$/;
+var INTERCEPTING = /^\(\.{1,3}\)/;
+function routesFromPages(files) {
+  const routes = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const rel = file.replace(/\\/g, "/");
+    if (!PAGE_FILE.test(rel)) continue;
+    const dirs = rel.split("/").slice(0, -1);
+    if (dirs.some((d) => INTERCEPTING.test(d) || d.startsWith("_"))) continue;
+    const url = dirs.filter((d) => !/^\(.*\)$/.test(d) && !d.startsWith("@"));
+    routes.add(`/${url.join("/")}`);
+  }
+  return [...routes].sort();
+}
+function routesFromManifest(manifest) {
+  const routes = /* @__PURE__ */ new Set();
+  for (const [key, route] of Object.entries(manifest ?? {})) {
+    if (!/(?:^|\/)page$/.test(key) || typeof route !== "string") continue;
+    if (route.split("/").some((d) => d.startsWith("_"))) continue;
+    routes.add(route);
+  }
+  return [...routes].sort();
+}
+var segmentsOf = (route) => route.split("/").filter(Boolean);
+var rank = (seg) => seg.startsWith("[[...") ? 3 : seg.startsWith("[...") ? 2 : seg.startsWith("[") ? 1 : 0;
+var cleanRoute = (route) => {
+  const path = route.replace(/[?#].*$/, "").replace(/\/+$/, "");
+  return path === "" ? "/" : path;
+};
+function routeMatches(pattern, route) {
+  if (pattern === route) return true;
+  const want = segmentsOf(pattern);
+  const have = segmentsOf(route);
+  for (let i = 0; i < want.length; i++) {
+    const seg = want[i];
+    if (seg.startsWith("[[...")) return true;
+    if (seg.startsWith("[...")) return have.length > i;
+    if (have[i] === void 0) return false;
+    if (!seg.startsWith("[") && seg !== have[i]) return false;
+  }
+  return want.length === have.length;
+}
+var moreSpecific = (a, b) => {
+  const x = segmentsOf(a).map(rank);
+  const y = segmentsOf(b).map(rank);
+  for (let i = 0; i < Math.min(x.length, y.length); i++) if (x[i] !== y[i]) return x[i] < y[i];
+  return x.length > y.length;
+};
+var excludes = (entry, page) => entry.endsWith("/*") ? page === entry.slice(0, -2) || page.startsWith(entry.slice(0, -1)) : entry === page;
+function judgeRoutes(pages, measuredRoutes, excluded = []) {
+  const problems = [];
+  excluded.forEach((e, i) => {
+    const at = `excludeRoutes[${i}]`;
+    const x = e;
+    if (typeof x?.route !== "string" || !x.route.startsWith("/")) problems.push(`${at}: names no route (start it with /)`);
+    else if (typeof x.reason !== "string" || !x.reason.trim()) problems.push(`${at} (${x.route}): no reason. Say why the gate cannot measure this page, or remove the entry.`);
+    else if (!pages.some((p) => excludes(x.route, p))) problems.push(`${at}: ${x.route} is not a page route of the app. Remove the entry.`);
+  });
+  const named = excluded.filter((e) => typeof e?.route === "string" && typeof e.reason === "string" && e.reason.trim());
+  const covered = /* @__PURE__ */ new Set();
+  for (const route of measuredRoutes.map(cleanRoute)) {
+    const hit = pages.filter((p) => routeMatches(p, route)).sort((a, b) => moreSpecific(a, b) ? -1 : moreSpecific(b, a) ? 1 : 0)[0];
+    if (hit) covered.add(hit);
+  }
+  for (const page of pages) if (named.some((e) => excludes(e.route, page))) covered.add(page);
+  return { missing: pages.filter((p) => !covered.has(p)), problems, covered: covered.size };
+}
 
 // src/phone/viewports.ts
 var BANDS = [
@@ -601,18 +722,44 @@ var DEFAULT_THRESHOLDS = {
   minImagePx: 32
 };
 var mainActionFor = (config, route) => typeof config === "string" ? config : config ? config[route] ?? config["*"] : void 0;
+function screenBudgetFor(budgets, route) {
+  if (!budgets) return void 0;
+  const path = cleanRoute(route);
+  let best;
+  for (const key of Object.keys(budgets)) {
+    const prefix = key.endsWith("/*") ? key.slice(0, -1) : null;
+    const hit = key === "*" ? 0 : prefix ? path === key.slice(0, -2) || path.startsWith(prefix) ? 1 + prefix.length : -1 : routeMatches(key, path) ? key === path ? 1e4 : 5e3 + key.length : -1;
+    if (hit >= 0 && (!best || hit > best.score)) best = { key, score: hit };
+  }
+  return best ? budgets[best.key] : void 0;
+}
+function checkScreenBudgets(budgets, where = "screens") {
+  if (budgets === void 0) return void 0;
+  if (!budgets || typeof budgets !== "object" || Array.isArray(budgets)) throw new Error(`${where} should map a route to its budget in phone screens, such as { "/": 6.5, "/services/*": 6 }`);
+  for (const [route, value] of Object.entries(budgets)) {
+    if (route !== "*" && !route.startsWith("/")) throw new Error(`${where}: "${route}" should start with / (or be *)`);
+    if (typeof value !== "number" || !(value > 0)) throw new Error(`${where}: "${route}" should be a number of phone screens above 0, not ${JSON.stringify(value)}`);
+  }
+  return budgets;
+}
+function formatScreens(routes, budgets) {
+  return routes.filter((r) => r.screens !== void 0).map((r) => {
+    const budget = screenBudgetFor(budgets, r.route);
+    return `${r.route} ${r.screens}${budget === void 0 ? "" : ` of ${budget}`}`;
+  }).join(", ");
+}
 function formatWidths(failing, tested) {
   const plain = tested.filter((n) => /^\d+$/.test(n)).sort((a, b) => Number(a) - Number(b));
-  const rank = new Map(plain.map((name, i) => [name, i]));
+  const rank2 = new Map(plain.map((name, i) => [name, i]));
   const names = [...new Set(failing)];
   const runs = [];
-  for (const name of names.filter((n) => rank.has(n)).sort((a, b) => rank.get(a) - rank.get(b))) {
+  for (const name of names.filter((n) => rank2.has(n)).sort((a, b) => rank2.get(a) - rank2.get(b))) {
     const last = runs.at(-1);
-    if (last && rank.get(name) === rank.get(last.at(-1)) + 1) last.push(name);
+    if (last && rank2.get(name) === rank2.get(last.at(-1)) + 1) last.push(name);
     else runs.push([name]);
   }
   const out = runs.map((r) => r.length > 1 ? `${r[0]}-${r.at(-1)}` : r[0]);
-  return [...out, ...names.filter((n) => !rank.has(n))].join(", ");
+  return [...out, ...names.filter((n) => !rank2.has(n))].join(", ");
 }
 var keyOf = (f) => `${f.check}\0${f.element.replace(/("[^]*)$/, (t) => t.replace(/\d+/g, "#"))}`;
 function mergeViewportFindings(perViewport, tested) {
@@ -697,6 +844,7 @@ async function collect(page, options) {
   const mainAction = mainActionFor(options.mainAction, options.route);
   const perViewport = [];
   const tested = [];
+  let screens;
   for (const stop of plan(options)) {
     await page.setViewportSize({ width: stop.width, height: stop.height });
     await settle(page, stop.ladder ? 150 : 60);
@@ -705,20 +853,36 @@ async function collect(page, options) {
     const findings = [];
     if (stop.ladder) findings.push(...await page.evaluate(measurePhoneInPage, { ...floors, only: stop.touch ? ["target", "field", "text"] : ["text"] }));
     findings.push(...await page.evaluate(measureViewportInPage, { groups: stop.groups, thresholds, mainAction, metaViewport: stop.width < 768 }));
+    if (stop.name === SHORT_PHONE.name) {
+      const height = await page.evaluate(() => document.documentElement.scrollHeight, void 0);
+      screens = Math.round(height / stop.height * 10) / 10;
+      const budget = screenBudgetFor(options.screens, options.route);
+      if (budget !== void 0 && screens > budget) findings.push({ check: "screens", element: "<page>", detail: `${screens} phone screens to the footer at ${stop.width} x ${stop.height}, over the budget of ${budget} for ${options.route}` });
+    }
     perViewport.push({ viewport: stop.name, findings });
     tested.push(stop.name);
   }
-  return { perViewport, tested };
+  return { perViewport, tested, ...screens !== void 0 ? { screens } : {} };
+}
+function mergeCollected(collected) {
+  const screens = collected.find((c) => c.screens !== void 0)?.screens;
+  return { perViewport: collected.flatMap((c) => c.perViewport), tested: collected.flatMap((c) => c.tested), ...screens !== void 0 ? { screens } : {} };
 }
 function finish(route, collected, out) {
-  const result = { route, viewports: collected.tested, findings: mergeViewportFindings(collected.perViewport, collected.tested), perViewport: collected.perViewport };
+  const result = {
+    route,
+    viewports: collected.tested,
+    ...collected.screens !== void 0 ? { screens: collected.screens } : {},
+    findings: mergeViewportFindings(collected.perViewport, collected.tested),
+    perViewport: collected.perViewport
+  };
   if (out !== false) writeMeasured(result, out ?? DEFAULT_MEASURED_DIR);
   return result;
 }
 function writeMeasured(result, dir) {
   (0, import_node_fs.mkdirSync)(dir, { recursive: true });
-  const { route, viewport, viewports, findings } = result;
-  (0, import_node_fs.writeFileSync)((0, import_node_path.join)(dir, routeFile(route)), `${JSON.stringify({ route, ...viewport ? { viewport } : {}, ...viewports ? { viewports } : {}, findings }, null, 1)}
+  const { route, viewport, viewports, screens, findings } = result;
+  (0, import_node_fs.writeFileSync)((0, import_node_path.join)(dir, routeFile(route)), `${JSON.stringify({ route, ...viewport ? { viewport } : {}, ...viewports ? { viewports } : {}, ...screens !== void 0 ? { screens } : {}, findings }, null, 1)}
 `);
 }
 async function measureViewports(page, options) {
@@ -739,7 +903,7 @@ async function measureRoute(open, options) {
       await close?.();
     }
   }
-  return finish(options.route, { perViewport: collected.flatMap((c) => c.perViewport), tested: collected.flatMap((c) => c.tested) }, options.out);
+  return finish(options.route, mergeCollected(collected), options.out);
 }
 async function measureSite(browser, options) {
   const result = { routes: [], errors: [] };
@@ -768,7 +932,7 @@ async function measureSite(browser, options) {
       result.errors.push({ route, error: failed });
       continue;
     }
-    result.routes.push(finish(route, { perViewport: collected.flatMap((c) => c.perViewport), tested: collected.flatMap((c) => c.tested) }, options.out));
+    result.routes.push(finish(route, mergeCollected(collected), options.out));
   }
   return result;
 }
@@ -777,7 +941,7 @@ async function measureSite(browser, options) {
 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 findings = await page.evaluate(measurePhoneInPage, { ...PHONE_FLOORS, ...options.floors ?? {} });
   const viewport = page.viewportSize?.() ?? void 0;
   const result = { route: options.route, ...viewport ? { viewport } : {}, findings };
   const dir = options.out ?? DEFAULT_MEASURED_DIR;
@@ -801,8 +965,15 @@ async function measurePhone(page, options) {
   WIDE_WIDTHS,
   bandOf,
   checkExceptions,
+  checkScreenBudgets,
+  cleanRoute,
+  formatScreens,
   formatWidths,
+  hasReason,
+  hasUnexcusedEntries,
+  judgeGrowth,
   judgeMeasured,
+  judgeRoutes,
   judgeStatic,
   mainActionFor,
   measurePhone,
@@ -813,9 +984,14 @@ async function measurePhone(page, options) {
   measureViewports,
   mergeViewportFindings,
   normaliseElement,
+  parseBaseline,
   reasonOf,
   routeFile,
+  routeMatches,
+  routesFromManifest,
+  routesFromPages,
   scanPhoneFirst,
+  screenBudgetFor,
   sweepWidths,
   writeBaseline
 });

package/dist/phone.d.cts

@@ -1,9 +1,3 @@
-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.
  *
@@ -23,12 +17,18 @@ interface PhoneFloors {
     targetPx: number;
     fieldFontPx: number;
     textPx: number;
+    /**
+     * The height of a text field, select or textarea (portal standard rule 5:
+     * 48px inputs). Left out, 48. Below `targetPx` the field also fails the
+     * target check; this floor is what catches 44 to 47px.
+     */
+    fieldHeightPx?: number;
 }
 /**
  * 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";
+type PhoneCheck = "scroll" | "target" | "field" | "text" | "title" | "overlap" | "action" | "layers" | "landscape" | "image" | "input" | "autocomplete" | "tel" | "linelength" | "screens";
 interface RawPhoneFinding {
     check: PhoneCheck;
     /** `<tag> "text"`: what a person looks for on the page. */
@@ -44,6 +44,12 @@ declare function measurePhoneInPage(floors: PhoneFloors & {
     only?: PhoneCheck[];
 }): 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.
@@ -62,6 +68,11 @@ declare function measurePhoneInPage(floors: PhoneFloors & {
  * 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.
+ *
+ * Shrinking is also enforced against the base branch (DOM-1053): a baseline
+ * entry, or a higher count, that main's copy does not have fails, unless the
+ * entry carries a `reason` (a named exception: third-party UI, a
+ * destructive-only form).
  */
 
 interface StaticFinding {
@@ -81,23 +92,37 @@ interface MeasuredRoute {
     };
     /** Set by the every-viewport measure: the viewports and widths the findings were gathered across, phone first. */
     viewports?: string[];
+    /** Phone screens to the footer (page height at 375 x 667 over 667), from the every-viewport measure. Absent when the short phone was not measured. */
+    screens?: number;
     findings: RawPhoneFinding[];
 }
 interface Baseline {
     /** Why the baseline exists and which issue burns it down. Free text, for a person. */
     note?: string;
+    /**
+     * `reason` makes an entry a named exception: it may be added, or raised,
+     * after the baseline went in. Absent on the faults that were there first.
+     */
     static: {
         file: string;
         count: number;
         found?: string[];
+        reason?: string;
     }[];
     measured: {
         route: string;
         check: PhoneCheck;
         element: string;
         count: number;
+        reason?: string;
     }[];
 }
+/** An entry is a named exception when its `reason` says something. */
+declare const hasReason: (entry: {
+    reason?: unknown;
+}) => boolean;
+/** A baseline file, read. Old files (no `reason`, no `note`) read as before; a `reason` that is not text is an error. */
+declare function parseBaseline(raw: unknown, where: string): Baseline;
 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;
@@ -106,7 +131,10 @@ declare function reasonOf(line: string | undefined): string | null;
  * `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[]): {
+declare function scanPhoneFirst(files: SourceFile[], exceptions?: FileException[], options?: {
+    /** True for a file in an app whose tailwindcss is v3: it is also scanned for `/NN` opacity on a `var()` colour. */
+    tailwind3?: (path: string) => boolean;
+}): {
     findings: StaticFinding[];
     excused: number;
 };
@@ -128,7 +156,48 @@ interface Judgement {
 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;
+declare function writeBaseline(findings: StaticFinding[], routes: MeasuredRoute[], note?: string, previous?: Baseline): Baseline;
+/**
+ * Entries the baseline holds that the base branch's copy does not, or holds
+ * at a lower count, and that name no reason. The baseline lists the faults
+ * that were there when the gate arrived; a new breach is fixed where it is.
+ * An entry with a `reason` is a named exception and may be added or raised.
+ */
+declare function judgeGrowth(current: Baseline, base: Baseline, baseName?: string): string[];
+/** Whether the baseline holds anything a reason does not name: only then is the base branch's copy needed. */
+declare const hasUnexcusedEntries: (b: Baseline) => boolean;
+/**
+ * Page routes from the page files of a Next app directory, as paths relative
+ * to it (`portal/(shell)/invoices/[id]/page.tsx`). Route groups `(x)`, parallel
+ * slots `@x` and private folders `_x` are not part of the URL; an intercepting
+ * route `(.)x` is a second way into a page, not a page of its own.
+ */
+declare function routesFromPages(files: string[]): string[];
+/** Page routes from Next's `app-path-routes-manifest.json` (`{ "/portal/page": "/portal" }`). Route handlers and internal `_` routes are not pages. */
+declare function routesFromManifest(manifest: unknown): string[];
+interface ExcludedRoute {
+    route: string;
+    reason: string;
+}
+/** A route as the gate names it: no query, no hash, no trailing slash. */
+declare const cleanRoute: (route: string) => string;
+/** Whether a measured route (`/portal/projects/p1`, or the pattern itself) is a page route (`/portal/projects/[id]`). */
+declare function routeMatches(pattern: string, route: string): boolean;
+interface RouteJudgement {
+    /** Page routes nothing measured and no exclusion covers: the gate fails on these. */
+    missing: string[];
+    /** Problems with `excludeRoutes` itself: no reason, or names no page. */
+    problems: string[];
+    /** Pages measured or excluded with a reason. */
+    covered: number;
+}
+/**
+ * Every page route of the app is in the gate's route list. A measured route
+ * counts for the most specific page it matches, so `/portal/projects/new` does
+ * not cover `/portal/projects/[id]`. A page that only redirects measures
+ * nothing: it is excluded with that reason.
+ */
+declare function judgeRoutes(pages: string[], measuredRoutes: string[], excluded?: ExcludedRoute[]): RouteJudgement;
 
 /**
  * What "every viewport" means (STANDARD.md section 10, DOM-787): the ladder
@@ -199,6 +268,23 @@ 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;
+/**
+ * A length budget per page type, in phone screens to the footer (page height at
+ * 375 x 667 over 667). Keys are a route (`/`), a route pattern (`/services/[slug]`),
+ * a prefix (`/services/*`: the route and everything under it) or `*` for the
+ * rest; the most specific match wins. No match is no budget: the count is
+ * reported and never fails.
+ */
+type ScreenBudgets = Record<string, number>;
+/** The budget for a route, or undefined when none of the keys covers it. */
+declare function screenBudgetFor(budgets: ScreenBudgets | undefined, route: string): number | undefined;
+/** `screens` as a person types it into config: every budget a positive number. */
+declare function checkScreenBudgets(budgets: unknown, where?: string): ScreenBudgets | undefined;
+/** `/ 12.7, /services 4.1`: the count per route, for the line a run prints whether or not a budget is set. */
+declare function formatScreens(routes: {
+    route: string;
+    screens?: number;
+}[], budgets?: ScreenBudgets): string;
 /**
  * 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`)
@@ -263,8 +349,13 @@ declare const PHONE: {
     readonly isMobile: true;
     readonly hasTouch: true;
 };
-/** The house floors at phone width. Not per-repo settings. */
-declare const PHONE_FLOORS: PhoneFloors;
+/**
+ * The house floors at phone width. A site may raise `textPx`, or lower
+ * `fieldHeightPx` with a reason; they are not per-repo taste. The field height
+ * is portal standard rule 5 (48px inputs); until DOM-1053 the gate held fields
+ * to the 44px target floor only.
+ */
+declare const PHONE_FLOORS: Required<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`. */
@@ -309,10 +400,17 @@ interface MeasureViewportsOptions {
     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. */
+    /** Override the 12 / 16 / 44px floors and the 48px field height (`fieldHeightPx`). 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;
+    /**
+     * A length budget per route, in phone screens to the footer (page height at
+     * 375 x 667 over 667): `{ "/": 6.5, "/services/*": 6 }`. A route over its
+     * budget fails the `screens` check. Without a budget the count is only
+     * reported, in `ViewportsResult.screens`.
+     */
+    screens?: ScreenBudgets;
     /** The width sweep, or `false` to measure the ladder only. */
     sweep?: Partial<Sweep> | false;
     /** Replace the ladder. */
@@ -440,6 +538,8 @@ interface MeasurePhoneOptions {
     route: string;
     /** The folder to write `<route>.json` into. Default `phone-first/measured`, from the working directory. */
     out?: string;
+    /** Override the 12 / 16 / 44 / 48px floors (text, field text, target, field height). The defaults are the house standard. */
+    floors?: Partial<PhoneFloors>;
 }
 /**
  * Measure the page as it is now and write the result for `craft phone-first`.
@@ -448,4 +548,4 @@ interface MeasurePhoneOptions {
  */
 declare function measurePhone(page: MinimalPage, options: MeasurePhoneOptions): Promise<MeasuredRoute>;
 
-export { BANDS, type Band, type Baseline, DEFAULT_MEASURED_DIR, DEFAULT_SWEEP, DEFAULT_THRESHOLDS, DESKTOP, EMPTY_BASELINE, type FileException, type InPageGroup, type Judgement, LADDER, type MainAction, type MeasurePhoneOptions, type MeasureSiteOptions, type MeasureViewportsOptions, type MeasuredRoute, type OpenedPage, 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, measureRoute, measureSite, measureViewportInPage, measureViewports, mergeViewportFindings, normaliseElement, reasonOf, routeFile, scanPhoneFirst, sweepWidths, writeBaseline };
+export { BANDS, type Band, type Baseline, DEFAULT_MEASURED_DIR, DEFAULT_SWEEP, DEFAULT_THRESHOLDS, DESKTOP, EMPTY_BASELINE, type ExcludedRoute, type FileException, type InPageGroup, type Judgement, LADDER, type MainAction, type MeasurePhoneOptions, type MeasureSiteOptions, type MeasureViewportsOptions, type MeasuredRoute, type OpenedPage, PHONE, PHONE_FLOORS, type PhoneCheck, type PhoneFloors, type RawPhoneFinding, type RouteJudgement, SHORT_PHONE, type ScreenBudgets, type SiteBrowser, type SitePage, type SiteResult, type StaticFinding, type Sweep, type Thresholds, type Viewport, type ViewportArg, type ViewportPage, type ViewportsResult, WIDE_WIDTHS, bandOf, checkExceptions, checkScreenBudgets, cleanRoute, formatScreens, formatWidths, hasReason, hasUnexcusedEntries, judgeGrowth, judgeMeasured, judgeRoutes, judgeStatic, mainActionFor, measurePhone, measurePhoneInPage, measureRoute, measureSite, measureViewportInPage, measureViewports, mergeViewportFindings, normaliseElement, parseBaseline, reasonOf, routeFile, routeMatches, routesFromManifest, routesFromPages, scanPhoneFirst, screenBudgetFor, sweepWidths, writeBaseline };