cbrowser 18.82.2 → 19.0.0

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,6 +4,49 @@
  * 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;
 export declare function runEmpathyAudit(url: string, options: EmpathyAuditOptions): Promise<EmpathyAuditResult>;

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;AAwJrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;AAy+DD,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,CA+Z7B"}

package/dist/analysis/accessibility-empathy.js

@@ -106,6 +106,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
@@ -1300,6 +1342,20 @@ 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.
+        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 +1655,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).
@@ -2737,6 +2797,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,
     };
 }