cbrowser 18.78.0 → 18.80.0

package/dist/mcp-tools/base/persona-comparison-tools.js

@@ -5,10 +5,11 @@
  * @license MIT
  */
 import { z } from "zod";
+import { resolveValuesForPersona } from "../../values/persona-values.js";
 import { writeArtifact } from "../../artifact-store.js";
 import { comparePersonas } from "../../analysis/index.js";
 import { isApiKeyConfigured } from "../../cognitive/index.js";
-import { getAnyPersona, getCognitiveProfile, createCognitivePersona, isAgentPersonaObject, BUILTIN_PERSONAS, ACCESSIBILITY_PERSONAS, EMOTIONAL_PERSONAS, } from "../../personas.js";
+import { getAnyPersona, resolvePersonaOrThrow, getCognitiveProfile, createCognitivePersona, isAgentPersonaObject, BUILTIN_PERSONAS, ACCESSIBILITY_PERSONAS, EMOTIONAL_PERSONAS, } from "../../personas.js";
 import { buildOTCognitiveProfile as buildOTProfile, cognitiveDistance, cognitiveBarycenter, cognitiveGeodesic, cognitiveDistanceMatrix, selectMaxCoveragePersonas, estimateCognitiveLoad, } from "../../visual/cognitive-transport.js";
 let distanceReference = null;
 function getDistanceReference() {
@@ -160,6 +161,9 @@ Example:
             const existingPersona = getAnyPersona(personaName);
             let personaObj;
             if (!existingPersona) {
+                // Unknown name: refuse. A fabricated persona here produces a complete
+                // per-persona assessment nobody can distinguish from a real one.
+                resolvePersonaOrThrow(personaName);
                 personaObj = createCognitivePersona(personaName, personaName, {});
             }
             else {
@@ -571,10 +575,16 @@ Begin with the first persona: ${personas[0]}
     });
     // ── Cognitive Effort (Full COT) ──
     server.registerTool("cognitive_effort", {
+        _meta: { ui: { resourceUri: "ui://cbrowser/effort" } },
         title: "Cognitive Effort Analysis",
-        description: "Compute total cognitive effort for a persona to use a page. Uses the 6-layer Sequential Transport Chain: saliency → cognitive load → decision → motor → frustration → readability. IMPORTANT: High-familiarity personas (power-user, confident-user) require site knowledge. If the user asks for these personas, first check if site knowledge exists by running site_model_status. If no site knowledge exists, either (1) ask the user if they want to build it first by navigating the site, or (2) warn them that results will treat the persona as a first-time visitor. The tool returns a familiarityWarning when site knowledge is missing.",
+        description: "Compute total cognitive effort for a persona to use a page. MEASURES THE VIEWPORT BY DEFAULT (above the fold); pass scope='full_page' to measure the whole page. Uses the 8-layer Sequential Transport Chain: saliency → cognitive load → decision → motor (target acquisition) → motor procedure (executing a sequence) → frustration → readability (decoding) → reading attention (holding the line, re-reading). IMPORTANT: High-familiarity personas (power-user, confident-user) require site knowledge. If the user asks for these personas, first check if site knowledge exists by running site_model_status. If no site knowledge exists, either (1) ask the user if they want to build it first by navigating the site, or (2) warn them that results will treat the persona as a first-time visitor. The tool returns a familiarityWarning when site knowledge is missing.",
         inputSchema: {
             url: z.string().url().describe("URL to analyze"),
+            // Per RUN, not per persona. A persona is familiar with one site and new
+            // to another, so this only has an answer once a URL is named. The
+            // persona's stored value, where one exists, is the fallback. (2026-08-01)
+            siteFamiliarity: z.number().min(0).max(1).optional()
+                .describe("How familiar this persona is with THIS url: 0 first visit, 1 daily user. Set it per run — familiarity is a persona-site pair, not a disposition. Supplying it also skips the site-knowledge downgrade, which exists only to stop a stored value asserting experience of a site nobody has crawled."),
             persona: z.string().describe("Persona name. WORKFLOW: For power-user, confident-user, or any persona the user describes as 'experienced' — check site_model_status first. If site knowledge exists, ask the user: 'Site knowledge exists for this domain. Should I use it to simulate an experienced user, or test as a first-time visitor?' If no site knowledge exists, warn: 'No site knowledge for this domain. power-user will be tested as a first-time visitor. Run page_understand first to build site knowledge.'"),
             _browserToken: z.string().optional().describe("Browser session token"),
             userLocation: z.string().optional().describe("User's approximate location (e.g., 'Denver, Colorado, US')"),
@@ -584,6 +594,7 @@ Begin with the first persona: ${personas[0]}
             useValues: z.boolean().optional().default(false).describe("Enable motivational value modulation (Schwartz values). When true, persona values modulate saliency maps, decision costs, and frustration costs. Default: false (trait-only mode)."),
             waitAfterLoad: z.number().optional().describe("Extra ms to wait after page loads (e.g., 3000 for sites with client-side translation)"),
             waitForSelector: z.string().optional().describe("CSS selector to wait for after load (e.g., '[data-translated]')"),
+            scope: z.enum(["viewport", "full_page", "sequential"]).optional().default("viewport").describe("What to measure: 'viewport' (first impression, above-the-fold — default), 'full_page' (scroll the whole page, count every element), or 'sequential' (score each screen on its own content, carrying capacity forward, and report where people stop). Viewport and full_page match empathy_audit's parameter. 'sequential' answers a different question from either: not 'what would the whole page cost' but 'how far do they get'. NOTE: every published CTC number predates this parameter and is a viewport measurement."),
         },
         annotations: {
             title: "Cognitive Effort Analysis",
@@ -592,7 +603,7 @@ Begin with the first persona: ${personas[0]}
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ url, persona: personaName, _browserToken, userLocation, userTimezone, userLanguage, proxy, useValues, waitAfterLoad, waitForSelector }) => {
+    }, async ({ url, persona: personaName, siteFamiliarity, _browserToken, userLocation, userTimezone, userLanguage, proxy, useValues, waitAfterLoad, waitForSelector, scope }) => {
         try {
             // Get browser
             let b;
@@ -674,14 +685,15 @@ Begin with the first persona: ${personas[0]}
                 };
             }
             // Get persona
+            // Refuses an unknown name rather than inventing one. An agent persona is
+            // still synthesised -- it exists, it just has no cognitive profile of its
+            // own -- but a name that resolves to nothing stops the run.
             const existingPersona = getAnyPersona(personaName);
-            let personaObj;
-            if (!existingPersona || isAgentPersonaObject(existingPersona)) {
-                personaObj = createCognitivePersona(personaName, personaName, {});
-            }
-            else {
-                personaObj = existingPersona;
-            }
+            if (!existingPersona)
+                resolvePersonaOrThrow(personaName);
+            const personaObj = isAgentPersonaObject(existingPersona)
+                ? createCognitivePersona(personaName, personaName, {})
+                : existingPersona;
             // v18.61.0: siteFamiliarity is a binary gate based on site knowledge
             // Has site knowledge → persona keeps its familiarity (maxed to 1.0 for experts)
             // No site knowledge → forced to 0.0 (first visit)
@@ -698,7 +710,15 @@ Begin with the first persona: ${personas[0]}
                 hasSiteKnowledge = !!(stats && stats.navigationNodes > 0);
             }
             catch { }
-            if (hasSiteKnowledge) {
+            // A caller who states familiarity for THIS run has answered the question
+            // the downgrade exists to answer. The gate guards against a value STORED
+            // on a persona claiming experience of a site nobody has crawled -- it was
+            // never meant to overrule someone naming the pair directly.
+            const familiarityFromCaller = typeof siteFamiliarity === "number";
+            if (familiarityFromCaller) {
+                traits.siteFamiliarity = siteFamiliarity;
+            }
+            else if (hasSiteKnowledge) {
                 // Site knowledge exists — high-familiarity personas get max familiarity
                 if (requestedFamiliarity > 0.5)
                     traits.siteFamiliarity = 1.0;
@@ -707,22 +727,96 @@ Begin with the first persona: ${personas[0]}
                 // No site knowledge — everyone is a first-time visitor
                 traits.siteFamiliarity = 0.0;
                 if (requestedFamiliarity > 0.5) {
-                    familiarityWarning = `"${personaName}" has siteFamiliarity=${requestedFamiliarity.toFixed(1)} but no site knowledge exists. Downgraded to 0.0 (first visit). To build site knowledge: navigate the site (navigate + click builds it automatically), or run page_understand for deeper analysis. Then re-run this tool.`;
+                    familiarityWarning = `"${personaName}" has siteFamiliarity=${requestedFamiliarity.toFixed(1)} stored on the persona but no site knowledge exists for this domain. Downgraded to 0.0 (first visit). Familiarity is a persona-site pair: pass siteFamiliarity on this call to state it for this run, or build knowledge by navigating the site (page_understand goes deeper).`;
                 }
             }
+            // Bridge the formal models into the trait vector BEFORE the chain runs.
+            //
+            // getReadingProfile and getPointingProfile already model this persona's
+            // decoding ability and Fitts pointing -- visual span, phonological
+            // decoding, throughput, endpoint dispersion -- and until now the chain
+            // never saw any of it. Its readability layer read `readingTendency`
+            // (a disposition: how much text someone reads) and its motor layer read
+            // patience and proceduralFluency, so a dyslexic persona scored LOWER
+            // readability cost than an ADHD persona on a text-dense page while the
+            // same response reported them at 157 WPM against 204.
+            //
+            // Injected here rather than stored on the persona: these are derived from
+            // the persona's profile, so storing them would create a second copy that
+            // can drift from the model that produces it. (2026-08-02)
+            let pointingProfileForResponse;
+            try {
+                const { getReadingProfile, getPointingProfile, readingCapacityOf, motorCapacityOf, sustainedAttentionOf } = await import("../../visual/cognitive-models.js");
+                // accessibilityTraits passed so an author's STATED reading capacity is
+                // honoured; without it the name lookup wins and the fields are inert.
+                const accTraits = personaObj.accessibilityTraits;
+                traits.readingCapacity = readingCapacityOf(getReadingProfile({ name: personaName, traits, accessibilityTraits: accTraits }));
+                const _pp = getPointingProfile({ name: personaName, traits });
+                pointingProfileForResponse = _pp;
+                traits.motorCapacity = motorCapacityOf(_pp);
+                // The attentional half of reading. Unlike the other two this one has no
+                // formal model behind it -- attentionSpan is stated directly, and the
+                // fallback is interruptRecovery -- so the resolver is the whole bridge.
+                traits.sustainedAttention = sustainedAttentionOf({ traits, accessibilityTraits: accTraits });
+            }
+            catch (e) {
+                // Left absent rather than defaulted: a missing capacity is visible as a
+                // gap, a defaulted one silently reads as average.
+                console.debug(`[cognitive_effort] capacity bridge unavailable: ${e.message}`);
+            }
             // Build OT profile (with potentially adjusted siteFamiliarity)
             const otProfile = buildOTProfile(personaName, traits);
             // Extract page metrics
             const { extractPageMetrics } = await import("../../visual/cognitive-transport.js");
-            const pageMetrics = await extractPageMetrics(page);
+            const measureScope = scope ?? "viewport";
+            // Sequential scores each screen on its own content; the aggregate path
+            // below still runs so every existing field keeps its meaning, measured at
+            // full_page since that is the comparable whole-document number.
+            const pageMetrics = await extractPageMetrics(page, measureScope === "sequential" ? "full_page" : measureScope);
             // Compute full COT
             const { computeDemandDistribution, computeSequentialCTC } = await import("../../visual/cognitive-transport-chain.js");
             const demand = computeDemandDistribution(pageMetrics);
+            // SEQUENTIAL PASS. Runs before the aggregate so a failure here degrades to
+            // the normal answer rather than losing the whole call.
+            let sequentialResult;
+            if (measureScope === "sequential") {
+                try {
+                    const { extractPerScreenMetrics } = await import("../../visual/cognitive-transport.js");
+                    const { computeSequentialScrollCTC } = await import("../../visual/cognitive-transport-chain.js");
+                    const perScreen = await extractPerScreenMetrics(page);
+                    const seqProfile = buildOTProfile(personaName, traits);
+                    const seq = computeSequentialScrollCTC(seqProfile, perScreen.map((m) => computeDemandDistribution(m)), { asymmetric: true, interactions: true });
+                    sequentialResult = {
+                        screensMeasured: seq.screens.length,
+                        totalAbandonment: `${Math.round(seq.totalAbandonment * 100)}%`,
+                        expectedDepthScreens: seq.expectedDepthScreens,
+                        dropOff: seq.dropOff
+                            ? { screen: seq.dropOff.screen, layer: seq.dropOff.layer, shareOfSessions: `${Math.round(seq.dropOff.share * 100)}%` }
+                            : null,
+                        reachWeightedCTC: seq.reachWeightedCTC,
+                        curve: seq.screens.map((x) => ({
+                            screen: x.screen,
+                            reach: `${Math.round(x.reachProbability * 100)}%`,
+                            stopHere: `${Math.round(x.stopHazard * 100)}%`,
+                            cumulativeAbandonment: `${Math.round(x.cumulativeAbandonment * 100)}%`,
+                            screenCTC: x.screenCTC,
+                            bottleneck: x.bottleneckLayer,
+                        })),
+                        note: "Each screen is measured on ITS OWN content, and capacity carries forward -- screen 7 is scored against what screens 1-6 left, not against a fresh persona. Count-based demands (interactive elements, choices) charge only elements not seen on an earlier screen, so a sticky nav is one decision rather than one per screen; text and visual density are NOT deduplicated, because re-encountering text is re-reading it.",
+                        differsFrom: "The aggregate `abandonmentRisk` above asks what the whole document would cost if it were all processed. This asks how far they get. They are different questions and will not agree.",
+                        uncalibrated: "The per-screen hazard uses the same ABANDONMENT_HILL_EXPONENT as the aggregate, which nothing empirical set. At 2 the curve is superlinear, so this model inherits a thumb on the scale.",
+                        readThisFirst: "TRUST THE SHAPE, NOT THE TOTAL. `totalAbandonment` compounds a per-screen hazard across every screen, so on a long page it saturates toward 100% almost regardless of the page -- measured, elderly-user reached 100% on a 7-screen university homepage. That is the uncalibrated exponent compounding, not a finding about that page. `expectedDepthScreens` and `dropOff` are the numbers to act on: they say how far people get and what stops them, and both depend on the RANKING of per-screen hazards rather than their absolute level, which is the part the exponent least disturbs. `dropOff` is persona-dependent by design and that is not noise: an impatient reader drops on screen one, a patient one survives to whichever screen is genuinely hardest, and the two answers are both correct for their reader.",
+                    };
+                }
+                catch (e) {
+                    sequentialResult = { error: `sequential pass failed: ${e.message}`, note: "The aggregate figures below are unaffected." };
+                }
+            }
             // Modulate demand by motivational values (opt-in, default off)
             if (useValues)
                 try {
                     const { getPersonaValues, registerPersonaValues: regPV2, createPersonaValues: createPV2 } = await import("../../values/index.js");
-                    let pValues = getPersonaValues(personaName);
+                    let pValues = resolveValuesForPersona(personaName);
                     // Custom persona CMS fallback
                     if (!pValues) {
                         try {
@@ -772,6 +866,14 @@ Begin with the first persona: ${personas[0]}
             // Also compute motor and readability from formal models
             let motorResult = null;
             let readabilityResult = null;
+            // Hoisted out of the try below: the readability OVERLAY is drawn later,
+            // outside that block, and needs the on-page rectangles the analysis
+            // itself does not carry.
+            let textBlockGeom = [];
+            // Hoisted for the same reason as textBlockGeom: the motor OVERLAY is drawn
+            // outside the block that scores these, and it must use the scored list
+            // rather than a second query with a different filter.
+            let motorGeom = [];
             try {
                 const { motorAccessibility, readability, getPointingProfile, getReadingProfile } = await import("../../visual/cognitive-models.js");
                 // Get interactive elements for motor analysis — viewport-visible only
@@ -779,23 +881,95 @@ Begin with the first persona: ${personas[0]}
                     const vw = window.innerWidth;
                     const vh = window.innerHeight;
                     const interactive = document.querySelectorAll('a, button, input, select, textarea, [role="button"]');
+                    // Only elements a POINTING DEVICE could actually hit.
+                    //
+                    // The old filter asked for non-zero size and in-viewport, which a
+                    // visually-hidden skip link passes: the standard implementation is a
+                    // 1px box with clip: rect(0,0,0,0), so it has non-zero geometry and
+                    // sits at the top of the page. It was then fed to Fitts, which
+                    // correctly reported a multi-second movement time at 1% accuracy for
+                    // a 1px target -- and the tool docked the site's motor accessibility
+                    // score for implementing WCAG 2.4.1 Bypass Blocks.
+                    //
+                    // An accessibility product penalising a site for correct accessibility
+                    // is the most expensive false positive available here, so the check is
+                    // now what actually decides a mouse click: elementFromPoint at the
+                    // element's centre. If the click would land on something else, it is
+                    // not a pointing target. Cheap style and area checks run first because
+                    // elementFromPoint forces layout.
+                    //
+                    // Skip links ARE interactive for keyboard users. If the motor model is
+                    // ever extended to keyboard traversal they belong there, with their
+                    // FOCUSED geometry rather than their hidden geometry. (2026-08-02)
+                    const MIN_TARGET_PX = 4;
                     return Array.from(interactive).filter((el) => {
                         const rect = el.getBoundingClientRect();
-                        return rect.width > 0 && rect.height > 0 &&
-                            rect.bottom > 0 && rect.top < vh &&
-                            rect.right > 0 && rect.left < vw;
+                        if (rect.width < MIN_TARGET_PX || rect.height < MIN_TARGET_PX)
+                            return false;
+                        if (rect.bottom <= 0 || rect.top >= vh || rect.right <= 0 || rect.left >= vw)
+                            return false;
+                        const cs = window.getComputedStyle(el);
+                        if (cs.visibility === "hidden" || cs.display === "none")
+                            return false;
+                        if (parseFloat(cs.opacity || "1") < 0.05)
+                            return false;
+                        if (cs.pointerEvents === "none")
+                            return false;
+                        // clip / clip-path collapsing the box to nothing is the classic
+                        // visually-hidden idiom and leaves the bounding rect intact.
+                        const clip = cs.clip || "";
+                        if (/rect\(\s*0(px)?[,\s]+0(px)?[,\s]+0(px)?[,\s]+0(px)?\s*\)/.test(clip))
+                            return false;
+                        if ((cs.clipPath || "").replace(/\s/g, "") === "inset(50%)")
+                            return false;
+                        // The decisive test: would a click at the centre reach this element?
+                        const x = Math.min(vw - 1, Math.max(0, rect.left + rect.width / 2));
+                        const y = Math.min(vh - 1, Math.max(0, rect.top + rect.height / 2));
+                        const hit = document.elementFromPoint(x, y);
+                        return !!hit && (hit === el || el.contains(hit) || hit.contains(el));
                     }).slice(0, 30).map((el) => {
                         const rect = el.getBoundingClientRect();
                         const cx = vw / 2;
                         const cy = vh / 2;
                         return {
-                            selector: el.tagName.toLowerCase() + (el.id ? `#${el.id}` : ''),
+                            // Identifying, not just the tag name.
+                            //
+                            // This reported barriers as bare "a", so every anchor on the page
+                            // looked identical and a finding like "an <a> with 1% hit
+                            // probability" named nothing anyone could go and fix. It also made
+                            // two runs look like they were measuring the same element when
+                            // they had surfaced different links -- which is how a slower
+                            // movement time appeared alongside a HIGHER throughput and read as
+                            // a model inversion. (2026-08-02)
+                            selector: (() => {
+                                const tag = el.tagName.toLowerCase();
+                                if (el.id)
+                                    return `${tag}#${el.id}`;
+                                // className via the guarded read: on an SVG element it is an
+                                // SVGAnimatedString, not a string, and calling .trim() on it
+                                // throws. There is a class-sweep test for exactly this and it
+                                // caught this line.
+                                const rawCls = el.className;
+                                const clsStr = typeof rawCls === "string"
+                                    ? rawCls
+                                    : String(rawCls?.baseVal ?? "");
+                                const cls = clsStr.trim() ? `.${clsStr.trim().split(/\s+/)[0]}` : "";
+                                const label = (el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 30);
+                                const sibs = el.parentElement ? Array.from(el.parentElement.children).filter((c) => c.tagName === el.tagName) : [];
+                                const nth = sibs.length > 1 ? `:nth-of-type(${sibs.indexOf(el) + 1})` : "";
+                                return `${tag}${cls}${nth}${label ? ` "${label}"` : ""}`;
+                            })(),
                             width: rect.width,
                             height: rect.height,
+                            // Carried so the overlay can be drawn from THIS list rather than
+                            // re-querying: see the note at the overlay site.
+                            x: rect.x,
+                            y: rect.y,
                             distance: Math.sqrt((rect.x + rect.width / 2 - cx) ** 2 + (rect.y + rect.height / 2 - cy) ** 2),
                         };
                     });
                 });
+                motorGeom = elements.map((e) => ({ selector: e.selector, x: e.x, y: e.y, width: e.width, height: e.height }));
                 motorResult = motorAccessibility(elements, otProfile);
                 // Get text blocks for readability analysis — viewport-visible only
                 const textBlocks = await page.evaluate(() => {
@@ -817,30 +991,85 @@ Begin with the first persona: ${personas[0]}
                         const lineHeight = parseFloat(style.lineHeight) / fontSize || 1.5;
                         const fontFamily = style.fontFamily || 'sans-serif';
                         const isSerif = /serif/i.test(fontFamily) && !/sans-serif/i.test(fontFamily);
-                        blocks.push({ text: text.slice(0, 500), fontSize, lineHeight, fontFamily, isSerif, contrastRatio: 7 });
+                        // Geometry travels with the block. Without it the readability
+                        // overlay cannot be drawn at all -- the analysis knew which text was
+                        // hard and not where any of it was.
+                        blocks.push({ text: text.slice(0, 500), fontSize, lineHeight, fontFamily, isSerif, contrastRatio: 7,
+                            x: rect.x, y: rect.y, width: rect.width, height: rect.height });
                         if (blocks.length >= 20)
                             break;
                     }
                     return blocks;
                 });
+                textBlockGeom = textBlocks.map((b) => ({ x: b.x, y: b.y, width: b.width, height: b.height, text: b.text }));
                 if (textBlocks.length > 0) {
-                    readabilityResult = readability(textBlocks, otProfile);
+                    // otProfile carries name + traits but not accessibilityTraits, so the
+                    // stated reading capacity is attached here or the fields stay inert.
+                    readabilityResult = readability(textBlocks, {
+                        ...otProfile,
+                        accessibilityTraits: personaObj.accessibilityTraits,
+                    });
                 }
             }
             catch { }
             // Format response
+            // What was actually measured, taken from the page after navigation rather
+            // than from the argument. The response used to echo the requested URL
+            // while describing a different site: `url: "https://www.ucdenver.edu"` on
+            // an analysis of cudenver.edu, which ucdenver.edu 301s to. `navigate`
+            // already warns on this mismatch; nothing else did.
+            const landedUrl = (() => { try {
+                return page.url();
+            }
+            catch {
+                return url;
+            } })();
+            const hostOf = (u) => { try {
+                return new URL(u).hostname.toLowerCase();
+            }
+            catch {
+                return "";
+            } };
+            const redirected = !!landedUrl && hostOf(landedUrl) !== "" && hostOf(landedUrl) !== hostOf(url);
             const response = {
                 url,
+                ...(redirected ? {
+                    resolvedUrl: landedUrl,
+                    redirectNote: `Requested ${hostOf(url)} and landed on ${hostOf(landedUrl)}. Every number below describes ${hostOf(landedUrl)}.`,
+                } : { resolvedUrl: landedUrl }),
                 persona: personaName,
                 cognitiveTransportCost: {
                     total: Math.round(result.totalCTC * 1000) / 1000,
                     additive: Math.round(result.additiveCTC * 1000) / 1000,
-                    sequentialAmplification: Math.round((result.totalCTC / Math.max(0.001, result.additiveCTC)) * 100) / 100,
+                    // The un-normalized cost. `total` is a sigmoid of this, so the two
+                    // are not interchangeable and any ratio must use `raw`.
+                    raw: Math.round(result.rawCTC * 1000) / 1000,
+                    // raw / additive — both in layer-cost units, so this is the genuine
+                    // contribution of interactions and sequential depletion.
+                    chainCoefficient: Math.round((result.rawCTC / Math.max(0.001, result.additiveCTC)) * 1000) / 1000,
+                    /**
+                     * @deprecated Use chainCoefficient. NOTE ITS VALUE CHANGED: this used
+                     * to divide `total` (a sigmoid, 0-1) by `additive` (a raw sum) and
+                     * reported ~0.3-0.5, which read as the chain dampening by 60%. That
+                     * was a unit error, not a measurement — it was reporting the sigmoid.
+                     * Preserving the old number bit-for-bit would preserve a meaningless
+                     * one, so this now carries the corrected value.
+                     */
+                    sequentialAmplification: Math.round((result.rawCTC / Math.max(0.001, result.additiveCTC)) * 1000) / 1000,
+                    chainNote: "chainCoefficient = raw / additive, both in layer-cost units. Above 1 means interactions and sequential depletion added cost. Re-measured 1.002-1.036 at EIGHT layers, after `motor` was split into target acquisition and sequence execution (2026-08-03). It was 1.003-1.054 at seven and 1.002-1.019 at six. The range narrowed rather than widening this time: splitting one layer into two halves each layer's per-step cost, so the same total is reached through smaller increments and less of it compounds. Real, and small. Do NOT compute total/additive — total is a sigmoid of raw and the ratio compares different units.",
+                    interpretationBasis: "total",
+                    interpretationBands: "total < 0.3 comfortable, < 0.6 moderate, < 0.8 struggling, else likely abandon",
                 },
                 layers: result.layers.map(l => ({
                     name: l.name,
                     cost: Math.round(l.transportCost * 1000) / 1000,
                     capacityConsumed: Math.round(l.capacityConsumed * 1000) / 1000,
+                    // Emitted only where it says something the cost cannot: at zero cost
+                    // the layer has stopped discriminating and headroom is the remaining
+                    // signal. Above zero the cost carries it, and a second number would
+                    // just be noise. (BUG-18)
+                    ...(l.transportCost < 0.001 && l.headroom > 0
+                        ? { headroom: l.headroom, costIsAtFloor: true } : {}),
                 })),
                 bottleneck: result.bottleneckLayer,
                 deficitVsSurplus: {
@@ -848,10 +1077,61 @@ Begin with the first persona: ${personas[0]}
                     surplus: Math.round(result.surplusCost * 1000) / 1000,
                 },
                 abandonmentRisk: Math.round(result.abandonmentRisk * 100) + "%",
+                // Says out loud that these two are different constructs.
+                //
+                // A run can read "easy" on CTC and 53% on abandonment and both be
+                // correct, which looks like a contradiction and is not one:
+                // abandonmentRisk is a sigmoid of (deficit - 0.3*surplus) against this
+                // persona's blended patience and resilience, and never touches
+                // totalCTC. CTC asks how expensive the page is; abandonment asks
+                // whether THIS persona's tolerance runs out first. A page can be cheap
+                // in absolute terms and still exceed someone with little patience.
+                // WHAT THIS NUMBER IS CONDITIONAL ON. It was reported as though it were
+                // "the fraction of visitors who leave", and it is not that at either
+                // scope -- it is two different conditional quantities depending on
+                // which scope produced it, and the output did not distinguish them.
+                abandonmentBasis: measureScope === "full_page"
+                    ? "P(this persona's budget is exhausted | they process the ENTIRE document). A conditional upper bound, not a prediction of observed behaviour: almost nobody reads a whole page. Deficit is summed across the whole document and compared against this persona's blended patience and resilience. Independent of totalCTC, so the two can disagree without either being wrong."
+                    : "P(this persona's budget is exhausted ON THE FIRST SCREEN). Real and interpretable, and it ignores everything below the fold. Deficit is summed across the viewport only and compared against this persona's blended patience and resilience. Independent of totalCTC, so the two can disagree without either being wrong.",
+                abandonmentNotModelled: "Neither figure is 'what fraction of visitors leave'. A page is consumed as a SEQUENCE of screens, each with its own chance of stopping, and this model evaluates one aggregate. Two consequences it cannot express: demand below the fold is not weighted by the probability of ever reaching it, and capacity depletes with scroll depth as well as across layers. A persona also has no variance here -- every trait is a scalar, so this is one hypothetical person's trajectory, not a population, and no fraction-of-visitors reading is available from it at all.",
                 interactions: Object.fromEntries(Object.entries(result.interactions)
                     .filter(([, v]) => v > 0.001)
                     .map(([k, v]) => [k, Math.round(v * 1000) / 1000])),
                 ...(motorResult ? {
+                    // WHY the two motor layers can disagree, shown rather than left to be
+                    // discovered. `motor` is target acquisition and `motorProcedure` is
+                    // sequence execution, and a persona can be poor at one and competent at
+                    // the other -- which is exactly what makes them separable and exactly
+                    // what read as a contradiction while they shared a scalar.
+                    //
+                    // Pointing is decomposed further because `motorCapacity` and
+                    // `hitProbability` are two different reductions of the same profile:
+                    // capacity weights Fitts throughput at 0.75, hit probability uses
+                    // endpoint dispersion alone. They therefore rank personas differently,
+                    // and a reader comparing them needs to see that rather than infer it.
+                    motorDecomposition: (() => {
+                        try {
+                            const pp = pointingProfileForResponse;
+                            if (!pp)
+                                return undefined;
+                            const L = result.layers;
+                            const acquire = L.find((l) => l.name === "motor")?.transportCost ?? 0;
+                            const sequence = L.find((l) => l.name === "motorProcedure")?.transportCost ?? 0;
+                            return {
+                                targetAcquisition: Math.round(acquire * 1000) / 1000,
+                                sequenceExecution: Math.round(sequence * 1000) / 1000,
+                                pointingInputs: {
+                                    fittsThroughput: Math.round(pp.throughput * 100) / 100,
+                                    endpointDispersionPx: Math.round(((pp.sigmaX + pp.sigmaY) / 2) * 10) / 10,
+                                    note: "throughput drives movementTimeMs; dispersion drives hitProbability. motorCapacity weights throughput at 0.75, so the `motor` layer and `hitProbability` legitimately rank personas differently.",
+                                },
+                                note: "These two are additive and unweighted against each other. There is no empirical basis for a relative weighting between acquiring a target and executing a sequence, so none is applied - see MOTOR_LAYER_WEIGHTS, both 1.0 and marked uncalibrated.",
+                            };
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    })(),
                     motorAccessibility: {
                         score: Math.round(motorResult.score * 100) + "%",
                         barriers: motorResult.barrierCount,
@@ -864,21 +1144,115 @@ Begin with the first persona: ${personas[0]}
                 } : {}),
                 ...(readabilityResult ? {
                     readability: {
+                        // Renamed from `score`. This is a QUALITY percentage where high is
+                        // good; the chain's `readability` layer is a COST where high is bad.
+                        // Both were called readability, so a run could report readability
+                        // 91% and readability as the bottleneck in the same payload and
+                        // look self-contradictory when it was reporting two different
+                        // measurements under one word. (2026-08-02)
+                        legibilityQuality: Math.round(readabilityResult.score * 100) + "%",
+                        /** @deprecated ambiguous against the layer cost — use legibilityQuality */
                         score: Math.round(readabilityResult.score * 100) + "%",
+                        // The note here previously said this was "a quality score for the
+                        // text itself", contrasted against the persona-relative layer cost.
+                        // That was wrong, and I wrote it. It comes from readability(), which
+                        // resolves a per-persona reading profile (visual span, phonological
+                        // decoding, crowding sensitivity) -- so it is persona-RELATIVE by
+                        // construction and reads 91% for one persona and 73% for another on
+                        // identical text. A field promising objectivity is the one most
+                        // likely to be quoted as an objective page score. (2026-08-02)
+                        note: "legibilityQuality is how legible this text is FOR THIS PERSONA (higher is better) — it is computed from their reading profile, so it varies across personas on identical text and is NOT an objective property of the page. The `readability` entry in `layers` is the DECODING transport cost for the same persona (higher is worse), and the two move together: for a given persona, lower legibility means higher readability cost until the cost reaches its floor of 0, which it does whenever decoding capacity exceeds what the page demands — at that point read `headroom` on the readability layer instead, because the cost cannot tell a comfortable reader from a very comfortable one. Across personas the ordering holds for any material difference in legibility, but not to the last decimal — layers spend from a budget the earlier ones depleted, so two readers with near-identical legibility can differ slightly if one arrived more depleted. The ATTENTIONAL cost of reading (holding the line, re-reading, being pulled away) is a separate layer, `readingAttention`, and is deliberately not part of this number.",
+                        legibilityQualityIsPersonaRelative: true,
                         averageWPM: Math.round(readabilityResult.blocks.reduce((s, b) => s + b.wordsPerMinute, 0) / readabilityResult.blocks.length),
                         hardestBlock: readabilityResult.blocks.length > 0
                             ? readabilityResult.blocks.reduce((worst, b) => b.difficulty > worst.difficulty ? b : worst).penalties
                             : [],
+                        // Every component of that block, including the zeroes.
+                        //
+                        // `hardestBlock` is a prose list and each entry is gated behind its
+                        // own threshold, so a component evaluating to 0 is simply absent --
+                        // and absent is indistinguishable from not modelled. That is how
+                        // `crowdingSensitivity` came to look like a trait that does
+                        // nothing: it is weighted 0.15 into readingCapacity AND priced per
+                        // block, but Pelli's crowding effect only begins below 16px and
+                        // every page tested sets body text at 16px or more. At 13px it
+                        // discriminates cleanly -- adhd +6ms, dyslexic +17ms, low-vision
+                        // +21ms, tracking sensitivities of 0.20 / 0.55 / 0.70. (BUG-12)
+                        ...(readabilityResult.blocks.length > 0 ? {
+                            hardestBlockPenaltyMs: readabilityResult.blocks
+                                .reduce((worst, b) => b.difficulty > worst.difficulty ? b : worst).penaltyBreakdown,
+                            penaltyNote: "hardestBlockPenaltyMs carries every component, including those that came to 0. A 0 means the component was evaluated and does not apply to this text -- crowding, for one, only begins below 16px (Pelli et al. 2004) -- not that it is unmodelled. crowdingSensitivity additionally carries a 0.15 weight into readingCapacity, which reaches the readability layer at every font size.",
+                        } : {}),
                     },
                 } : {}),
-                interpretation: result.totalCTC < 0.3
-                    ? `${personaName} should handle this page comfortably.`
-                    : result.totalCTC < 0.6
-                        ? `${personaName} will experience moderate cognitive effort. Bottleneck: ${result.bottleneckLayer}.`
-                        : result.totalCTC < 0.8
-                            ? `${personaName} will struggle significantly. ${result.bottleneckLayer} is the primary barrier. Consider simplifying.`
-                            : `${personaName} is likely to abandon this page. Cognitive transport cost is ${Math.round(result.totalCTC * 100)}%. Immediate remediation needed on ${result.bottleneckLayer}.`,
+                // The verdict names its own scope. Reading "should handle this page
+                // comfortably" off a measurement of the top 800px of a 6436px page is
+                // the same class of output defect as the skip-link false positive:
+                // internally consistent and indefensible to a customer.
+                //
+                // `subject` is what was actually measured, so the sentence stays true
+                // at either scope instead of the scope being a footnote elsewhere.
+                interpretation: (() => {
+                    const subject = measureScope === "full_page" ? "this page" : "the top of this page";
+                    const where = measureScope === "full_page" ? "" : " (viewport only";
+                    const screens = pageMetrics.pageScreens > 1.2
+                        ? `${measureScope === "full_page" ? " Measured across" : `${where}; the page is`} ${pageMetrics.pageScreens} screens${measureScope === "full_page" ? "." : ", so most of it was not measured — pass scope='full_page' for the whole thing.)"}`
+                        : where ? `${where}.)` : "";
+                    const verdict = result.totalCTC < 0.3
+                        ? `${personaName} should handle ${subject} comfortably.`
+                        : result.totalCTC < 0.6
+                            ? `${personaName} will experience moderate cognitive effort on ${subject}. Bottleneck: ${result.bottleneckLayer}.`
+                            : result.totalCTC < 0.8
+                                ? `${personaName} will struggle significantly with ${subject}. ${result.bottleneckLayer} is the primary barrier. Consider simplifying.`
+                                : `${personaName} is likely to abandon ${subject}. Cognitive transport cost is ${Math.round(result.totalCTC * 100)}%. Immediate remediation needed on ${result.bottleneckLayer}.`;
+                    return verdict + screens;
+                })(),
+                // ONE AUTHORITATIVE FIELD PER READING DIMENSION, stated rather than
+                // left to be inferred from which layer moved. Reading ability was
+                // encoded in two places -- five explicit fields in accessibility_traits
+                // AND `comprehension` plus `readingTendency` in the main vector -- with
+                // nothing saying which the model reads. That is the two-registry
+                // divergence shape, caught before the fields drifted. (BUG-13 / D-11)
+                readingModel: {
+                    decoding: {
+                        authoritative: "accessibility_traits.{orthographicFluency, phonologicalDecoding, visualSpan, vocabularyBreadth, crowdingSensitivity}",
+                        reaches: "readability layer, via the derived readingCapacity dimension",
+                    },
+                    attention: {
+                        authoritative: "accessibility_traits.attentionSpan, falling back to traits.interruptRecovery",
+                        reaches: "readingAttention layer, via the derived sustainedAttention dimension",
+                    },
+                    engagement: {
+                        authoritative: "traits.readingTendency",
+                        reaches: "modulates readingAttention DEMAND only — a disposition, not an ability, and it does not touch decoding",
+                    },
+                    notConsumedForReading: {
+                        "traits.comprehension": "grasp of UI conventions, not reading. Consumed by cognitiveLoad only. A persona's 0.5 here says nothing about how well they read.",
+                    },
+                },
+                ...(sequentialResult ? { sequential: sequentialResult } : {}),
+                scope: measureScope,
+                pageScreens: pageMetrics.pageScreens,
+                scopeNote: measureScope === "full_page"
+                    ? "Whole-page measurement: every laid-out element counted, densities normalised against document area, and the page scrolled first so lazy content exists. Not comparable with viewport-scoped numbers, including every CTC this tool published before 2026-08-02."
+                    : "VIEWPORT ONLY: demand is computed from elements intersecting the first screenful. Content below the fold contributed nothing. This was the tool's undeclared behaviour until 2026-08-02 — measured on a 229-link, 8-screen page it saw 4 links and 47 words and reported LOWER cognitive load than a shorter homepage. Pass scope='full_page' to measure the whole page.",
                 ...(familiarityWarning ? { familiarityWarning, siteFamiliarityAdjusted: true, originalFamiliarity: requestedFamiliarity, effectiveFamiliarity: traits.siteFamiliarity } : {}),
+                // Reports what was USED, not what was passed.
+                //
+                // This previously said "supplied for this run" whenever the caller sent
+                // a number, without any check that the number reached the model. It
+                // did not: siteFamiliarity had no demand term and no home layer, so
+                // three runs at unset / 1 / 0 came back byte-identical under a response
+                // asserting the parameter had been applied. An attestation nobody
+                // verifies is worse than no attestation, because it makes an
+                // output-level audit report the knob as working. (2026-08-02)
+                siteFamiliarity: traits.siteFamiliarity,
+                siteFamiliaritySource: familiarityFromCaller
+                    ? "supplied for this run"
+                    : hasSiteKnowledge
+                        ? "derived from this install's crawl of the site"
+                        : "defaulted to first visit — no site knowledge and none supplied",
+                siteFamiliarityEffect: `Consumed by the cognitiveLoad layer against a demand set by navigation depth. A page reachable in one click demands no site knowledge, so this changes nothing there.`,
                 ...(languageWarning ? { languageWarning } : {}),
                 ...(userLocation ? { userContext: { location: userLocation, timezone: userTimezone, language: userLanguage } } : {}),
                 ...(token ? { _browserToken: token } : {}),
@@ -894,18 +1268,21 @@ Begin with the first persona: ${personas[0]}
                     await page.screenshot({ path: ssPath, fullPage: false });
                     // Get element bounding boxes for motor overlay
                     const motorElements = await page.evaluate(() => {
-                        const els = document.querySelectorAll('a, button, input, select, textarea, [role="button"]');
-                        return Array.from(els).slice(0, 30).map(el => {
-                            const rect = el.getBoundingClientRect();
-                            return {
-                                selector: el.tagName.toLowerCase(),
-                                x: rect.x, y: rect.y, width: rect.width, height: rect.height,
-                            };
-                        }).filter((e) => e.width > 0 && e.height > 0);
+                        return [];
                     });
                     const { generateMotorOverlay } = await import("../../visual/visual-overlays.js");
-                    const motorOverlayElements = motorElements.map((el, i) => ({
-                        ...el,
+                    // Drawn from the SAME list that was scored.
+                    //
+                    // This used to run a second querySelectorAll with a different filter
+                    // and zip it to motorResult.elements BY INDEX, so the two lists only
+                    // lined up while both filters happened to admit the same elements in
+                    // the same order. Tightening the scoring filter to exclude
+                    // non-hit-testable targets would have guaranteed a mismatch, and the
+                    // overlay would have drawn each element's hit probability on some
+                    // other element's box. (2026-08-02)
+                    const motorOverlayElements = motorGeom.map((el, i) => ({
+                        selector: el.selector,
+                        x: el.x, y: el.y, width: el.width, height: el.height,
                         hitProbability: motorResult.elements[i]?.hitProbability ?? 0.9,
                         isBarrier: motorResult.elements[i]?.isBarrier ?? false,
                     }));
@@ -915,7 +1292,115 @@ Begin with the first persona: ${personas[0]}
                     if (written)
                         response.motorOverlayUrl = written.url;
                     response.motorOverlayNote = "Green = easy to click. Yellow = moderate difficulty. Red = motor barrier for this persona.";
-                    content.push({ type: "image", data: motorBase64, mimeType: "image/png" });
+                    // Inlined ONLY when small. A tool result is not an image transport.
+                    //
+                    // This pushed the full base64 overlay unconditionally, and on a real
+                    // page that was 309,296 of a 312,580-byte result -- 99% image around
+                    // 2,828 bytes of data. Hosts cap tool-result size, and past that cap
+                    // the widget does not degrade, it fails to load. The MCP Apps guidance
+                    // says heavy assets travel via callServerTool, which is exactly what
+                    // the chain widget now does: every overlay, motor included, is written
+                    // as an artifact and fetched on demand by the bar that shows it.
+                    //
+                    // A small overlay still rides along so the model can see it without a
+                    // round trip. A large one is named, not carried. (2026-08-02)
+                    const INLINE_IMAGE_MAX_B64 = 40_000;
+                    if (motorBase64.length <= INLINE_IMAGE_MAX_B64) {
+                        content.push({ type: "image", data: motorBase64, mimeType: "image/png" });
+                    }
+                    else {
+                        response.motorOverlayInline = false;
+                        response.motorOverlayNote = `${response.motorOverlayNote ?? ""} Overlay is ${Math.round(motorBase64.length / 1024)}KB, too large to inline in a tool result; fetch it with artifact_fetch using the filename in layerOverlays, or open it from the chain view.`.trim();
+                    }
+                    // ssPath is deliberately NOT deleted here any more -- the other
+                    // layer overlays are drawn from the same screenshot below.
+                }
+            }
+            catch (e) {
+                console.debug(`[cognitive_effort] Motor overlay failed: ${e.message}`);
+            }
+            // Per-layer visual evidence, so a bar in the chain can be opened into the
+            // thing it measured.
+            //
+            // Only layers with a real generator get one. The other two are listed with
+            // the reason rather than omitted: a chain of six where four are clickable
+            // and two silently are not reads as a broken widget, while "no overlay for
+            // this layer, and here is why" is information. Nothing is fabricated to
+            // fill the gap. (2026-08-02)
+            const layerOverlays = [];
+            try {
+                const { join: joinPath } = await import("path");
+                const { tmpdir: getTmpDir } = await import("os");
+                const { unlinkSync: ul, existsSync: ex } = await import("fs");
+                const ssPath = joinPath(getTmpDir(), `cog-effort-layers-${Date.now()}.png`);
+                await page.screenshot({ path: ssPath, fullPage: false });
+                // saliency -- keyless. Lab-space centre-surround over the screenshot,
+                // so this needs no API key and no model call.
+                try {
+                    const { computeLabSaliency } = await import("../../visual/attention-transport.js");
+                    const { generateHeatmapOverlay } = await import("../../visual/heatmap-overlay.js");
+                    const sal = await computeLabSaliency(ssPath);
+                    const b64 = await generateHeatmapOverlay(ssPath, sal.cells, sal.rows, sal.cols, `${personaName} — saliency`);
+                    const w = writeArtifact(Buffer.from(b64, "base64"), `saliency-${personaName}-${Date.now()}.png`);
+                    if (w)
+                        layerOverlays.push({ layer: "saliency", file: w.url.split("/").pop(), available: true,
+                            legend: "Hotter = more visually salient before any reading happens." });
+                }
+                catch (e) {
+                    layerOverlays.push({ layer: "saliency", available: false, reason: `saliency map failed: ${e.message}` });
+                }
+                // motor -- already drawn above; surfaced here so the chain has one list.
+                if (response.motorOverlayUrl) {
+                    layerOverlays.push({ layer: "motor", file: String(response.motorOverlayUrl).split("/").pop(), available: true,
+                        legend: String(response.motorOverlayNote || "") });
+                }
+                else {
+                    layerOverlays.push({ layer: "motor", available: false, reason: "no interactive elements were found to score" });
+                }
+                // readability
+                if (readabilityResult && readabilityResult.blocks.length > 0) {
+                    try {
+                        const { generateReadabilityOverlay } = await import("../../visual/visual-overlays.js");
+                        const rb = readabilityResult.blocks.map((b, i) => ({
+                            x: textBlockGeom[i]?.x ?? 0, y: textBlockGeom[i]?.y ?? 0,
+                            width: textBlockGeom[i]?.width ?? 0, height: textBlockGeom[i]?.height ?? 0,
+                            difficulty: b.difficulty ?? 0, wpm: b.wordsPerMinute ?? 0,
+                            text: textBlockGeom[i]?.text ?? "",
+                        })).filter((b) => b.width > 0 && b.height > 0);
+                        if (rb.length) {
+                            const b64 = await generateReadabilityOverlay(ssPath, rb, personaName);
+                            const w = writeArtifact(Buffer.from(b64, "base64"), `readability-${personaName}-${Date.now()}.png`);
+                            if (w)
+                                layerOverlays.push({ layer: "readability", file: w.url.split("/").pop(), available: true,
+                                    legend: "Hotter = slower for this persona to read." });
+                        }
+                        else {
+                            layerOverlays.push({ layer: "readability", available: false, reason: "text blocks carried no on-page geometry" });
+                        }
+                    }
+                    catch (e) {
+                        layerOverlays.push({ layer: "readability", available: false, reason: `readability overlay failed: ${e.message}` });
+                    }
+                }
+                else {
+                    layerOverlays.push({ layer: "readability", available: false, reason: "no readable text blocks in the viewport" });
+                }
+                // The remaining two have no generator, and no data here to build one
+                // from. Said plainly rather than left as a dead bar.
+                // camelCase, matching LAYER_DEFINITIONS. Emitted as "cognitive-load" at
+                // first, which matched nothing: the bar got neither a button nor a
+                // no-overlay tag and silently looked different from its five siblings.
+                layerOverlays.push({ layer: "cognitiveLoad", available: false,
+                    reason: "no per-region load data is produced by this tool, so there is nothing to draw" });
+                layerOverlays.push({ layer: "decision", available: false,
+                    reason: "decision cost is computed over the page as a whole, not per region" });
+                layerOverlays.push({ layer: "frustration", available: false,
+                    reason: "frustration is a running state across the chain, not a place on the page" });
+                layerOverlays.push({ layer: "motorProcedure", available: false,
+                    reason: "sequence execution is a property of a flow across pages, not a place on this one \u2014 the motor overlay above shows where TARGET ACQUISITION is hard" });
+                layerOverlays.push({ layer: "readingAttention", available: false,
+                    reason: "attentional reading cost is a property of the reader against the whole page, not of any one region \u2014 the readability overlay above shows where DECODING is slow" });
+                if (ex(ssPath)) {
                     try {
                         ul(ssPath);
                     }
@@ -923,7 +1408,11 @@ Begin with the first persona: ${personas[0]}
                 }
             }
             catch (e) {
-                console.debug(`[cognitive_effort] Motor overlay failed: ${e.message}`);
+                console.debug(`[cognitive_effort] Layer overlays failed: ${e.message}`);
+            }
+            if (layerOverlays.length) {
+                response.layerOverlays = layerOverlays;
+                response.layerOverlayNote = "Each entry maps to a bar in the transport chain. Layers without an overlay say why.";
             }
             content.unshift({
                 type: "text",