jig-ui 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.13.0
+
+Meaning before presentation, and one fewer step anyone can skip.
+
+### Added
+
+- **`H-119` A generic element where a native one says what the content is.**
+  The rule carries a decision order: what is this content, is there a native
+  element whose meaning is that, does it describe it accurately, does order or
+  relationship matter, can CSS do the presentation, and only then a generic
+  container. It is not a rule against `div` — a `div` is right where nothing
+  more specific is true, and an approximate element is worse than a generic
+  one because it asserts something untrue. Presentation must not be required
+  to understand the content.
+  Its detector decides what the source can: a page with no `<main>`, a row of
+  destinations in a header or footer with no `<nav>`, a generic element named
+  or styled as a heading, and a repeated set on a page with no list or table.
+- **`jig probe --run <page> --save <surface>`.** The CLI renders the page
+  itself, at 360, 768 and 1280, in a headless Chrome, Chromium or Edge it
+  finds for itself — including the browsers Playwright or Puppeteer have
+  already downloaded. No dependency: Chrome's own debugging protocol over the
+  WebSocket client Node has had since 22. The Stop hook runs it before judging
+  a critique, so a review is measured whether or not anyone remembered to.
+- **The probe measures markup order against reading order.** A block the CSS
+  lifts above the one that precedes it in the markup is reported, whatever the
+  verdicts say. Two columns side by side are not an inversion: putting the
+  sidebar after the main content and moving it left is the correct pattern.
+- **The probe reads the rendered text for em dashes.** A string built in code —
+  a description assembled in a framework's frontmatter, a label written by a
+  script — reaches the page having passed no file check.
+
+### Changed
+
+- **`I-118` reads every place a reader sees text.** Every template language the
+  suite knows, and the markdown a framework renders as pages. Repository
+  documents are still exempt, and capitals now mean "document" only beside the
+  lockfile, so `docs/FAQ.md` is a page. Code is not copy: a script's text is
+  read only between real tags.
+- **The scan skips `.claude`, `.codex`, `.cursor`, `.opencode`, `.gemini` and
+  `.github`.** Jig's own vendored rules are not the project's interface.
+- **Probe files are version 3.** Older ones no longer validate.
+
 ## 0.12.0
 
 ### Added

package/README.md

@@ -12,13 +12,13 @@ Installed as `npx jig-ui` — the bare name was taken on npm.
 Jig is **a skill your coding agent reads**, and **a CLI you can run yourself**.
 They are two halves of the same thing, and the split is not arbitrary:
 
-- Of the 114 rules, **17 can be decided by a machine** — a hard-coded colour, a
+- Of the 115 rules, **18 can be decided by a machine** — a hard-coded colour, a
   contrast ratio below the floor, a removed focus ring. The CLI decides those.
 - The other **97 are judgment** — whether an empty state says anything useful,
   whether a label reads as an instruction, whether motion earns its place. No
   regex settles those. An agent reads the rules and applies them.
 
-Running only the CLI gets you the 17. Running only the agent gets you the 97 with
+Running only the CLI gets you the 18. Running only the agent gets you the 97 with
 no verification. **A clean `jig check` is not a clean review**, and the skill
 says so to every agent that reads it.
 
@@ -371,7 +371,7 @@ treatment.
 
 | File | Contents |
 | --- | --- |
-| `rules/00-anti-patterns.md` | 96 universal rules with corrections |
+| `rules/00-anti-patterns.md` | 97 universal rules with corrections |
 | `rules/01-modes.md` | `editorial` / `product` / `operator` profiles |
 | `rules/02-tokens.md` | Token contract, naming, consumption |
 | `rules/03-patterns.md` | Component anatomy and behaviour |

package/dist/index.js

@@ -3,8 +3,8 @@
 // src/index.ts
 import { Command } from "commander";
 import { readFileSync as readFileSync28 } from "fs";
-import { homedir } from "os";
-import { join as join34 } from "path";
+import { homedir as homedir2 } from "os";
+import { join as join35 } from "path";
 
 // src/paths.ts
 import { existsSync } from "fs";
@@ -1472,7 +1472,17 @@ var EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "out",
   "coverage",
   ".svelte-kit",
-  "vendor"
+  "vendor",
+  // Where the agent harnesses keep their own files, including the copy of
+  // Jig's rules and slash command that `install` vendors. Those are the
+  // system's own text, not the project's interface: scanning them reported
+  // 115 em dashes in Jig's command file and called them the user's copy.
+  ".claude",
+  ".codex",
+  ".cursor",
+  ".opencode",
+  ".gemini",
+  ".github"
 ]);
 function isGitRepo(root) {
   try {
@@ -1796,6 +1806,35 @@ var STYLE_HOST_EXTENSIONS = [
 function isStyleBearing(file) {
   return hasExtension(file, CSS_EXTENSIONS) || hasExtension(file, STYLE_HOST_EXTENSIONS);
 }
+var MARKDOWN_EXTENSIONS = [".md", ".markdown", ".mdx"];
+var REPO_DOCUMENTS = /* @__PURE__ */ new Set([
+  "readme",
+  "changelog",
+  "contributing",
+  "license",
+  "licence",
+  "notice",
+  "code_of_conduct",
+  "security",
+  "support",
+  "governance",
+  "maintainers",
+  "authors",
+  "agents",
+  "claude",
+  "gemini",
+  "copilot-instructions"
+]);
+function isRepoDocument(file) {
+  const base = file.split("/").pop() ?? file;
+  const name = base.replace(/\.[^.]+$/, "");
+  if (REPO_DOCUMENTS.has(name.toLowerCase())) return true;
+  return !file.includes("/") && /^[A-Z0-9][A-Z0-9._-]*$/.test(name);
+}
+function isReaderText(file) {
+  if (hasExtension(file, MARKDOWN_EXTENSIONS)) return !isRepoDocument(file);
+  return hasExtension(file, STYLE_HOST_EXTENSIONS);
+}
 
 // src/check/run.ts
 import { readFileSync as readFileSync13 } from "fs";
@@ -3300,54 +3339,136 @@ var undeclaredToken = {
 };
 
 // src/check/detectors/em-dash.ts
-var MARKUP = [".html", ".htm", ".vue", ".svelte", ".astro", ".jsx", ".tsx", ".php", ".erb", ".twig", ".hbs"];
+var MARKDOWN = /\.(md|markdown|mdx)$/i;
+var INDENTED = /\.(pug|jade|haml|slim)$/i;
+var SCRIPT = /\.(js|mjs|cjs|ts|mts|cts)$/i;
+var CODEY = /[;{}`]|\$\{|=>/;
 var TEXT_ATTRS = /\b(aria-label|aria-description|aria-placeholder|title|placeholder|alt|label|value|content)\s*=\s*("([^"]*)"|'([^']*)')/gi;
 var EM_DASH = /—/;
+var TAG = /<\/?[A-Za-z][\w.:-]*(?:\s[^<>]*)?\/?>/g;
 function maskNonProse(source) {
   const blank3 = (m) => " ".repeat(m.length);
-  return source.replace(/<script\b[\s\S]*?<\/script\s*>/gi, blank3).replace(/<style\b[\s\S]*?<\/style\s*>/gi, blank3).replace(/<!--[\s\S]*?-->/g, blank3).replace(/\/\*[\s\S]*?\*\//g, blank3).replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + " ".repeat(m.length - p1.length));
+  return source.replace(/^---\n[\s\S]*?\n---/, blank3).replace(/<script\b[\s\S]*?<\/script\s*>/gi, blank3).replace(/<style\b[\s\S]*?<\/style\s*>/gi, blank3).replace(/<!--[\s\S]*?-->/g, blank3).replace(/\/\*[\s\S]*?\*\//g, blank3).replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + " ".repeat(m.length - p1.length));
 }
-function proseSpans(masked) {
+function markdownProse(source) {
+  const blank3 = (m) => " ".repeat(m.length);
+  return source.replace(/^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[^\n]*$/gm, blank3).replace(/`[^`\n]*`/g, blank3).replace(/<!--[\s\S]*?-->/g, blank3).replace(/\]\([^)\s]*/g, blank3);
+}
+function proseSpans(masked, edges) {
   const spans = [];
+  const tags = [...masked.matchAll(TAG)];
   let last = 0;
-  for (const tag of masked.matchAll(/<[^>]*>/g)) {
+  tags.forEach((tag, i) => {
     const between = masked.slice(last, tag.index);
-    if (between.trim()) spans.push({ index: last, text: between });
+    if (between.trim() && (edges || i > 0)) spans.push({ index: last, text: between });
     for (const attr of tag[0].matchAll(TEXT_ATTRS)) {
       const value = attr[3] ?? attr[4] ?? "";
       spans.push({ index: tag.index + attr.index + attr[0].indexOf(value), text: value });
     }
     last = tag.index + tag[0].length;
-  }
+  });
   const tail = masked.slice(last);
-  if (tail.trim()) spans.push({ index: last, text: tail });
+  if (tail.trim() && edges && tags.length > 0) spans.push({ index: last, text: tail });
   return spans;
 }
+function indentedProse(source) {
+  const blank3 = (m) => " ".repeat(m.length);
+  return source.split("\n").map((line) => /^\s*(-|\/\/|#(?!\w)|=)/.test(line) ? blank3(line) : line).join("\n");
+}
 var emDash = {
   name: "em-dash",
-  appliesTo: (file) => hasExtension(file, MARKUP),
+  appliesTo: (file) => isReaderText(file),
   run(_source, file, ctx) {
-    const masked = maskNonProse(ctx.raw);
+    const markdown = MARKDOWN.test(file);
+    const indented = INDENTED.test(file);
+    const masked = markdown ? markdownProse(ctx.raw) : indented ? indentedProse(maskNonProse(ctx.raw)) : maskNonProse(ctx.raw);
     const starts = buildLineIndex(ctx.raw);
     const findings = [];
     const seen = /* @__PURE__ */ new Set();
-    for (const span of proseSpans(masked)) {
+    const script = SCRIPT.test(file);
+    const spans = markdown || indented ? [{ index: 0, text: masked }] : proseSpans(masked, !script).filter((span) => !script || !CODEY.test(span.text));
+    for (const span of spans) {
       if (!EM_DASH.test(span.text)) continue;
-      const offset = span.index + span.text.indexOf("\u2014");
+      for (const hit of span.text.matchAll(/\u2014/g)) {
+        const line = lineForOffset(starts, span.index + hit.index);
+        if (seen.has(line)) continue;
+        seen.add(line);
+        findings.push(
+          mkFinding(
+            ctx,
+            "em-dash",
+            file,
+            line,
+            "an em dash in interface text: use a full stop, a comma, a colon, or a second element",
+            sourceLine(ctx.raw, line)
+          )
+        );
+      }
+    }
+    return findings.sort((a, b) => a.line - b.line);
+  }
+};
+
+// src/check/detectors/semantic-element.ts
+var BODY = /<body\b/i;
+var MAIN = /<main\b|role\s*=\s*["']main["']/i;
+var NAV_ELEMENT = /<nav\b|role\s*=\s*["']navigation["']/i;
+var CHROME = /<(header|footer)\b[\s\S]*?<\/\1\s*>/gi;
+var NAV_CONTAINER = /<(div|section|ul|span)\b[^>]*\b(?:class|className|id)\s*=\s*["'][^"']*\b(?:nav|navigation|navbar|menu)\b[^"']*["'][^>]*>/i;
+var LINK = /<a\b[^>]*\bhref\b/gi;
+var HEADING_SHAPED = /<(div|span|p)\b[^>]*\b(?:class|className)\s*=\s*["']([^"']*\b(?:title|heading|headline|text-(?:2xl|3xl|4xl|5xl))\b[^"']*)["'][^>]*>([\s\S]{0,120}?)<\/\1\s*>/gi;
+var HEADING_INSIDE = /<h[1-6]\b/i;
+var REPEATED = /<(div|article|section|a)\b[^>]*\b(?:class|className)\s*=\s*["']([^"']+)["']/gi;
+var LIST_OR_TABLE = /<(ul|ol|dl|table|tbody|menu)\b/i;
+var semanticElement = {
+  name: "semantic-element",
+  appliesTo: (file) => isReaderText(file),
+  run(_source, file, ctx) {
+    const raw = ctx.raw;
+    if (!BODY.test(raw)) return [];
+    const starts = buildLineIndex(raw);
+    const findings = [];
+    const at = (offset, message) => {
       const line = lineForOffset(starts, offset);
-      if (seen.has(line)) continue;
-      seen.add(line);
-      findings.push(
-        mkFinding(
-          ctx,
-          "em-dash",
-          file,
-          line,
-          "an em dash in interface text: use a full stop, a comma, a colon, or a second element",
-          sourceLine(ctx.raw, line)
-        )
+      findings.push(mkFinding(ctx, "semantic-element", file, line, message, sourceLine(raw, line)));
+    };
+    if (!MAIN.test(raw)) {
+      at(
+        BODY.exec(raw).index,
+        "this page has no <main> \u2014 nothing tells a reader skipping the chrome where the page itself starts"
       );
     }
+    if (!NAV_ELEMENT.test(raw)) {
+      const container = NAV_CONTAINER.exec(raw);
+      const links = (raw.match(LINK) ?? []).length;
+      if (container && links >= 3) {
+        at(container.index, "navigation links in a generic container, with no <nav> on the page \u2014 the element is what makes it a landmark, not the class name");
+      } else {
+        for (const region of raw.matchAll(CHROME)) {
+          if ((region[0].match(LINK) ?? []).length < 3) continue;
+          at(region.index, `the ${region[1].toLowerCase()} holds a row of links and the page has no <nav> \u2014 a set of destinations is a navigation landmark, and the element is what makes it one`);
+          break;
+        }
+      }
+    }
+    for (const m of raw.matchAll(HEADING_SHAPED)) {
+      if (HEADING_INSIDE.test(m[3])) continue;
+      const text = m[3].replace(/<[^>]*>/g, "").trim();
+      if (!text || text.length > 80) continue;
+      at(m.index, `"${text.slice(0, 40)}" is a ${m[1].toLowerCase()} named and styled as a heading \u2014 if it is the heading, it is an h1-h6, and CSS gives it the size`);
+    }
+    if (!LIST_OR_TABLE.test(raw)) {
+      const counts = /* @__PURE__ */ new Map();
+      for (const m of raw.matchAll(REPEATED)) {
+        const key = `${m[1].toLowerCase()}.${m[2].trim()}`;
+        const seen = counts.get(key) ?? { n: 0, index: m.index };
+        counts.set(key, { n: seen.n + 1, index: seen.index });
+      }
+      const repeated = [...counts.entries()].filter(([, v]) => v.n >= 3).sort((a, b) => a[1].index - b[1].index)[0];
+      if (repeated) {
+        at(repeated[1].index, `${repeated[1].n} sibling ${repeated[0]} elements are a repeated set, and nothing on this page is a list or a table \u2014 decide which collection this is (ul, ol, dl, table) before using a generic container`);
+      }
+    }
     return findings;
   }
 };
@@ -3370,7 +3491,8 @@ var DETECTORS = [
   safeArea,
   menuState,
   undeclaredToken,
-  emDash
+  emDash,
+  semanticElement
 ];
 function getDetector(name) {
   return DETECTORS.find((d) => d.name === name);
@@ -4934,8 +5056,8 @@ Could not write to ${wireTarget}: ${err.message}`);
 }
 
 // src/commands/verdicts.ts
-import { existsSync as existsSync18, readFileSync as readFileSync25 } from "fs";
-import { join as join31, resolve as resolve4 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync25 } from "fs";
+import { join as join32, resolve as resolve4 } from "path";
 
 // src/rules/citations.ts
 import { join as join28 } from "path";
@@ -4949,16 +5071,16 @@ function citableIds(packageRoot2) {
 }
 
 // src/probe/check.ts
-import { existsSync as existsSync17, readdirSync as readdirSync11, readFileSync as readFileSync24 } from "fs";
-import { join as join30 } from "path";
+import { existsSync as existsSync18, readdirSync as readdirSync13, readFileSync as readFileSync24 } from "fs";
+import { join as join31 } from "path";
 
 // src/probe/save.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync7, readFileSync as readFileSync23, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync7, readdirSync as readdirSync12, readFileSync as readFileSync23, writeFileSync as writeFileSync6 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join29, relative as relative3, resolve as resolve3 } from "path";
+import { join as join30, relative as relative3, resolve as resolve3 } from "path";
 
 // src/probe/script.ts
-var PROBE_VERSION = 2;
+var PROBE_VERSION = 3;
 var PROBE_SCRIPT = `(async () => {
   const doc = document.documentElement;
   const vis = (e) => { const r = e.getBoundingClientRect(); const s = getComputedStyle(e); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none'; };
@@ -4978,6 +5100,48 @@ var PROBE_SCRIPT = `(async () => {
       }
     }
   }
+  // Markup order against reading order (H-119). Only a vertical inversion
+  // counts: an element that sits entirely ABOVE another on screen while coming
+  // after it in the markup. Two columns side by side are not an inversion \u2014
+  // putting the sidebar after the main content and moving it left with CSS is
+  // the correct pattern, and flagging it would punish the right answer.
+  // What to call a region in a report: its own label, else its heading, else
+  // nothing. Its whole text content reads as gibberish inside a finding.
+  const label = (el) => {
+    const aria = (el.getAttribute('aria-label') || '').trim();
+    if (aria) return aria;
+    const id = el.getAttribute('aria-labelledby');
+    const target = id ? document.getElementById(id) : null;
+    const heading = target || (/^h[1-6]$/i.test(el.tagName) ? el : el.querySelector('h1, h2, h3, h4, h5, h6'));
+    const t = (heading ? heading.textContent : '').replace(/\\s+/g, ' ').trim();
+    return t.length > 42 ? t.slice(0, 40).trimEnd() + '\u2026' : t;
+  };
+  const all = [...document.querySelectorAll('main, nav, aside, header, footer, section, article, h1, h2, h3')].filter(vis);
+  // Only the outermost regions. A nested heading inverts with its own parent
+  // and with every sibling of it, so one swapped column reported four times.
+  const landmarks = all
+    .filter((el) => !all.some((other) => other !== el && other.contains(el)))
+    .map((el, order) => {
+      const r = el.getBoundingClientRect();
+      return {
+        order,
+        tag: el.tagName.toLowerCase(),
+        name: label(el),
+        top: Math.round(r.top + scrollY),
+        bottom: Math.round(r.bottom + scrollY),
+      };
+    });
+  const describe = (l) => '<' + l.tag + '>' + (l.name ? ' \u201C' + l.name + '\u201D' : '');
+  const inversions = [];
+  for (let i = 0; i < landmarks.length; i++) {
+    for (let j = i + 1; j < landmarks.length; j++) {
+      const earlier = landmarks[i], later = landmarks[j];
+      // The later element sits wholly above the earlier one, past a rounding wobble.
+      if (later.bottom - earlier.top <= 8 && later.top < earlier.top) {
+        inversions.push({ markupFirst: describe(earlier), seenFirst: describe(later) });
+      }
+    }
+  }
   const navLinks = () => [...document.querySelectorAll('nav a, header a, [role=navigation] a')].filter(vis).length;
   // Measured before anything is clicked: what a reader sees on arrival.
   const navAtRest = navLinks();
@@ -5022,12 +5186,183 @@ var PROBE_SCRIPT = `(async () => {
     defaultFont: getComputedStyle(document.body).fontFamily === defaultFont,
     unresolvedTokens: [...unresolved],
     junkText: junk,
+    emDashes: [...new Set((text.match(/[^.!?\\n]{0,28}\u2014[^.!?\\n]{0,28}/g) || []).map((t) => t.trim()))].slice(0, 5),
     brokenImages: [...document.images].filter((i) => i.complete && i.naturalWidth === 0).length,
     navLinksVisible: navAtRest,
+    landmarks: landmarks.map(describe),
+    orderInversions: inversions.slice(0, 5),
     menu,
   });
 })()`;
 
+// src/probe/browser.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync16, mkdtempSync, readdirSync as readdirSync11, rmSync as rmSync3 } from "fs";
+import { homedir, tmpdir } from "os";
+import { join as join29 } from "path";
+var CHROME_ENV = ["JIG_CHROME", "CHROME_PATH", "PUPPETEER_EXECUTABLE_PATH", "CHROMIUM_PATH"];
+var CHROME_COMMANDS = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge", "brave-browser"];
+var CHROME_APPS = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+  "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"
+];
+function cachedBrowsers() {
+  const roots = [
+    join29(homedir(), ".cache", "ms-playwright"),
+    join29(homedir(), "Library", "Caches", "ms-playwright"),
+    join29(homedir(), "AppData", "Local", "ms-playwright"),
+    join29(homedir(), ".cache", "puppeteer", "chrome")
+  ];
+  const found = [];
+  for (const root of roots) {
+    let entries;
+    try {
+      entries = readdirSync11(root);
+    } catch {
+      continue;
+    }
+    for (const entry of entries.sort().reverse()) {
+      for (const rel of [
+        ["chrome-linux", "chrome"],
+        ["chrome-linux64", "chrome"],
+        ["chrome-headless-shell-linux64", "chrome-headless-shell"],
+        ["chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium"],
+        ["chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"],
+        ["chrome-win", "chrome.exe"],
+        ["chrome-win64", "chrome.exe"]
+      ]) {
+        const candidate = join29(root, entry, ...rel);
+        if (existsSync16(candidate)) found.push(candidate);
+      }
+    }
+  }
+  return found;
+}
+function findChrome() {
+  for (const key of CHROME_ENV) {
+    const value = process.env[key];
+    if (value && existsSync16(value)) return value;
+  }
+  for (const command of CHROME_COMMANDS) {
+    const resolved = which(command);
+    if (resolved) return resolved;
+  }
+  for (const app of CHROME_APPS) if (existsSync16(app)) return app;
+  return cachedBrowsers()[0];
+}
+function which(command) {
+  const dirs = (process.env.PATH ?? "").split(process.platform === "win32" ? ";" : ":");
+  for (const dir of dirs) {
+    if (!dir) continue;
+    const candidate = join29(dir, command);
+    if (existsSync16(candidate)) return candidate;
+  }
+  return void 0;
+}
+async function runProbe(opts) {
+  const chrome = opts.chrome ?? findChrome();
+  if (!chrome) {
+    throw new Error(
+      "No browser found to run the probe. Install one, or set JIG_CHROME to a Chrome, Chromium or Edge binary. A project with Playwright or Puppeteer already has one, and Jig will find it."
+    );
+  }
+  const profile = mkdtempSync(join29(tmpdir(), "jig-probe-"));
+  const child = spawn(chrome, [
+    "--headless=new",
+    "--remote-debugging-port=0",
+    `--user-data-dir=${profile}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-gpu",
+    "--hide-scrollbars",
+    "--disable-extensions",
+    "--disable-background-networking",
+    "--no-sandbox",
+    "about:blank"
+  ], { stdio: ["ignore", "ignore", "pipe"] });
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  try {
+    const endpoint = await new Promise((done, fail) => {
+      const timer = setTimeout(() => fail(new Error(`${chrome} did not start within ${timeoutMs / 1e3}s.`)), timeoutMs);
+      let buffered = "";
+      child.stderr.on("data", (chunk) => {
+        buffered += chunk.toString();
+        const match = /ws:\/\/[^\s]+/.exec(buffered);
+        if (match) {
+          clearTimeout(timer);
+          done(match[0]);
+        }
+      });
+      child.on("exit", (code) => {
+        clearTimeout(timer);
+        fail(new Error(`${chrome} exited with code ${code} before it was ready.`));
+      });
+    });
+    return await evaluate(endpoint, opts.url, opts.width, opts.height ?? 900, timeoutMs);
+  } finally {
+    child.kill();
+    rmSync3(profile, { recursive: true, force: true });
+  }
+}
+async function evaluate(endpoint, url, width, height, timeoutMs) {
+  const socket = new WebSocket(endpoint);
+  let nextId = 1;
+  const pending = /* @__PURE__ */ new Map();
+  const loaded = { fired: false, waiters: [] };
+  await new Promise((done, fail) => {
+    socket.addEventListener("open", () => done(), { once: true });
+    socket.addEventListener("error", () => fail(new Error("Could not connect to the browser.")), { once: true });
+  });
+  socket.addEventListener("message", (event) => {
+    const message = JSON.parse(String(event.data));
+    if (message.id && pending.has(message.id)) {
+      const { done, fail } = pending.get(message.id);
+      pending.delete(message.id);
+      if (message.error) fail(new Error(message.error.message));
+      else done(message.result ?? {});
+    }
+    if (message.method === "Page.loadEventFired") {
+      loaded.fired = true;
+      for (const waiter of loaded.waiters.splice(0)) waiter();
+    }
+  });
+  const send = (method, params = {}, sessionId) => new Promise((done, fail) => {
+    const id = nextId++;
+    pending.set(id, { done, fail });
+    socket.send(JSON.stringify({ id, method, params, sessionId }));
+    setTimeout(() => {
+      if (pending.delete(id)) fail(new Error(`${method} timed out.`));
+    }, timeoutMs);
+  });
+  try {
+    const target = await send("Target.createTarget", { url: "about:blank" });
+    const attached = await send("Target.attachToTarget", { targetId: target.targetId, flatten: true });
+    const session = attached.sessionId;
+    await send("Page.enable", {}, session);
+    await send("Emulation.setDeviceMetricsOverride", { width, height, deviceScaleFactor: 1, mobile: false }, session);
+    await send("Page.navigate", { url }, session);
+    if (!loaded.fired) {
+      await Promise.race([
+        new Promise((done) => loaded.waiters.push(done)),
+        new Promise((done) => setTimeout(done, timeoutMs / 2))
+      ]);
+    }
+    await new Promise((done) => setTimeout(done, 250));
+    const result = await send("Runtime.evaluate", { expression: PROBE_SCRIPT, awaitPromise: true, returnByValue: true }, session);
+    const value = result.result?.value;
+    if (typeof value !== "string") {
+      const description = result.exceptionDetails?.text;
+      throw new Error(`The probe returned nothing${description ? `: ${description}` : ""}. Is ${url} a page this browser can open?`);
+    }
+    return value;
+  } finally {
+    socket.close();
+  }
+}
+
 // src/probe/save.ts
 function saveProbe(opts) {
   let probe;
@@ -5049,9 +5384,9 @@ function saveProbe(opts) {
   probe.pageFile = relative3(opts.projectRoot, page).split("\\").join("/");
   probe.pageChecksum = checksum(readFileSync23(page, "utf8"));
   probe.recordedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join29(opts.projectRoot, ".jig", "critique", opts.surface);
+  const dir = join30(opts.projectRoot, ".jig", "critique", opts.surface);
   mkdirSync7(dir, { recursive: true });
-  const path = join29(dir, `probe-${width}.json`);
+  const path = join30(dir, `probe-${width}.json`);
   writeFileSync6(path, JSON.stringify(probe), "utf8");
   return { path: `.jig/critique/${opts.surface}/probe-${width}.json`, width, page: probe.pageFile };
 }
@@ -5065,7 +5400,49 @@ function pageFile(projectRoot, url) {
   }
   const abs = resolve3(path);
   if (!abs.startsWith(resolve3(projectRoot))) return void 0;
-  return existsSync16(abs) ? abs : void 0;
+  return existsSync17(abs) ? abs : void 0;
+}
+var PROBE_WIDTHS = [360, 768, 1280];
+async function runAndSaveProbes(opts) {
+  const abs = resolve3(opts.projectRoot, opts.page);
+  if (!existsSync17(abs)) throw new Error(`${opts.page} does not exist, so there is nothing to render.`);
+  const url = /^https?:/i.test(opts.page) ? opts.page : `file://${abs}`;
+  const saved = [];
+  for (const width of opts.widths ?? PROBE_WIDTHS) {
+    const json = await runProbe({ url, width });
+    saved.push(saveProbe({ projectRoot: opts.projectRoot, surface: opts.surface, json }));
+  }
+  return saved;
+}
+async function ensureProbes(opts) {
+  const dir = join30(opts.projectRoot, ".jig", "critique", opts.surface);
+  const abs = resolve3(opts.projectRoot, opts.page);
+  let current;
+  try {
+    current = checksum(readFileSync23(abs, "utf8"));
+  } catch {
+    return { recorded: [], reason: `${opts.page} could not be read` };
+  }
+  const missing = PROBE_WIDTHS.filter((width) => {
+    try {
+      const probe = JSON.parse(readFileSync23(join30(dir, `probe-${width}.json`), "utf8"));
+      return probe.jigProbe !== PROBE_VERSION || probe.pageChecksum !== current;
+    } catch {
+      return true;
+    }
+  });
+  if (missing.length === 0) return { recorded: [] };
+  if (!findChrome()) return { recorded: [], reason: "no browser on this machine" };
+  const url = /^https?:/i.test(opts.page) ? opts.page : `file://${abs}`;
+  for (const width of missing) {
+    saveProbe({ projectRoot: opts.projectRoot, surface: opts.surface, json: await runProbe({ url, width }) });
+  }
+  return { recorded: missing };
+}
+function critiquedSurfaces(projectRoot) {
+  const root = join30(projectRoot, ".jig", "critique");
+  if (!existsSync17(root)) return [];
+  return readdirSync12(root).filter((surface) => existsSync17(join30(root, surface, "screen.json")) || existsSync17(join30(root, surface, "code.json")));
 }
 
 // src/probe/check.ts
@@ -5087,11 +5464,11 @@ function stampProblem(projectRoot, file, p) {
   return void 0;
 }
 function readProbes(projectRoot, dir, errors) {
-  if (!existsSync17(dir)) return [];
+  if (!existsSync18(dir)) return [];
   const probes = [];
-  for (const f of readdirSync11(dir).filter((n) => /^probe-\d+\.json$/.test(n)).sort()) {
+  for (const f of readdirSync13(dir).filter((n) => /^probe-\d+\.json$/.test(n)).sort()) {
     try {
-      const p = JSON.parse(readFileSync24(join30(dir, f), "utf8"));
+      const p = JSON.parse(readFileSync24(join31(dir, f), "utf8"));
       if (p.jigProbe !== PROBE_VERSION || typeof p.width !== "number") {
         errors.push(`${f} is not output of \`jig probe\` (version ${PROBE_VERSION}). Re-run the probe; do not write it by hand.`);
         continue;
@@ -5122,6 +5499,12 @@ function probeContradictions(probes, verdictOf) {
     if (p.unresolvedTokens.length) {
       errors.push(`${at(p)}: ${p.unresolvedTokens.length} token(s) have no value in the browser (${p.unresolvedTokens.slice(0, 6).join(", ")}) \u2014 every property using them is dropped (H-117).`);
     }
+    for (const inv of p.orderInversions ?? []) {
+      errors.push(`${at(p)}: "${inv.seenFirst}" is read first on screen but comes after "${inv.markupFirst}" in the markup. At this width the markup order is not the reading order (H-119) \u2014 reorder the document, or move it with CSS that leaves the order intact.`);
+    }
+    if (p.emDashes?.length) {
+      errors.push(`${at(p)}: the rendered page shows an em dash in ${p.emDashes.map((t) => `"${t}"`).join(", ")} (I-118) \u2014 use a full stop, a comma, a colon, or a second element.`);
+    }
     if (p.junkText.length) {
       errors.push(`${at(p)}: the rendered text contains ${p.junkText.map((j) => `"${j}"`).join(", ")} \u2014 template code or a failed value is showing to readers.`);
     }
@@ -5161,7 +5544,7 @@ function probeContradictions(probes, verdictOf) {
 var VERDICTS = ["ok", "finding", "n/a"];
 var ABSENCE = /\b(rule (not found|does not exist)|context unavailable|cannot (find|read|access) (the )?rule|not in (the )?(accessible )?corpus)\b/i;
 function readJson(path, errors) {
-  if (!existsSync18(path)) return null;
+  if (!existsSync19(path)) return null;
   try {
     return JSON.parse(readFileSync25(path, "utf8"));
   } catch (e) {
@@ -5170,8 +5553,8 @@ function readJson(path, errors) {
   }
 }
 function specNeedsNav(projectRoot, surface) {
-  const path = join31(projectRoot, ".jig", "specs", `${surface}.spec.md`);
-  if (!existsSync18(path)) return false;
+  const path = join32(projectRoot, ".jig", "specs", `${surface}.spec.md`);
+  if (!existsSync19(path)) return false;
   const front = readFileSync25(path, "utf8").split(/^---\s*$/m)[1] ?? "";
   const navField = [...front.matchAll(/^\s*nav:\s*(.+)$/gim)].some((m) => !/^\s*(none|n\/a|-)\b/i.test(m[1]));
   const navRegion = /^\s*-\s*(nav|navigation)\s*:/im.test(front);
@@ -5223,7 +5606,7 @@ function checkArm(name, file, required, otherPass, extraAllowed, extraRequired,
 function verifyVerdicts(opts) {
   const root = opts.packageRoot ?? assetRoot();
   const errors = [];
-  const index = JSON.parse(readFileSync25(join31(root, "rules.index.json"), "utf8"));
+  const index = JSON.parse(readFileSync25(join32(root, "rules.index.json"), "utf8"));
   const judgment = index.filter((r) => r.bucket === "judgment");
   const screenIds = judgment.filter((r) => r.pass === "screen").map((r) => r.id);
   const codeIds = judgment.filter((r) => r.pass === "code").map((r) => r.id);
@@ -5232,16 +5615,16 @@ function verifyVerdicts(opts) {
     ...judgment.map((r) => [r.id, r.pass ?? ""])
   ]);
   const specIds = new Set(citableIds(root).filter((id) => /^[PMLRT]-\d+$/.test(id)));
-  const dir = join31(opts.projectRoot, ".jig", "critique", opts.surface);
-  const screenFile = readJson(join31(dir, "screen.json"), errors);
-  const codeFile = readJson(join31(dir, "code.json"), errors);
+  const dir = join32(opts.projectRoot, ".jig", "critique", opts.surface);
+  const screenFile = readJson(join32(dir, "screen.json"), errors);
+  const codeFile = readJson(join32(dir, "code.json"), errors);
   const screenExtraRequired = specNeedsNav(opts.projectRoot, opts.surface) ? ["P-14"] : [];
   const screen = checkArm("screen", screenFile, screenIds, passOf, specIds, screenExtraRequired, errors);
   const code = checkArm("code", codeFile, codeIds, passOf, specIds, [], errors);
   let rendered = false;
   if (screenFile && screenFile.rendered === true) {
     const artefacts = Array.isArray(screenFile.artefacts) ? screenFile.artefacts.filter((a) => typeof a === "string") : [];
-    const absent = artefacts.filter((a) => !existsSync18(resolve4(opts.projectRoot, a)));
+    const absent = artefacts.filter((a) => !existsSync19(resolve4(opts.projectRoot, a)));
     if (artefacts.length === 0) errors.push("screen.json says rendered: true but lists no artefacts. A render leaves a screenshot.");
     else if (absent.length) errors.push(`screen.json says rendered: true, but these artefacts do not exist: ${absent.join(", ")}.`);
     else rendered = true;
@@ -5268,20 +5651,20 @@ function verifyVerdicts(opts) {
 }
 
 // src/commands/gate.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync8, readdirSync as readdirSync13, readFileSync as readFileSync27, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync21, mkdirSync as mkdirSync8, readdirSync as readdirSync15, readFileSync as readFileSync27, writeFileSync as writeFileSync7 } from "fs";
 import { createHash as createHash2 } from "crypto";
-import { join as join33 } from "path";
+import { join as join34 } from "path";
 
 // src/check/spec-shape.ts
-import { existsSync as existsSync19, readFileSync as readFileSync26, readdirSync as readdirSync12, statSync as statSync2 } from "fs";
-import { join as join32 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync26, readdirSync as readdirSync14, statSync as statSync2 } from "fs";
+import { join as join33 } from "path";
 function newestSpec(projectRoot) {
-  const dir = join32(projectRoot, ".jig", "specs");
-  if (!existsSync19(dir)) return void 0;
-  const files = readdirSync12(dir).filter((f) => f.endsWith(".md"));
+  const dir = join33(projectRoot, ".jig", "specs");
+  if (!existsSync20(dir)) return void 0;
+  const files = readdirSync14(dir).filter((f) => f.endsWith(".md"));
   if (files.length === 0) return void 0;
-  const newest = files.map((f) => ({ f, at: statSync2(join32(dir, f)).mtimeMs })).sort((a, b) => b.at - a.at)[0].f;
-  return { path: `.jig/specs/${newest}`, slug: newest.replace(/\.spec\.md$|\.md$/, ""), body: readFileSync26(join32(dir, newest), "utf8") };
+  const newest = files.map((f) => ({ f, at: statSync2(join33(dir, f)).mtimeMs })).sort((a, b) => b.at - a.at)[0].f;
+  return { path: `.jig/specs/${newest}`, slug: newest.replace(/\.spec\.md$|\.md$/, ""), body: readFileSync26(join33(dir, newest), "utf8") };
 }
 function specProblems(spec) {
   const parts = spec.body.split(/^---\s*$/m);
@@ -5350,7 +5733,7 @@ function navProblems(spec) {
 // src/commands/gate.ts
 var MAX_BLOCKS = 3;
 function lastJigCommand(transcriptPath) {
-  if (!transcriptPath || !existsSync20(transcriptPath)) return void 0;
+  if (!transcriptPath || !existsSync21(transcriptPath)) return void 0;
   let text;
   try {
     text = readFileSync27(transcriptPath, "utf8");
@@ -5371,7 +5754,7 @@ function commandProblems(root, command) {
   const problems = [];
   const spec = newestSpec(root);
   if (command === "decide") {
-    const file = ["jig/DECISIONS.md", "DECISIONS.md", ".jig/DECISIONS.md"].map((p) => join33(root, p)).find((p) => existsSync20(p));
+    const file = ["jig/DECISIONS.md", "DECISIONS.md", ".jig/DECISIONS.md"].map((p) => join34(root, p)).find((p) => existsSync21(p));
     if (!file) problems.push("decide wrote no DECISIONS.md beside the token layer.");
     else {
       const body = readFileSync27(file, "utf8");
@@ -5395,13 +5778,13 @@ function commandProblems(root, command) {
     const at = /^\s*mockup_at\s*:\s*(.+)$/im.exec(front)?.[1]?.trim().replace(/^["']|["']$/g, "") ?? "";
     if (/^approved/i.test(mockup)) {
       if (!at) problems.push(`${spec.path}: \`mockup_at:\` is empty. Record where the approved drawing is.`);
-      else if (!/^https?:/i.test(at) && !existsSync20(join33(root, at))) problems.push(`${spec.path}: \`mockup_at: ${at}\` does not exist.`);
+      else if (!/^https?:/i.test(at) && !existsSync21(join34(root, at))) problems.push(`${spec.path}: \`mockup_at: ${at}\` does not exist.`);
       else if (!/^https?:/i.test(at) && !at.startsWith(".jig/mockups/")) problems.push(`The drawing is at ${at}. A mockup lives in .jig/mockups/, outside what check scans and outside what ships.`);
     }
   }
   if (command === "critique") {
-    const dir = join33(root, ".jig", "critique");
-    const surfaces = existsSync20(dir) ? readdirSync13(dir).filter((s) => existsSync20(join33(dir, s, "screen.json")) || existsSync20(join33(dir, s, "code.json"))) : [];
+    const dir = join34(root, ".jig", "critique");
+    const surfaces = existsSync21(dir) ? readdirSync15(dir).filter((s) => existsSync21(join34(dir, s, "screen.json")) || existsSync21(join34(dir, s, "code.json"))) : [];
     for (const surface of surfaces) {
       const v = verifyVerdicts({ projectRoot: root, surface });
       if (v.ok && v.screen.state === "skipped") {
@@ -5414,9 +5797,19 @@ function commandProblems(root, command) {
   }
   return problems;
 }
+function surfacePage(projectRoot, surface) {
+  const spec = newestSpec(projectRoot);
+  const front = spec?.body.split(/^---\s*$/m)[1] ?? "";
+  const declared = /^\s*surface\s*:\s*(.+)$/im.exec(front)?.[1]?.trim().replace(/^["']|["']$/g, "");
+  const candidates = [declared, `${surface}.html`, declared ? `${declared.replace(/^\//, "")}.html` : void 0].filter((c) => !!c && /\.\w+$/.test(c) === (c === declared ? /\.\w+$/.test(c) : true));
+  for (const candidate of candidates) {
+    if (candidate && existsSync21(join34(projectRoot, candidate))) return candidate;
+  }
+  return void 0;
+}
 function gate(opts) {
   const root = opts.projectRoot;
-  if (!existsSync20(join33(root, "jig.config.json")) && !existsSync20(join33(root, ".jig"))) {
+  if (!existsSync21(join34(root, "jig.config.json")) && !existsSync21(join34(root, ".jig"))) {
     return { block: false, reason: "" };
   }
   const command = lastJigCommand(opts.input.transcript_path);
@@ -5435,11 +5828,11 @@ function gate(opts) {
       );
     }
   }
-  const critiqueDir = join33(root, ".jig", "critique");
-  if (existsSync20(critiqueDir)) {
-    for (const surface of readdirSync13(critiqueDir)) {
-      const dir = join33(critiqueDir, surface);
-      if (!existsSync20(join33(dir, "screen.json")) && !existsSync20(join33(dir, "code.json"))) continue;
+  const critiqueDir = join34(root, ".jig", "critique");
+  if (existsSync21(critiqueDir)) {
+    for (const surface of readdirSync15(critiqueDir)) {
+      const dir = join34(critiqueDir, surface);
+      if (!existsSync21(join34(dir, "screen.json")) && !existsSync21(join34(dir, "code.json"))) continue;
       const v = verifyVerdicts({ projectRoot: root, surface });
       if (!v.ok) {
         const shown = v.errors.slice(0, 6).map((e) => `  ${e}`);
@@ -5453,7 +5846,7 @@ function gate(opts) {
   }
   const session = opts.input.session_id ?? "unknown";
   const key = `${session}:${createHash2("sha256").update(problems.join("\n")).digest("hex").slice(0, 12)}`;
-  const stateFile = join33(root, ".jig", "gate.json");
+  const stateFile = join34(root, ".jig", "gate.json");
   let state = {};
   try {
     state = JSON.parse(readFileSync27(stateFile, "utf8"));
@@ -5486,7 +5879,7 @@ ${problems.join("\n\n")}`
 }
 function save(file, state) {
   try {
-    mkdirSync8(join33(file, ".."), { recursive: true });
+    mkdirSync8(join34(file, ".."), { recursive: true });
     writeFileSync7(file, JSON.stringify(state), "utf8");
   } catch {
   }
@@ -5494,7 +5887,7 @@ function save(file, state) {
 
 // src/index.ts
 var packageRoot = getPackageRoot();
-var { version } = JSON.parse(readFileSync28(join34(packageRoot, "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync28(join35(packageRoot, "package.json"), "utf8"));
 function warnIfUnpublishedPin() {
   if (isPublishedBuild(packageRoot)) return;
   console.warn(
@@ -5532,7 +5925,7 @@ program.command("install").description("Install Jig rules and the agent skill fi
       projectRoot,
       packageRoot: assetRoot(),
       version,
-      homeDir: homedir(),
+      homeDir: homedir2(),
       hook
     });
     if (result.warning) {
@@ -5570,7 +5963,7 @@ program.command("update").description("Update vendored Jig rules, skipping files
       projectRoot,
       packageRoot: assetRoot(),
       version,
-      homeDir: homedir()
+      homeDir: homedir2()
     });
     const label = result.targets.map((t) => `${t.agent} (${t.scope}, ${t.fromVersion})`).join(", ");
     warnIfUnpublishedPin();
@@ -5608,7 +6001,7 @@ program.command("check").description("Check the repo against Jig's mechanical +
   try {
     const result = check({
       projectRoot,
-      homeDir: homedir(),
+      homeDir: homedir2(),
       version,
       all: opts.all,
       ci: opts.ci
@@ -5620,7 +6013,23 @@ program.command("check").description("Check the repo against Jig's mechanical +
     process.exit(1);
   }
 });
-program.command("probe").description("Print the render probe. With --save, read what it returned on stdin and record it for `jig verdicts`.").option("--save <surface>", "record the probe's output (piped in) under .jig/critique/<surface>/").action(async (opts) => {
+program.command("probe").description("Print the render probe. With --save, read what it returned on stdin and record it for `jig verdicts`.").option("--save <surface>", "record the probe's output (piped in) under .jig/critique/<surface>/").option("--run <page>", "render this page here, at 360, 768 and 1280, and record each (needs --save)").action(async (opts) => {
+  if (opts.run) {
+    if (!opts.save) {
+      console.error("  \u2717 --run records what it measures, so it needs --save <surface>.");
+      process.exit(1);
+    }
+    const projectRoot2 = findProjectRoot(process.cwd());
+    try {
+      for (const saved of await runAndSaveProbes({ projectRoot: projectRoot2, surface: opts.save, page: opts.run })) {
+        console.log(`  Recorded ${saved.path} \u2014 ${saved.page} at ${saved.width}px.`);
+      }
+    } catch (err) {
+      console.error(`  \u2717 ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
   if (!opts.save) {
     console.log(PROBE_SCRIPT);
     return;
@@ -5643,7 +6052,7 @@ program.command("probe").description("Print the render probe. With --save, read
     process.exit(1);
   }
 });
-program.command("gate").description("Run by the Claude Code Stop hook: block stopping while check or a critique fails.").action(() => {
+program.command("gate").description("Run by the Claude Code Stop hook: block stopping while check or a critique fails.").action(async () => {
   let input = {};
   try {
     if (!process.stdin.isTTY) input = JSON.parse(readFileSync28(0, "utf8") || "{}");
@@ -5651,7 +6060,16 @@ program.command("gate").description("Run by the Claude Code Stop hook: block sto
   }
   const cwd = input.cwd ?? process.cwd();
   try {
-    const result = gate({ projectRoot: findProjectRoot(cwd), version, input });
+    const projectRoot = findProjectRoot(cwd);
+    for (const surface of critiquedSurfaces(projectRoot)) {
+      const page = surfacePage(projectRoot, surface);
+      if (!page) continue;
+      try {
+        await ensureProbes({ projectRoot, surface, page });
+      } catch {
+      }
+    }
+    const result = gate({ projectRoot, version, input });
     if (result.block) console.log(JSON.stringify({ decision: "block", reason: result.reason }));
     else if (result.reason) console.error(result.reason);
   } catch (err) {
@@ -5665,7 +6083,7 @@ program.command("init").description("Set the project up to use Jig: a brand file
     await init({
       projectRoot,
       packageRoot: assetRoot(),
-      homeDir: homedir(),
+      homeDir: homedir2(),
       version,
       yes: opts.yes
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jig-ui",
-  "version": "0.12.0",
-  "description": "A design system for coding agents. 114 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
+  "version": "0.13.0",
+  "description": "A design system for coding agents. 115 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {

package/rules/00-anti-patterns.md

@@ -544,6 +544,20 @@ Deletion is a real answer and the easy one to miss, because the correction point
 ❌ Scroll listeners for sticky positioning; scripted accordions and dialogs that have native equivalents
 ✅ Platform first: `position: sticky`, `<details>`, `<dialog>`, `:has()`, container queries, `scroll-behavior`, `popover`. Reach for a framework when the platform genuinely lacks the capability.
 
+### H-119 A generic element where a native one says what the content is
+❌ `<div class="page-title">Our products</div>`, a row of links in a `<div class="nav">`, a page whose top-level content sits in `<div class="main">`
+✅ `<h1>Our products</h1>`, `<nav>`, `<main>`. Choose the element from what the content **is**, then style it. The two versions can look identical; only one of them tells a screen reader, a search engine, a reader-mode button and a keyboard user what they are looking at.
+**The decision order**, before writing any markup:
+1. What is this content? A heading, a list, a sequence, a quotation, tabular data, navigation, a control, a landmark region?
+2. Is there a native element whose meaning is that? If yes, use it.
+3. Does it describe the content accurately, or only approximately? An approximate fit is worse than a generic container, because it asserts something untrue.
+4. Does the content have an order or a relationship that the markup should carry? Ordered steps are `<ol>`; rows and columns of related values are a `<table>`; a term and its explanation are `<dl>`.
+5. Can CSS produce the presentation without changing the element? It nearly always can.
+6. Only when no native element fits, a generic container.
+**This is not a rule against `div`.** A `div` is the right answer when nothing more specific is true: a grouping that exists for layout alone. What is forbidden is choosing an element for how it looks, or reaching for a generic one without asking steps 1 and 2.
+**Presentation must not be required to understand the content.** Turn the stylesheet off in your head: the page should still read as what it is, in an order that makes sense. A sidebar that must come first visually does not have to come first in the DOM, and usually should not (`L-01`).
+Related: `E-33` (an interactive `div`), `B-17` (heading levels), `H-48` (native elements over scripted ones), `P-14` (navigation).
+
 ### H-117 A token name nothing declares
 ❌ `font-family: var(--font-body)`, `padding: var(--space-lg)` — in a project whose token layer declares neither
 ✅ Use the names the token layer declares — `02-tokens.md` lists them, and the token files in the project are the source. If the value you need has no token, that is a finding to report or a value to delete (`H-47`), never a name to make up.

package/rules/01-modes.md

@@ -190,7 +190,7 @@ Attempting to vary these by mode is a category error:
 - **Accessibility floors.** Contrast, focus indication, target size, semantic markup. Identical in all three. `operator` being dense does not license a 24px tap target or a 3:1 body contrast.
 - **Brand identity.** Palette, typeface, logo, voice.
 - **State completeness.** Every mode renders loading, empty, error and disabled.
-- **The anti-pattern file.** All 96 rules in it apply everywhere.
+- **The anti-pattern file.** All 97 rules in it apply everywhere.
 
 ---
 

package/rules/05-copy.md

@@ -88,7 +88,7 @@ Whichever you choose, be consistent across sibling elements — a list where thr
 ✅ A full stop, a comma, a colon or a new element. "Your plan renews monthly, including every seat." "Free forever." "Deleted. This cannot be undone."
 Interface text is read in fragments, at a glance, in a space someone else's content has to fit too. An em dash is a pause the reader has to interpret: it stands in for a comma, a colon, a bracket or a full stop, and which one it is only becomes clear after reading past it. The punctuation that says exactly one thing is faster.
 It is also the clearest tell of machine-written copy. Generated text reaches for the em dash far more often than a person does, and readers have learned to notice. Copy that reads as generated is copy the reader trusts less, whatever it says.
-This is about interface strings — labels, buttons, headings, errors, empty states, help text, and the prose a page ships. It is not a rule about your documentation, your commit messages or this file.
+This is about interface strings: labels, buttons, headings, errors, empty states, help text, and the prose a page ships. Markdown counts where a framework renders it as a page, which is most of them (`src/content`, `content/`, MDX routes). A repository document does not: `README.md`, `CHANGELOG.md`, `AGENTS.md` and their kin are written for whoever works on the code, and so are your commit messages and this file.
 The en dash keeps its one job: ranges, where it is read as "to" (`2–10 seats`, `Mon–Fri`). That is not a pause, and it is not affected.
 
 ### I-87 Inconsistent vocabulary

package/rules.index.json

@@ -800,5 +800,12 @@
     "severity": "warning",
     "since": "0.12.0",
     "detector": "em-dash"
+  },
+  {
+    "id": "H-119",
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.13.0",
+    "detector": "semantic-element"
   }
 ]

package/templates/COMMAND.md.tmpl

@@ -318,6 +318,11 @@ deviations: []             # `make` writes here; `spec` leaves it empty
 - **No shell before there are features.** If the product has no navigation yet,
   `nav:` says `none yet` — it is decided once there is more than one feature to
   move between, not invented for the first one.
+- **Regions say what the content is, not what it looks like.** `- plans: three
+  cards` describes a shape; `- plans: a comparable set, one per tier` describes
+  content, and the second is what `make` can choose an element from. `H-119` runs
+  its decision order against these lines, so a region named only by its
+  appearance leaves the element to chance.
 - **`nav:` at every size, on any screen with navigation — decided by `P-14`'s table
   at that width, not copied.** It is the field most likely to be written once and
   copied, and most likely to be genuinely different at every size on a page that
@@ -641,6 +646,14 @@ change. Write base styles for the phone and add width as it is available — not
 the desktop layout with overrides that take it apart again. A layout built wide
 and subtracted from ends up correct at exactly the widths somebody checked.
 
+**Choose every element from what its content is, before styling any of it**
+(`H-119`). For each region in the spec, run the decision order: what is this
+content — a heading, a list, a sequence, a quotation, tabular data, navigation,
+a control, a landmark? Is there a native element whose meaning is that? Does it
+describe the content accurately? Only when nothing fits is a generic container
+right. The page must read as what it is with the stylesheet off, in an order
+that makes sense; CSS then arranges it, and never the reverse.
+
 Then the ordinary rules apply: tokens by semantic name, the relevant
 `03-patterns.md` section for each component, `05-copy.md` for every string.
 
@@ -852,12 +865,19 @@ Each reader arm writes its own file. The arm reports back only that it wrote it.
 probe in the browser and save what it returns beside the verdicts:
 
 ```
-{{scripts_path}} probe > .jig/probe.js
-# at each width: set the viewport, open the page, evaluate .jig/probe.js, and pipe
-# exactly what it returned into:
+# If a browser is on this machine, one command renders and records all three:
+{{scripts_path}} probe --run <page> --save <surface>
+
+# Otherwise, at each width: open the page in whatever browser you have, evaluate
+# what `{{scripts_path}} probe` prints, and pipe exactly what it returned into:
 {{scripts_path}} probe --save <surface>
 ```
 
+`--run` drives a headless Chrome, Chromium or Edge it finds for itself — a
+project with Playwright or Puppeteer already has one — and needs nothing
+installed. The Stop hook runs it too, before it judges a review, so a render is
+not a step anyone can forget.
+
 **The CLI writes the probe file, you do not.** `--save` reads the probe's output,
 stamps it with the page's checksum, and stores it. That is what makes the file a
 measurement: `verdicts` recomputes the checksum, so a file written by hand, or one
@@ -918,6 +938,13 @@ source and imagining the page is not a render.
   composition. The same layout with smaller numbers is not.
 - Check the page is styled at all. A stylesheet that 404s renders a page that
   passes every file-based check ever written.
+- **Read the markup as a document, not a layout** (`H-119`). For each region:
+  does its element say what the content is? Would the page still read correctly
+  with the stylesheet off, in this order? A row of links that is not a `<nav>`, a
+  heading that is a styled `<div>`, steps in no particular element, a comparison
+  of values that is not a table: each is a finding, and each names the element
+  the content asks for. A `<div>` is right where nothing more specific is true;
+  say so rather than inventing a fault.
 - Run the squint test from `L-01` against the render, not the analogue: render
   each size once more with `filter: grayscale(1)` on the root, and check that the
   primary action, the headings and the groups still read in order without colour.

package/templates/command-metadata.json

@@ -30,8 +30,8 @@
     "status": "available"
   },
   "probe": {
-    "description": "Print the render probe: a script the critique runs in a browser at 360, 768 and 1280px. With --save it records what the probe returned, stamped with the page's checksum, so `verdicts` can tell a measurement from a claim.",
-    "argumentHint": "[--save <surface>]",
+    "description": "Print the render probe, or run it here. `--run <page> --save <surface>` drives a headless browser it finds for itself and records the measurement at 360, 768 and 1280, stamped with the page's checksum, so `verdicts` can tell a measurement from a claim.",
+    "argumentHint": "[--run <page>] [--save <surface>]",
     "status": "available"
   },
   "gate": {