cbrowser 18.77.0 → 18.78.0

package/dist/visual/fixation-corpus.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Fixation corpora — human eye-tracking ground truth, in one shape.
+ *
+ * WHAT A CORPUS IS FOR HERE
+ *
+ * Three distinct uses, and conflating them is how saliency work goes wrong:
+ *
+ *   1. VALIDATION — score the shipped model against human fixations. This is
+ *      what makes an accuracy claim sayable out loud. Study 1 did this against
+ *      UEyes and reported AUC-Judd 0.663 / NSS 0.544 / CC 0.216.
+ *   2. CALIBRATION — tune model parameters (channel weights, surround radius,
+ *      cell size) to maximise those metrics. Legitimate, but it spends the
+ *      corpus: a model tuned on a set can no longer be honestly validated on
+ *      that same set, which is why `split` exists below.
+ *   3. PRIORS — derive empirical structure from the corpus and bake it into the
+ *      model. A centre-bias prior alone lifts AUC substantially on almost any
+ *      dataset, because humans fixate the middle regardless of content.
+ *
+ * The interface is deliberately corpus-agnostic. UEyes is what is on disk
+ * today; MIT1003, CAT2000 and SALICON have the same shape (images + fixation
+ * points + density maps) and should not need new plumbing.
+ *
+ * WHAT UEYES GIVES THAT MOST CORPORA DO NOT
+ *
+ * - It is WEB PAGES (1980 of them), not natural scenes. Saliency models tuned on
+ *   photographs transfer poorly to interfaces, where text and affordances
+ *   dominate.
+ * - Fixation maps at 1s / 3s / 7s separately. Attention at first impression is
+ *   not attention after consideration, and cbrowser's personas differ precisely
+ *   on patience — an impatient persona should be scored against 1s, a thorough
+ *   one against 7s. Scoring every persona against one horizon throws that away.
+ * - Per-fixation logs with duration and saccade magnitude/direction, so scanpath
+ *   ORDER is available, not just aggregate density.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import type { Fixation, SaliencyGrid } from "./saliency-metrics.js";
+/** Viewing durations UEyes separates. Others may expose only one. */
+export type FixationHorizon = "1s" | "3s" | "7s";
+export interface CorpusStimulus {
+    /** Stable id — the image filename without extension. */
+    id: string;
+    /** Absolute path to the stimulus image. */
+    imagePath: string;
+    /** Ground-truth fixation density map per horizon, when the corpus has them. */
+    fixationMaps: Partial<Record<FixationHorizon, string>>;
+}
+export interface CorpusInfo {
+    name: string;
+    root: string;
+    stimuli: CorpusStimulus[];
+    horizons: FixationHorizon[];
+    /** Absent when the corpus ships only density maps and no raw logs. */
+    fixationLogDir?: string;
+    citation: string;
+}
+/**
+ * One participant fixation as recorded by the tracker.
+ *
+ * Coordinates are NORMALIZED 0-1 in the source logs and stay that way here.
+ * Converting to pixels requires the stimulus dimensions, and doing it at load
+ * time — before the caller says which grid they are scoring against — is how
+ * coordinate-space bugs get baked in. `fixationsToGrid` does the conversion at
+ * the point the target size is actually known.
+ */
+export interface RawFixation {
+    /** 0-1, left to right. */
+    xNorm: number;
+    /** 0-1, top to bottom. */
+    yNorm: number;
+    /** Dwell in seconds. */
+    duration: number;
+    /** Seconds since stimulus onset — this is what makes horizon filtering possible. */
+    startTime: number;
+    participantId: string;
+    stimulusId: string;
+}
+/**
+ * Discover a UEyes-layout corpus.
+ *
+ * Returns null rather than throwing when the directory is absent: the corpus is
+ * 13GB and is not, and should not be, a dependency of the shipped package.
+ * Anything that needs it degrades to "not available" rather than failing.
+ */
+export declare function loadUEyesCorpus(root: string): CorpusInfo | null;
+/**
+ * Parse one Gazepoint-format tracker log.
+ *
+ * The columns that matter: MEDIA_NAME (which stimulus), FPOGX/FPOGY (gaze point
+ * of regard, normalized), FPOGD (duration), FPOGS (start time), FPOGV (valid).
+ *
+ * INVALID SAMPLES ARE DROPPED, not clamped. FPOGV=0 means the tracker lost the
+ * eye — a blink, a look away, a calibration slip. Those rows still carry
+ * coordinates, and treating them as fixations manufactures ground truth from
+ * noise. Off-screen coordinates are dropped for the same reason.
+ */
+export declare function parseGazepointLog(logPath: string): RawFixation[];
+/**
+ * Keep only fixations that occurred within `seconds` of stimulus onset.
+ *
+ * This is what lets a persona be scored against the horizon that matches it: an
+ * impatient persona compared to 1s of human viewing, a thorough one to 7s.
+ * Comparing every persona to the same aggregate map discards the one dimension
+ * this corpus was built to expose.
+ */
+export declare function filterByHorizon(fixations: RawFixation[], seconds: number): RawFixation[];
+/** Convert normalized fixations to a grid's pixel space. */
+export declare function toGridFixations(fixations: RawFixation[], gridWidth: number, gridHeight: number): Fixation[];
+/**
+ * Build a fixation density map by accumulating Gaussian blobs.
+ *
+ * Ground-truth maps ship with UEyes, but a corpus that provides only raw logs
+ * needs this to score CC at all. Sigma is in grid cells; the literature
+ * convention is roughly one degree of visual angle, and for a 32x32 analysis
+ * grid that lands near 1.
+ */
+export declare function fixationsToGrid(fixations: Fixation[], width: number, height: number, sigma?: number): SaliencyGrid;
+/**
+ * Deterministic train/test split.
+ *
+ * Calibrating on a corpus and then reporting accuracy on the same corpus is
+ * measuring how well the parameters were fitted, not how well the model
+ * generalises — and it is the single easiest way to publish a number that does
+ * not survive review. The split is by stimulus id hash so it is stable across
+ * runs and machines without storing a manifest.
+ */
+export declare function splitCorpus(corpus: CorpusInfo, testFraction?: number): {
+    train: CorpusStimulus[];
+    test: CorpusStimulus[];
+};
+//# sourceMappingURL=fixation-corpus.d.ts.map

package/dist/visual/fixation-corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixation-corpus.d.ts","sourceRoot":"","sources":["../../src/visual/fixation-corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEpE,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAgC/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CA+ChE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAExF;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,QAAQ,EAAE,CAMZ;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,QAAQ,EAAE,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,SAAM,GACV,YAAY,CAoBd;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,YAAY,SAAM,GACjB;IAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IAAC,IAAI,EAAE,cAAc,EAAE,CAAA;CAAE,CAarD"}

package/dist/visual/fixation-corpus.js

@@ -0,0 +1,212 @@
+/**
+ * Fixation corpora — human eye-tracking ground truth, in one shape.
+ *
+ * WHAT A CORPUS IS FOR HERE
+ *
+ * Three distinct uses, and conflating them is how saliency work goes wrong:
+ *
+ *   1. VALIDATION — score the shipped model against human fixations. This is
+ *      what makes an accuracy claim sayable out loud. Study 1 did this against
+ *      UEyes and reported AUC-Judd 0.663 / NSS 0.544 / CC 0.216.
+ *   2. CALIBRATION — tune model parameters (channel weights, surround radius,
+ *      cell size) to maximise those metrics. Legitimate, but it spends the
+ *      corpus: a model tuned on a set can no longer be honestly validated on
+ *      that same set, which is why `split` exists below.
+ *   3. PRIORS — derive empirical structure from the corpus and bake it into the
+ *      model. A centre-bias prior alone lifts AUC substantially on almost any
+ *      dataset, because humans fixate the middle regardless of content.
+ *
+ * The interface is deliberately corpus-agnostic. UEyes is what is on disk
+ * today; MIT1003, CAT2000 and SALICON have the same shape (images + fixation
+ * points + density maps) and should not need new plumbing.
+ *
+ * WHAT UEYES GIVES THAT MOST CORPORA DO NOT
+ *
+ * - It is WEB PAGES (1980 of them), not natural scenes. Saliency models tuned on
+ *   photographs transfer poorly to interfaces, where text and affordances
+ *   dominate.
+ * - Fixation maps at 1s / 3s / 7s separately. Attention at first impression is
+ *   not attention after consideration, and cbrowser's personas differ precisely
+ *   on patience — an impatient persona should be scored against 1s, a thorough
+ *   one against 7s. Scoring every persona against one horizon throws that away.
+ * - Per-fixation logs with duration and saccade magnitude/direction, so scanpath
+ *   ORDER is available, not just aggregate density.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join, basename, extname } from "path";
+/**
+ * Discover a UEyes-layout corpus.
+ *
+ * Returns null rather than throwing when the directory is absent: the corpus is
+ * 13GB and is not, and should not be, a dependency of the shipped package.
+ * Anything that needs it degrades to "not available" rather than failing.
+ */
+export function loadUEyesCorpus(root) {
+    const imagesDir = join(root, "images");
+    if (!existsSync(imagesDir))
+        return null;
+    const horizons = [];
+    for (const h of ["1s", "3s", "7s"]) {
+        if (existsSync(join(root, "saliency_maps", `fixmaps_${h}`)))
+            horizons.push(h);
+    }
+    const stimuli = [];
+    for (const file of readdirSync(imagesDir)) {
+        const ext = extname(file).toLowerCase();
+        if (ext !== ".jpg" && ext !== ".png" && ext !== ".jpeg")
+            continue;
+        const id = basename(file, ext);
+        const fixationMaps = {};
+        for (const h of horizons) {
+            const candidate = join(root, "saliency_maps", `fixmaps_${h}`, file);
+            if (existsSync(candidate))
+                fixationMaps[h] = candidate;
+        }
+        stimuli.push({ id, imagePath: join(imagesDir, file), fixationMaps });
+    }
+    const logDir = join(root, "eyetracker_logs");
+    return {
+        name: "UEyes",
+        root,
+        stimuli: stimuli.sort((a, b) => a.id.localeCompare(b.id)),
+        horizons,
+        fixationLogDir: existsSync(logDir) ? logDir : undefined,
+        citation: "Jiang et al., UEyes: Understanding Visual Saliency across User Interface Types. CHI 2023.",
+    };
+}
+/**
+ * Parse one Gazepoint-format tracker log.
+ *
+ * The columns that matter: MEDIA_NAME (which stimulus), FPOGX/FPOGY (gaze point
+ * of regard, normalized), FPOGD (duration), FPOGS (start time), FPOGV (valid).
+ *
+ * INVALID SAMPLES ARE DROPPED, not clamped. FPOGV=0 means the tracker lost the
+ * eye — a blink, a look away, a calibration slip. Those rows still carry
+ * coordinates, and treating them as fixations manufactures ground truth from
+ * noise. Off-screen coordinates are dropped for the same reason.
+ */
+export function parseGazepointLog(logPath) {
+    const text = readFileSync(logPath, "utf8");
+    const lines = text.split("\n").filter((l) => l.trim().length > 0);
+    if (lines.length < 2)
+        return [];
+    const header = lines[0].split(",").map((h) => h.trim());
+    const col = (name) => header.findIndex((h) => h === name || h.startsWith(`${name}(`));
+    const iMedia = col("MEDIA_NAME");
+    const iX = col("FPOGX");
+    const iY = col("FPOGY");
+    const iD = col("FPOGD");
+    const iS = col("FPOGS");
+    const iV = col("FPOGV");
+    const iId = col("FPOGID");
+    if (iX < 0 || iY < 0)
+        return [];
+    const participantId = basename(logPath).replace(/_fixations\.csv$/i, "");
+    const out = [];
+    const seen = new Set();
+    for (let i = 1; i < lines.length; i++) {
+        const parts = lines[i].split(",");
+        if (iV >= 0 && parts[iV]?.trim() !== "1")
+            continue; // tracker lost the eye
+        const xNorm = Number(parts[iX]);
+        const yNorm = Number(parts[iY]);
+        if (!Number.isFinite(xNorm) || !Number.isFinite(yNorm))
+            continue;
+        if (xNorm < 0 || xNorm > 1 || yNorm < 0 || yNorm > 1)
+            continue; // off-stimulus
+        // One row per SAMPLE, many samples per fixation. Deduplicate on FPOGID so a
+        // long fixation counts once — otherwise dwell time silently becomes a vote
+        // multiplier and every metric is weighted by how long the tracker sampled.
+        const fixId = iId >= 0 ? parts[iId]?.trim() : undefined;
+        const media = iMedia >= 0 ? (parts[iMedia] ?? "").trim() : "";
+        const key = `${media}|${fixId ?? `${i}`}`;
+        if (fixId && seen.has(key))
+            continue;
+        if (fixId)
+            seen.add(key);
+        out.push({
+            xNorm,
+            yNorm,
+            duration: iD >= 0 ? Number(parts[iD]) || 0 : 0,
+            startTime: iS >= 0 ? Number(parts[iS]) || 0 : 0,
+            participantId,
+            stimulusId: media ? basename(media, extname(media)) : "",
+        });
+    }
+    return out;
+}
+/**
+ * Keep only fixations that occurred within `seconds` of stimulus onset.
+ *
+ * This is what lets a persona be scored against the horizon that matches it: an
+ * impatient persona compared to 1s of human viewing, a thorough one to 7s.
+ * Comparing every persona to the same aggregate map discards the one dimension
+ * this corpus was built to expose.
+ */
+export function filterByHorizon(fixations, seconds) {
+    return fixations.filter((f) => f.startTime <= seconds);
+}
+/** Convert normalized fixations to a grid's pixel space. */
+export function toGridFixations(fixations, gridWidth, gridHeight) {
+    return fixations.map((f) => ({
+        x: f.xNorm * gridWidth,
+        y: f.yNorm * gridHeight,
+        duration: f.duration * 1000,
+    }));
+}
+/**
+ * Build a fixation density map by accumulating Gaussian blobs.
+ *
+ * Ground-truth maps ship with UEyes, but a corpus that provides only raw logs
+ * needs this to score CC at all. Sigma is in grid cells; the literature
+ * convention is roughly one degree of visual angle, and for a 32x32 analysis
+ * grid that lands near 1.
+ */
+export function fixationsToGrid(fixations, width, height, sigma = 1.0) {
+    const values = new Float64Array(width * height);
+    const radius = Math.max(1, Math.ceil(sigma * 3));
+    const twoSigmaSq = 2 * sigma * sigma;
+    for (const f of fixations) {
+        const cx = f.x;
+        const cy = f.y;
+        const x0 = Math.max(0, Math.floor(cx - radius));
+        const x1 = Math.min(width - 1, Math.ceil(cx + radius));
+        const y0 = Math.max(0, Math.floor(cy - radius));
+        const y1 = Math.min(height - 1, Math.ceil(cy + radius));
+        for (let y = y0; y <= y1; y++) {
+            for (let x = x0; x <= x1; x++) {
+                const d2 = (x + 0.5 - cx) ** 2 + (y + 0.5 - cy) ** 2;
+                values[y * width + x] += Math.exp(-d2 / twoSigmaSq);
+            }
+        }
+    }
+    return { values, width, height };
+}
+/**
+ * Deterministic train/test split.
+ *
+ * Calibrating on a corpus and then reporting accuracy on the same corpus is
+ * measuring how well the parameters were fitted, not how well the model
+ * generalises — and it is the single easiest way to publish a number that does
+ * not survive review. The split is by stimulus id hash so it is stable across
+ * runs and machines without storing a manifest.
+ */
+export function splitCorpus(corpus, testFraction = 0.3) {
+    const hash = (s) => {
+        let h = 2166136261;
+        for (let i = 0; i < s.length; i++) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+        }
+        return (h >>> 0) / 4294967296;
+    };
+    const train = [];
+    const test = [];
+    for (const s of corpus.stimuli)
+        (hash(s.id) < testFraction ? test : train).push(s);
+    return { train, test };
+}
+//# sourceMappingURL=fixation-corpus.js.map

package/dist/visual/fixation-corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixation-corpus.js","sourceRoot":"","sources":["../../src/visual/fixation-corpus.ts"],"names":[],"mappings":"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"}

package/dist/visual/saliency-metrics.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Saliency evaluation metrics against human fixation ground truth.
+ *
+ * WHY THIS IS IN src/ AND NOT research/
+ *
+ * The Study 1 benchmark (UEyes, Jiang et al. CHI 2023 — 495 web pages, 62
+ * participants) reported AUC-Judd 0.663 / NSS 0.544 / CC 0.216 for the COT
+ * saliency model. Those numbers were produced by a *Python reimplementation*
+ * whose own docstring calls it a "vectorized Python port of CBrowser's
+ * computeLabSaliency()" — and the port had already drifted from the shipped
+ * code on the day the results were written: the TypeScript weights chrominance
+ * 3x over luminance (wA = wB = 3.0), the Python summed all three Lab channels
+ * unweighted.
+ *
+ * So the published accuracy claim did not describe the shipped model. Not
+ * because anyone was careless — because two implementations of one concept with
+ * nothing binding them will always drift, and a number is the last place that
+ * shows up.
+ *
+ * Putting the metrics here means the benchmark scores the code that ships, by
+ * construction. There is one saliency implementation and the evaluator calls it.
+ *
+ * THE METRICS
+ *
+ * Standard in the saliency literature (Bylinskii et al., "What do different
+ * evaluation metrics tell us about saliency models?", TPAMI 2019). They
+ * disagree with each other on purpose, and reporting one alone is how models
+ * get oversold:
+ *
+ * - AUC-Judd — location-based, ranks fixated pixels against all others.
+ *   Invariant to monotonic rescaling, so it says nothing about calibration.
+ *   Chance = 0.5.
+ * - NSS — value-based, mean normalized saliency at fixated points. Sensitive to
+ *   false positives in a way AUC is not. Chance = 0.
+ * - CC — distribution-based, linear correlation with the full fixation map.
+ *   Penalises both misses and false alarms symmetrically. Range [-1, 1].
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+/** A grid of saliency values. Row-major, any scale. */
+export interface SaliencyGrid {
+    values: Float64Array | number[];
+    width: number;
+    height: number;
+}
+/** A single human fixation, in the grid's coordinate space. */
+export interface Fixation {
+    x: number;
+    y: number;
+    /** Dwell in ms, if known. Unused by these metrics but carried for weighting. */
+    duration?: number;
+}
+export interface SaliencyScores {
+    /** Ranks fixated pixels against all pixels. Chance 0.5. */
+    aucJudd: number;
+    /** Mean normalized saliency at fixations. Chance 0. */
+    nss: number;
+    /** Pearson correlation with the ground-truth map. Range [-1, 1]. */
+    cc: number;
+    /** How many fixations landed inside the grid and were scored. */
+    fixationsScored: number;
+}
+/**
+ * Normalized Scanpath Saliency: the mean of the standardized saliency map at
+ * fixated locations.
+ *
+ * Unlike AUC this punishes a map that is salient everywhere — standardizing
+ * first means a model cannot buy score by raising the whole map.
+ */
+export declare function computeNSS(grid: SaliencyGrid, fixations: Fixation[]): {
+    nss: number;
+    scored: number;
+};
+/**
+ * AUC-Judd: sweep a threshold over the saliency map; at each level the true
+ * positive rate is the share of fixations above it and the false positive rate
+ * is the share of ALL pixels above it. Area under that curve.
+ *
+ * Thresholds are the saliency values AT the fixations, which is what makes this
+ * Judd's variant rather than Borji's — no random negative sampling, so it is
+ * deterministic. That matters here: a metric used to compare model revisions
+ * must not itself introduce variance between runs.
+ */
+export declare function computeAUCJudd(grid: SaliencyGrid, fixations: Fixation[]): {
+    auc: number;
+    scored: number;
+};
+/**
+ * Pearson correlation between the predicted map and a ground-truth fixation
+ * density map. Both are standardized, so this is scale-invariant.
+ */
+export declare function computeCC(grid: SaliencyGrid, groundTruth: SaliencyGrid): number;
+/**
+ * Score a predicted saliency map against human fixations.
+ *
+ * `groundTruth` (a fixation density map) is optional because CC needs one while
+ * AUC and NSS need only the fixation points. Reporting CC as 0 when it was
+ * never computable would be indistinguishable from a genuinely uncorrelated
+ * model, so it is omitted from the average rather than faked.
+ */
+export declare function scoreSaliency(predicted: SaliencyGrid, fixations: Fixation[], groundTruth?: SaliencyGrid): SaliencyScores;
+/**
+ * Resample a grid to a target size by area-averaging.
+ *
+ * Ground-truth fixation maps and predicted grids rarely share dimensions, and
+ * comparing them at different resolutions is the mistake `computeCC` refuses to
+ * make silently. This is the explicit way to reconcile them.
+ */
+export declare function resampleGrid(grid: SaliencyGrid, width: number, height: number): SaliencyGrid;
+//# sourceMappingURL=saliency-metrics.d.ts.map

package/dist/visual/saliency-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saliency-metrics.d.ts","sourceRoot":"","sources":["../../src/visual/saliency-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;CACzB;AAmBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAYrG;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAgEzG;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,GAAG,MAAM,CAa/E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,QAAQ,EAAE,EACrB,WAAW,CAAC,EAAE,YAAY,GACzB,cAAc,CAShB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAsB5F"}

package/dist/visual/saliency-metrics.js

@@ -0,0 +1,225 @@
+/**
+ * Saliency evaluation metrics against human fixation ground truth.
+ *
+ * WHY THIS IS IN src/ AND NOT research/
+ *
+ * The Study 1 benchmark (UEyes, Jiang et al. CHI 2023 — 495 web pages, 62
+ * participants) reported AUC-Judd 0.663 / NSS 0.544 / CC 0.216 for the COT
+ * saliency model. Those numbers were produced by a *Python reimplementation*
+ * whose own docstring calls it a "vectorized Python port of CBrowser's
+ * computeLabSaliency()" — and the port had already drifted from the shipped
+ * code on the day the results were written: the TypeScript weights chrominance
+ * 3x over luminance (wA = wB = 3.0), the Python summed all three Lab channels
+ * unweighted.
+ *
+ * So the published accuracy claim did not describe the shipped model. Not
+ * because anyone was careless — because two implementations of one concept with
+ * nothing binding them will always drift, and a number is the last place that
+ * shows up.
+ *
+ * Putting the metrics here means the benchmark scores the code that ships, by
+ * construction. There is one saliency implementation and the evaluator calls it.
+ *
+ * THE METRICS
+ *
+ * Standard in the saliency literature (Bylinskii et al., "What do different
+ * evaluation metrics tell us about saliency models?", TPAMI 2019). They
+ * disagree with each other on purpose, and reporting one alone is how models
+ * get oversold:
+ *
+ * - AUC-Judd — location-based, ranks fixated pixels against all others.
+ *   Invariant to monotonic rescaling, so it says nothing about calibration.
+ *   Chance = 0.5.
+ * - NSS — value-based, mean normalized saliency at fixated points. Sensitive to
+ *   false positives in a way AUC is not. Chance = 0.
+ * - CC — distribution-based, linear correlation with the full fixation map.
+ *   Penalises both misses and false alarms symmetrically. Range [-1, 1].
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+/** Normalize to zero mean, unit standard deviation. */
+function standardize(values) {
+    const n = values.length;
+    const out = new Float64Array(n);
+    if (n === 0)
+        return out;
+    let mean = 0;
+    for (let i = 0; i < n; i++)
+        mean += values[i];
+    mean /= n;
+    let variance = 0;
+    for (let i = 0; i < n; i++)
+        variance += (values[i] - mean) ** 2;
+    variance /= n;
+    const sd = Math.sqrt(variance);
+    if (sd === 0)
+        return out; // A flat map carries no signal; NSS is 0, not NaN.
+    for (let i = 0; i < n; i++)
+        out[i] = (values[i] - mean) / sd;
+    return out;
+}
+/**
+ * Normalized Scanpath Saliency: the mean of the standardized saliency map at
+ * fixated locations.
+ *
+ * Unlike AUC this punishes a map that is salient everywhere — standardizing
+ * first means a model cannot buy score by raising the whole map.
+ */
+export function computeNSS(grid, fixations) {
+    const z = standardize(grid.values);
+    let sum = 0;
+    let scored = 0;
+    for (const f of fixations) {
+        const x = Math.floor(f.x);
+        const y = Math.floor(f.y);
+        if (x < 0 || y < 0 || x >= grid.width || y >= grid.height)
+            continue;
+        sum += z[y * grid.width + x];
+        scored++;
+    }
+    return { nss: scored > 0 ? sum / scored : 0, scored };
+}
+/**
+ * AUC-Judd: sweep a threshold over the saliency map; at each level the true
+ * positive rate is the share of fixations above it and the false positive rate
+ * is the share of ALL pixels above it. Area under that curve.
+ *
+ * Thresholds are the saliency values AT the fixations, which is what makes this
+ * Judd's variant rather than Borji's — no random negative sampling, so it is
+ * deterministic. That matters here: a metric used to compare model revisions
+ * must not itself introduce variance between runs.
+ */
+export function computeAUCJudd(grid, fixations) {
+    const n = grid.values.length;
+    const inBounds = [];
+    for (const f of fixations) {
+        const x = Math.floor(f.x);
+        const y = Math.floor(f.y);
+        if (x < 0 || y < 0 || x >= grid.width || y >= grid.height)
+            continue;
+        inBounds.push(grid.values[y * grid.width + x]);
+    }
+    if (inBounds.length === 0 || n === 0)
+        return { auc: 0.5, scored: 0 };
+    // Sorted copy of the whole map, so each threshold's false-positive rate is a
+    // binary search rather than a scan — O(n log n) once instead of O(n) per
+    // fixation, which is the difference between usable and not on 1980 images.
+    const sorted = Float64Array.from(grid.values).sort();
+    const countAbove = (t) => {
+        let lo = 0;
+        let hi = sorted.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (sorted[mid] < t)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return sorted.length - lo;
+    };
+    const nFix = inBounds.length;
+    // UNIQUE thresholds, and TPR counted rather than assumed.
+    //
+    // Using (i+1)/nFix as the true-positive rate assumes every fixation sits at a
+    // distinct saliency value. Ties break it badly, and ties are the normal case:
+    // on a flat map every threshold is identical, so FPR jumped straight to 1
+    // while TPR was still 1/nFix — which scored a flat map 0.25 instead of the
+    // 0.5 that "carries no information" must produce, and pinned the WORST
+    // possible predictor at exactly 0.5. Both are the same arithmetic slip.
+    // Counting both rates at each distinct threshold is Judd's formulation.
+    // (2026-07-29)
+    const uniqueThresholds = [...new Set(inBounds)].sort((a, b) => b - a);
+    const fixSorted = [...inBounds].sort((a, b) => a - b);
+    const fixAtOrAbove = (t) => {
+        let lo = 0;
+        let hi = fixSorted.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (fixSorted[mid] < t)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return fixSorted.length - lo;
+    };
+    // Curve from (0,0) through each threshold to (1,1), trapezoidal integration.
+    let auc = 0;
+    let prevFpr = 0;
+    let prevTpr = 0;
+    for (const t of uniqueThresholds) {
+        const tpr = fixAtOrAbove(t) / nFix;
+        const fpr = countAbove(t) / n;
+        auc += ((fpr - prevFpr) * (tpr + prevTpr)) / 2;
+        prevFpr = fpr;
+        prevTpr = tpr;
+    }
+    auc += ((1 - prevFpr) * (1 + prevTpr)) / 2;
+    return { auc: Math.min(1, Math.max(0, auc)), scored: nFix };
+}
+/**
+ * Pearson correlation between the predicted map and a ground-truth fixation
+ * density map. Both are standardized, so this is scale-invariant.
+ */
+export function computeCC(grid, groundTruth) {
+    if (grid.values.length !== groundTruth.values.length) {
+        throw new Error(`CC needs matching grids: predicted ${grid.width}x${grid.height} vs ground truth ${groundTruth.width}x${groundTruth.height}. ` +
+            `Resample one before comparing — silently reshaping here would compare unrelated regions.`);
+    }
+    const a = standardize(grid.values);
+    const b = standardize(groundTruth.values);
+    let num = 0;
+    for (let i = 0; i < a.length; i++)
+        num += a[i] * b[i];
+    // Both are unit-variance, so the denominator is n.
+    return a.length > 0 ? num / a.length : 0;
+}
+/**
+ * Score a predicted saliency map against human fixations.
+ *
+ * `groundTruth` (a fixation density map) is optional because CC needs one while
+ * AUC and NSS need only the fixation points. Reporting CC as 0 when it was
+ * never computable would be indistinguishable from a genuinely uncorrelated
+ * model, so it is omitted from the average rather than faked.
+ */
+export function scoreSaliency(predicted, fixations, groundTruth) {
+    const { auc, scored } = computeAUCJudd(predicted, fixations);
+    const { nss } = computeNSS(predicted, fixations);
+    return {
+        aucJudd: auc,
+        nss,
+        cc: groundTruth ? computeCC(predicted, groundTruth) : Number.NaN,
+        fixationsScored: scored,
+    };
+}
+/**
+ * Resample a grid to a target size by area-averaging.
+ *
+ * Ground-truth fixation maps and predicted grids rarely share dimensions, and
+ * comparing them at different resolutions is the mistake `computeCC` refuses to
+ * make silently. This is the explicit way to reconcile them.
+ */
+export function resampleGrid(grid, width, height) {
+    const out = new Float64Array(width * height);
+    const xScale = grid.width / width;
+    const yScale = grid.height / height;
+    for (let y = 0; y < height; y++) {
+        const y0 = Math.floor(y * yScale);
+        const y1 = Math.min(grid.height, Math.max(y0 + 1, Math.ceil((y + 1) * yScale)));
+        for (let x = 0; x < width; x++) {
+            const x0 = Math.floor(x * xScale);
+            const x1 = Math.min(grid.width, Math.max(x0 + 1, Math.ceil((x + 1) * xScale)));
+            let sum = 0;
+            let count = 0;
+            for (let yy = y0; yy < y1; yy++) {
+                for (let xx = x0; xx < x1; xx++) {
+                    sum += grid.values[yy * grid.width + xx];
+                    count++;
+                }
+            }
+            out[y * width + x] = count > 0 ? sum / count : 0;
+        }
+    }
+    return { values: out, width, height };
+}
+//# sourceMappingURL=saliency-metrics.js.map

package/dist/visual/saliency-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saliency-metrics.js","sourceRoot":"","sources":["../../src/visual/saliency-metrics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "18.77.0",
+  "version": "18.78.0",
   "type": "module",
   "description": "Cognitive browser automation that thinks like your users—and helps AI agents navigate too. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery. Sites that pass CBrowser's cognitive tests are easier for both humans and AI agents to navigate.",
   "main": "dist/index.js",