cbrowser 18.82.2 → 19.0.1

package/README.md

@@ -128,7 +128,7 @@ Five tools to make your site ready for the AI agent era:
 
 | Tool | What It Does |
 |------|-------------|
-| `agent_ready_audit` | Score site on findability, stability, accessibility, semantics (A-F grade) |
+| `agent_ready_audit` | Score site on findability, stability, agent-perceivability, semantics (A-F grade) |
 | `ai_benchmark` | Compare AI-friendliness across competitor URLs |
 | `webmcp_ready_audit` | Audit MCP server for WebMCP compatibility |
 | `remediation_patches` | Generate actionable code fixes for audit findings |
@@ -299,9 +299,36 @@ npx cbrowser competitive-benchmark \
 
 ---
 
+## Upgrading to 19.0.0
+
+One breaking change: the agent-ready **accessibility** axis is now
+**agentPerceivability**, and three deprecated aliases are removed.
+
+| removed | use instead |
+|---|---|
+| `score.accessibility` | `score.agentPerceivability` |
+| `summary.dynamicContentCount` | `summary.deferredLoadingPatterns` |
+| `comparison.bestAccessibility` | `comparison.bestAgentPerceivability` |
+| issue `category: "accessibility"` | `category: "agentPerceivability"` |
+
+All three replacements have carried identical values since 18.82.0, so if you
+upgraded within that range you can switch keys before upgrading and take this
+release with no further change.
+
+The rename is not cosmetic. That axis measures whether a *machine* can perceive
+your elements — ARIA present, elements carry text. It is **not** a WCAG
+conformance score, and it returned 100 on a page where `empathy_audit` found two
+WCAG violations. Both numbers were right; calling one of them "accessibility" was
+not. Run `empathy_audit` for conformance, and expect the two to differ.
+
+On input, `category: "accessibility"` is still accepted and scores identically, so
+tools that *send* issues need not change immediately. Tools that *read* scores do.
+
+---
+
 ## Geo Proxy
 
-Test from 12 global regions via residential proxies:
+Test from 10 global regions via residential proxies:
 
 ```bash
 npx cbrowser cognitive-journey \
@@ -311,7 +338,19 @@ npx cbrowser cognitive-journey \
   --geo-region uk
 ```
 
-**Regions:** `us-west`, `us-east`, `us-central`, `uk`, `germany`, `france`, `japan`, `australia`, `brazil`, `india`, `canada`, `singapore`
+**Regions:** `us-west`, `us-east`, `us-central`, `uk`, `germany`, `france`, `japan`, `australia`, `canada`, `brazil`
+
+Geo routing needs your own residential-proxy credentials — the package ships the
+mechanism and no keys. Set `IPROYAL_USERNAME` / `IPROYAL_PASSWORD`, or place a
+`geo-proxy.json` at `~/.cbrowser/`. Without either, `--geo-region` fails loudly
+rather than silently running from your own IP.
+
+A `geo-proxy.json` may define additional regions; they merge over the ten above.
+
+> **Corrected 2026-08-11.** This section previously advertised 12 regions
+> including `india` and `singapore`. Those are not in the shipped defaults and
+> resolve to nothing on a clean install — they existed only in a local config
+> file on one machine. Advertising them was a claim the package could not keep.
 
 ---
 

package/dist/analysis/accessibility-empathy.d.ts

@@ -4,7 +4,75 @@
  * Learn more at https://cbrowser.ai - MIT License
  */
 import type { EmpathyAuditResult, EmpathyAuditOptions } from "../types.js";
+/**
+ * Drop barriers outside the viewport when the audit is viewport-scoped.
+ *
+ * `viewportOnly` existed and had exactly ONE consumer:
+ * `detectSmallTouchTargets`. The other ten detectors scanned the whole document
+ * regardless of scope, so `scope: "viewport"` filtered touch targets and nothing
+ * else.
+ *
+ * Measured on /docs/home at 1280x800: six `sensory` barriers at y=5638, seven
+ * screens below the fold, with x up to 2029 -- 749px past the right edge. All
+ * six were counted in `affectedElements`, charged as `missing_alt: -2.2`, and
+ * folded into `barrierOnlyScore`. The response even stamped each one
+ * `outsideScreenshot: true`: the geometry was computed, published, and not
+ * acted on.
+ *
+ * So every viewport-scoped empathy score published to date may carry demand
+ * from content the persona never saw. It is the mirror of the bug
+ * `cognitive_effort`'s scopeNote documents -- that one measured too little and
+ * said so; this one measured too much and said nothing.
+ *
+ * Filtered HERE, once, after every detector and before scoring, rather than in
+ * each detector. Eleven copies of a rule is how it came to be applied in one
+ * place, and adding a twelfth detector must not be able to reintroduce this.
+ *
+ * A barrier with no rect is KEPT. Page-level findings -- navigation item count,
+ * animation presence, reading level -- have no coordinates and are properties of
+ * the page rather than of a location on it. Dropping the unlocatable would trade
+ * this bug for its opposite. (2026-08-05)
+ */
+export declare function filterBarriersToViewport<T extends {
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}>(barriers: T[], viewport: {
+    width: number;
+    height: number;
+}): {
+    kept: T[];
+    dropped: number;
+};
 export declare function formatEmpathyAuditReport(result: EmpathyAuditResult): string;
 export declare function generateEmpathyAuditHtmlReport(result: EmpathyAuditResult): string;
+/**
+ * The published WCAG list, DERIVED from the barriers rather than accumulated
+ * alongside them.
+ *
+ * It used to be a Set that each detector appended to by hand, in parallel with
+ * the barrier it was pushing. Two lists maintained by hand drift, and this pair
+ * drifted in the direction that matters: a barrier declared criteria that the
+ * adjacent `.add()` line did not repeat, so the audit DETECTED a violation,
+ * displayed it on the barrier, and left it out of the conformance list.
+ * Measured on one fixture page: 1.3.1, 2.5.5, 2.5.7 and 3.3.4 all shown as
+ * barriers, none listed. 1.3.1 there was an unlabelled form input -- Level A,
+ * and among the most common real failures there is.
+ *
+ * Deriving also fixes the reported inverse (a criterion listed with no barrier
+ * explaining it), because barriers dropped by the viewport filter now take
+ * their criteria with them instead of leaving the string behind.
+ *
+ * Criteria no barrier ever claimed are still honoured -- see
+ * `criteriaEverOnABarrier`. The rule is "mirrors are derived", not "throw away
+ * anything the barriers do not know about". (2026-08-11)
+ */
+export declare function deriveWcagViolations(barriers: Array<{
+    wcagCriteria?: string[];
+    wcagAdvisoryCriteria?: string[];
+}>, recordedByDetectors: Set<string>, criteriaEverOnABarrier: Set<string>, wcagLevel: "A" | "AA" | "AAA"): string[];
 export declare function runEmpathyAudit(url: string, options: EmpathyAuditOptions): Promise<EmpathyAuditResult>;
 //# sourceMappingURL=accessibility-empathy.d.ts.map

package/dist/analysis/accessibility-empathy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accessibility-empathy.d.ts","sourceRoot":"","sources":["../../src/analysis/accessibility-empathy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EASpB,MAAM,aAAa,CAAC;AA0mErB,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAmF3E;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAkTjF;AAqJD,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CA0Z7B"}
+{"version":3,"file":"accessibility-empathy.d.ts","sourceRoot":"","sources":["../../src/analysis/accessibility-empathy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EASpB,MAAM,aAAa,CAAC;AAkKrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACnH,QAAQ,EAAE,CAAC,EAAE,EACb,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAWhC;AAw/DD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAmF3E;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAkTjF;AAqJD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,KAAK,CAAC;IAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EAC7E,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,EAChC,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAAC,EACnC,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,GAC5B,MAAM,EAAE,CAkBV;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CA+Z7B"}

package/dist/analysis/accessibility-empathy.js

@@ -28,10 +28,12 @@ const WCAG_CRITERIA = {
     "1.2.5": { level: "AA", description: "Audio Description (Prerecorded)" },
     "1.3.1": { level: "A", description: "Info and Relationships" },
     "1.4.1": { level: "A", description: "Use of Color" },
+    "1.4.2": { level: "A", description: "Audio Control" },
     "1.4.3": { level: "AA", description: "Contrast (Minimum)" },
     "1.4.4": { level: "AA", description: "Resize Text" },
     "1.4.6": { level: "AAA", description: "Contrast (Enhanced)" },
     "1.4.10": { level: "AA", description: "Reflow" },
+    "1.4.12": { level: "AA", description: "Text Spacing" },
     "2.1.1": { level: "A", description: "Keyboard" },
     "2.1.2": { level: "A", description: "No Keyboard Trap" },
     "2.2.1": { level: "A", description: "Timing Adjustable" },
@@ -42,13 +44,16 @@ const WCAG_CRITERIA = {
     "2.4.4": { level: "A", description: "Link Purpose" },
     "2.4.6": { level: "AA", description: "Headings and Labels" },
     "2.4.7": { level: "AA", description: "Focus Visible" },
-    "2.5.5": { level: "AAA", description: "Target Size" },
+    "2.5.1": { level: "A", description: "Pointer Gestures" },
+    "2.5.5": { level: "AAA", description: "Target Size (Enhanced)" },
+    "2.5.7": { level: "AA", description: "Dragging Movements" },
     "2.5.8": { level: "AA", description: "Target Size (Minimum)" },
     "3.1.1": { level: "A", description: "Language of Page" },
     "3.2.1": { level: "A", description: "On Focus" },
     "3.2.2": { level: "A", description: "On Input" },
     "3.3.1": { level: "A", description: "Error Identification" },
     "3.3.2": { level: "A", description: "Labels or Instructions" },
+    "3.3.4": { level: "AA", description: "Error Prevention (Legal, Financial, Data)" },
     "4.1.1": { level: "A", description: "Parsing" },
     "4.1.2": { level: "A", description: "Name, Role, Value" },
 };
@@ -106,6 +111,48 @@ function adjustSeverityForLevel(severity, barrierWcagLevel, auditLevel) {
     }
     return severity;
 }
+/**
+ * Drop barriers outside the viewport when the audit is viewport-scoped.
+ *
+ * `viewportOnly` existed and had exactly ONE consumer:
+ * `detectSmallTouchTargets`. The other ten detectors scanned the whole document
+ * regardless of scope, so `scope: "viewport"` filtered touch targets and nothing
+ * else.
+ *
+ * Measured on /docs/home at 1280x800: six `sensory` barriers at y=5638, seven
+ * screens below the fold, with x up to 2029 -- 749px past the right edge. All
+ * six were counted in `affectedElements`, charged as `missing_alt: -2.2`, and
+ * folded into `barrierOnlyScore`. The response even stamped each one
+ * `outsideScreenshot: true`: the geometry was computed, published, and not
+ * acted on.
+ *
+ * So every viewport-scoped empathy score published to date may carry demand
+ * from content the persona never saw. It is the mirror of the bug
+ * `cognitive_effort`'s scopeNote documents -- that one measured too little and
+ * said so; this one measured too much and said nothing.
+ *
+ * Filtered HERE, once, after every detector and before scoring, rather than in
+ * each detector. Eleven copies of a rule is how it came to be applied in one
+ * place, and adding a twelfth detector must not be able to reintroduce this.
+ *
+ * A barrier with no rect is KEPT. Page-level findings -- navigation item count,
+ * animation presence, reading level -- have no coordinates and are properties of
+ * the page rather than of a location on it. Dropping the unlocatable would trade
+ * this bug for its opposite. (2026-08-05)
+ */
+export function filterBarriersToViewport(barriers, viewport) {
+    const kept = barriers.filter((b) => {
+        if (!b.rect)
+            return true; // page-level finding, not a located one
+        const { x, y, width, height } = b.rect;
+        // Document coordinates, and a viewport-scoped audit never scrolls, so the
+        // visible band is y 0..height and x 0..width.
+        const intersectsY = y < viewport.height && y + height > 0;
+        const intersectsX = x < viewport.width && x + width > 0;
+        return intersectsY && intersectsX;
+    });
+    return { kept, dropped: barriers.length - kept.length };
+}
 /**
  * Detect small touch targets that are hard for motor-impaired users
  * v10.10.0: Always detect touch target issues regardless of persona
@@ -435,6 +482,14 @@ async function detectCognitiveLoad(ctx) {
             description: issue.description + (mapping.criteria.length === 0 ? ' (UX recommendation, not a WCAG violation)' : ''),
             affectedPersonas: ["cognitive-adhd", "dyslexic-user"],
             wcagCriteria: mapping.criteria,
+            // `violation: null` with a non-empty `criteria` means "relates to, does
+            // not violate" -- a text-wall is a readability recommendation under 1.3.1,
+            // not a 1.3.1 failure. Recording that on the barrier is what lets the
+            // published list be DERIVED from barriers without promoting
+            // recommendations into violations. (2026-08-11)
+            ...(mapping.violation === null && mapping.criteria.length > 0
+                ? { wcagAdvisoryCriteria: mapping.criteria }
+                : {}),
             severity: issue.type === "long-form" ? "major" : "minor",
             remediation: issue.type === "long-form"
                 ? "Break form into multiple steps or sections"
@@ -1216,6 +1271,7 @@ async function simulateAccessibilityJourney(page, url, goal, persona, scope = "v
         barriers: [],
         frictionPoints: [],
         wcagViolations: new Set(),
+        criteriaEverOnABarrier: new Set(),
         stepCount: 0,
         viewportOnly: scope === "viewport",
         wcagLevel,
@@ -1300,6 +1356,28 @@ async function simulateAccessibilityJourney(page, url, goal, persona, scope = "v
                 await detectVisionBarriers(ctx);
                 break;
         }
+        // Scope is enforced HERE, once, rather than in each detector -- see
+        // filterBarriersToViewport. Ten of the eleven detectors above never honoured
+        // it, so a viewport audit was scoring content seven screens below the fold.
+        // Snapshotted BEFORE the filter runs, so the derivation below can tell a
+        // criterion that no barrier ever claimed (a genuine page-level finding,
+        // keep it) from one whose barriers were all filtered away (an orphan, drop
+        // it). Without the distinction the two are indistinguishable afterwards.
+        for (const b of ctx.barriers) {
+            for (const c of b.wcagCriteria ?? [])
+                ctx.criteriaEverOnABarrier.add(c);
+        }
+        if (ctx.viewportOnly) {
+            const vp = await page.evaluate(() => ({
+                width: window.innerWidth, height: window.innerHeight,
+            })).catch(() => ({ width: 1280, height: 800 }));
+            const { kept, dropped } = filterBarriersToViewport(ctx.barriers, vp);
+            if (dropped > 0) {
+                ctx.barriers.length = 0;
+                ctx.barriers.push(...kept);
+                ctx.outOfViewportDropped = dropped;
+            }
+        }
         // Use cognitive journey for realistic step tracking if API key available
         // v18.35.0: Add hard timeout to prevent MCP proxy disconnection (~60s limit on claude.ai)
         const journeyTimeoutMs = Math.min(maxTime * 1000, 45000); // Hard cap at 45s to leave margin
@@ -1599,6 +1677,10 @@ async function simulateAccessibilityJourney(page, url, goal, persona, scope = "v
         // Deprecated alias, one release only. See EmpathyPersonaResult.
         goalAchieved: noBlockingBarriers,
         barriers: ctx.barriers,
+        // Surfaced, not kept internal: a filter whose effect is invisible cannot be
+        // told apart from a filter that never ran, and that is exactly the defect
+        // this closes.
+        ...(ctx.outOfViewportDropped ? { outOfViewportBarriersDropped: ctx.outOfViewportDropped } : {}),
         frictionPoints: ctx.frictionPoints,
         // Filtered to the audit's conformance level, exactly as the top-level
         // allWcagViolations is (see the filter near the end of runEmpathyAudit).
@@ -1606,11 +1688,7 @@ async function simulateAccessibilityJourney(page, url, goal, persona, scope = "v
         // had dropped at AA, so wcagViolationCount read 2 beside an
         // allWcagViolations of ["2.2.2"] — the same finding counted under two
         // different rules. (2026-07-29)
-        wcagViolations: Array.from(ctx.wcagViolations).filter((v) => {
-            const criteria = WCAG_CRITERIA[v];
-            const order = { A: 1, AA: 2, AAA: 3 };
-            return !criteria || order[criteria.level] <= order[wcagLevel];
-        }),
+        wcagViolations: deriveWcagViolations(ctx.barriers, ctx.wcagViolations, ctx.criteriaEverOnABarrier, wcagLevel),
         remediationPriority,
         empathyScore,
         scoreContext, // v18.22.0: Added score breakdown
@@ -2371,6 +2449,48 @@ function inferGoalType(goal) {
         return "navigate_to";
     return "complete_action";
 }
+/**
+ * The published WCAG list, DERIVED from the barriers rather than accumulated
+ * alongside them.
+ *
+ * It used to be a Set that each detector appended to by hand, in parallel with
+ * the barrier it was pushing. Two lists maintained by hand drift, and this pair
+ * drifted in the direction that matters: a barrier declared criteria that the
+ * adjacent `.add()` line did not repeat, so the audit DETECTED a violation,
+ * displayed it on the barrier, and left it out of the conformance list.
+ * Measured on one fixture page: 1.3.1, 2.5.5, 2.5.7 and 3.3.4 all shown as
+ * barriers, none listed. 1.3.1 there was an unlabelled form input -- Level A,
+ * and among the most common real failures there is.
+ *
+ * Deriving also fixes the reported inverse (a criterion listed with no barrier
+ * explaining it), because barriers dropped by the viewport filter now take
+ * their criteria with them instead of leaving the string behind.
+ *
+ * Criteria no barrier ever claimed are still honoured -- see
+ * `criteriaEverOnABarrier`. The rule is "mirrors are derived", not "throw away
+ * anything the barriers do not know about". (2026-08-11)
+ */
+export function deriveWcagViolations(barriers, recordedByDetectors, criteriaEverOnABarrier, wcagLevel) {
+    const violated = new Set();
+    for (const b of barriers) {
+        const advisory = new Set(b.wcagAdvisoryCriteria ?? []);
+        for (const c of b.wcagCriteria ?? []) {
+            if (!advisory.has(c))
+                violated.add(c);
+        }
+    }
+    // Page-level findings: recorded by a detector, never attached to any barrier.
+    // Kept. A criterion whose barriers existed and were filtered away is NOT kept.
+    for (const c of recordedByDetectors) {
+        if (!criteriaEverOnABarrier.has(c))
+            violated.add(c);
+    }
+    const order = { A: 1, AA: 2, AAA: 3 };
+    return Array.from(violated).filter((v) => {
+        const criteria = WCAG_CRITERIA[v];
+        return !criteria || order[criteria.level] <= order[wcagLevel];
+    });
+}
 export async function runEmpathyAudit(url, options) {
     const { goal, disabilities, wcagLevel = "AA", maxSteps = 20, maxTime = 120, headless = true, } = options;
     const startTime = Date.now();
@@ -2737,6 +2857,11 @@ export async function runEmpathyAudit(url, options) {
         topBarriers: deduplicatedBarriers, // v11.11.0: Deduplicated barriers grouped by type
         combinedRemediation,
         overallScore,
+        // Summed from the per-persona audits: a filter whose effect is invisible is
+        // indistinguishable from one that did not run.
+        ...(results.reduce((n, r) => n + (r.outOfViewportBarriersDropped ?? 0), 0) > 0
+            ? { outOfViewportBarriersDropped: results.reduce((n, r) => n + (r.outOfViewportBarriersDropped ?? 0), 0) }
+            : {}),
         duration: Date.now() - startTime,
     };
 }