cbrowser 20.2.2 → 21.0.0

package/README.md

@@ -124,7 +124,7 @@ The eight-layer Sequential Transport Chain computes how hard a page is for a giv
 
 | Layer | The Question It Answers | Research Basis |
 |-------|------------------------|----------------|
-| **Saliency** | Can they find the thing they came for? | CIE-Lab W₂ perceptual model |
+| **Visual Complexity** | How much visual clutter and motion is there to see past? | A count of visual elements plus animation level (hand-set; not the attention model) |
 | **Cognitive Load** | Is there more on this page than they can hold at once? | Sweller (1988) CLT |
 | **Decision** | Are there too many choices to pick between? | Hick-Hyman Law |
 | **Motor** | Can they physically hit the target? | Grossman & Balakrishnan (2005) |
@@ -186,7 +186,7 @@ The agent-perceivability axis measures whether a machine can perceive your eleme
 
 ## Cognitive User Simulation
 
-Research-backed cognitive traits and motivational values model how real users think, struggle and give up:
+Cognitive traits and motivational values model how users think, struggle and give up. Each trait's scale is drawn from the research in the table below; the values the built-in personas carry on those scales are set by hand and registered as hypotheses, not measured:
 
 | Trait | Research Basis | What It Models |
 |-------|---------------|----------------|

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

@@ -3,7 +3,7 @@
  * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
  * Learn more at https://cbrowser.ai - MIT License
  */
-import type { EmpathyAuditResult, EmpathyAuditOptions, AccessibilityBarrier, AccessibilityBarrierSeverity } from "../types.js";
+import type { EmpathyAuditResult, EmpathyAuditOptions, AccessibilityBarrier, AccessibilityBarrierSeverity, AccessibilityTraits } from "../types.js";
 /**
  * Move findings ABOVE the audited WCAG level out of the scored set.
  *
@@ -127,5 +127,33 @@ export declare function deriveWcagViolations(barriers: Array<{
     wcagCriteria?: string[];
     wcagAdvisoryCriteria?: string[];
 }>, recordedByDetectors: Set<string>, criteriaEverOnABarrier: Set<string>, wcagLevel: "A" | "AA" | "AAA"): string[];
+/**
+ * The accessibility traits empathy_audit scores a persona with when it is not
+ * one of the built-in accessibility personas (those carry their own record).
+ *
+ * Inferred from name keywords and cognitive traits, then overlaid with what the
+ * persona's record stores: a stored trait always wins, and inference fills only
+ * the fields the record leaves out. Until 2026-10-22 the inference replaced the
+ * record outright, so a custom persona with low vision on record (visionLevel
+ * 0.3) was audited as fully sighted (1.0), and its stored reading traits were
+ * dropped, while attention_analysis drew the same persona through a low-vision
+ * filter. No built-in persona on this path stores accessibility traits, so the
+ * change moves custom personas only. (ISC-48.1)
+ *
+ * The name hints also decide whether the persona is reported as a disability
+ * persona; stored traits do not, yet.
+ */
+export declare function wrappedPersonaAccessibility(personaName: string, persona: object): {
+    accessibilityTraits: AccessibilityTraits;
+    hints: {
+        vision: boolean;
+        motor: boolean;
+        cognitive: boolean;
+        screenReader: boolean;
+        hearing: boolean;
+    };
+    /** The fields that came from the record rather than from inference. */
+    storedFields: 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;AAoCH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EAEnB,oBAAoB,EAEpB,4BAA4B,EAK7B,MAAM,aAAa,CAAC;AA+OrB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,4BAA4B,CAAA;CAAE,EAChH,QAAQ,EAAE,CAAC,EAAE,EACb,UAAU,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,GAC7B;IAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,eAAe,EAAE,IAAI,CAAC;QAAC,kBAAkB,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,CAAA;KAAE,CAAC,CAAA;CAAE,CAmB3G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;AA4iFD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAuG3E;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA2UjF;AAsBD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAE9E;AAmKD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAmB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;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,CAqY7B"}
+{"version":3,"file":"accessibility-empathy.d.ts","sourceRoot":"","sources":["../../src/analysis/accessibility-empathy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoCH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EAEnB,oBAAoB,EAEpB,4BAA4B,EAI5B,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AAgPrB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,4BAA4B,CAAA;CAAE,EAChH,QAAQ,EAAE,CAAC,EAAE,EACb,UAAU,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,GAC7B;IAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,eAAe,EAAE,IAAI,CAAC;QAAC,kBAAkB,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,CAAA;KAAE,CAAC,CAAA;CAAE,CAmB3G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;AA4iFD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAuG3E;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA2UjF;AAsBD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAE9E;AAmKD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAmB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd;IACD,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,KAAK,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACxG,uEAAuE;IACvE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAiCA;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAsX7B"}

package/dist/analysis/accessibility-empathy.js

@@ -8,10 +8,11 @@ import { VERSION } from "../version.js";
 import { CBrowser } from "../browser.js";
 import { navigationError as toNavigationError } from "../navigation-errors.js";
 import { getAccessibilityPersona, PERSONA_ALIASES } from "../personas.js";
+import { storedAccessibilityTraits } from "../visual/stored-accessibility-traits.js";
 import { runCognitiveJourney, isApiKeyConfigured, } from "../cognitive/index.js";
 import { calculatePerceptualScore, analyzePerceptualTransport, } from "../visual/perceptual-transport.js";
 import { buildOTCognitiveProfile, estimateCognitiveLoad, extractPageMetrics, } from "../visual/cognitive-transport.js";
-import { bridgeCapacityTraits } from "../visual/cognitive-models.js";
+import { bridgeCapacityTraits, personaRateContext } from "../visual/cognitive-models.js";
 import { analyzeAttention, } from "../visual/attention-transport.js";
 import { getEmotionVisualizationStyles, generateEmotionVisualizationSection, } from "../utils.js";
 import { makeTempDir } from "../temp-files.js";
@@ -3270,6 +3271,55 @@ export function deriveWcagViolations(barriers, recordedByDetectors, criteriaEver
         return !criteria || order[criteria.level] <= order[wcagLevel];
     });
 }
+/**
+ * The accessibility traits empathy_audit scores a persona with when it is not
+ * one of the built-in accessibility personas (those carry their own record).
+ *
+ * Inferred from name keywords and cognitive traits, then overlaid with what the
+ * persona's record stores: a stored trait always wins, and inference fills only
+ * the fields the record leaves out. Until 2026-10-22 the inference replaced the
+ * record outright, so a custom persona with low vision on record (visionLevel
+ * 0.3) was audited as fully sighted (1.0), and its stored reading traits were
+ * dropped, while attention_analysis drew the same persona through a low-vision
+ * filter. No built-in persona on this path stores accessibility traits, so the
+ * change moves custom personas only. (ISC-48.1)
+ *
+ * The name hints also decide whether the persona is reported as a disability
+ * persona; stored traits do not, yet.
+ */
+export function wrappedPersonaAccessibility(personaName, persona) {
+    const ct = persona.cognitiveTraits || {};
+    const name = personaName.toLowerCase();
+    const vision = name.includes("vision") || name.includes("blind") || name.includes("elderly") || name.includes("magnif");
+    const motor = name.includes("motor") || name.includes("tremor") || name.includes("parkinsons");
+    const cognitive = name.includes("adhd") || name.includes("dyslexic") || name.includes("cognitive") || name.includes("memory");
+    // Assistive-technology and hearing personas were in neither bucket, so
+    // screen-reader-user came back isDisabilityPersona: false -- while the
+    // same payload listed it as an exemplar on a sensory barrier and
+    // list_cognitive_personas filed it under accessibility. Three parts of
+    // the system disagreeing about whether a screen reader user has a
+    // disability, and the "no" was the one that drove the score.
+    const screenReader = name.includes("screen-reader") || name.includes("screenreader")
+        || name.includes("nvda") || name.includes("jaws") || name.includes("voiceover");
+    const hearing = name.includes("deaf") || name.includes("hearing")
+        || name.includes("hard-of-hearing");
+    const inferred = {
+        motorControl: motor ? 0.3 : ct.motorControl ?? 1.0,
+        tremor: motor,
+        reachability: motor ? 0.4 : 1.0,
+        visionLevel: vision ? 0.4 : ct.visionLevel ?? 1.0,
+        contrastSensitivity: vision ? 0.5 : ct.contrastSensitivity ?? 1.0,
+        processingSpeed: ct.comprehension ?? (cognitive ? 0.4 : 0.8),
+        attentionSpan: ct.patience ?? (cognitive ? 0.3 : 0.7),
+        fatigueSusceptibility: vision || motor ? 0.7 : 0.3,
+    };
+    const stored = storedAccessibilityTraits(persona);
+    return {
+        accessibilityTraits: { ...inferred, ...stored },
+        hints: { vision, motor, cognitive, screenReader, hearing },
+        storedFields: stored ? Object.keys(stored) : [],
+    };
+}
 export async function runEmpathyAudit(url, options) {
     const { goal, disabilities, wcagLevel = "AA", maxSteps = 20, maxTime = 120, headless = true, } = options;
     const startTime = Date.now();
@@ -3298,6 +3348,9 @@ export async function runEmpathyAudit(url, options) {
         const personaName = resolvedNames[index];
         let persona = getAccessibilityPersona(personaName);
         let isDisabilityPersona = !!persona;
+        // What the persona's record stores, for the attention pass below: the
+        // filter attention_analysis draws this persona with. (ISC-48.1)
+        let storedTraits = storedAccessibilityTraits(persona);
         if (!persona) {
             // Try to find as a regular cognitive persona and wrap it
             const { getAnyPersona, createCognitivePersona } = await import("../personas.js");
@@ -3306,39 +3359,15 @@ export async function runEmpathyAudit(url, options) {
             // into the scoped registry above, so getAnyPersona already sees them, and
             // a name nothing resolves was refused before the loop. (2026-10-09)
             if (cognitivePersona) {
-                // Wrap cognitive persona as accessibility persona, inferring traits from name + cognitive traits
-                const ct = cognitivePersona.cognitiveTraits || {};
-                const name = personaName.toLowerCase();
-                const hasVisionHint = name.includes("vision") || name.includes("blind") || name.includes("elderly") || name.includes("magnif");
-                const hasMotorHint = name.includes("motor") || name.includes("tremor") || name.includes("parkinsons");
-                const hasCognitiveHint = name.includes("adhd") || name.includes("dyslexic") || name.includes("cognitive") || name.includes("memory");
-                // Assistive-technology and hearing personas were in neither bucket, so
-                // screen-reader-user came back isDisabilityPersona: false -- while the
-                // same payload listed it as an exemplar on a sensory barrier and
-                // list_cognitive_personas filed it under accessibility. Three parts of
-                // the system disagreeing about whether a screen reader user has a
-                // disability, and the "no" was the one that drove the score.
-                const hasScreenReaderHint = name.includes("screen-reader") || name.includes("screenreader")
-                    || name.includes("nvda") || name.includes("jaws") || name.includes("voiceover");
-                const hasHearingHint = name.includes("deaf") || name.includes("hearing")
-                    || name.includes("hard-of-hearing");
-                persona = {
-                    ...cognitivePersona,
-                    accessibilityTraits: {
-                        motorControl: hasMotorHint ? 0.3 : ct.motorControl ?? 1.0,
-                        tremor: hasMotorHint,
-                        reachability: hasMotorHint ? 0.4 : 1.0,
-                        visionLevel: hasVisionHint ? 0.4 : ct.visionLevel ?? 1.0,
-                        contrastSensitivity: hasVisionHint ? 0.5 : ct.contrastSensitivity ?? 1.0,
-                        processingSpeed: ct.comprehension ?? (hasCognitiveHint ? 0.4 : 0.8),
-                        attentionSpan: ct.patience ?? (hasCognitiveHint ? 0.3 : 0.7),
-                        fatigueSusceptibility: hasVisionHint || hasMotorHint ? 0.7 : 0.3,
-                    },
-                };
+                // Wrap cognitive persona as accessibility persona: its stored traits,
+                // and traits inferred from name + cognitive traits for the rest.
+                storedTraits = storedAccessibilityTraits(cognitivePersona);
+                const wrapped = wrappedPersonaAccessibility(personaName, cognitivePersona);
+                const h = wrapped.hints;
+                persona = { ...cognitivePersona, accessibilityTraits: wrapped.accessibilityTraits };
                 // If the name hints at a disability, treat it as a disability persona for routing
-                isDisabilityPersona = hasVisionHint || hasMotorHint || hasCognitiveHint
-                    || hasScreenReaderHint || hasHearingHint;
-                console.log(`[empathy_audit] "${disability}" wrapped as ${isDisabilityPersona ? "disability" : "general"} persona (vision=${hasVisionHint}, motor=${hasMotorHint}, cognitive=${hasCognitiveHint}, screenReader=${hasScreenReaderHint}, hearing=${hasHearingHint})`);
+                isDisabilityPersona = h.vision || h.motor || h.cognitive || h.screenReader || h.hearing;
+                console.log(`[empathy_audit] "${disability}" wrapped as ${isDisabilityPersona ? "disability" : "general"} persona (vision=${h.vision}, motor=${h.motor}, cognitive=${h.cognitive}, screenReader=${h.screenReader}, hearing=${h.hearing}, stored=[${wrapped.storedFields.join(",")}])`);
             }
             else {
                 // Return an explicit error instead of silently skipping
@@ -3387,7 +3416,9 @@ export async function runEmpathyAudit(url, options) {
                 attnTemp = await makeTempDir("empathy-attn");
                 const attnScreenshot = attnTemp.file("page.png");
                 await page.screenshot({ path: attnScreenshot, fullPage: false });
-                const attnAnalysis = await analyzeAttention(attnScreenshot, personaName, 16);
+                // The record's stored traits, not the wrapped set: attention_analysis
+                // passes the record's, so both tools resolve the same filter.
+                const attnAnalysis = await analyzeAttention(attnScreenshot, personaName, 16, undefined, undefined, undefined, undefined, undefined, storedTraits);
                 attentionData = {
                     entropy: attnAnalysis.entropy,
                     concentration: attnAnalysis.concentration,
@@ -3405,12 +3436,15 @@ export async function runEmpathyAudit(url, options) {
                 //
                 // Anyone who wants attention metrics should call attention_analysis,
                 // which runs the same function at the finer default grid.
+                // perceptualProfile is not a metric: it says which filter drew the
+                // pass, as attention_analysis reports it, so the two can be compared.
                 result.attentionAnalysis = {
                     entropy: attnAnalysis.entropy,
                     concentration: attnAnalysis.concentration,
                     transportCost: attnAnalysis.transportCost,
                     computeTimeMs: Math.round(attnAnalysis.computeTimeMs),
                     gridCellPx: 16,
+                    perceptualProfile: attnAnalysis.perceptualProfile,
                 };
             }
             catch (e) {
@@ -3480,7 +3514,7 @@ export async function runEmpathyAudit(url, options) {
                 // persona scored the same on all three (B29, 2026-10-10). The copy keeps
                 // the bridge from writing into the persona record itself.
                 const loadTraits = { ...(resolvedPersona.cognitiveTraits || {}) };
-                bridgeCapacityTraits(personaName, loadTraits, resolvedPersona.accessibilityTraits);
+                bridgeCapacityTraits(personaName, loadTraits, resolvedPersona.accessibilityTraits, personaRateContext(resolvedPersona));
                 const otProfile = buildOTCognitiveProfile(personaName, loadTraits);
                 const cogLoad = estimateCognitiveLoad(otProfile, pageMetrics);
                 // Three separate models each produce a number called "cognitive load",