scenescout 3.15.0 → 3.16.0

package/dist/engine/crawl.js

@@ -0,0 +1,49 @@
+/**
+ * What a crawl makes of one route it loaded: whether an explicitly requested
+ * path joins the route contract, and the summary line it prints. Kept out of
+ * browser.ts so both rules can be table-tested without a browser.
+ */
+import { isNonPageRoute } from "./fingerprint.js";
+/** The crawl flag for a main area showing only its state, or null. */
+export function mainStateFlag(state) {
+    return state === "error" ? "ERROR-VIEW" : state === "loading" ? "STILL-LOADING" : null;
+}
+/**
+ * The route an explicitly requested crawl path adds to the route contract,
+ * or null. A path someone asked for, that answered with a page and stayed
+ * where it was asked, is a route of the app whether or not any link names
+ * it: left out, a sweep of forty extra paths left "Routes visited: 37/37"
+ * unchanged and the report understated what was checked. A path that
+ * redirected is not added (the page it landed on is the route that exists),
+ * nor one that failed, nor a dead end (an app that answers 200 for every
+ * path), nor one whose main area showed only an error view or a loading
+ * placeholder (a client-rendered app answers 200 and draws its not-found
+ * view), nor an API or download path. Added routes are remembered across
+ * runs, so a probe of made-up paths must not become part of the contract.
+ */
+export function crawledRoute(o) {
+    if (typeof o.status !== "number" || o.status >= 400 || o.deadEnd || o.mainState)
+        return null;
+    if (o.loginRedirect || o.landedRoute !== o.requestedRoute)
+        return null;
+    if (isNonPageRoute(o.requestedRoute))
+        return null;
+    return o.requestedRoute;
+}
+/**
+ * The crawl's one line for a route. A path that ended on another route says
+ * so, as scout_navigate does: "/old — 200 · 94 el" read as the old page
+ * answering, when the 200 and the 94 elements were the page it landed on.
+ * The sign-in bounce has its own flag (AUTH-REDIRECT) and is not repeated.
+ * `main` is what the page's main area holds (collector mainRegionTag), so
+ * "41 el" alone cannot hide a main area that rendered nothing.
+ */
+export function crawlLine(o, counts, flags) {
+    const redirected = !o.loginRedirect && o.landedRoute !== o.requestedRoute;
+    const allFlags = [...(redirected ? [`REDIRECTED → ${o.landedRoute}`] : []), ...flags];
+    return (`${o.path} — ${o.status} · ${counts.elements} el` +
+        (counts.main ? ` · ${counts.main}` : "") +
+        (counts.missingTestid ? ` · ${counts.missingTestid} no-testid` : "") +
+        (counts.unnamed ? ` · ${counts.unnamed} unnamed` : "") +
+        (allFlags.length ? ` · ${allFlags.join(" ")}` : ""));
+}

package/dist/engine/design.js

@@ -21,6 +21,17 @@
  * grays, a focused accent palette, one elevation system, consistent
  * controls, visible keyboard focus.
  */
+import { missingName, NAME_SRC, placeholderOnly } from "./collector.js";
+/**
+ * Whether some text names a filter or a facet, as page-side source: one of its
+ * words, split at camelCase and punctuation, is filter(s) or facet(s). Whole
+ * words only, so "filterable-list" or "unfiltered" says nothing.
+ */
+export const FILTER_WORDS_SRC = `(s) => (s || "").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z]+/).some((w) => w === "filter" || w === "filters" || w === "facet" || w === "facets")`;
+/** FILTER_WORDS_SRC run outside a page, from the same source, so a table test exercises the rule the collector ships. */
+export function namesFilter(text) {
+    return new Function(`return (${FILTER_WORDS_SRC});`)()(text);
+}
 /**
  * In-page collector, shipped as a string expression (immune to loader
  * transforms — same rationale as the interactables collector).
@@ -79,6 +90,20 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     }
     return false;
   };
+  const nameOf = ${NAME_SRC};
+  const namesFilter = ${FILTER_WORDS_SRC};
+  // A filter panel names itself one somewhere on the way up: its test id, id,
+  // label, the element its aria-labelledby points at, or a fieldset's legend.
+  const inFilterOf = (el) => {
+    for (let n = el, i = 0; n && n !== document.body && i < 15; n = n.parentElement, i++) {
+      const legend = n.tagName === "FIELDSET" ? n.querySelector(":scope > legend") : null;
+      const labelledBy = (n.getAttribute("aria-labelledby") || "").split(/\\s+/).filter(Boolean)
+        .map((id) => { const t = document.getElementById(id); return t ? t.textContent || "" : ""; }).join(" ");
+      const said = [n.getAttribute("data-testid"), n.id, n.getAttribute("aria-label"), labelledBy, legend ? legend.textContent : ""].join(" ");
+      if (namesFilter(said)) return true;
+    }
+    return false;
+  };
   const interactiveSel = 'a[href], button, input, select, textarea, [role="button"], [role="link"], [onclick]';
   // The app shell, as the markup declares it. A <header>/<footer> inside a
   // <section> is that section's own heading block, not the page banner (the
@@ -108,6 +133,33 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     else h = (r - g) / (max - min) + 4;
     return ((h * 60) + 360) % 360;
   };
+  // The box a pointer user hits to operate a native input (StyleRecord.target).
+  const unionBox = (boxes) => {
+    let l = Infinity, t = Infinity, r = -Infinity, b = -Infinity;
+    for (const x of boxes) { l = Math.min(l, x.left); t = Math.min(t, x.top); r = Math.max(r, x.right); b = Math.max(b, x.bottom); }
+    return { x: Math.round(l), y: Math.round(t), w: Math.round(r - l), h: Math.round(b - t) };
+  };
+  const gapBetween = (a, b) => Math.max(a.left - b.right, b.left - a.right, a.top - b.bottom, b.top - a.bottom, 0);
+  const targetOf = (el, rect, hiddenInput) => {
+    if (el.tagName !== "INPUT") return null;
+    const boxes = [];
+    for (const label of Array.from(el.labels || [])) {
+      const lr = label.getBoundingClientRect();
+      if (lr.width === 0 || lr.height === 0) continue;
+      // A label elsewhere on the page also operates the input, but it is a
+      // second target, not a bigger one; only a label that wraps or touches
+      // the input makes one box with it. A hidden input has no box of its own,
+      // so any label of it is the target.
+      if (hiddenInput || label.contains(el) || gapBetween(lr, rect) <= 4) boxes.push(lr);
+    }
+    if (hiddenInput && boxes.length === 0 && el.parentElement) {
+      const zone = el.parentElement.closest('button, [role="button"], [onclick], [tabindex]:not([tabindex="-1"])');
+      if (zone) boxes.push(zone.getBoundingClientRect());
+    }
+    if (boxes.length === 0) return null;
+    if (!hiddenInput) boxes.push(rect);
+    return unionBox(boxes);
+  };
   const vh = window.innerHeight;
   let density = 0;
   const all = document.querySelectorAll("body *");
@@ -155,6 +207,8 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     const slop = sideStripe || gradientText || glass || glow || aiGradient;
     if (!interactive && !ownText && !slop) continue;
     const fullText = ownText ? (el.textContent || "").trim().replace(/\\s+/g, " ") : "";
+    const target = interactive ? targetOf(el, rect, srOnly || s.opacity === "0") : null;
+    const named = interactive ? nameOf(el) : null;
     out.push({
       tag: el.tagName.toLowerCase(),
       testid: el.getAttribute("data-testid"),
@@ -174,14 +228,16 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
       padding: [px(s.paddingTop), px(s.paddingRight), px(s.paddingBottom), px(s.paddingLeft)],
       marginV: [px(s.marginTop), px(s.marginBottom)],
       radius: px(s.borderTopLeftRadius),
-      shadow: s.boxShadow && s.boxShadow !== "none" ? s.boxShadow.replace(/\\s+/g, " ").slice(0, 80) : "",
+      shadow: s.boxShadow && s.boxShadow !== "none" ? s.boxShadow.replace(/\\s+/g, " ").slice(0, 400) : "",
       // srOnly text is DELIBERATELY a 1px box with overflow hidden — the exact
       // signature of "text wider than its box". Flagging it reported the
       // accessibility affordance itself as an accessibility defect.
       clipped: !srOnly && el.scrollWidth > el.clientWidth + 2 && /hidden|clip/.test(s.overflowX) && s.textOverflow !== "ellipsis" && ownText,
+      ...(target ? { target } : {}),
       fixed: s.position === "fixed" || s.position === "sticky",
       required: el.hasAttribute("required") || el.getAttribute("aria-required") === "true",
       submitish: el.matches('button[type="submit"], input[type="submit"]') || /\\b(save|submit|create|send|confirm|apply|continue|next|finish|approve|sign)\\b/i.test(fullText),
+      ...(named ? { name: named.name, nameFrom: named.from, ariaHidden: el.closest('[aria-hidden="true"]') !== null } : {}),
       inputType: el.tagName === "INPUT" ? (el.getAttribute("type") || "text").toLowerCase() : "",
       role: (el.getAttribute("role") || "").toLowerCase(),
       filled: ownFill(s),
@@ -189,6 +245,7 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
       inRow: !!el.closest('tr, [role="row"]'),
       inSearch: !!el.closest('search, [role="search"]'),
       inBreadcrumb: !!el.closest('[aria-label*="breadcrumb" i], [class*="breadcrumb" i]'),
+      inFilter: interactive && inFilterOf(el),
       shell: inShell(el),
       sideStripe, gradientText, glass, glow, aiGradient,
     });
@@ -256,9 +313,20 @@ function hueOf([r, g, b]) {
         h = (r - g) / (max - min) + 4;
     return Math.round((h * 60 + 360) % 360);
 }
-const label = (r) => (r.testid ? `[${r.testid}]` : `<${r.tag}> "${r.text.slice(0, 30) || "(no text)"}"`);
+/**
+ * How an audit line names an element: its test id, else what a user hears for
+ * a control (its accessible name, the snapshot's), else its own text. A name
+ * that is only the field's name attribute or type is not one anybody hears,
+ * so it gives way to the text.
+ */
+const label = (r) => {
+    if (r.testid)
+        return `[${r.testid}]`;
+    const heard = r.name && r.nameFrom !== "fallback" ? r.name : r.text;
+    return `<${r.tag}> "${heard.slice(0, 30) || "(no text)"}"`;
+};
 /** One wording for a small target, page or shell alike: the shell section's, so its prose is unchanged. */
-const tinyTargetDetail = (r) => `${label(r)} — ${Math.round(r.rect.w)}×${Math.round(r.rect.h)}px tap target`;
+const tinyTargetDetail = (r) => `${label(r)} — ${Math.round(targetBox(r).w)}×${Math.round(targetBox(r).h)}px tap target`;
 const clippedTextDetail = (r) => `${label(r)} — text is clipped by its container`;
 /** One wording for body-coloured links, page or shell alike. */
 const indistinctDetail = (bodyColor) => `links with no underline in the body-text colour ${bodyColor}`;
@@ -309,8 +377,16 @@ function gridValues(top) {
         .map((v) => `${v}px`)
         .join(", ");
 }
+/** The box a pointer user hits to operate the control: its label or drop zone where one operates it, else its own. */
+export function targetBox(r) {
+    return r.target ?? r.rect;
+}
+/** The WCAG 2.2 target-size minimum, in CSS pixels. */
+const MIN_TARGET = 24;
 /** Inputs that are buttons, not fields. */
 const BUTTON_INPUT_TYPES = new Set(["submit", "button", "reset", "image"]);
+/** Inputs a user types into. Every other type (a checkbox, radio, range, colour or file) is picked rather than typed, and outside a form most of those apply at once. */
+const TYPED_INPUT_TYPES = new Set(["text", "email", "number", "tel", "url", "password", "date", "datetime-local", "month", "week", "time"]);
 /** A button, or a link painted as one. Fields, selects and plain links never compete as actions. */
 function buttonLike(r) {
     if (r.tag === "button" || r.role === "button")
@@ -322,10 +398,14 @@ function buttonLike(r) {
 /**
  * The fields a user is asked to fill in and submit. Excluded: controls in a
  * table row (a selection checkbox, or a select that edits the row in place),
- * search boxes, and inputs that are buttons. When some fields sit in a <form>,
- * only those count: the rest of the page (filters, toolbars) is not part of
- * what gets submitted. A page with no <form> at all is judged on every field,
- * because many apps build their forms without the element.
+ * search boxes, controls in a panel that names itself a filter, and inputs
+ * that are buttons. When some fields sit in a <form>, only those count: the
+ * rest of the page (filters, toolbars) is not part of what gets submitted. A
+ * page with no <form> at all is judged on the fields a user types into,
+ * because many apps build their forms without the element; its selects and
+ * every input not in TYPED_INPUT_TYPES (checkboxes, radios, file pickers) are
+ * left out, since outside a form those are most often filters and settings
+ * that apply as they change.
  */
 function formFields(records) {
     const candidates = records.filter((r) => r.interactive &&
@@ -333,13 +413,166 @@ function formFields(records) {
         !BUTTON_INPUT_TYPES.has(r.inputType) &&
         r.inputType !== "search" &&
         !r.inSearch &&
-        !r.inRow);
+        !r.inRow &&
+        !r.inFilter);
     const inForm = candidates.filter((r) => r.inForm);
-    return inForm.length > 0 ? inForm : candidates;
+    return inForm.length > 0 ? inForm : candidates.filter(typedField);
+}
+/** A field a user types into: a text-like input or a textarea. */
+function typedField(r) {
+    return r.tag === "textarea" || (r.tag === "input" && TYPED_INPUT_TYPES.has(r.inputType || "text"));
+}
+/**
+ * The layers of a computed box-shadow that draw something: a layer with no
+ * offset, blur or spread, or a transparent colour, paints nothing. Utility CSS
+ * stacks such placeholder layers (empty rings) in front of the real shadow on
+ * every element, so a census keyed on the raw value counts the placeholders.
+ * Returned in order, whitespace normalized; empty when nothing is drawn.
+ */
+export function shadowLayers(shadow) {
+    const layers = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of shadow) {
+        if (ch === "(")
+            depth += 1;
+        if (ch === ")")
+            depth = Math.max(0, depth - 1);
+        if (ch === "," && depth === 0) {
+            layers.push(current);
+            current = "";
+        }
+        else
+            current += ch;
+    }
+    layers.push(current);
+    return layers
+        .map((l) => l.replace(/\s+/g, " ").trim())
+        .filter((l) => {
+        if (!l || l === "none")
+            return false;
+        const lengths = (l.match(/-?[0-9.]+px/g) ?? []).map(parseFloat);
+        if (lengths.every((n) => n === 0))
+            return false;
+        if (/\btransparent\b/.test(l))
+            return false;
+        const colour = l.match(/rgba?\([^)]*\)/);
+        return !(colour && parseRgb(colour[0])?.[3] === 0);
+    });
+}
+/** The elevation a box-shadow draws, as one key: its drawing layers. "" for none. */
+export function elevationKey(shadow) {
+    return shadowLayers(shadow).join(", ");
+}
+/**
+ * The layer that tells one elevation from the others listed beside it: its
+ * first layer that not every other key has. Shown in place of the whole value,
+ * whose differences often begin past any width an example can be given.
+ */
+export function distinguishingLayer(key, others) {
+    const layers = shadowLayers(key);
+    const rest = others.filter((o) => o !== key).map(shadowLayers);
+    return layers.find((l) => rest.some((o) => !o.includes(l))) ?? layers[0] ?? "";
+}
+/**
+ * A colour with no hue family is a gray: neutral or tinted (a slate or a warm
+ * stone), the shades text and surfaces are built from. Near-white and
+ * near-black are left out, as before: every page has them.
+ */
+export function grayOf(rgb) {
+    const avg = (rgb[0] + rgb[1] + rgb[2]) / 3;
+    return hueOf(rgb) === null && avg > 20 && avg < 245;
+}
+/**
+ * Grays counted as the steps of a scale: colours within GRAY_STEP of one in
+ * every channel are one step (a translucent text colour composited over two
+ * backgrounds lands a unit or two apart). Commonest first, each with its use count.
+ */
+export function grayCensus(colours) {
+    const freq = new Map();
+    for (const c of colours) {
+        if (!grayOf(c))
+            continue;
+        const k = c.join(",");
+        const e = freq.get(k) ?? { rgb: c, n: 0 };
+        e.n += 1;
+        freq.set(k, e);
+    }
+    const steps = [];
+    for (const e of [...freq.values()].sort((a, b) => b.n - a.n)) {
+        const near = steps.find((s) => s.rgb.every((v, i) => Math.abs(v - e.rgb[i]) <= GRAY_STEP));
+        if (near)
+            near.n += e.n;
+        else
+            steps.push({ ...e });
+    }
+    return steps.sort((a, b) => b.n - a.n);
+}
+/** How far apart, per channel, two grays may be and still be one step of a scale. */
+const GRAY_STEP = 4;
+/**
+ * The page's controls a screen-reader user cannot tell apart: fields and
+ * controls with no name, and fields whose only label is the placeholder. The
+ * snapshot's own predicates (collector.ts), over the snapshot's own name, so
+ * the audit and the snapshot agree on a page. Records with no name read are
+ * left out rather than guessed.
+ */
+export function unnamedControls(records) {
+    const named = records.filter((r) => r.interactive && typeof r.name === "string");
+    const asSnapshot = (r) => ({
+        role: r.role,
+        name: r.name ?? "",
+        nameFrom: r.nameFrom ?? null,
+        interactive: true,
+        ariaHidden: r.ariaHidden === true,
+    });
+    return {
+        unnamed: named.filter((r) => missingName(asSnapshot(r))),
+        placeholder: named.filter((r) => placeholderOnly(asSnapshot(r))),
+    };
 }
 /** Below the WCAG 2.2 target-size minimum; inline links are exempt by that rule. */
-function tooSmall(r) {
-    return r.tag !== "a" && (r.rect.h < 24 || r.rect.w < 24) && r.rect.h > 0;
+function undersized(r) {
+    const b = targetBox(r);
+    return r.interactive && r.tag !== "a" && (b.h < MIN_TARGET || b.w < MIN_TARGET) && b.h > 0;
+}
+const centreOf = (b) => [b.x + b.w / 2, b.y + b.h / 2];
+/** Distance from a point to the nearest edge of a box; 0 inside it. */
+function distanceToBox([px, py], b) {
+    const dx = Math.max(b.x - px, 0, px - (b.x + b.w));
+    const dy = Math.max(b.y - py, 0, py - (b.y + b.h));
+    return Math.hypot(dx, dy);
+}
+/**
+ * The WCAG 2.5.8 spacing exception: an undersized target passes when a 24px
+ * circle on its centre touches no other target and no other undersized
+ * target's circle. `others` is every interactive record on the page, shell
+ * included, since a neighbour in the shell is as easy to hit by mistake.
+ */
+export function spacedApart(r, others) {
+    const c = centreOf(targetBox(r));
+    for (const o of others) {
+        if (o === r || !o.interactive)
+            continue;
+        const ob = targetBox(o);
+        if (ob.w === 0 || ob.h === 0)
+            continue;
+        if (undersized(o)) {
+            const [ox, oy] = centreOf(ob);
+            if (Math.hypot(ox - c[0], oy - c[1]) < MIN_TARGET)
+                return false;
+        }
+        else if (distanceToBox(c, ob) < MIN_TARGET / 2)
+            return false;
+    }
+    return true;
+}
+/**
+ * A target that fails WCAG 2.5.8: under 24px, measured on what the user hits
+ * (targetBox), and not saved by the spacing exception.
+ */
+export function tooSmall(r, all) {
+    return undersized(r) && !spacedApart(r, all);
 }
 /**
  * Reduce raw style records + page facts to a judgeable design digest + score.
@@ -451,14 +684,16 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         spacingLines.push(`${mar.pct}% of vertical margins are off a 4px grid — ad-hoc values: ${mar.top.map(([v, n]) => `${v}px×${n}`).join(", ")}`);
     if (spacingLines.length > 0)
         sections.push(`SPACING: ` + spacingLines.join("\n  "));
-    // ---- 5. Touch/click targets below ~24px are hard to hit. Inline links are
-    //      exempt (mirrors the WCAG 2.2 target-size exception); worst offenders first.
-    const tiny = records.filter((r) => r.interactive && tooSmall(r)).sort((a, b) => a.rect.w * a.rect.h - b.rect.w * b.rect.h);
+    // ---- 5. Touch/click targets below ~24px are hard to hit (WCAG 2.5.8). Measured
+    //      on what the user hits (a native input's label or drop zone), with
+    //      that rule's exceptions: inline links, and a small target with nothing
+    //      else within its 24px circle. Worst offenders first.
+    const tiny = records.filter((r) => tooSmall(r, allRecords)).sort((a, b) => targetBox(a).w * targetBox(a).h - targetBox(b).w * targetBox(b).h);
     if (tiny.length > 0) {
         sections.push(`TINY targets (${tiny.length}, smallest first):\n` +
             tiny
                 .slice(0, 6)
-                .map((r) => `  ⚠ ${label(r)} — ${r.rect.w}×${r.rect.h}px`)
+                .map((r) => `  ⚠ ${label(r)} — ${targetBox(r).w}×${targetBox(r).h}px`)
                 .join("\n"));
     }
     // ---- 6. Clipped text (overflow hidden without ellipsis) — content silently cut off.
@@ -503,15 +738,16 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     if (buttonHeights.length > 3) {
         consistency.push(`→ buttons render at ${buttonHeights.length} different heights (${buttonHeights.slice(0, 8).join(", ")}px) — 1–2 control sizes read as a system`);
     }
+    // Keyed on the layers that draw something (elevationKey); each example shows the layer that sets it apart.
     const shadows = new Map();
-    for (const r of records)
-        if (r.shadow)
-            shadows.set(r.shadow, (shadows.get(r.shadow) ?? 0) + 1);
+    for (const r of records) {
+        const key = elevationKey(r.shadow);
+        if (key)
+            shadows.set(key, (shadows.get(key) ?? 0) + 1);
+    }
     if (shadows.size > 4) {
-        const top = [...shadows.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 3)
-            .map(([s]) => `"${s.slice(0, 40)}"`);
+        const keys = [...shadows.entries()].sort((a, b) => b[1] - a[1]).map(([k]) => k);
+        const top = keys.slice(0, 3).map((k) => `"${distinguishingLayer(k, keys.slice(0, 3)).slice(0, 60)}"`);
         consistency.push(`→ ${shadows.size} distinct box-shadow styles (${top.join(", ")}…) — an elevation system needs 2–3 levels, not one per component`);
     }
     if (consistency.length > 0)
@@ -522,20 +758,15 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     if (pureBlack.length > 0) {
         palette.push(`→ pure #000-on-#fff body text (${pureBlack.length} block(s), e.g. ${label(pureBlack[0])}) — near-black (rgb(23,23,23)-ish) reads softer at length`);
     }
-    const grayFreq = new Map();
     const hueFamilies = new Map();
+    const colours = [];
     for (const r of records) {
         for (const c of [r.color, r.bg]) {
             const p = parseRgb(c);
             if (!p)
                 continue;
             const rgb = [p[0], p[1], p[2]];
-            const spread = Math.max(...rgb) - Math.min(...rgb);
-            const avg = (rgb[0] + rgb[1] + rgb[2]) / 3;
-            if (spread <= 10 && avg > 20 && avg < 245) {
-                const key = rgb.join(",");
-                grayFreq.set(key, (grayFreq.get(key) ?? 0) + 1);
-            }
+            colours.push(rgb);
             const hue = hueOf(rgb);
             if (hue !== null) {
                 const bucket = (Math.round(hue / 30) * 30) % 360;
@@ -543,12 +774,10 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
             }
         }
     }
-    if (grayFreq.size > 6) {
-        const top = [...grayFreq.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 5)
-            .map(([k]) => `rgb(${k})`);
-        palette.push(`→ ${grayFreq.size} distinct grays (${top.join(", ")}…) — a deliberate gray scale runs 4–6 steps; near-duplicates suggest ad-hoc values`);
+    const grays = grayCensus(colours);
+    if (grays.length > 6) {
+        const top = grays.slice(0, 5).map((g) => `rgb(${g.rgb.join(",")})`);
+        palette.push(`→ ${grays.length} distinct grays (${top.join(", ")}…) — a deliberate gray scale runs 4–6 steps; near-duplicates suggest ad-hoc values`);
     }
     if (hueFamilies.size > 5) {
         const hues = [...hueFamilies.keys()].sort((a, b) => a - b);
@@ -613,6 +842,20 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     }
     if (structure.length > 0)
         sections.push(`STRUCTURE:\n` + structure.map((s) => `  ${s}`).join("\n"));
+    // ---- 10b. NAMES: a control a screen reader cannot name, or a field labelled
+    //      only by a placeholder that disappears as the user types.
+    const names = unnamedControls(records);
+    const nameLines = [
+        ...names.unnamed.map((r) => `⚠ ${label(r)} — ${r.tag === "input" || r.tag === "select" || r.tag === "textarea" ? "field" : "control"} with no accessible name`),
+        ...names.placeholder.map((r) => `⚠ ${label(r)} — labelled only by its placeholder, which is gone once the user types`),
+    ];
+    if (nameLines.length > 0) {
+        sections.push(`NAMES (${nameLines.length}):\n` +
+            nameLines
+                .slice(0, 6)
+                .map((s) => `  ${s}`)
+                .join("\n"));
+    }
     // ---- 11. AFFORDANCES: keyboard focus visibility (trusted-Tab sampled engine-side) + indistinguishable links.
     const affordances = [];
     const focusless = page.focusSamples.filter((f) => !f.indicator);
@@ -740,13 +983,13 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     const gridPct = pad.n > 0 ? 100 - pad.pct : 100;
     const summary = `SYSTEM SUMMARY: ${sizes.length} font sizes (≤7 healthy) · ${families.length} families (≤2) · ` +
         `${buttonRadii.length} button radii (1–2) · ${buttonHeights.length} button heights (1–3) · ${shadows.size} shadow styles (≤3) · ` +
-        `${grayFreq.size} grays (4–6) · ${hueFamilies.size} accent hue families (1–3 + status) · ${gridPct}% spacing on 4px grid · ` +
+        `${grays.length} grays (4–6) · ${hueFamilies.size} accent hue families (1–3 + status) · ${gridPct}% spacing on 4px grid · ` +
         `${page.density} interactive elements in first viewport${page.density > 40 ? " (dense — consider progressive disclosure)" : ""}`;
     // ---- Multi-indicator PAGE SCORE. Deductive: start at 100 per dimension,
     //      subtract per measured issue, floor at 0. Weights favour a11y and
     //      task clarity — a page can be pretty and still hard to use.
     const floor0 = (n) => Math.max(0, Math.round(n));
-    const a11yScore = floor0(100 - contrastFails.length * 4 - focusless.length * 6 - tiny.length * 3);
+    const a11yScore = floor0(100 - contrastFails.length * 4 - focusless.length * 6 - tiny.length * 3 - names.unnamed.length * 6 - names.placeholder.length * 4);
     const craftScore = floor0(100 - readability.length * 4 - palette.length * 4 - slopTells.length * 5 - clipped.length * 3 - distorted.length * 4);
     const consistencyScore = floor0(100 -
         consistency.length * 8 -
@@ -771,7 +1014,7 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     const chromeSection = [];
     const chromeDefects = [];
     if (chromeRecords.length > 0) {
-        chromeDefects.push(...contrastFailures(chromeRecords).map((detail) => ({ rule: "contrast", detail, chrome: true })), ...chromeRecords.filter((r) => r.interactive && tooSmall(r)).map((r) => ({ rule: "tiny-target", detail: tinyTargetDetail(r), chrome: true })), ...chromeRecords.filter((r) => r.clipped && r.textLen > 0).map((r) => ({ rule: "clipped-text", detail: clippedTextDetail(r), chrome: true })), ...(chromeIndistinct.length > 0 ? [{ rule: "indistinct-link", detail: indistinctDetail(dominantBody ?? ""), chrome: true }] : []));
+        chromeDefects.push(...contrastFailures(chromeRecords).map((detail) => ({ rule: "contrast", detail, chrome: true })), ...chromeRecords.filter((r) => tooSmall(r, allRecords)).map((r) => ({ rule: "tiny-target", detail: tinyTargetDetail(r), chrome: true })), ...chromeRecords.filter((r) => r.clipped && r.textLen > 0).map((r) => ({ rule: "clipped-text", detail: clippedTextDetail(r), chrome: true })), ...(chromeIndistinct.length > 0 ? [{ rule: "indistinct-link", detail: indistinctDetail(dominantBody ?? ""), chrome: true }] : []));
         // A convention (indistinct-link) is a → line, as it is on the page; the rest are measurable defects.
         const chromeIssues = chromeDefects.map((d) => `${d.rule === "indistinct-link" ? "→" : "⚠"} ${d.detail}`);
         if (chromeIssues.length > 0) {