ultra11y 5.14.2 → 5.14.4

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "5.14.2",
+      "version": "5.14.4",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "5.14.2",
+  "version": "5.14.4",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "5.14.2",
+  "version": "5.14.4",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "5.14.2";
+const ULTRA11Y_PLUGIN_VERSION = "5.14.4";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.14.2",
+  "version": "5.14.4",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.14.2";
+var VERSION = "5.14.4";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -56864,12 +56864,27 @@ function sectionBody(md, n) {
 function checkSampleCaptured(root = ".", lang = "en") {
   const fr = lang === "fr";
   let declared = [];
+  const rc = join34(root, ".ultra11yrc.json");
+  let raw;
   try {
-    const cfg = JSON.parse(readFileSync18(join34(root, ".ultra11yrc.json"), "utf8"));
-    declared = cfg.sample?.pages ?? [];
+    raw = readFileSync18(rc, "utf8");
   } catch {
     return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   }
+  try {
+    const cfg = JSON.parse(raw);
+    declared = cfg.sample?.pages ?? [];
+  } catch (e) {
+    return {
+      ok: false,
+      issues: [
+        fr ? `.ultra11yrc.json est pr\xE9sent mais illisible (${e instanceof Error ? e.message : String(e)}) \u2014 impossible de savoir quelles pages ce run devait couvrir. La porte de couverture ne peut pas r\xE9pondre, et ne r\xE9pondra donc pas \xAB couvert \xBB.` : `.ultra11yrc.json is present but unreadable (${e instanceof Error ? e.message : String(e)}) \u2014 there is no way to know which pages this run was meant to cover. The coverage gate cannot answer, so it does not answer "covered".`
+      ],
+      missing: [],
+      declared: 0,
+      captured: 0
+    };
+  }
   if (!declared.length) return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   let captured = /* @__PURE__ */ new Set();
   try {
@@ -59170,10 +59185,23 @@ var PROBE_FIELDS = [
   { key: "inputOverflowSpacing", engine: "input-overflow-spacing" },
   { key: "liveRegion", engine: "live-region" }
 ];
+function loopbackToHostGateway(target) {
+  const m = /^http:\/\/(localhost|127(?:\.\d{1,3}){3})(:\d+)?(\/.*)?$/i.exec(target);
+  if (!m) return { url: target, addHost: false };
+  return { url: `http://host.docker.internal${m[2] ?? ""}${m[3] ?? ""}`, addHost: true };
+}
 function runRunner(target, isFile, tag, snapshot = true) {
+  const hostTarget = target;
   const args2 = ["run", "--rm"];
   if (!snapshot) args2.push("-e", "ULTRA11Y_SNAPSHOT=0");
   if (isFile) args2.push("-v", `${resolve11(target)}:${MOUNT}:ro`);
+  else {
+    const gw = loopbackToHostGateway(target);
+    if (gw.addHost && process.platform === "linux") {
+      args2.push("--add-host", "host.docker.internal:host-gateway");
+    }
+    target = gw.url;
+  }
   args2.push(tag, isFile ? MOUNT : target);
   let stdout;
   try {
@@ -59184,7 +59212,12 @@ function runRunner(target, isFile, tag, snapshot = true) {
     throw new Error(`docker run failed \u2014 ${detail}`);
   }
   const line = stdout.trim().split("\n").filter(Boolean).pop() ?? "{}";
-  return JSON.parse(line);
+  const out2 = JSON.parse(line);
+  if (loopbackToHostGateway(hostTarget).addHost && out2.url) {
+    const hostSchemeName = hostTarget.match(/^http:\/\/[^:/]+/)?.[0] ?? hostTarget;
+    out2.url = out2.url.replace(/^http:\/\/host\.docker\.internal(?=:\d+|\/|$)/i, hostSchemeName);
+  }
+  return out2;
 }
 function hostPageOf(url, target) {
   if (!url) return target;
@@ -59703,18 +59736,29 @@ function localTestedScs(interact) {
 }
 var PW_SPEC = "@playwright/test";
 var AXE_SPEC = "@axe-core/playwright";
-function localAvailable(cwd) {
+function localTierStatus(cwd) {
+  const req = createRequire(resolve12(cwd, "package.json"));
+  for (const spec of [PW_SPEC, AXE_SPEC]) {
+    try {
+      req.resolve(spec);
+    } catch {
+      return { ok: false, reason: `${spec} does not resolve from ${cwd}` };
+    }
+  }
   try {
-    const req = createRequire(resolve12(cwd, "package.json"));
-    req.resolve(PW_SPEC);
-    req.resolve(AXE_SPEC);
     const pw = req(PW_SPEC);
     const bin = pw.chromium?.executablePath?.();
-    return typeof bin !== "string" || bin.length === 0 ? true : existsSync24(bin);
-  } catch {
-    return false;
+    if (typeof bin === "string" && bin.length > 0 && !existsSync24(bin)) {
+      return { ok: false, reason: `no browser binary at ${bin} \u2014 run \`npx playwright install chromium\`` };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `${PW_SPEC} failed to load: ${e.message.split("\n")[0]}` };
   }
 }
+function localAvailable(cwd) {
+  return localTierStatus(cwd).ok;
+}
 function resolveLocalDeps(cwd) {
   let chromium;
   let AxeBuilder;
@@ -68653,8 +68697,13 @@ async function cmdScan(p) {
   if (runtimeFlag === "local") useLocal = true;
   else if (runtimeFlag === "docker") useLocal = false;
   else if (localAvailable(cwd)) useLocal = true;
-  else if (dockerAvailable()) useLocal = false;
-  else {
+  else if (dockerAvailable()) {
+    useLocal = false;
+    const s = localTierStatus(cwd);
+    console.error(
+      lang === "fr" ? `ultra11y scan : tier local indisponible${s.ok ? "" : ` (${s.reason})`} \u2014 bascule sur Docker. Passez --runtime local pour en faire une erreur.` : `ultra11y scan: local tier unavailable${s.ok ? "" : ` (${s.reason})`} \u2014 falling back to Docker. Pass --runtime local to make this an error instead.`
+    );
+  } else {
     console.error(
       lang === "fr" ? "ultra11y scan : aucun runtime disponible \u2014 ni Playwright local (passez --cwd vers un projet avec @playwright/test + @axe-core/playwright install\xE9s), ni Docker. Voir --runtime." : "ultra11y scan: no runtime available \u2014 neither a local Playwright (pass --cwd at a project with @playwright/test + @axe-core/playwright installed) nor Docker. See --runtime."
     );

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 5.14.2
+  version: 5.14.4
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.14.2";
+var VERSION = "5.14.4";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -56864,12 +56864,27 @@ function sectionBody(md, n) {
 function checkSampleCaptured(root = ".", lang = "en") {
   const fr = lang === "fr";
   let declared = [];
+  const rc = join34(root, ".ultra11yrc.json");
+  let raw;
   try {
-    const cfg = JSON.parse(readFileSync18(join34(root, ".ultra11yrc.json"), "utf8"));
-    declared = cfg.sample?.pages ?? [];
+    raw = readFileSync18(rc, "utf8");
   } catch {
     return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   }
+  try {
+    const cfg = JSON.parse(raw);
+    declared = cfg.sample?.pages ?? [];
+  } catch (e) {
+    return {
+      ok: false,
+      issues: [
+        fr ? `.ultra11yrc.json est pr\xE9sent mais illisible (${e instanceof Error ? e.message : String(e)}) \u2014 impossible de savoir quelles pages ce run devait couvrir. La porte de couverture ne peut pas r\xE9pondre, et ne r\xE9pondra donc pas \xAB couvert \xBB.` : `.ultra11yrc.json is present but unreadable (${e instanceof Error ? e.message : String(e)}) \u2014 there is no way to know which pages this run was meant to cover. The coverage gate cannot answer, so it does not answer "covered".`
+      ],
+      missing: [],
+      declared: 0,
+      captured: 0
+    };
+  }
   if (!declared.length) return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   let captured = /* @__PURE__ */ new Set();
   try {
@@ -59170,10 +59185,23 @@ var PROBE_FIELDS = [
   { key: "inputOverflowSpacing", engine: "input-overflow-spacing" },
   { key: "liveRegion", engine: "live-region" }
 ];
+function loopbackToHostGateway(target) {
+  const m = /^http:\/\/(localhost|127(?:\.\d{1,3}){3})(:\d+)?(\/.*)?$/i.exec(target);
+  if (!m) return { url: target, addHost: false };
+  return { url: `http://host.docker.internal${m[2] ?? ""}${m[3] ?? ""}`, addHost: true };
+}
 function runRunner(target, isFile, tag, snapshot = true) {
+  const hostTarget = target;
   const args2 = ["run", "--rm"];
   if (!snapshot) args2.push("-e", "ULTRA11Y_SNAPSHOT=0");
   if (isFile) args2.push("-v", `${resolve11(target)}:${MOUNT}:ro`);
+  else {
+    const gw = loopbackToHostGateway(target);
+    if (gw.addHost && process.platform === "linux") {
+      args2.push("--add-host", "host.docker.internal:host-gateway");
+    }
+    target = gw.url;
+  }
   args2.push(tag, isFile ? MOUNT : target);
   let stdout;
   try {
@@ -59184,7 +59212,12 @@ function runRunner(target, isFile, tag, snapshot = true) {
     throw new Error(`docker run failed \u2014 ${detail}`);
   }
   const line = stdout.trim().split("\n").filter(Boolean).pop() ?? "{}";
-  return JSON.parse(line);
+  const out2 = JSON.parse(line);
+  if (loopbackToHostGateway(hostTarget).addHost && out2.url) {
+    const hostSchemeName = hostTarget.match(/^http:\/\/[^:/]+/)?.[0] ?? hostTarget;
+    out2.url = out2.url.replace(/^http:\/\/host\.docker\.internal(?=:\d+|\/|$)/i, hostSchemeName);
+  }
+  return out2;
 }
 function hostPageOf(url, target) {
   if (!url) return target;
@@ -59703,18 +59736,29 @@ function localTestedScs(interact) {
 }
 var PW_SPEC = "@playwright/test";
 var AXE_SPEC = "@axe-core/playwright";
-function localAvailable(cwd) {
+function localTierStatus(cwd) {
+  const req = createRequire(resolve12(cwd, "package.json"));
+  for (const spec of [PW_SPEC, AXE_SPEC]) {
+    try {
+      req.resolve(spec);
+    } catch {
+      return { ok: false, reason: `${spec} does not resolve from ${cwd}` };
+    }
+  }
   try {
-    const req = createRequire(resolve12(cwd, "package.json"));
-    req.resolve(PW_SPEC);
-    req.resolve(AXE_SPEC);
     const pw = req(PW_SPEC);
     const bin = pw.chromium?.executablePath?.();
-    return typeof bin !== "string" || bin.length === 0 ? true : existsSync24(bin);
-  } catch {
-    return false;
+    if (typeof bin === "string" && bin.length > 0 && !existsSync24(bin)) {
+      return { ok: false, reason: `no browser binary at ${bin} \u2014 run \`npx playwright install chromium\`` };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `${PW_SPEC} failed to load: ${e.message.split("\n")[0]}` };
   }
 }
+function localAvailable(cwd) {
+  return localTierStatus(cwd).ok;
+}
 function resolveLocalDeps(cwd) {
   let chromium;
   let AxeBuilder;
@@ -68653,8 +68697,13 @@ async function cmdScan(p) {
   if (runtimeFlag === "local") useLocal = true;
   else if (runtimeFlag === "docker") useLocal = false;
   else if (localAvailable(cwd)) useLocal = true;
-  else if (dockerAvailable()) useLocal = false;
-  else {
+  else if (dockerAvailable()) {
+    useLocal = false;
+    const s = localTierStatus(cwd);
+    console.error(
+      lang === "fr" ? `ultra11y scan : tier local indisponible${s.ok ? "" : ` (${s.reason})`} \u2014 bascule sur Docker. Passez --runtime local pour en faire une erreur.` : `ultra11y scan: local tier unavailable${s.ok ? "" : ` (${s.reason})`} \u2014 falling back to Docker. Pass --runtime local to make this an error instead.`
+    );
+  } else {
     console.error(
       lang === "fr" ? "ultra11y scan : aucun runtime disponible \u2014 ni Playwright local (passez --cwd vers un projet avec @playwright/test + @axe-core/playwright install\xE9s), ni Docker. Voir --runtime." : "ultra11y scan: no runtime available \u2014 neither a local Playwright (pass --cwd at a project with @playwright/test + @axe-core/playwright installed) nor Docker. See --runtime."
     );

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 5.14.2
+  version: 5.14.4
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.14.2";
+var VERSION = "5.14.4";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -56864,12 +56864,27 @@ function sectionBody(md, n) {
 function checkSampleCaptured(root = ".", lang = "en") {
   const fr = lang === "fr";
   let declared = [];
+  const rc = join34(root, ".ultra11yrc.json");
+  let raw;
   try {
-    const cfg = JSON.parse(readFileSync18(join34(root, ".ultra11yrc.json"), "utf8"));
-    declared = cfg.sample?.pages ?? [];
+    raw = readFileSync18(rc, "utf8");
   } catch {
     return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   }
+  try {
+    const cfg = JSON.parse(raw);
+    declared = cfg.sample?.pages ?? [];
+  } catch (e) {
+    return {
+      ok: false,
+      issues: [
+        fr ? `.ultra11yrc.json est pr\xE9sent mais illisible (${e instanceof Error ? e.message : String(e)}) \u2014 impossible de savoir quelles pages ce run devait couvrir. La porte de couverture ne peut pas r\xE9pondre, et ne r\xE9pondra donc pas \xAB couvert \xBB.` : `.ultra11yrc.json is present but unreadable (${e instanceof Error ? e.message : String(e)}) \u2014 there is no way to know which pages this run was meant to cover. The coverage gate cannot answer, so it does not answer "covered".`
+      ],
+      missing: [],
+      declared: 0,
+      captured: 0
+    };
+  }
   if (!declared.length) return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   let captured = /* @__PURE__ */ new Set();
   try {
@@ -59170,10 +59185,23 @@ var PROBE_FIELDS = [
   { key: "inputOverflowSpacing", engine: "input-overflow-spacing" },
   { key: "liveRegion", engine: "live-region" }
 ];
+function loopbackToHostGateway(target) {
+  const m = /^http:\/\/(localhost|127(?:\.\d{1,3}){3})(:\d+)?(\/.*)?$/i.exec(target);
+  if (!m) return { url: target, addHost: false };
+  return { url: `http://host.docker.internal${m[2] ?? ""}${m[3] ?? ""}`, addHost: true };
+}
 function runRunner(target, isFile, tag, snapshot = true) {
+  const hostTarget = target;
   const args2 = ["run", "--rm"];
   if (!snapshot) args2.push("-e", "ULTRA11Y_SNAPSHOT=0");
   if (isFile) args2.push("-v", `${resolve11(target)}:${MOUNT}:ro`);
+  else {
+    const gw = loopbackToHostGateway(target);
+    if (gw.addHost && process.platform === "linux") {
+      args2.push("--add-host", "host.docker.internal:host-gateway");
+    }
+    target = gw.url;
+  }
   args2.push(tag, isFile ? MOUNT : target);
   let stdout;
   try {
@@ -59184,7 +59212,12 @@ function runRunner(target, isFile, tag, snapshot = true) {
     throw new Error(`docker run failed \u2014 ${detail}`);
   }
   const line = stdout.trim().split("\n").filter(Boolean).pop() ?? "{}";
-  return JSON.parse(line);
+  const out2 = JSON.parse(line);
+  if (loopbackToHostGateway(hostTarget).addHost && out2.url) {
+    const hostSchemeName = hostTarget.match(/^http:\/\/[^:/]+/)?.[0] ?? hostTarget;
+    out2.url = out2.url.replace(/^http:\/\/host\.docker\.internal(?=:\d+|\/|$)/i, hostSchemeName);
+  }
+  return out2;
 }
 function hostPageOf(url, target) {
   if (!url) return target;
@@ -59703,18 +59736,29 @@ function localTestedScs(interact) {
 }
 var PW_SPEC = "@playwright/test";
 var AXE_SPEC = "@axe-core/playwright";
-function localAvailable(cwd) {
+function localTierStatus(cwd) {
+  const req = createRequire(resolve12(cwd, "package.json"));
+  for (const spec of [PW_SPEC, AXE_SPEC]) {
+    try {
+      req.resolve(spec);
+    } catch {
+      return { ok: false, reason: `${spec} does not resolve from ${cwd}` };
+    }
+  }
   try {
-    const req = createRequire(resolve12(cwd, "package.json"));
-    req.resolve(PW_SPEC);
-    req.resolve(AXE_SPEC);
     const pw = req(PW_SPEC);
     const bin = pw.chromium?.executablePath?.();
-    return typeof bin !== "string" || bin.length === 0 ? true : existsSync24(bin);
-  } catch {
-    return false;
+    if (typeof bin === "string" && bin.length > 0 && !existsSync24(bin)) {
+      return { ok: false, reason: `no browser binary at ${bin} \u2014 run \`npx playwright install chromium\`` };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `${PW_SPEC} failed to load: ${e.message.split("\n")[0]}` };
   }
 }
+function localAvailable(cwd) {
+  return localTierStatus(cwd).ok;
+}
 function resolveLocalDeps(cwd) {
   let chromium;
   let AxeBuilder;
@@ -68653,8 +68697,13 @@ async function cmdScan(p) {
   if (runtimeFlag === "local") useLocal = true;
   else if (runtimeFlag === "docker") useLocal = false;
   else if (localAvailable(cwd)) useLocal = true;
-  else if (dockerAvailable()) useLocal = false;
-  else {
+  else if (dockerAvailable()) {
+    useLocal = false;
+    const s = localTierStatus(cwd);
+    console.error(
+      lang === "fr" ? `ultra11y scan : tier local indisponible${s.ok ? "" : ` (${s.reason})`} \u2014 bascule sur Docker. Passez --runtime local pour en faire une erreur.` : `ultra11y scan: local tier unavailable${s.ok ? "" : ` (${s.reason})`} \u2014 falling back to Docker. Pass --runtime local to make this an error instead.`
+    );
+  } else {
     console.error(
       lang === "fr" ? "ultra11y scan : aucun runtime disponible \u2014 ni Playwright local (passez --cwd vers un projet avec @playwright/test + @axe-core/playwright install\xE9s), ni Docker. Voir --runtime." : "ultra11y scan: no runtime available \u2014 neither a local Playwright (pass --cwd at a project with @playwright/test + @axe-core/playwright installed) nor Docker. See --runtime."
     );

package/src/check.ts

@@ -362,14 +362,36 @@ export interface SampleCoverage {
 export function checkSampleCaptured(root = ".", lang: Lang = "en"): SampleCoverage {
   const fr = lang === "fr";
   let declared: { id: string; name?: string; url?: string }[] = [];
+  const rc = join(root, ".ultra11yrc.json");
+  let raw: string;
   try {
-    const cfg = JSON.parse(readFileSync(join(root, ".ultra11yrc.json"), "utf8")) as {
-      sample?: { pages?: { id: string; name?: string; url?: string }[] };
-    };
-    declared = cfg.sample?.pages ?? [];
+    raw = readFileSync(rc, "utf8");
   } catch {
+    // NO CONFIG AT ALL — nothing is declared, so there is nothing to answer for. This is the
+    // one silence that may pass: a gate that fails on its own absence is a gate that gets
+    // turned off.
     return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
   }
+  try {
+    const cfg = JSON.parse(raw) as { sample?: { pages?: { id: string; name?: string; url?: string }[] } };
+    declared = cfg.sample?.pages ?? [];
+  } catch (e) {
+    // A CONFIG THAT EXISTS AND CANNOT BE READ is the opposite case, and it must not pass. The
+    // file is where the sample is declared, so an unparseable one means this gate does not know
+    // what the run was supposed to cover — and answering "covered" to that is how a gate
+    // disarms itself at exactly the moment something is wrong.
+    return {
+      ok: false,
+      issues: [
+        fr
+          ? `.ultra11yrc.json est présent mais illisible (${e instanceof Error ? e.message : String(e)}) — impossible de savoir quelles pages ce run devait couvrir. La porte de couverture ne peut pas répondre, et ne répondra donc pas « couvert ».`
+          : `.ultra11yrc.json is present but unreadable (${e instanceof Error ? e.message : String(e)}) — there is no way to know which pages this run was meant to cover. The coverage gate cannot answer, so it does not answer "covered".`,
+      ],
+      missing: [],
+      declared: 0,
+      captured: 0,
+    };
+  }
   if (!declared.length) return { ok: true, issues: [], missing: [], declared: 0, captured: 0 };
 
   let captured = new Set<string>();

package/src/cli.ts

@@ -53,7 +53,7 @@ import {
 import { entriesFrom, isLedger, ledgerPath, mergeLedger, readLedger, replayLedger, type VerdictLedger, writeLedger } from "./ledger.js";
 import { BATCH_SIZE, apiKeyFromEnv, applyRawVerdicts, judgeAll, modelFromEnv } from "./llm.js";
 import { runScan, runScanMany, runCrawlScan, runSampleScan, mergeDynamic, mergeSnapshotAudit, cleanDynamic, dockerAvailable } from "./scan.js";
-import { runScanLocal, runScanManyLocal, runCrawlScanLocal, runSampleScanLocal, localAvailable } from "./scan-local.js";
+import { runScanLocal, runScanManyLocal, runCrawlScanLocal, runSampleScanLocal, localAvailable, localTierStatus } from "./scan-local.js";
 import { validateSample, lintSample, kindLabel, proposeSamplePages, mergeSample, sampleFromSnapshots, unionSample } from "./sample.js";
 import { createAdapter } from "./external/registry.js";
 import { diffSides, sideOfExternal, type DiffBucket } from "./external/diff.js";
@@ -3244,8 +3244,17 @@ async function cmdScan(p: ParsedArgs): Promise<number> {
   if (runtimeFlag === "local") useLocal = true;
   else if (runtimeFlag === "docker") useLocal = false;
   else if (localAvailable(cwd)) useLocal = true;
-  else if (dockerAvailable()) useLocal = false;
-  else {
+  else if (dockerAvailable()) {
+    useLocal = false;
+    // A silent degrade is indistinguishable from a working fallback — name what was
+    // missing, so the one line a reader gets answers "what do I install".
+    const s = localTierStatus(cwd);
+    console.error(
+      lang === "fr"
+        ? `ultra11y scan : tier local indisponible${s.ok ? "" : ` (${s.reason})`} — bascule sur Docker. Passez --runtime local pour en faire une erreur.`
+        : `ultra11y scan: local tier unavailable${s.ok ? "" : ` (${s.reason})`} — falling back to Docker. Pass --runtime local to make this an error instead.`,
+    );
+  } else {
     console.error(
       lang === "fr"
         ? "ultra11y scan : aucun runtime disponible — ni Playwright local (passez --cwd vers un projet avec @playwright/test + @axe-core/playwright installés), ni Docker. Voir --runtime."

package/src/scan-local.ts

@@ -59,6 +59,37 @@ interface LocalDeps {
 const PW_SPEC = "@playwright/test";
 const AXE_SPEC = "@axe-core/playwright";
 
+/** Why the LOCAL tier is (un)usable from `cwd` — the one line a reader of a
+ *  `runtime: auto` log gets before the Docker fallback takes over. A silent degrade is
+ *  indistinguishable from a working fallback, so the reason must NAME what to install. */
+export type LocalTierStatus = { ok: true } | { ok: false; reason: string };
+
+/** The same probe as `localAvailable`, keeping the reason instead of collapsing it to a
+ *  boolean. Drives the `runtime: auto` decision AND the message printed when it degrades
+ *  to Docker. */
+export function localTierStatus(cwd: string): LocalTierStatus {
+  const req = createRequire(resolve(cwd, "package.json"));
+  for (const spec of [PW_SPEC, AXE_SPEC]) {
+    try {
+      req.resolve(spec);
+    } catch {
+      return { ok: false, reason: `${spec} does not resolve from ${cwd}` };
+    }
+  }
+  try {
+    const pw = req(PW_SPEC) as { chromium?: { executablePath?: () => string } };
+    const bin = pw.chromium?.executablePath?.();
+    // No path at all ⇒ a Playwright that cannot tell us; treat as available and let the
+    // launch report its own failure, rather than refusing a tier that might work.
+    if (typeof bin === "string" && bin.length > 0 && !existsSync(bin)) {
+      return { ok: false, reason: `no browser binary at ${bin} — run \`npx playwright install chromium\`` };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `${PW_SPEC} failed to load: ${(e as Error).message.split("\n")[0]}` };
+  }
+}
+
 /** Is the LOCAL tier actually usable from `cwd`? Drives `runtime: auto`.
  *
  *  Both packages must resolve — and the browser BINARY must be on disk. The second half is not
@@ -73,18 +104,7 @@ const AXE_SPEC = "@axe-core/playwright";
  *  browser, and failed rather than degrading. `executablePath()` is a pure path computation, so
  *  this stays cheap: no launch, no download, one `stat`. */
 export function localAvailable(cwd: string): boolean {
-  try {
-    const req = createRequire(resolve(cwd, "package.json"));
-    req.resolve(PW_SPEC);
-    req.resolve(AXE_SPEC);
-    const pw = req(PW_SPEC) as { chromium?: { executablePath?: () => string } };
-    const bin = pw.chromium?.executablePath?.();
-    // No path at all ⇒ a Playwright that cannot tell us; treat as available and let the launch
-    // report its own failure, rather than refusing a tier that might work.
-    return typeof bin !== "string" || bin.length === 0 ? true : existsSync(bin);
-  } catch {
-    return false;
-  }
+  return localTierStatus(cwd).ok;
 }
 
 /** Load Playwright `chromium` + the `AxeBuilder` class from the target project. */

package/src/scan.ts

@@ -251,10 +251,34 @@ const PROBE_FIELDS: { key: keyof RunnerOutput; engine: Exclude<DynamicEngine, "a
   { key: "liveRegion", engine: "live-region" },
 ];
 
+/** Rewrite a HOST loopback URL into one a container can reach. `docker run` gets no
+ *  `--network host`, so the container's 127.0.0.1 is its own — a scan of
+ *  `http://localhost:3000` (the action's `start:` + `urls:` shape) died on
+ *  ERR_CONNECTION_REFUSED while the app ran the whole time, which is how this
+ *  repository's CI stayed red for a day. `host.docker.internal` is natively resolved by
+ *  Docker Desktop (macOS/Windows); on Linux the caller adds
+ *  `--add-host host.docker.internal:host-gateway`. https:// loopback is deliberately NOT
+ *  rewritten: the container would fail the self-signed certificate anyway. */
+export function loopbackToHostGateway(target: string): { url: string; addHost: boolean } {
+  const m = /^http:\/\/(localhost|127(?:\.\d{1,3}){3})(:\d+)?(\/.*)?$/i.exec(target);
+  if (!m) return { url: target, addHost: false };
+  return { url: `http://host.docker.internal${m[2] ?? ""}${m[3] ?? ""}`, addHost: true };
+}
+
 function runRunner(target: string, isFile: boolean, tag: string, snapshot = true): RunnerOutput {
+  const hostTarget = target;
   const args = ["run", "--rm"];
   if (!snapshot) args.push("-e", "ULTRA11Y_SNAPSHOT=0");
   if (isFile) args.push("-v", `${resolve(target)}:${MOUNT}:ro`);
+  else {
+    // The container must reach the HOST's loopback through host.docker.internal; on
+    // Linux that name needs the host-gateway mapping Docker Desktop provides natively.
+    const gw = loopbackToHostGateway(target);
+    if (gw.addHost && process.platform === "linux") {
+      args.push("--add-host", "host.docker.internal:host-gateway");
+    }
+    target = gw.url;
+  }
   args.push(tag, isFile ? MOUNT : target);
   let stdout: string;
   try {
@@ -272,7 +296,17 @@ function runRunner(target: string, isFile: boolean, tag: string, snapshot = true
     throw new Error(`docker run failed — ${detail}`);
   }
   const line = stdout.trim().split("\n").filter(Boolean).pop() ?? "{}";
-  return JSON.parse(line) as RunnerOutput;
+  const out = JSON.parse(line) as RunnerOutput;
+  // Report what a HOST reader can open: the runner finished on host.docker.internal, and
+  // every downstream citation (hostPageOf, snapshot identity) derives from out.url. Only
+  // the HOSTNAME is restored — the port stays from the container URL, which was copied
+  // from the target, so pasting a full origin would double it
+  // (`http://127.0.0.1:8931:8931/…`).
+  if (loopbackToHostGateway(hostTarget).addHost && out.url) {
+    const hostSchemeName = hostTarget.match(/^http:\/\/[^:/]+/)?.[0] ?? hostTarget;
+    out.url = out.url.replace(/^http:\/\/host\.docker\.internal(?=:\d+|\/|$)/i, hostSchemeName);
+  }
+  return out;
 }
 
 /** Map the runner's reported page back to a HOST-meaningful citation: the container mount

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "5.14.2";
+export const VERSION = "5.14.4";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,