@ryuxdsgn/design-intelligence 2.14.2 → 2.18.0

package/README.md

@@ -22,6 +22,8 @@ npx @ryuxdsgn/design-intelligence                                          # sta
 npx @ryuxdsgn/design-intelligence setup                                    # teach RYUX about the project (DESIGN.md)
 npx @ryuxdsgn/design-intelligence setup --audience "..." --market "..."    # same, without questions
 npx @ryuxdsgn/design-intelligence check                                    # health check (exit 1 on problems)
+npx @ryuxdsgn/design-intelligence check --json                             # the same findings as JSON, for agents and CI
+npx @ryuxdsgn/design-intelligence init --agent claude --dry-run            # list what would change, write nothing
 npx @ryuxdsgn/design-intelligence init --agent claude                      # install + empty project context block
 npx @ryuxdsgn/design-intelligence install --agent claude,cursor,codex      # non-interactive
 npx @ryuxdsgn/design-intelligence install --agent all                      # every supported agent
@@ -35,12 +37,14 @@ npx @ryuxdsgn/design-intelligence remove --yes                             # rem
 | Command | What it does |
 | --- | --- |
 | `setup` | Asks a few questions with plain choices, "Write my own", or Skip: product, current work, audience, market and locale, constraints, design intent, and UX, UI, and motion direction. Saves the answers to the `<!-- ryux-context -->` block in `DESIGN.md`, changing only the fields you answer. The answers are direction, not evidence. Without a terminal, set fields with `--product`, `--work`, `--audience`, `--market`, `--constraints`, `--intent`, `--ux`, `--ui`, `--motion`. |
-| `init` | Installs RYUX, then adds a `<!-- ryux-context -->` block to `DESIGN.md` (product, audience, market and locale, design system, evidence sources, constraints), prefilled only with what it can detect. Re-running never overwrites what you wrote. |
-| `install` | Writes the `ryux/` skill into each agent's folder and a short pointer block into `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`. Interactive installs then offer `setup`. |
-| `check` (`doctor`) | Checks every install: all files present, frontmatter valid, version matches this CLI, every module reference resolves, no RYUX 1.x folders, pointer blocks, project context and how many setup fields are filled. Exits 1 on errors, so it works in CI. |
+| `init` | Installs RYUX, then adds a `<!-- ryux-context -->` block to `DESIGN.md` (product, audience, market and locale, design system, evidence sources, constraints), prefilled only with what it can detect. Re-running never overwrites what you wrote. `--dry-run` lists what it would create or update and writes nothing. |
+| `install` | Writes the `ryux/` skill into each agent's folder and a short pointer block into `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`. Interactive installs then offer `setup`. `--dry-run` lists the folders and blocks it would create or update and writes nothing. |
+| `check` (`doctor`) | Checks every install: all files present, frontmatter valid, version matches this CLI, every module reference resolves, no RYUX 1.x folders, pointer blocks, project context and how many setup fields are filled. Each problem names the command that fixes it. Exits 1 on errors, so it works in CI; `--json` prints `{ ok, cli, scope, installs, findings: [{ level, where, message, fix }] }`. |
 | `update` | Rewrites installs at this version and migrates RYUX 1.x. |
 | `remove` | Removes the skill and the pointer blocks. Leaves your `DESIGN.md` context. |
 
+Exit codes: 0 done or healthy, 1 a problem was found or the command failed, 2 the command was used wrongly (an unknown command or agent).
+
 One version: `packages/cli/package.json`. The skill header, the plugin manifests, and
 `ryux --version` all derive from it.
 

package/dist/cli/hook.js

@@ -0,0 +1,55 @@
+// The opt-in Claude Code hook that runs `ryux scan --hook` after each Edit or Write. It lives in
+// .claude/settings.json next to the user's own settings; only the RYUX entry is added, updated, or removed.
+import { join } from "node:path";
+import { CLI_CMD, VERSION } from "../product.js";
+import { readIfExists, writeFileEnsured } from "./fsutil.js";
+const SETTINGS = ".claude/settings.json";
+const MATCHER = "Edit|MultiEdit|Write";
+// Pinned to this version so every edit runs the same detectors; `update` moves the pin.
+const command = () => `${CLI_CMD.replace("npx ", "npx -y ")}@${VERSION} scan --hook`;
+const isOurs = (c) => typeof c === "string" && c.includes("@ryuxdsgn/design-intelligence") && c.includes("scan --hook");
+async function read(root) {
+    const raw = await readIfExists(join(root, SETTINGS));
+    if (raw === null)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+const ours = (s) => (s.hooks?.PostToolUse ?? []).filter((e) => e.hooks?.some((h) => isOurs(h.command)));
+export async function hasHook(root) {
+    const s = await read(root);
+    return Boolean(s && ours(s).length);
+}
+/** Add the hook, or move an existing one to this version. Throws when settings.json is not valid JSON,
+ *  so a file we cannot read is never overwritten. */
+export async function installHook(root) {
+    const s = await read(root);
+    if (!s)
+        throw new Error(`${SETTINGS} is not valid JSON; fix it, then run this again`);
+    const existing = ours(s);
+    if (existing.some((e) => e.hooks.some((h) => h.command === command())))
+        return `${SETTINGS} (scan hook already present)`;
+    const post = (s.hooks?.PostToolUse ?? []).filter((e) => !existing.includes(e));
+    s.hooks = { ...s.hooks, PostToolUse: [...post, { matcher: MATCHER, hooks: [{ type: "command", command: command() }] }] };
+    await writeFileEnsured(join(root, SETTINGS), `${JSON.stringify(s, null, 2)}\n`);
+    return `${SETTINGS} (scan hook ${existing.length ? "updated" : "added"})`;
+}
+/** Remove the RYUX entry and any hook lists it leaves empty. True when something was removed. */
+export async function removeHook(root) {
+    const s = await read(root);
+    if (!s || !ours(s).length)
+        return false;
+    const post = s.hooks.PostToolUse.filter((e) => !ours(s).includes(e));
+    if (post.length)
+        s.hooks.PostToolUse = post;
+    else
+        delete s.hooks.PostToolUse;
+    if (!Object.keys(s.hooks).length)
+        delete s.hooks;
+    await writeFileEnsured(join(root, SETTINGS), `${JSON.stringify(s, null, 2)}\n`);
+    return true;
+}

package/dist/cli/index.js

@@ -10,6 +10,8 @@ import { CLI_CMD, CONTEXT_END, CONTEXT_FILE, CONTEXT_START, MARK_START, MCP_STAT
 import { validateBundle } from "../validate.js";
 import { renderAgentsBlock, renderBundle, renderPointerBlock, SKILL_NAME } from "../render.js";
 import { hasBlock, readIfExists, rel, removeBlock, removePath, upsertBlock, writeFileEnsured } from "./fsutil.js";
+import { hasHook, installHook, removeHook } from "./hook.js";
+import { runScan } from "./scan.js";
 import { readFile, readdir } from "node:fs/promises";
 const AGENT_IDS = [...AGENT_TARGETS.map((a) => a.id), AGENTS_MD_INLINE.id];
 const targetDir = (a, scope) => join(scope.root, scope.global ? a.globalDir : a.dir);
@@ -73,6 +75,27 @@ async function install(agentIds, scope) {
     }
     return done;
 }
+/** What install would do, without writing: each skill folder and pointer block, created or updated. */
+async function planInstall(agentIds, scope) {
+    const plan = [];
+    for (const dir of dirsFor(agentIds, scope)) {
+        const skillDir = join(dir, SKILL_NAME);
+        const old = OLD_SKILL_DIRS.filter((n) => existsSync(join(dir, n))).length;
+        plan.push(`${existsSync(skillDir) ? "update" : "create"} ${rel(skillDir)}/ (${Object.keys(renderBundle()).length} files)`);
+        if (old)
+            plan.push(`replace ${old} RYUX 1.x folder${old === 1 ? "" : "s"} in ${rel(dir)}`);
+    }
+    if (scope.global)
+        return plan;
+    const inline = agentIds.includes(AGENTS_MD_INLINE.id);
+    const files = pointersFor(agentIds).filter((f) => !(f === "AGENTS.md" && inline));
+    for (const file of [...files, ...(inline ? ["AGENTS.md"] : [])]) {
+        const content = await readIfExists(join(scope.root, file));
+        const what = file === "AGENTS.md" && inline ? "rules inline" : "pointer block";
+        plan.push(content === null ? `create ${file} with the ${what}` : hasBlock(content) ? `update the ${what} in ${file}` : `add the ${what} to ${file} (the rest of the file is kept)`);
+    }
+    return plan;
+}
 const hasInstall = (dir) => existsSync(join(dir, SKILL_NAME, "SKILL.md")) || existsSync(join(dir, "ryux-core")) || existsSync(join(dir, "ryux-rules"));
 /** Skill folders that already hold a RYUX install (the single skill, or the RYUX 1.x folders). */
 function detectInstalled(scope) {
@@ -122,7 +145,7 @@ async function runInstall(flags) {
         showMcp = Boolean(flags.mcp);
         if (!agents.length) {
             console.error(`Invalid agent.\nAgents: ${AGENT_IDS.join(",")},all`);
-            process.exitCode = 1;
+            process.exitCode = 2;
             return;
         }
     }
@@ -153,7 +176,27 @@ async function runInstall(flags) {
         console.log(pc.yellow("agents-md is project-only; skipped for --global."));
         agents = agents.filter((x) => x !== AGENTS_MD_INLINE.id);
     }
+    let hook = Boolean(flags.hook);
+    if (!nonInteractive && agents.includes("claude")) {
+        const h = await p.confirm({ message: "Run ryux scan on each file Claude Code edits? (adds a hook to .claude/settings.json)", initialValue: false });
+        if (p.isCancel(h))
+            return cancel();
+        hook = h;
+    }
+    if (hook && !agents.includes("claude")) {
+        console.log(pc.yellow("--hook works with Claude Code only for now; skipped."));
+        hook = false;
+    }
+    if (flags["dry-run"]) {
+        const plan = await planInstall(agents, scope);
+        if (hook)
+            plan.push(`${(await hasHook(scope.root)) ? "update" : "add"} the scan hook in .claude/settings.json (runs ryux scan after each edit)`);
+        console.log(`Dry run: nothing was written. ${CLI_CMD} ${flags.init ? "init" : "install"} would:\n${plan.map((l) => `  ${l}`).join("\n")}`);
+        return;
+    }
     const written = await install(agents, scope);
+    if (hook)
+        written.push(await installHook(scope.root));
     const summary = written.map((w) => pc.green("✓ ") + w).join("\n");
     if (nonInteractive)
         console.log(summary);
@@ -196,6 +239,8 @@ async function runUpdate(flags) {
     const done = [];
     for (const dir of dirs)
         done.push(...(await writeSkills(dir, scope.root)));
+    if (await hasHook(scope.root))
+        done.push(await installHook(scope.root));
     if (!scope.global) {
         for (const file of ["CLAUDE.md", "GEMINI.md", "AGENTS.md"]) {
             const path = join(scope.root, file);
@@ -215,7 +260,7 @@ async function runRemove(flags) {
     const pointerFiles = scope.global ? [] : ["CLAUDE.md", "GEMINI.md", "AGENTS.md"];
     const hasBlocks = (await Promise.all(pointerFiles.map(async (f) => (await readIfExists(join(scope.root, f)))?.includes(MARK_START)))).some(Boolean);
     const hasLegacyCursor = existsSync(join(scope.root, LEGACY_CURSOR_RULES_DIR));
-    if (!hasSkills && !hasBlocks && !hasLegacyCursor) {
+    if (!hasSkills && !hasBlocks && !hasLegacyCursor && !(await hasHook(scope.root))) {
         console.log("No RYUX install found.");
         return;
     }
@@ -238,6 +283,8 @@ async function runRemove(flags) {
     for (const f of pointerFiles)
         if (await removeBlock(join(scope.root, f)))
             removed.push(`${f} (block)`);
+    if (await removeHook(scope.root))
+        removed.push(".claude/settings.json (scan hook)");
     console.log(removed.length ? removed.map((r) => pc.red("− ") + r).join("\n") : "No files removed.");
 }
 /** Read every file of an installed skill folder, keyed by its path inside the folder. */
@@ -253,53 +300,63 @@ async function readBundle(skillDir) {
 }
 async function runCheck(flags) {
     const scope = scopeOf(flags);
-    const ok = (m) => console.log(`${pc.green("✓")} ${m}`);
-    const warn = (m) => console.log(`${pc.yellow("!")} ${m}`);
-    const fail = (m) => {
-        console.log(`${pc.red("✗")} ${m}`);
-        process.exitCode = 1;
+    const findings = [];
+    const installs = [];
+    const add = (level, where, message, fix) => {
+        findings.push({ level, where, message, ...(fix ? { fix: `${CLI_CMD} ${fix}` } : {}) });
     };
     const dirs = detectInstalled(scope);
-    if (!dirs.length) {
-        fail(`RYUX is not installed ${scope.global ? "in your home directory" : "in this project"}. Run: ${CLI_CMD} init`);
-        return;
-    }
+    if (!dirs.length)
+        add("fail", scope.global ? "~" : ".", `RYUX is not installed ${scope.global ? "in your home directory" : "in this project"}`, "init");
     for (const dir of dirs) {
         const where = rel(dir);
         const skillDir = join(dir, SKILL_NAME);
         const leftovers = OLD_SKILL_DIRS.filter((n) => existsSync(join(dir, n)));
         if (leftovers.length)
-            fail(`${where}: RYUX 1.x folders remain (${leftovers.length}). Run: ${CLI_CMD} update`);
+            add("fail", where, `RYUX 1.x folders remain (${leftovers.length})`, "update");
         if (!existsSync(join(skillDir, "SKILL.md"))) {
-            fail(`${where}: no ${SKILL_NAME}/ skill. Run: ${CLI_CMD} update`);
+            add("fail", where, `no ${SKILL_NAME}/ skill`, "update");
             continue;
         }
         const report = validateBundle(await readBundle(skillDir));
+        installs.push({ dir: `${where}/${SKILL_NAME}`, version: report.version ?? null });
         for (const e of report.errors)
-            fail(`${where}/${SKILL_NAME}: ${e}`);
+            add("fail", `${where}/${SKILL_NAME}`, e, "update");
         for (const w of report.warnings)
-            warn(`${where}/${SKILL_NAME}: ${w}`);
+            add("warn", `${where}/${SKILL_NAME}`, w);
         if (report.version && report.version !== VERSION)
-            warn(`${where}: installed RYUX ${report.version}, this CLI is ${VERSION}. Run: ${CLI_CMD} update`);
+            add("warn", where, `installed RYUX ${report.version}, this CLI is ${VERSION}`, "update");
         if (!report.errors.length)
-            ok(`${where}/${SKILL_NAME}: complete, RYUX ${report.version}`);
+            add("ok", `${where}/${SKILL_NAME}`, `complete, RYUX ${report.version}`);
     }
-    if (!scope.global) {
+    if (dirs.length && !scope.global) {
         const agentsHere = agentsAt(scope, true);
         for (const file of pointersFor(agentsHere)) {
             if (hasBlock(await readIfExists(join(scope.root, file))))
-                ok(`${file}: RYUX pointer block present`);
+                add("ok", file, "RYUX pointer block present");
             else
-                warn(`${file}: no RYUX pointer block. Run: ${CLI_CMD} update`);
+                add("warn", file, "no RYUX pointer block", "update");
         }
         const context = contextBody(await readIfExists(join(scope.root, CONTEXT_FILE)));
         if (context !== null) {
-            ok(`${CONTEXT_FILE}: project context present, ${filledCount(context)} of ${ASKED_FIELDS.length} setup fields filled (blanks are treated as unknown)`);
+            add("ok", CONTEXT_FILE, `project context present, ${filledCount(context)} of ${ASKED_FIELDS.length} setup fields filled (blanks are treated as unknown)`);
         }
         else
-            warn(`${CONTEXT_FILE}: no RYUX project context. Run: ${CLI_CMD} setup`);
+            add("warn", CONTEXT_FILE, "no RYUX project context", "setup");
     }
-    if (!process.exitCode)
+    if (await hasHook(scope.root))
+        add("ok", ".claude/settings.json", "scan hook present");
+    const ok = !findings.some((f) => f.level === "fail");
+    if (!ok)
+        process.exitCode = 1;
+    if (flags.json) {
+        console.log(JSON.stringify({ ok, cli: VERSION, scope: scope.global ? "global" : "project", installs, findings }, null, 2));
+        return;
+    }
+    const mark = { ok: pc.green("✓"), warn: pc.yellow("!"), fail: pc.red("✗") };
+    for (const f of findings)
+        console.log(`${mark[f.level]} ${f.where}: ${f.message}${f.fix ? `. Run: ${f.fix}` : ""}`);
+    if (ok)
         console.log(pc.green("\nRYUX is ready."));
 }
 /** Facts init can detect without guessing: the project name and where design tokens live. */
@@ -660,9 +717,13 @@ async function runInit(flags) {
     const scope = scopeOf(flags);
     const path = join(scope.root, CONTEXT_FILE);
     const had = hasBlock(await readIfExists(path), CONTEXT_MARKS);
-    await runInstall(flags);
+    await runInstall({ ...flags, init: true });
     if (process.exitCode)
         return;
+    if (flags["dry-run"]) {
+        console.log(`  ${had ? `keep the project context in ${CONTEXT_FILE} as you wrote it` : `add the project context block to ${CONTEXT_FILE}`}`);
+        return;
+    }
     if (had) {
         console.log(`${pc.green("✓ ")}${CONTEXT_FILE}: project context already present (left as you wrote it). Edit it with: ${CLI_CMD} setup`);
     }
@@ -685,6 +746,9 @@ Commands:
   setup       Teach RYUX about this project: a few skippable questions, saved to DESIGN.md.
   init        Install RYUX and add the DESIGN.md project context block.
   check       Check the install: files, version, references, pointers, project context.
+  scan        Check source files for rules a machine can see (Rupiah format, alt text, zoom, focus, ...).
+              No LLM, no network. Default path: this folder. Give a URL to measure the rendered page
+              (sideways scroll, contrast, target size, colliding text); that needs Playwright.
   update      Update an install to this version (also migrates RYUX 1.x folders).
   remove      Remove RYUX and the marked blocks.
   help        Show this help.
@@ -698,6 +762,12 @@ Options:
   --global             install into your home directory instead of this project
   --mcp                print the ryux MCP connect command
   --yes                skip the confirmation (remove)
+  --dry-run            list what install or init would create or update, and write nothing
+  --json               print check's or scan's findings as JSON (for agents and CI)
+  --hook               install: run ryux scan after each Claude Code edit (opt-in)
+  --list-rules         scan: list what each check looks for
+  --ignore <ids>       scan: skip rules, e.g. RX-DS-03 (or a ryux-ignore RX-.. comment in the file)
+  --widths <list>      scan <url>: viewport widths in CSS px (default 320,390,1280)
   --product, --work, --audience, --market, --constraints, --intent, --ux, --ui, --motion <text>
                        set project context fields without questions (setup)
 
@@ -711,7 +781,15 @@ Examples:
   ${CLI_CMD} install --agent all
   ${CLI_CMD} install --agent claude --global
   ${CLI_CMD} update
-  ${CLI_CMD} remove --yes`);
+  ${CLI_CMD} remove --yes
+  ${CLI_CMD} init --agent claude --dry-run
+  ${CLI_CMD} check --json
+  ${CLI_CMD} scan src
+  ${CLI_CMD} scan http://localhost:3000/checkout
+  ${CLI_CMD} scan --list-rules
+  ${CLI_CMD} install --agent claude --hook
+
+Exit codes: 0 done or healthy, 1 a problem was found (for scan: a fail) or the command failed, 2 the command was used wrongly.`);
 }
 async function main() {
     const argv = process.argv.slice(2);
@@ -730,6 +808,8 @@ async function main() {
         case "check":
         case "doctor":
             return runCheck(flags);
+        case "scan":
+            return runScan(argv.slice(1));
         case "init":
             return runInit(flags);
         case "setup":
@@ -741,7 +821,7 @@ async function main() {
         default:
             console.error(`Unknown command: ${cmd}\n`);
             help();
-            process.exitCode = 1;
+            process.exitCode = 2;
     }
 }
 main().catch((err) => {

package/dist/cli/page-probe.js

@@ -0,0 +1,228 @@
+// @ts-nocheck: this function runs inside the page (Playwright serializes it), where the DOM exists;
+// the package compiles for Node without DOM types.
+// Measures a rendered page at the current viewport: horizontal scroll, text contrast, text size,
+// target size, and text that collides. Returns plain findings; the caller adds the width and URL.
+export function probe() {
+    const out = [];
+    const vw = document.documentElement.clientWidth;
+    const selector = (el) => {
+        const parts = [];
+        for (let e = el; e && e !== document.body && parts.length < 3; e = e.parentElement) {
+            let s = e.tagName.toLowerCase();
+            if (e.id) {
+                parts.unshift(`${s}#${e.id}`);
+                break;
+            }
+            const cls = typeof e.className === "string" ? e.className.trim().split(/\s+/)[0] : "";
+            if (cls)
+                s += `.${cls}`;
+            parts.unshift(s);
+        }
+        return parts.join(" > ");
+    };
+    const style = (el) => getComputedStyle(el);
+    const shown = (el) => {
+        for (let e = el; e; e = e.parentElement) {
+            const cs = style(e);
+            if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+                return false;
+            // Visually hidden (the sr-only pattern): clipped, or inside a box of 1px or less that hides overflow.
+            if ((cs.clip && cs.clip !== "auto") || /inset\(50%\)/.test(cs.clipPath))
+                return false;
+            const box = e.getBoundingClientRect();
+            if (cs.overflow !== "visible" && (box.width <= 1 || box.height <= 1))
+                return false;
+        }
+        const r = el.getBoundingClientRect();
+        return r.width > 1 && r.height > 1;
+    };
+    const disabled = (el) => Boolean(el.closest("[disabled],[aria-disabled='true'],[inert]"));
+    const quote = (s) => (s.length > 40 ? `"${s.slice(0, 37)}..."` : `"${s}"`);
+    // Horizontal scroll (RX-RD-01): name the outermost elements that reach past the viewport.
+    if (document.documentElement.scrollWidth > vw + 1) {
+        const culprits = [...document.body.querySelectorAll("*")].filter((el) => {
+            const r = el.getBoundingClientRect();
+            const p = el.parentElement?.getBoundingClientRect();
+            return r.right > vw + 1 && r.width > 0 && (!p || p.right <= vw + 1) && shown(el);
+        });
+        const names = culprits.slice(0, 3).map((el) => `${selector(el)} (to ${Math.round(el.getBoundingClientRect().right)}px)`);
+        out.push({
+            rule: "RX-RD-01",
+            level: "fail",
+            selector: culprits[0] ? selector(culprits[0]) : "html",
+            message: `the page scrolls sideways: ${document.documentElement.scrollWidth}px of content in ${vw}px${names.length ? `; widest: ${names.join(", ")}` : ""}`,
+        });
+    }
+    // Text: every visible element with its own text.
+    const texts = [];
+    for (const el of document.body.querySelectorAll("*")) {
+        if (/^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE|OPTION)$/.test(el.tagName) || el.closest("svg"))
+            continue;
+        const nodes = [...el.childNodes].filter((n) => n.nodeType === 3 && n.textContent.trim());
+        if (!nodes.length || !shown(el))
+            continue;
+        texts.push({ el, nodes, text: nodes.map((n) => n.textContent).join(" ").replace(/\s+/g, " ").trim() });
+    }
+    const rgba = (c) => {
+        const m = c.match(/rgba?\(([^)]+)\)/);
+        if (!m)
+            return null;
+        const [r, g, b, a = 1] = m[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+        return [r, g, b, a];
+    };
+    const over = (top, bottom) => {
+        const a = top[3];
+        return [0, 1, 2].map((i) => top[i] * a + bottom[i] * (1 - a)).concat(1);
+    };
+    // The solid color behind an element, or null when an image, gradient, or blend makes it unknown.
+    const background = (el) => {
+        const layers = [];
+        for (let e = el; e; e = e.parentElement) {
+            const cs = style(e);
+            if (cs.backgroundImage !== "none" || cs.mixBlendMode !== "normal" || (cs.filter && cs.filter !== "none"))
+                return null;
+            const c = rgba(cs.backgroundColor);
+            if (c && c[3] > 0) {
+                layers.push(c);
+                if (c[3] >= 1)
+                    break;
+            }
+        }
+        let color = [255, 255, 255, 1];
+        for (const layer of layers.reverse())
+            color = over(layer, color);
+        return color;
+    };
+    const luminance = ([r, g, b]) => [r, g, b]
+        .map((v) => v / 255)
+        .map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+        .reduce((sum, v, i) => sum + v * [0.2126, 0.7152, 0.0722][i], 0);
+    // True when something other than the element's own ancestors sits under its text (an image or a
+    // positioned sibling), so the ancestor background is not what the reader sees.
+    const coveredBy = (t) => {
+        t.el.scrollIntoView({ block: "center" });
+        const range = document.createRange();
+        range.setStartBefore(t.nodes[0]);
+        range.setEndAfter(t.nodes[t.nodes.length - 1]);
+        const r = range.getBoundingClientRect();
+        const stack = document.elementsFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        const below = stack.find((e) => !t.el.contains(e));
+        return Boolean(below && !below.contains(t.el));
+    };
+    const hex = (c) => `#${c.slice(0, 3).map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
+    // Contrast (RX-A11Y-01) and size (RX-A11Y-02), grouped so one style used 40 times is one finding.
+    const contrast = new Map();
+    const small = new Map();
+    for (const t of texts) {
+        const cs = style(t.el);
+        const size = Number.parseFloat(cs.fontSize);
+        if (size < 12) {
+            const g = small.get(size) ?? { t, count: 0 };
+            g.count++;
+            small.set(size, g);
+        }
+        if (disabled(t.el) || cs.webkitTextFillColor === "rgba(0, 0, 0, 0)")
+            continue;
+        const bg = background(t.el);
+        const fgRaw = rgba(cs.color);
+        if (!bg || !fgRaw)
+            continue;
+        const fg = fgRaw[3] < 1 ? over(fgRaw, bg) : fgRaw;
+        const [hi, lo] = [luminance(fg), luminance(bg)].sort((a, b) => b - a);
+        const ratio = (hi + 0.05) / (lo + 0.05);
+        const large = size >= 24 || (size >= 18.66 && Number(cs.fontWeight) >= 700);
+        const need = large ? 3 : 4.5;
+        if (ratio >= need || coveredBy(t))
+            continue;
+        const key = `${hex(fg)}|${hex(bg)}|${need}`;
+        const g = contrast.get(key) ?? { t, ratio, fg, bg, need, count: 0 };
+        g.count++;
+        contrast.set(key, g);
+    }
+    for (const g of contrast.values()) {
+        out.push({
+            rule: "RX-A11Y-01",
+            level: "fail",
+            selector: selector(g.t.el),
+            message: `${quote(g.t.text)}: contrast ${g.ratio.toFixed(2)}:1 (${hex(g.fg)} on ${hex(g.bg)}), needs ${g.need}:1${g.count > 1 ? `; ${g.count - 1} more with the same colors` : ""}`,
+        });
+    }
+    for (const [size, g] of small) {
+        out.push({
+            rule: "RX-A11Y-02",
+            level: "warn",
+            selector: selector(g.t.el),
+            message: `${quote(g.t.text)}: ${size}px text${g.count > 1 ? ` (${g.count} elements)` : ""}; body text is 14 to 16px on mobile, below 12px is hard to read`,
+        });
+    }
+    window.scrollTo(0, 0);
+    // Target size (RX-A11Y-02): under 24px fails unless spaced as WCAG 2.5.8 allows; inline links in a
+    // sentence are exempt.
+    const controls = [
+        ...document.body.querySelectorAll("a[href],button,input:not([type=hidden]),select,textarea,summary,[role=button],[role=link],[role=checkbox],[role=radio],[role=switch],[role=tab],[role=menuitem]"),
+    ].filter((el) => shown(el) && !disabled(el));
+    const rects = controls.map((el) => el.getBoundingClientRect());
+    const inSentence = (el) => {
+        if (el.tagName !== "A" || style(el).display !== "inline")
+            return false;
+        const block = el.parentElement;
+        return Boolean(block && block.textContent.replace(el.textContent, "").trim().length > 0);
+    };
+    const center = (r) => [r.left + r.width / 2, r.top + r.height / 2];
+    const undersized = controls.map((el, i) => (rects[i].width < 24 || rects[i].height < 24) && !inSentence(el));
+    controls.forEach((el, i) => {
+        if (!undersized[i])
+            return;
+        const [cx, cy] = center(rects[i]);
+        const crowded = rects.some((r, j) => {
+            if (j === i || el.contains(controls[j]) || controls[j].contains(el))
+                return false;
+            if (undersized[j]) {
+                const [x, y] = center(r);
+                return Math.hypot(cx - x, cy - y) < 24;
+            }
+            const dx = Math.max(r.left - cx, 0, cx - r.right);
+            const dy = Math.max(r.top - cy, 0, cy - r.bottom);
+            return Math.hypot(dx, dy) < 12;
+        });
+        const size = `${Math.round(rects[i].width)}x${Math.round(rects[i].height)}px`;
+        const name = quote((el.getAttribute("aria-label") || el.textContent || el.tagName.toLowerCase()).trim().replace(/\s+/g, " "));
+        out.push(crowded
+            ? { rule: "RX-A11Y-02", level: "fail", selector: selector(el), message: `${name}: target ${size}, under 24x24 and crowded by its neighbours; 44x44 is the preferred hit area` }
+            : { rule: "RX-A11Y-02", level: "warn", selector: selector(el), message: `${name}: target ${size}, under 24x24 (spaced enough to pass WCAG 2.5.8); 44x44 is the preferred hit area` });
+    });
+    // Colliding text (RX-QA-03): the text boxes of two unrelated elements overlap.
+    const boxes = texts.slice(0, 1500).map((t) => {
+        const range = document.createRange();
+        range.setStartBefore(t.nodes[0]);
+        range.setEndAfter(t.nodes[t.nodes.length - 1]);
+        return { t, r: range.getBoundingClientRect() };
+    });
+    // Content that scrolls under a fixed or sticky bar is not a collision.
+    const pinned = (el) => {
+        for (let e = el; e; e = e.parentElement)
+            if (/^(fixed|sticky)$/.test(style(e).position))
+                return true;
+        return false;
+    };
+    const seen = new Set();
+    for (let i = 0; i < boxes.length; i++) {
+        for (let j = i + 1; j < boxes.length; j++) {
+            const a = boxes[i];
+            const b = boxes[j];
+            if (a.t.el.contains(b.t.el) || b.t.el.contains(a.t.el) || pinned(a.t.el) !== pinned(b.t.el))
+                continue;
+            const w = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+            const h = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+            if (w <= 2 || h <= 2)
+                continue;
+            const smaller = Math.min(a.r.width * a.r.height, b.r.width * b.r.height);
+            if (w * h < 0.3 * smaller || seen.has(a.t.el) || seen.has(b.t.el))
+                continue;
+            seen.add(a.t.el);
+            seen.add(b.t.el);
+            out.push({ rule: "RX-QA-03", level: "warn", selector: selector(a.t.el), message: `${quote(a.t.text)} overlaps ${quote(b.t.text)} (${selector(b.t.el)})` });
+        }
+    }
+    return out;
+}

package/dist/cli/page-scan.js

@@ -0,0 +1,70 @@
+// `ryux scan <url>`: render a page with Playwright at each width and measure it (./page-probe.ts).
+// Playwright is optional: it is loaded from the user's project (or a global install) and never
+// bundled, so installing RYUX stays light.
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { probe } from "./page-probe.js";
+export const PLAYWRIGHT_MISSING = "Scanning a URL needs Playwright, which RYUX does not install for you. In this project run:\n  npm i -D playwright && npx playwright install chromium";
+async function loadChromium() {
+    const fromProject = createRequire(join(process.cwd(), "noop.js"));
+    for (const name of ["playwright", "playwright-core", "@playwright/test"]) {
+        try {
+            const mod = (await import(pathToFileURL(fromProject.resolve(name)).href));
+            const chromium = mod.chromium ?? mod.default?.chromium;
+            if (chromium)
+                return chromium;
+        }
+        catch {
+            // not installed under this name; try the next
+        }
+    }
+    return null;
+}
+/** Render each URL at each width and return the findings. Throws PLAYWRIGHT_MISSING when there is no
+ *  Playwright, and a launch error when its browser is not installed. */
+export async function scanPages(urls, widths) {
+    const chromium = await loadChromium();
+    if (!chromium)
+        throw new Error(PLAYWRIGHT_MISSING);
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch (err) {
+        throw new Error(`Playwright could not start Chromium. Run: npx playwright install chromium\n${err instanceof Error ? err.message.split("\n")[0] : err}`);
+    }
+    const findings = [];
+    try {
+        for (const url of urls) {
+            for (const width of widths) {
+                // Reduced motion lets animations settle, so the page is measured in its final state.
+                const ctx = await browser.newContext({ viewport: { width, height: width <= 480 ? 844 : 900 }, reducedMotion: "reduce" });
+                const page = await ctx.newPage();
+                const errors = [];
+                page.on("pageerror", (e) => errors.push(e.message.split("\n")[0]));
+                const add = (f) => {
+                    findings.push({ ...f, file: url, line: 0, column: 0, width });
+                };
+                try {
+                    await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 }).catch(() => page.goto(url, { waitUntil: "load", timeout: 30_000 }));
+                }
+                catch (err) {
+                    add({ rule: "RX-QA-08", level: "fail", selector: "page", message: `the page did not load: ${err instanceof Error ? err.message.split("\n")[0] : err}` });
+                    await ctx.close();
+                    continue;
+                }
+                await page.waitForTimeout(300);
+                (await page.evaluate(probe)).forEach(add);
+                for (const message of [...new Set(errors)]) {
+                    add({ rule: "RX-QA-08", level: "warn", selector: "page", message: `the page threw "${message}" while loading; check that the primary task still completes` });
+                }
+                await ctx.close();
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return findings;
+}