humanish 0.75.0 → 0.76.0

package/dist/cua-actor-lab.js

@@ -736,10 +736,13 @@ async function fillDesktopBrowserWindow(desktop, windowId, resolution, requestTi
     })
         .catch(() => undefined);
 }
-async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, browserPreference) {
+async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, browserPreference, 
+/** Launch-time flags that make mobile fidelity (#221) hold across every tab: the user agent and
+ *  touch events are browser-wide here, where the CDP holder covers only the launch page. */
+extraChromiumFlags = []) {
     const requestedBrowser = browserPreference ?? "default";
     if (isHttpUrl(targetUrl)) {
-        const chromiumFlags = CHROMIUM_EVIDENCE_HYGIENE_FLAGS.map(shellSingleQuote).join(" ");
+        const chromiumFlags = [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, ...extraChromiumFlags].map(shellSingleQuote).join(" ");
         const browserLaunchCommand = [
             "set -euo pipefail",
             `target_url=${shellSingleQuote(targetUrl)}`,
@@ -937,6 +940,79 @@ export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, end
         };
     };
 }
+/** The user agent a mobile-emulated lane presents unless the lab sets its own. */
+export const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+/**
+ * Apply mobile emulation (#221) to the lane's launch page and read back what the page reports.
+ * Fails CLOSED: a request that cannot be applied throws, because a desktop run labelled mobile is
+ * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
+ * (the emulation was applied; only the proof is missing).
+ */
+export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint, targetId, request) {
+    const command = (mode) => chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer: "pinned", mode, emulation: request });
+    const read = async () => {
+        const result = await desktop.commands.run(command("fidelity"), { requestTimeoutMs, timeoutMs: 15_000 });
+        if (result.exitCode !== undefined && result.exitCode !== 0) {
+            return { unavailable: `probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}` };
+        }
+        return parseChromeCdpProbeOutput(result.stdout);
+    };
+    // The UA / touch / DPR overrides are bound to the DevTools session that set them and lapse the
+    // moment its socket closes (measured: only the viewport width survived a one-shot apply). So the
+    // applier stays attached for the lane's whole life as a detached process; the sandbox teardown
+    // ends it. Its first stdout line says what was applied.
+    const holderName = `mobile-emulation-${Date.now().toString(36)}`;
+    await startDetachedProcess(desktop, { name: holderName, command: command("hold"), requestTimeoutMs });
+    let announced;
+    for (let attempt = 0; attempt < 30 && announced === undefined; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const log = await readDetachedLog(desktop, holderName, requestTimeoutMs).catch(() => "");
+        const line = log.split("\n").find((candidate) => candidate.trim().startsWith("{"));
+        if (line !== undefined)
+            announced = parseChromeCdpProbeOutput(line);
+    }
+    if (announced === undefined) {
+        throw new Error("mobile emulation could not be applied: the in-sandbox applier printed nothing within 15 s");
+    }
+    if (announced.unavailable !== undefined) {
+        throw new Error(`mobile emulation could not be applied (${announced.unavailable}); applied before failing: ${(announced.applied ?? []).join(", ") || "nothing"}`);
+    }
+    const applied = announced;
+    const warnings = [];
+    // The reload inside the applier takes a moment; the read-back is retried until the page reports
+    // the requested viewport and user agent, so a slow page does not read as "no proof".
+    let readBack = await read();
+    for (let attempt = 0; attempt < 20 && (readBack.fidelity === undefined || readBack.fidelity.innerWidth !== request.width || !readBack.fidelity.userAgent.includes(request.userAgent.slice(0, 24))); attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        readBack = await read();
+    }
+    const fidelityRead = readBack;
+    const requested = {
+        width: request.width,
+        height: request.height,
+        deviceScaleFactor: request.deviceScaleFactor,
+        touch: request.touch,
+        userAgent: request.userAgent
+    };
+    if (fidelityRead.fidelity === undefined) {
+        warnings.push(`Mobile emulation was applied but the page's own report could not be read (${fidelityRead.unavailable ?? "no fidelity read"}); desktopGeometry.fidelity carries the request without a resolved block.`);
+        return { fidelity: { tier: "mobile-emulated", requested, applied: applied.applied ?? [] }, warnings };
+    }
+    const resolved = { ...fidelityRead.fidelity, source: "cdp" };
+    if (resolved.innerWidth !== request.width) {
+        warnings.push(`Mobile emulation requested a ${request.width} px viewport; the page reports ${resolved.innerWidth} px.`);
+    }
+    if (resolved.devicePixelRatio !== request.deviceScaleFactor) {
+        warnings.push(`Mobile emulation requested devicePixelRatio ${request.deviceScaleFactor}; the page reports ${resolved.devicePixelRatio}.`);
+    }
+    if (request.touch && resolved.maxTouchPoints === 0) {
+        warnings.push("Mobile emulation requested touch; the page reports navigator.maxTouchPoints 0.");
+    }
+    if (!resolved.userAgent.includes("Mobile") && !resolved.userAgent.includes("Android") && !resolved.userAgent.includes("iPhone")) {
+        warnings.push("Mobile emulation requested a mobile user agent; the page reports a desktop one.");
+    }
+    return { fidelity: { tier: "mobile-emulated", requested, applied: applied.applied ?? [], resolved }, warnings };
+}
 function isMeasuredRect(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -1018,11 +1094,14 @@ export async function captureDesktopBrowserGeometry(args) {
         : undefined;
     const browserWindow = chromeGeometry?.browserWindow ?? xdotoolWindow;
     const viewport = chromeGeometry?.viewport;
+    // The fill check reads the X window when it was measured: under mobile emulation (#221) the
+    // page's window.outerWidth reports the EMULATED screen (414), which is not a fill failure.
+    const fillBounds = xdotoolWindow ?? browserWindow;
     if (!browserWindow) {
         warnings.push(`Browser outer bounds could not be measured for lane ${args.laneId}.`);
     }
-    else if (browserWindow.width !== args.requestedScreen[0] || browserWindow.height !== args.requestedScreen[1]) {
-        warnings.push(`Browser window fill did not reach the requested ${args.requestedScreen[0]}x${args.requestedScreen[1]} screen for lane ${args.laneId}; measured outer bounds are ${browserWindow.width}x${browserWindow.height}.`);
+    else if (fillBounds !== undefined && (fillBounds.width !== args.requestedScreen[0] || fillBounds.height !== args.requestedScreen[1])) {
+        warnings.push(`Browser window fill did not reach the requested ${args.requestedScreen[0]}x${args.requestedScreen[1]} screen for lane ${args.laneId}; measured outer bounds are ${fillBounds.width}x${fillBounds.height}.`);
     }
     if (!viewport) {
         // Name the cause, not only the symptom: the same dead DevTools channel that loses the viewport
@@ -1165,8 +1244,17 @@ function hasBlockerLanguage(text) {
 // study completed without a participant-reported finding". Friction is the INCLUSIVE scan; a
 // false positive here adds a candidate a person then reads, which is the cheap direction.
 const REPORTED_DEFECT_LANGUAGE = /\b(defects?|bugs?|accessibilit(y|ies)|inaccessible|not (keyboard|screen.?reader)[- ]?accessible|confus(ed|ing)|hesitat(ed|ion)|unexpected(ly)?|unclear|hard to (find|tell|see|read|reach)|no (visible )?focus|overlap(ped|ping|s)?|truncat(ed|es|ion)|cut off|did nothing|nothing happened|no effect)\b/;
+// The friction scan's own negations (#614). "Nothing was confusing", "no defects", "not unclear"
+// are what a participant writes when it has NOTHING to report, and until 2026-09-03 each of them
+// counted as reported friction and became a feedback candidate whose "actual" was a sentence
+// reporting no problem. Only the report-shaped adjectives are negatable here: "no visible focus",
+// "not keyboard-accessible" and "did nothing" are defects and stay.
+const NEGATED_REPORT_LANGUAGE = /\b(?:nothing|no|not|never|without|none)\s+(?:was\s+|were\s+|felt\s+|seemed\s+|really\s+|particularly\s+|especially\s+|major\s+|real\s+|obvious\s+|noticeable\s+)*(?:confus(?:ed|ing|ion)|unclear|unexpected(?:ly)?|hesitat(?:ed|ion|ions)|surpris(?:ed|ing|es)|defects?|bugs?|overlap(?:ped|ping|s)?|truncat(?:ed|es|ion)|hard to (?:find|tell|see|read|reach))\b/g;
+function stripNegatedReportLanguage(text) {
+    return text.replace(NEGATED_REPORT_LANGUAGE, " ");
+}
 function completionReasonContradictsGoal(reason) {
-    const text = stripQuotedSpans(stripNegatedNonBlockerPhrases(reason.toLowerCase()));
+    const text = stripQuotedSpans(stripNegatedReportLanguage(stripNegatedNonBlockerPhrases(reason.toLowerCase())));
     return hasBlockerLanguage(text) || REPORTED_DEFECT_LANGUAGE.test(text);
 }
 /** The verdict scan (strict): like the friction scan, but resolved-arc segments are stripped
@@ -1371,6 +1459,7 @@ export async function runCuaLane(spec, deps) {
     let browserLaunchIdentity;
     let browserLaunched = false;
     let initialBrowserGeometry;
+    let appliedFidelity;
     let browserWindowId;
     let browserTargetId;
     const declaredScreen = declaredScreenForRender(spec.devicePreset, spec.deviceName, spec.resolution);
@@ -1562,12 +1651,44 @@ export async function runCuaLane(spec, deps) {
                 });
             }
             if (!desktopCliRoute) {
-                const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
+                const requestedFidelity = config.execution?.desktop?.fidelity;
+                const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser, requestedFidelity?.mobileEmulation && spec.devicePreset.isMobile
+                    ? [
+                        `--user-agent=${requestedFidelity.userAgent ?? DEFAULT_MOBILE_USER_AGENT}`,
+                        ...(requestedFidelity.touch === false ? [] : ["--touch-events=enabled"])
+                    ]
+                    : []);
                 desktopBrowser = browserLaunch.evidence;
                 launchedBrowserFamily = browserLaunch.family;
                 browserLaunchIdentity = browserLaunch.identity;
                 browserLaunched = true;
                 await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+                // Mobile fidelity beyond viewport size (#221): applied to the launch page before the
+                // geometry capture and the participant's first observation, OUTSIDE the stream/geometry
+                // try below (whose catch degrades to a warning): a request that cannot be applied fails
+                // the lane closed with the reason.
+                // Only lanes on a mobile preset are emulated: a run-wide flag must not hand a desktop or
+                // tablet lane an iPhone user agent (the first live proof did exactly that to the desktop
+                // newcomer beside the phone lane). Those lanes carry no fidelity block, which is honest.
+                const fidelityRequest = config.execution?.desktop?.fidelity;
+                if (fidelityRequest?.mobileEmulation && spec.devicePreset.isMobile) {
+                    if (launchedBrowserFamily !== "chromium") {
+                        throw new Error(`execution.desktop.fidelity.mobileEmulation needs Chrome or Chromium on lane ${spec.laneId}; the launched browser family is ${launchedBrowserFamily}. Set execution.desktop.browser: chrome.`);
+                    }
+                    const applied = await applyMobileEmulation(desktop, deps.requestTimeoutMs, {
+                        ...(browserLaunchIdentity?.cdpPort === undefined ? {} : { cdpPort: browserLaunchIdentity.cdpPort }),
+                        ...(browserLaunchIdentity?.profileDir === undefined ? {} : { profileDir: browserLaunchIdentity.profileDir }),
+                        targetUrl
+                    }, browserTargetId, {
+                        width: spec.devicePreset.width,
+                        height: spec.devicePreset.height,
+                        deviceScaleFactor: fidelityRequest.deviceScaleFactor ?? spec.devicePreset.deviceScaleFactor,
+                        touch: fidelityRequest.touch ?? true,
+                        userAgent: fidelityRequest.userAgent ?? DEFAULT_MOBILE_USER_AGENT
+                    });
+                    appliedFidelity = applied.fidelity;
+                    warnings.push(...applied.warnings);
+                }
             }
             else {
                 // A terminal window, opened the way the browser is opened on every other route: the
@@ -1792,6 +1913,7 @@ export async function runCuaLane(spec, deps) {
                     screen: desktopGeometry.screen,
                     ...(chosenGeometry.browserWindow === undefined ? {} : { browserWindow: chosenGeometry.browserWindow }),
                     ...(chosenGeometry.viewport === undefined ? {} : { viewport: chosenGeometry.viewport }),
+                    ...(appliedFidelity === undefined ? {} : { fidelity: appliedFidelity }),
                     ...((desktopGeometry.warnings?.length ?? 0) + geometryWarnings.length === 0
                         ? {}
                         : { warnings: [...(desktopGeometry.warnings ?? []), ...geometryWarnings] })