@gemboss/website-ui 0.0.0-stage → 0.2.0

package/bin/lib/check.mjs

@@ -0,0 +1,695 @@
+// `gemboss-website check`: a site's HTML and CSS against the kit's rules (AGENTS.md), with every value read from
+// system.json. Generic on purpose: nothing here knows about one brand, one domain or one product's claims.
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { PKG, SYSTEM, UsageError, blank, c, isKitPath, lineIndex, parseArgs, rel, walkFiles } from "./util.mjs";
+
+const RADII = new Set(SYSTEM.radius.scale);
+const TYPE = new Set(SYSTEM.type.scale);
+// The page gutter (layout.gutter) is a system value too: horizontal padding and the negative bleed that undoes it.
+const SPACE = new Set([...SYSTEM.space.scale, SYSTEM.layout.gutter]);
+const DISPLAY_ABOVE = SYSTEM.type.display_above;
+const list = (s) => [...s].join(" ");
+
+/** Every rule: level, a one-line title, why it matters and how to fix it. Order = report order. */
+export const RULES = {
+  "color-literal": {
+    level: "error", title: "Colour outside the tokens",
+    why: "A hard-coded colour does not follow dark mode or the brand's theme, and drifts from the system.",
+    fix: "Use a kit colour variable (var(--gw-ink), var(--gw-muted), var(--gw-line), var(--gw-accent)…). A brand sets its accent once, in a :root block that redefines only --gw-accent*/--gw-wash-* (docs/theming.md).",
+  },
+  "token-redefined": {
+    level: "error", title: "Kit token redefined",
+    why: "Only the accent family and the wash hues are themable. Changing another --gw-* token changes every component on the site.",
+    fix: "Remove it. If the brand really needs a different value, report a gap: npx gemboss-website gap --kind token.",
+  },
+  "radius-off-scale": {
+    level: "error", title: "Radius not on the scale",
+    why: "Actions are 8px rectangles, cards 12px, panels 16px, chips 999px. Other radii make a page look improvised.",
+    fix: `Use one of ${list(RADII)} (px), or a kit class that already has the shape.`,
+  },
+  "type-off-scale": {
+    level: "error", title: "Font size not on the type scale",
+    why: "Every page reads the same when sizes come from one scale; one 15px next to 14px and 16px looks like a mistake.",
+    fix: `Use ${list(TYPE)} (px). Headings above ${DISPLAY_ABOVE}px use the kit's h1/h2 display sizes.`,
+  },
+  "space-off-scale": {
+    level: "error", title: "Spacing not on the scale",
+    why: "Spacing comes from one 4px scale; off-scale gaps are what makes a layout feel slightly wrong.",
+    fix: `Use ${list(SYSTEM.space.scale)} (px), or the ${SYSTEM.layout.gutter}px page gutter. Vertical rhythm between sections comes from .gw-section.`,
+  },
+  "half-pixel": {
+    level: "error", title: "Half-pixel size",
+    why: "Fractional pixels render blurry and are never on a scale.",
+    fix: "Round to a whole value on the scale (type and tracking in the kit use em for letter-spacing).",
+  },
+  "shadow-not-token": {
+    level: "error", title: "Shadow that is not a kit shadow",
+    why: "Cards are separated by a hairline, not a shadow. The kit has three shadows and that is the whole budget.",
+    fix: "Use a 1px var(--gw-line) border, or var(--gw-shadow), var(--gw-shadow-sm), var(--gw-shadow-raised). An illustration may light itself: put illus, mock or visual in its class name.",
+  },
+  "uppercase-label": {
+    level: "error", title: "Uppercase label with letter spacing",
+    why: "Labels are sentence case. Uppercase with tracking (\"FEATURES\") is the one look the kit rules out.",
+    fix: "Remove text-transform and letter-spacing and use .gw-label.",
+  },
+  "accent-button": {
+    level: "error", title: "Button filled with the accent, a wash or a gradient",
+    why: "The thing you click is ink. The accent marks links, focus and the active item; it is never a button fill.",
+    fix: "Use .gw-btn (ink) or .gw-btn--secondary as they are. Do not restyle buttons.",
+  },
+  "gw-override": {
+    level: "error", title: "Site CSS overrides a kit class",
+    why: "Restyling a .gw-* class changes the component for this site only and breaks on the next kit release.",
+    fix: "Remove the override. If the kit's version does not fit, build a kitgap- stopgap in kit-gaps.css and report it: npx gemboss-website gap.",
+  },
+  "em-dash": {
+    level: "error", title: "Em dash in visible text",
+    why: "The em dash reads as machine-written copy; the kit's copy rules ban it in anything a visitor sees.",
+    fix: "Use a comma, a colon or a full stop.",
+  },
+  "img-alt": {
+    level: "error", title: "Image without alt",
+    why: "A screen reader reads out the file name of an image that has no alt.",
+    fix: "Add alt=\"what it shows\", or alt=\"\" when it is decoration.",
+  },
+  "vague-link": {
+    level: "error", title: "Link text that does not say where it goes",
+    why: "\"Learn more\" or \"click here\" means nothing out of context, for screen readers and for people scanning.",
+    fix: "Make the destination the link text, e.g. \"See pricing\" or \"Read the setup guide\".",
+  },
+  "multiple-h1": {
+    level: "error", title: "More than one h1",
+    why: "One h1 per page: it is the page's title for search engines and screen readers.",
+    fix: "Keep one h1 and make the others h2.",
+  },
+  "missing-lang": {
+    level: "error", title: "<html> without lang",
+    why: "Without lang, screen readers, browsers and translation tools guess the language.",
+    fix: "Add it, e.g. <html lang=\"en\">.",
+  },
+  "clickable-div": {
+    level: "error", title: "Clickable div or span",
+    why: "A div or span with onclick cannot be reached by keyboard and is not announced as a control.",
+    fix: "Use <a href> to go somewhere and <button type=\"button\"> to do something.",
+  },
+  "busy-button": {
+    level: "error", title: "Loading button not marked with aria-busy",
+    why: "The kit draws a waiting button from aria-busy=\"true\": the label keeps the width and the accessible name, the ring turns (still under reduced motion) and website.js ignores a second press. A loading class or a hand-made spinner does none of that, and disabled throws the keyboard focus back to the top of the page.",
+    fix: "While it waits, set aria-busy=\"true\" on the <button class=\"gw-btn\"> and remove it when the answer comes. No loading class, no spinner element, no disabled.",
+  },
+  "segmented-markup": {
+    level: "error", title: "Segmented control without its radio-group markup",
+    why: "website.js and screen readers find the choice through the markup: a radiogroup with a name and data-gw-segmented, two to four <button role=\"radio\"> options, exactly one aria-checked=\"true\". Without it the arrows do nothing and the choice is not announced.",
+    fix: "Copy the markup from docs/components.md (Segmented control) or templates/sections/pricing.html.",
+  },
+  "uppercase-text": {
+    level: "warning", title: "Uppercase text",
+    why: "Headings, buttons, labels and menu items are sentence case.",
+    fix: "Write it in sentence case instead of capitals or text-transform: uppercase.",
+  },
+  "illustrative-caption": {
+    level: "warning", title: "Numbers in a drawn mock-up with no caption",
+    why: "A drawn mock-up's numbers are made up. Without a caption a visitor reads them as a claim, and a claim found to be made up makes every other number on the page doubtful.",
+    fix: "Add <p class=\"gw-window__caption\">Illustrative data.</p> as the last child of the .gw-window (vi: Dữ liệu minh hoạ. zh: 示意数据。), or the source when the numbers are real.",
+  },
+  "possible-gap": {
+    level: "note", title: "Possible kit gap: a site class used on several pages",
+    why: "A site class styled in site CSS and used on 3 or more pages is often a reusable part the kit does not have yet.",
+    fix: "If it is reusable (a section shape, a component), move it to kit-gaps.css as kitgap-… and report it: npx gemboss-website gap. If it is page content (an illustration, a mock-up), ignore this note.",
+  },
+  "kitgap": {
+    level: "note", title: "Open stopgap (kitgap-*)",
+    why: "Site code standing in for something the kit should have.",
+    fix: "Make sure it is reported (npx gemboss-website gap) and that a comment names the gap number (/* gap #N */); upgrade tells you when the kit has it.",
+  },
+};
+const LEVEL_ORDER = { error: 0, warning: 1, note: 2 };
+const RULE_ORDER = Object.fromEntries(Object.keys(RULES).map((k, i) => [k, i]));
+
+// ---------------------------------------------------------------------------------------------- CSS parsing
+
+/** Split on commas at depth 0 (outside (), [] and strings). */
+export function splitTop(s, sepChar = ",") {
+  const out = [];
+  let depth = 0, q = null, start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (q) { if (ch === "\\") i++; else if (ch === q) q = null; continue; }
+    if (ch === '"' || ch === "'") q = ch;
+    else if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth = Math.max(0, depth - 1);
+    else if (ch === sepChar && depth === 0) { out.push(s.slice(start, i)); start = i + 1; }
+  }
+  out.push(s.slice(start));
+  return out.map((x) => x.trim()).filter(Boolean);
+}
+
+/** Remove fn(...) calls (with nested parens) for the given names. */
+function stripFns(value, names) {
+  const re = new RegExp(`\\b(?:${names.join("|")})\\(`, "gi");
+  let out = "", i = 0, m;
+  re.lastIndex = 0;
+  while ((m = re.exec(value))) {
+    out += value.slice(i, m.index);
+    let depth = 1, j = m.index + m[0].length;
+    for (; j < value.length && depth; j++) {
+      if (value[j] === "(") depth++;
+      else if (value[j] === ")") depth--;
+    }
+    out += " ";
+    i = j;
+    re.lastIndex = j;
+  }
+  return out + value.slice(i);
+}
+
+function resolveNested(sel, parent) {
+  if (!parent) return sel;
+  const p = splitTop(parent).length > 1 ? `:is(${parent})` : parent;
+  return splitTop(sel).map((s) => (s.includes("&") ? s.replace(/&/g, p) : `${p} ${s}`)).join(", ");
+}
+
+/**
+ * Parse CSS into flat rules { selector, at: [at-rule preludes], decls: [{ prop, value, line }], line }.
+ * Handles comments, strings, at-rule blocks and CSS nesting. `baseLine` offsets lines for <style> blocks.
+ */
+export function parseCss(css, baseLine = 1) {
+  const text = css.replace(/\/\*[\s\S]*?\*\//g, blank);
+  const lineAt = lineIndex(text);
+  const L = (off) => lineAt(off) + baseLine - 1;
+  const rules = [];
+  let i = 0;
+  const n = text.length;
+  function scan() {
+    let depth = 0, q = null;
+    const start = i;
+    for (; i < n; i++) {
+      const ch = text[i];
+      if (q) { if (ch === "\\") i++; else if (ch === q) q = null; continue; }
+      if (ch === '"' || ch === "'") q = ch;
+      else if (ch === "(") depth++;
+      else if (ch === ")") depth = Math.max(0, depth - 1);
+      else if (depth === 0 && (ch === "{" || ch === "}" || ch === ";")) return { start, end: i, ch };
+    }
+    return { start, end: n, ch: null };
+  }
+  function block(parentSel, at, rule) {
+    for (;;) {
+      const seg = scan();
+      const raw = text.slice(seg.start, seg.end);
+      const trimmed = raw.trim();
+      const off = seg.start + (raw.length - raw.trimStart().length);
+      if (seg.ch === "{") {
+        i++;
+        if (trimmed.startsWith("@")) {
+          const name = (/^@([\w-]+)/.exec(trimmed) || [, ""])[1].toLowerCase();
+          if (/^(media|supports|layer|container|document|scope|starting-style)$/.test(name)) block(parentSel, [...at, trimmed], null);
+          else if (/keyframes$/.test(name)) block(null, [...at, trimmed], null);
+          else {
+            const r = { selector: trimmed, at, decls: [], line: L(off), atBlock: true };
+            rules.push(r);
+            block(null, at, r);
+          }
+        } else {
+          const r = { selector: resolveNested(trimmed, parentSel), at, decls: [], line: L(off) };
+          rules.push(r);
+          block(r.selector, at, r);
+        }
+        continue;
+      }
+      if (trimmed && rule && !trimmed.startsWith("@")) {
+        const colon = trimmed.indexOf(":");
+        if (colon > 0) rule.decls.push({ prop: trimmed.slice(0, colon).trim().toLowerCase(), value: trimmed.slice(colon + 1).trim(), line: L(off) });
+      }
+      if (seg.ch === ";") { i++; continue; }
+      if (seg.ch === "}") i++;
+      return;
+    }
+  }
+  while (i < n) block(null, [], null);
+  return rules;
+}
+
+/** Declarations of a style="" attribute. */
+function parseInline(style, line) {
+  return splitTop(style, ";").map((d) => {
+    const colon = d.indexOf(":");
+    return colon > 0 ? { prop: d.slice(0, colon).trim().toLowerCase(), value: d.slice(colon + 1).trim(), line } : null;
+  }).filter(Boolean);
+}
+
+/** The rightmost compound selector, with :not()/:has() arguments removed (they do not style the subject). */
+export function subjectOf(sel) {
+  let s = sel;
+  for (let k; (k = s.search(/:(?:not|has)\(/i)) !== -1;) {
+    let depth = 0, j = s.indexOf("(", k);
+    for (; j < s.length; j++) {
+      if (s[j] === "(") depth++;
+      else if (s[j] === ")" && --depth === 0) break;
+    }
+    s = s.slice(0, k) + s.slice(j + 1);
+  }
+  s = s.trim();
+  let depth = 0, start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth--;
+    else if (depth === 0 && /[\s>+~]/.test(ch)) start = i + 1;
+  }
+  return s.slice(start).trim();
+}
+
+const ATTR_THEME = String.raw`\[\s*data-theme(?:\s*[~|^$*]?=\s*(?:"[^"]*"|'[^']*'|[\w-]+))?\s*\]`;
+const ROOTISH = new RegExp(`^(?::root|html)?(?:${ATTR_THEME}|:not\\(\\s*${ATTR_THEME}\\s*\\))*$`, "i");
+const isRootish = (sel) => splitTop(sel).every((s) => s && ROOTISH.test(s));
+const THEMABLE = /^--gw-(?:accent(?:-[\w-]+)?|on-accent(?:-(?:light|dark))?|wash(?:-[\w-]+)?)$/; // docs/theming.md: the eight accent variables (-light/-dark) + wash
+
+const COLOR_PROPS = /^(?:color|background(?:-color|-image)?|border(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?(?:-color)?|outline(?:-color)?|fill|stroke|text-decoration(?:-color)?|caret-color|accent-color|column-rule(?:-color)?|text-emphasis(?:-color)?|-webkit-text-fill-color|-webkit-text-stroke(?:-color)?|scrollbar-color|stop-color|flood-color|lighting-color)$/;
+const NAMED = new Set(("white black red green blue yellow orange purple pink gray grey silver gold navy teal maroon olive lime aqua " +
+  "cyan magenta fuchsia beige ivory linen wheat tan brown coral salmon crimson indigo violet lavender khaki whitesmoke " +
+  "gainsboro lightgray lightgrey darkgray darkgrey dimgray dimgrey snow ghostwhite floralwhite oldlace antiquewhite seashell " +
+  "cornsilk honeydew mintcream azure aliceblue mistyrose papayawhip bisque moccasin peachpuff lemonchiffon lightyellow").split(" "));
+
+function colorLiterals(value) {
+  const v = stripFns(value, ["var", "url", "env", "image-set"]).replace(/"[^"]*"|'[^']*'/g, " ");
+  const found = [];
+  for (const m of v.matchAll(/#[0-9a-f]{3,8}\b/gi)) if ([4, 5, 7, 9].includes(m[0].length)) found.push(m[0]);
+  for (const m of v.matchAll(/\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\([^)]*\)/gi)) found.push(m[0]);
+  for (const m of v.matchAll(/(?<![\w-])[a-z]+(?![\w-])/gi)) if (NAMED.has(m[0].toLowerCase())) found.push(m[0]);
+  return found;
+}
+
+const RADIUS_PROPS = /^border(?:-(?:top|bottom|start|end)-(?:left|right|start|end))?-radius$/;
+const SPACE_PROPS = /^(?:(?:margin|padding)(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?|(?:grid-)?(?:row-|column-)?gap)$/;
+const HALF_PX_PROPS = /^(?:width|height|(?:min|max)-(?:width|height)|inset(?:-[\w-]+)?|top|right|bottom|left|line-height|letter-spacing|word-spacing|border(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?(?:-width)?|outline(?:-width|-offset)?|flex-basis|text-indent|text-underline-offset|text-decoration-thickness)$/;
+const ILLUSTRATION = /illus|illo|artwork|mock|visual|graphic|scene|decor|drawing|figure|(?:^|[-_.\s])art(?:$|[-_\s])/i;
+const BUTTONISH = /btn|button/i;
+const pxNumbers = (v) => [...v.matchAll(/(-?\d*\.?\d+)(px|rem)\b/gi)].map((m) => ({ raw: m[0], px: Math.abs(parseFloat(m[1])) * (m[2].toLowerCase() === "rem" ? 16 : 1), unit: m[2].toLowerCase() }));
+const isFraction = (n) => Math.abs(n - Math.round(n)) > 1e-6;
+const normShadow = (s) => s.toLowerCase().replace(/\b0\./g, ".").replace(/\s*([,()])\s*/g, "$1").replace(/\s+/g, " ").trim();
+const TOKEN_SHADOWS = new Set(Object.entries(SYSTEM.shadow).filter(([k]) => !k.startsWith("$")).map(([, v]) => normShadow(v)));
+
+function okShadowPart(p) {
+  const v = p.trim();
+  if (/^var\(\s*--gw-shadow[\w-]*\s*\)$/i.test(v)) return true;
+  // A focus or hairline ring (0 0 0 Npx) is state, not elevation.
+  if (/^(?:inset\s+)?0(?:px)?\s+0(?:px)?\s+0(?:px)?\s+\d+(?:\.\d+)?px(?:\s|$)/i.test(v)) return true;
+  return false;
+}
+
+function excerptOf(selector, d) {
+  const s = `${selector ? selector + " { " : ""}${d.prop}: ${d.value}${selector ? " }" : ""}`.replace(/\s+/g, " ");
+  return s.length > 140 ? s.slice(0, 137) + "…" : s;
+}
+
+/**
+ * Check one rule and its declarations. `ctx`: { file, svg, inline } where svg = the CSS sits inside an <svg> (an
+ * illustration's own styles, where colours are allowed) and inline = a style="" attribute (no selector of its own).
+ */
+function checkRule(rule, ctx, add) {
+  if (rule.atBlock) return;
+  const sel = rule.selector || "";
+  const selNoNot = withoutNot(sel);
+  const illustration = ctx.svg || ILLUSTRATION.test(sel);
+  const rootish = sel && isRootish(sel);
+  let upper = null, tracking = false;
+  for (const d of rule.decls) {
+    const value = d.value.replace(/!important\s*$/i, "").trim();
+    const where = { file: ctx.file, line: d.line, excerpt: excerptOf(sel, d) };
+    if (d.prop.startsWith("--")) {
+      if (d.prop.startsWith("--gw-")) {
+        if (!(THEMABLE.test(d.prop) && rootish)) add("token-redefined", where);
+      } else if (!ctx.svg && colorLiterals(value).length) add("color-literal", where);
+      continue;
+    }
+    if (COLOR_PROPS.test(d.prop) && !ctx.svg && colorLiterals(value).length) add("color-literal", where);
+    if (RADIUS_PROPS.test(d.prop)) {
+      const v = stripFns(value, ["var", "calc"]);
+      for (const tok of v.split(/[\s/]+/).filter(Boolean)) {
+        const m = /^(-?\d*\.?\d+)(px|rem|%)?$/i.exec(tok);
+        if (!m) continue;
+        const unit = (m[2] || "px").toLowerCase();
+        if (unit === "%") { if (parseFloat(m[1]) !== 50) add("radius-off-scale", where); continue; }
+        const px = parseFloat(m[1]) * (unit === "rem" ? 16 : 1);
+        if (unit === "px" && isFraction(px)) add("half-pixel", where);
+        else if (!RADII.has(px)) add("radius-off-scale", where);
+      }
+    }
+    if (d.prop === "font-size" || d.prop === "font") checkFontSize(d, value, where, add);
+    if (SPACE_PROPS.test(d.prop)) {
+      for (const n of pxNumbers(stripFns(value, ["var", "calc"]))) {
+        if (n.unit === "px" && isFraction(n.px)) { add("half-pixel", where); break; }
+        if (n.px >= 1000) continue; // an off-screen trick, not spacing
+        if (!SPACE.has(n.px)) { add("space-off-scale", where); break; }
+      }
+    }
+    if (HALF_PX_PROPS.test(d.prop) && pxNumbers(value).some((n) => n.unit === "px" && isFraction(n.px))) add("half-pixel", where);
+    if (d.prop === "box-shadow" && !illustration && !/^(?:none|initial|inherit|unset|revert(?:-layer)?)$/i.test(value)) {
+      if (!TOKEN_SHADOWS.has(normShadow(value)) && !splitTop(value).every(okShadowPart)) add("shadow-not-token", where);
+    }
+    if (/^background(?:-color|-image)?$/.test(d.prop) && BUTTONISH.test(selNoNot) &&
+        (/var\(\s*--gw-(?:accent|wash)/i.test(value) || /gradient\(/i.test(value))) add("accent-button", where);
+    if (d.prop === "text-transform" && /\buppercase\b/i.test(value) && !/::?first-letter/i.test(sel)) upper = where;
+    if (d.prop === "letter-spacing" && !/^(?:normal|0(?:\.0+)?(?:px|em|rem)?|initial|inherit|unset)$/i.test(value)) tracking = true;
+  }
+  if (upper) add(tracking ? "uppercase-label" : "uppercase-text", upper);
+  if (!ctx.inline) {
+    for (const s of splitTop(sel)) {
+      if (/\.gw-[\w-]/.test(subjectOf(s))) { add("gw-override", { file: ctx.file, line: rule.line, excerpt: `${s} { … }` }); break; }
+    }
+  }
+}
+const withoutNot = (sel) => sel.replace(/:not\([^)]*\)/gi, "");
+
+function checkFontSize(d, value, where, add) {
+  let v = value;
+  if (d.prop === "font") {
+    // The size is the token with a unit right before "/line-height" or the family: font: 600 15px/1.4 var(--gw-font)
+    const m = /(?:^|\s)((?:clamp|min|max|calc)\([^)]*\)|-?\d*\.?\d+(?:px|rem|em|%|vw|vh|pt))(?=\s*\/|\s|$)/i.exec(stripFns(v, ["var"]));
+    if (!m) return;
+    v = m[1];
+  }
+  const nums = pxNumbers(stripFns(v, ["var"]));
+  if (!nums.length) return; // em, %, keywords, vw-only or a variable: not ours to judge
+  if (nums.some((n) => n.unit === "px" && isFraction(n.px))) { add("half-pixel", where); return; }
+  const fluid = /\b(?:clamp|min|max|calc)\(/i.test(v);
+  if (fluid && Math.max(...nums.map((n) => n.px)) > DISPLAY_ABOVE) return; // display sizes are fluid by design
+  for (const n of nums) {
+    if (n.px > DISPLAY_ABOVE) continue;
+    if (isFraction(n.px) || !TYPE.has(n.px)) { add("type-off-scale", where); return; }
+  }
+}
+
+// --------------------------------------------------------------------------------------------- HTML scanning
+
+const TAG_RE = /<([a-zA-Z][\w:-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*\/?>/g;
+const ATTR_RE = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", mdash: "—", ndash: "–", rarr: "→", larr: "←", hellip: "…", rsquo: "’", lsquo: "‘", ldquo: "“", rdquo: "”" };
+const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+  if (e[0] === "#") { const cp = e[1].toLowerCase() === "x" ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10); return Number.isFinite(cp) ? String.fromCodePoint(cp) : m; }
+  return ENTITIES[e.toLowerCase()] ?? m;
+});
+const EM_DASH_RE = /—|&mdash;|&#8212;|&#x0*2014;/gi;
+const hasEmDash = (s) => /—|&mdash;|&#8212;|&#x0*2014;/i.test(s);
+const VAGUE = new Set(["click here", "here", "learn more", "read more", "more", "see more", "find out more", "click", "this link", "link", "details", "more info"]);
+const LABELISH = /label|eyebrow|kicker|overline|badge|chip|btn|button|pill/i;
+const SKIP_CLASS = /^(?:gw-|is-|has-|js-|kitgap-)/;
+
+/** The end offset of the element whose start tag is at `start`, counting nested tags of the same name; -1 if unclosed. */
+function elementEnd(text, start, tag) {
+  const re = new RegExp(`<(/?)${tag}\\b[^>]*>`, "gi");
+  re.lastIndex = start;
+  let depth = 0;
+  for (let m; (m = re.exec(text));) {
+    if (m[1]) { if (--depth <= 0) return m.index + m[0].length; } else if (!m[0].endsWith("/>")) depth++;
+  }
+  return -1;
+}
+const LOADING_CLASS = /^(?:is-)?(?:loading|busy)$|--(?:loading|busy)$/;
+const SPINNER_CLASS = /\bclass\s*=\s*["'][^"']*(?:spinner|loader|loading)/i;
+
+function parseAttrs(s) {
+  const a = {};
+  for (const m of s.matchAll(ATTR_RE)) a[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
+  return a;
+}
+function ranges(text, re) { return [...text.matchAll(re)].map((m) => [m.index, m.index + m[0].length]); }
+const within = (rs, off) => rs.some(([a, b]) => off >= a && off < b);
+
+function shouty(text) {
+  const t = decode(text).trim();
+  if (!t || /\p{Ll}/u.test(t)) return false;
+  const words = t.match(/\p{Lu}{2,}/gu) || [];
+  return words.some((w) => w.length >= 5) || words.filter((w) => w.length >= 3).length >= 2;
+}
+
+function analyzeHtml(file, text, out) {
+  const relFile = rel(file);
+  const add = out.add;
+  const noComments = text.replace(/<!--[\s\S]*?-->/g, blank);
+  const lineAt = lineIndex(text);
+  // Raw-text elements: their content is code, never tags or visible copy.
+  const raw = [...noComments.matchAll(/<(script|style)\b([^>]*)>([\s\S]*?)<\/\1\s*>/gi)].map((m) => {
+    const start = m.index + m[0].indexOf(">") + 1;
+    return { tag: m[1].toLowerCase(), start, end: start + m[3].length };
+  });
+  let scanText = noComments;
+  for (const r of raw) scanText = scanText.slice(0, r.start) + blank(scanText.slice(r.start, r.end)) + scanText.slice(r.end);
+  const svg = ranges(scanText, /<svg\b[\s\S]*?<\/svg\s*>/gi);
+  const code = ranges(scanText, /<(pre|code|kbd|samp|template|svg)\b[\s\S]*?<\/\1\s*>/gi);
+
+  // <style> blocks: CSS rules apply, and lines point into the HTML file.
+  for (const r of raw.filter((x) => x.tag === "style")) {
+    const css = noComments.slice(r.start, r.end);
+    const rules = parseCss(css, lineAt(r.start));
+    const isSvg = within(svg, r.start);
+    for (const rule of rules) checkRule(rule, { file: relFile, svg: isSvg }, add);
+    out.cssRules.push({ file: relFile, rules, text, inline: true });
+  }
+
+  // Visible text: tags and code blanked, offsets kept.
+  let visible = scanText;
+  for (const [a, b] of code) visible = visible.slice(0, a) + blank(visible.slice(a, b)) + visible.slice(b);
+  visible = visible.replace(TAG_RE, blank).replace(/<\/[a-zA-Z][\w:-]*\s*>/g, blank).replace(/<![^>]*>/g, blank);
+  for (const m of visible.matchAll(EM_DASH_RE)) {
+    const ls = visible.lastIndexOf("\n", m.index) + 1, le = visible.indexOf("\n", m.index);
+    const around = decode(visible.slice(Math.max(ls, m.index - 60), Math.min(le === -1 ? visible.length : le, m.index + 60))).replace(/\s+/g, " ").trim();
+    add("em-dash", { file: relFile, line: lineAt(m.index), col: m.index, excerpt: around });
+  }
+
+  const classes = new Set();
+  let h1 = 0;
+  for (const m of scanText.matchAll(TAG_RE)) {
+    const tag = m[1].toLowerCase();
+    const a = parseAttrs(m[2] || "");
+    const line = lineAt(m.index);
+    const where = (excerpt) => ({ file: relFile, line, excerpt: excerpt ?? m[0].replace(/\s+/g, " ").slice(0, 140) });
+    if (tag === "img" && !("alt" in a)) add("img-alt", where());
+    if (tag === "h1" && ++h1 === 2) add("multiple-h1", where());
+    if (tag === "html" && !(a.lang || "").trim()) add("missing-lang", where());
+    if ((tag === "div" || tag === "span") && "onclick" in a) add("clickable-div", where());
+    for (const k of ["alt", "title", "aria-label", "placeholder"]) {
+      if (a[k] && hasEmDash(a[k])) add("em-dash", where(`${k}="${a[k]}"`));
+    }
+    if (tag === "meta" && /^(?:description|og:description|twitter:description)$/i.test(a.name || a.property || "") && hasEmDash(a.content || "")) {
+      add("em-dash", where(`content="${a.content}"`));
+    }
+    const cls = (a.class || "").split(/\s+/).filter(Boolean);
+    for (const k of cls) {
+      classes.add(k);
+      if (k.startsWith("kitgap-") && !out.kitgapUse.has(gapBlock(k))) out.kitgapUse.set(gapBlock(k), { file: relFile, line });
+    }
+    const inner = () => { const end = elementEnd(scanText, m.index, tag); return end < 0 ? "" : scanText.slice(m.index + m[0].length, end); };
+    if (cls.includes("gw-btn")) {
+      const busy = (a["aria-busy"] || "").trim() === "true";
+      if (busy ? "disabled" in a : cls.some((k) => LOADING_CLASS.test(k)) || SPINNER_CLASS.test(inner())) add("busy-button", where());
+    }
+    if (cls.includes("gw-segmented")) {
+      const opts = [...inner().matchAll(/<button\b([^>]*)>/gi)].map((x) => parseAttrs(x[1]));
+      const missing = [
+        a.role !== "radiogroup" && 'role="radiogroup"',
+        !(a["aria-label"] || a["aria-labelledby"]) && "aria-label",
+        !(a["data-gw-segmented"] || "").trim() && "data-gw-segmented=\"name\"",
+        (opts.length < 2 || opts.length > 4) && "two to four <button> options",
+        opts.some((o) => o.role !== "radio" || !("aria-checked" in o)) && 'role="radio" and aria-checked on each option',
+        opts.filter((o) => o["aria-checked"] === "true").length !== 1 && 'exactly one aria-checked="true"',
+      ].filter(Boolean);
+      if (missing.length) add("segmented-markup", where(`${m[0].replace(/\s+/g, " ").slice(0, 100)}  missing: ${missing.join(", ")}`));
+    }
+    if (cls.includes("gw-window")) {
+      const end = elementEnd(scanText, m.index, tag);
+      const body = end < 0 ? "" : scanText.slice(m.index, end);
+      const words = end < 0 ? "" : decode(visible.slice(m.index, end)).replace(/\s+/g, " ").trim();
+      if (/\d/.test(words) && !/<(?:img|picture|video|iframe|canvas)\b/i.test(body) && !/\bgw-window__caption\b/.test(body)) {
+        add("illustrative-caption", where(`${m[0].replace(/\s+/g, " ").slice(0, 60)} ${words.slice(0, 70)}`));
+      }
+    }
+    if ("style" in a && a.style.trim()) {
+      const selector = tag + (a.id ? `#${a.id}` : "") + cls.map((k) => "." + k).join("");
+      checkRule({ selector, decls: parseInline(decode(a.style), line), line }, { file: relFile, svg: within(svg, m.index), inline: true }, add);
+    }
+    if (tag === "a" && "href" in a) {
+      const end = m.index + m[0].length;
+      const close = scanText.slice(end).search(/<\/a\s*>/i);
+      if (close !== -1) {
+        const inner = scanText.slice(end, end + close);
+        const alts = [...inner.matchAll(/\balt\s*=\s*"([^"]*)"/gi)].map((x) => x[1]).join(" ");
+        let words = decode(inner.replace(/<[^>]*>/g, " ")).trim() || alts;
+        words = words.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
+        if (VAGUE.has(words)) add("vague-link", where(`<a href="${a.href}">${decode(inner.replace(/<[^>]*>/g, "")).trim()}</a>`));
+      }
+    }
+    if (cls.some((k) => LABELISH.test(k)) && tag !== "html" && tag !== "body") {
+      const after = scanText.slice(m.index + m[0].length, m.index + m[0].length + 200);
+      const txt = after.slice(0, after.search(/<|$/));
+      if (shouty(txt)) add("uppercase-text", where(`${m[0].slice(0, 60)}${txt.trim()}`));
+    }
+  }
+  out.pageClasses.push({ file: relFile, classes });
+}
+
+// ------------------------------------------------------------------------------------------------- running
+
+function isKitCopy(file, text) {
+  if (/^\s*\/\*!?\s*@gemboss\/website-ui\b/.test(text.slice(0, 400))) return true;
+  return /^website(?:\.min)?\.css$/.test(basename(file)) && /--gw-bg\s*:/.test(text) && /\.gw-btn\b/.test(text);
+}
+
+/** kitgap-tabs__tab--active -> kitgap-tabs: one stopgap per block. */
+const gapBlock = (k) => k.replace(/(__|--).*$/, "");
+
+/**
+ * Gap numbers (#N, or an issues/N URL) named on a stopgap's definition line or in the comment block right above it
+ * (up to a blank line or the end of the previous rule).
+ */
+export function gapRefsNear(text, line) {
+  const lines = text.split("\n");
+  const block = [lines[line - 1] || ""];
+  for (let i = line - 2; i >= 0 && i >= line - 12; i--) {
+    const l = lines[i];
+    if (!l.trim() || /[};]\s*$/.test(l.replace(/\/\*.*?\*\//g, ""))) break;
+    block.push(l);
+  }
+  const refs = new Set();
+  for (const m of block.join("\n").matchAll(/gap\s*#\s*(\d+)|\/issues\/(\d+)/gi)) refs.add(Number(m[1] || m[2]));
+  return [...refs];
+}
+
+/** Scan files; returns { files: {html, css}, findings }. */
+export function runCheck(paths, { ignore = [], includeKit = false } = {}) {
+  const files = walkFiles(paths, /\.(?:html?|css)$/i, { ignore, includeKit });
+  const findings = [];
+  const seen = new Set();
+  const add = (rule, w) => {
+    const key = `${rule}|${w.file}|${w.line}|${w.col ?? ""}|${w.excerpt}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    const r = RULES[rule];
+    findings.push({ rule, level: r.level, file: w.file, line: w.line, excerpt: w.excerpt, title: r.title, why: r.why, fix: r.fix });
+  };
+  const out = { add, cssRules: [], pageClasses: [], kitgapUse: new Map() };
+  const counts = { html: 0, css: 0, skipped: [] };
+  for (const f of files) {
+    let text;
+    try { text = readFileSync(f, "utf8"); } catch { continue; }
+    if (/\.css$/i.test(f)) {
+      // The kit's own CSS defines the .gw-* classes and the tokens: never site CSS, even with --include-kit.
+      if (isKitPath(f) || isKitCopy(f, text)) { counts.skipped.push(rel(f)); continue; }
+      counts.css++;
+      const rules = parseCss(text);
+      for (const rule of rules) checkRule(rule, { file: rel(f) }, add);
+      out.cssRules.push({ file: rel(f), rules, text });
+    } else {
+      counts.html++;
+      analyzeHtml(f, text, out);
+    }
+  }
+
+  // Classes styled in site CSS: first definition of each.
+  const styled = new Map();
+  for (const { file, rules, text } of [...out.cssRules].sort((a, b) => (a.inline ? 1 : 0) - (b.inline ? 1 : 0))) {
+    for (const r of rules) {
+      if (r.atBlock) continue;
+      for (const m of (r.selector || "").matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)) {
+        const k = m[1].startsWith("kitgap-") ? gapBlock(m[1]) : m[1];
+        if (!styled.has(k)) styled.set(k, { file, line: r.line, text });
+      }
+    }
+  }
+  // Possible gaps: a site class on 3+ pages that site CSS styles.
+  const pagesOf = new Map();
+  for (const { file, classes } of out.pageClasses) {
+    for (const k of classes) {
+      if (SKIP_CLASS.test(k) || !styled.has(k)) continue;
+      if (!pagesOf.has(k)) pagesOf.set(k, []);
+      pagesOf.get(k).push(file);
+    }
+  }
+  [...pagesOf].filter(([, p]) => p.length >= 3).sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0])).slice(0, 25)
+    .forEach(([k, pages]) => {
+      const d = styled.get(k);
+      add("possible-gap", { file: d.file, line: d.line, excerpt: `.${k} on ${pages.length} pages (${pages.slice(0, 3).join(", ")}${pages.length > 3 ? ", …" : ""})` });
+    });
+  // Open stopgaps.
+  const kitgaps = [];
+  const names = new Set([...styled.keys(), ...out.kitgapUse.keys()].filter((k) => k.startsWith("kitgap-")));
+  for (const k of [...names].sort()) {
+    const d = styled.get(k);
+    const at = d || out.kitgapUse.get(k);
+    const refs = d ? gapRefsNear(d.text, d.line) : [];
+    kitgaps.push({ class: k, file: at.file, line: at.line, refs });
+    add("kitgap", { file: at.file, line: at.line, excerpt: `.${k}${refs.length ? `  (gap ${refs.map((n) => "#" + n).join(", ")})` : "  (no gap number in a comment above it)"}${d ? "" : "  used in HTML, not styled in site CSS"}` });
+  }
+  findings.sort((a, b) => LEVEL_ORDER[a.level] - LEVEL_ORDER[b.level] || RULE_ORDER[a.rule] - RULE_ORDER[b.rule] ||
+    a.file.localeCompare(b.file) || a.line - b.line);
+  return { files: counts, findings, kitgaps };
+}
+
+const HELP_LIMIT = 40;
+
+export function cmdCheck(argv) {
+  const opts = parseArgs(argv, { json: "bool", "fix-list": "bool", ignore: "list", "include-kit": "bool" });
+  const paths = opts._.length ? opts._ : ["."];
+  for (const p of paths) if (!existsSync(p)) throw new UsageError(`no such file or folder: ${p}`);
+  const res = runCheck(paths.map((p) => resolve(p)), { ignore: opts.ignore, includeKit: opts["include-kit"] });
+  const n = { error: 0, warning: 0, note: 0 };
+  for (const f of res.findings) n[f.level]++;
+  const exit = n.error ? 1 : 0;
+  const plural = (k, w) => `${k} ${w}${k === 1 ? "" : "s"}`;
+  const summary = `${plural(n.error, "error")}, ${plural(n.warning, "warning")}, ${plural(n.note, "note")}`;
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      tool: "gemboss-website check", kit: `${PKG.name}@${PKG.version}`, cwd: process.cwd(), paths,
+      files: { html: res.files.html, css: res.files.css, skippedKitCopies: res.files.skipped },
+      summary: { errors: n.error, warnings: n.warning, notes: n.note, ok: !exit },
+      findings: res.findings, kitgaps: res.kitgaps,
+    }, null, 2) + "\n");
+    return exit;
+  }
+  const groups = new Map();
+  for (const f of res.findings) {
+    if (!groups.has(f.rule)) groups.set(f.rule, []);
+    groups.get(f.rule).push(f);
+  }
+  const head = `${res.files.html} HTML and ${res.files.css} CSS files checked against ${PKG.name} ${PKG.version}`;
+
+  if (opts["fix-list"]) {
+    const md = [`# Website check: to-do`, "", `${head}: ${summary}.`, ""];
+    for (const [level, heading] of [["error", "Errors (fix all of these)"], ["warning", "Warnings"], ["note", "Notes: possible gaps and open stopgaps"]]) {
+      const rules = [...groups].filter(([, fs]) => fs[0].level === level);
+      if (!rules.length) continue;
+      md.push(`## ${heading}`, "");
+      for (const [rule, fs] of rules) {
+        const r = RULES[rule];
+        md.push(`### ${rule}: ${r.title} (${fs.length})`, "", `Why: ${r.why}`, "", `Fix: ${r.fix}`, "");
+        for (const f of fs) md.push(`- [ ] \`${f.file}:${f.line}\` ${f.excerpt.replace(/`/g, "'")}`);
+        md.push("");
+      }
+    }
+    if (!res.findings.length) md.push("Nothing to do.", "");
+    md.push("Run `npx gemboss-website check` again when done. It does not replace looking at each page at 320px and 1366px.");
+    process.stdout.write(md.join("\n") + "\n");
+    return exit;
+  }
+
+  const lines = [c.bold("gemboss-website check") + `  ${head}`];
+  if (res.files.skipped.length) lines.push(c.dim(`(skipped kit copies: ${res.files.skipped.join(", ")})`));
+  if (!res.files.html && !res.files.css) lines.push("", `No .html, .htm or .css files under ${paths.join(", ")}.`);
+  for (const [rule, fs] of groups) {
+    const r = RULES[rule];
+    const tag = r.level === "error" ? c.red("error") : r.level === "warning" ? c.yellow("warning") : c.cyan("note");
+    lines.push("", `${tag} ${c.bold(rule)} (${fs.length}): ${r.title}`, `  why: ${r.why}`, `  fix: ${r.fix}`);
+    const width = Math.min(48, Math.max(...fs.map((f) => `${f.file}:${f.line}`.length)));
+    for (const f of fs.slice(0, HELP_LIMIT)) lines.push(`    ${`${f.file}:${f.line}`.padEnd(width)}  ${f.excerpt}`);
+    if (fs.length > HELP_LIMIT) lines.push(`    … ${fs.length - HELP_LIMIT} more (all of them: --fix-list or --json)`);
+  }
+  lines.push("", exit
+    ? `${c.red(summary)}. Fix the errors and run the check again.`
+    : `${c.green(summary)}. ${n.warning ? "No errors; look at the warnings." : "No errors."} Now look at each page at 320px and 1366px.`);
+  if (n.note) lines.push(c.dim("Notes do not fail the check. A real gap: npx gemboss-website gap (AGENTS.md section 9)."));
+  process.stdout.write(lines.join("\n") + "\n");
+  return exit;
+}