@tangle-network/browser-agent-driver 0.12.1 → 0.14.0

package/dist/design/audit/measure/contrast.js

@@ -0,0 +1,201 @@
+/**
+ * Real WCAG 2.1 contrast measurement.
+ *
+ * Walks every visible text element in the page, computes its actual rendered
+ * text color and resolved background color (climbing the parent chain through
+ * transparent backgrounds), then calculates the WCAG relative luminance ratio.
+ *
+ * This is deterministic — pure math, no LLM. Replaces the LLM's "estimated
+ * contrast ratio" guesses with ground truth.
+ */
+/**
+ * In-page worker that walks the DOM and returns failing elements.
+ * Runs entirely in the page context — no Playwright round-trips per element.
+ */
+function inPageContrastCheck() {
+    // ── Color parsing ───────────────────────────────────────────────────────
+    function parseRGBA(value) {
+        const m = value.match(/rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)/);
+        if (!m)
+            return null;
+        return {
+            r: parseFloat(m[1]),
+            g: parseFloat(m[2]),
+            b: parseFloat(m[3]),
+            a: m[4] !== undefined ? parseFloat(m[4]) : 1,
+        };
+    }
+    function rgbToHex(r, g, b) {
+        const h = (n) => Math.round(n).toString(16).padStart(2, '0');
+        return `#${h(r)}${h(g)}${h(b)}`;
+    }
+    // Composite a translucent color over an opaque background.
+    function composite(fg, bg) {
+        const a = fg.a + bg.a * (1 - fg.a);
+        if (a === 0)
+            return { r: 0, g: 0, b: 0, a: 0 };
+        return {
+            r: (fg.r * fg.a + bg.r * bg.a * (1 - fg.a)) / a,
+            g: (fg.g * fg.a + bg.g * bg.a * (1 - fg.a)) / a,
+            b: (fg.b * fg.a + bg.b * bg.a * (1 - fg.a)) / a,
+            a,
+        };
+    }
+    // ── WCAG 2.1 contrast math ──────────────────────────────────────────────
+    function relativeLuminance(r, g, b) {
+        const norm = (c) => {
+            const v = c / 255;
+            return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+        };
+        return 0.2126 * norm(r) + 0.7152 * norm(g) + 0.0722 * norm(b);
+    }
+    function contrastRatio(fg, bg) {
+        const l1 = relativeLuminance(fg.r, fg.g, fg.b);
+        const l2 = relativeLuminance(bg.r, bg.g, bg.b);
+        const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+        return (hi + 0.05) / (lo + 0.05);
+    }
+    // Resolve the effective background color of an element by walking parents
+    // and compositing translucent layers.
+    function resolveBackground(el) {
+        let composed = { r: 255, g: 255, b: 255, a: 1 };
+        let current = el;
+        const stack = [];
+        while (current) {
+            const cs = window.getComputedStyle(current);
+            const bg = parseRGBA(cs.backgroundColor);
+            if (bg && bg.a > 0) {
+                stack.push(bg);
+                if (bg.a >= 1)
+                    break;
+            }
+            current = current.parentElement;
+        }
+        // Composite from outermost (root) to innermost (element)
+        composed = { r: 255, g: 255, b: 255, a: 1 };
+        for (let i = stack.length - 1; i >= 0; i--) {
+            composed = composite(stack[i], composed);
+        }
+        return composed;
+    }
+    // Generate a stable, human-readable selector for an element.
+    function selectorFor(el) {
+        if (el.id)
+            return `#${CSS.escape(el.id)}`;
+        const tag = el.tagName.toLowerCase();
+        const cls = (el.className && typeof el.className === 'string')
+            ? el.className.split(/\s+/).filter(Boolean).slice(0, 2).map(c => '.' + CSS.escape(c)).join('')
+            : '';
+        let parent = el.parentElement;
+        let parentSel = '';
+        if (parent && parent !== document.body) {
+            const ptag = parent.tagName.toLowerCase();
+            const pid = parent.id ? `#${CSS.escape(parent.id)}` : '';
+            parentSel = `${ptag}${pid} > `;
+        }
+        return `${parentSel}${tag}${cls}`;
+    }
+    // Determine if an element qualifies as "large text" per WCAG 2.1:
+    // 18pt+ regular OR 14pt+ bold (1pt = 1.333px → 24px or 18.66px)
+    function isLargeText(fontSize, fontWeight) {
+        const weight = parseInt(fontWeight, 10) || 400;
+        if (fontSize >= 24)
+            return true;
+        if (fontSize >= 18.66 && weight >= 700)
+            return true;
+        return false;
+    }
+    // ── Walk the DOM ────────────────────────────────────────────────────────
+    const aaFailures = [];
+    const aaaFailures = [];
+    let totalChecked = 0;
+    // Only consider visible text-bearing elements.
+    const candidates = document.querySelectorAll('*');
+    for (const el of candidates) {
+        if (totalChecked >= 5000)
+            break; // safety bound
+        // Must have direct text content (not just nested children with text)
+        const hasDirectText = Array.from(el.childNodes).some(n => n.nodeType === Node.TEXT_NODE && (n.textContent ?? '').trim().length > 0);
+        if (!hasDirectText)
+            continue;
+        // Must be visible
+        if (el.offsetWidth === 0 || el.offsetHeight === 0)
+            continue;
+        const cs = window.getComputedStyle(el);
+        if (cs.visibility === 'hidden' || cs.display === 'none' || parseFloat(cs.opacity) === 0)
+            continue;
+        const fg = parseRGBA(cs.color);
+        if (!fg)
+            continue;
+        const bg = resolveBackground(el);
+        if (bg.a === 0)
+            continue;
+        // Composite text color over background if text has alpha
+        const compositedFg = fg.a < 1 ? composite(fg, bg) : fg;
+        const ratio = contrastRatio(compositedFg, bg);
+        const fontSize = parseFloat(cs.fontSize) || 16;
+        const large = isLargeText(fontSize, cs.fontWeight);
+        const aaRequired = large ? 3 : 4.5;
+        const aaaRequired = large ? 4.5 : 7;
+        totalChecked++;
+        if (ratio < aaRequired) {
+            const text = (el.textContent ?? '').trim().slice(0, 60);
+            aaFailures.push({
+                selector: selectorFor(el),
+                text,
+                color: rgbToHex(compositedFg.r, compositedFg.g, compositedFg.b),
+                background: rgbToHex(bg.r, bg.g, bg.b),
+                ratio: Math.round(ratio * 100) / 100,
+                required: aaRequired,
+                fontSize,
+                isLargeText: large,
+            });
+        }
+        else if (ratio < aaaRequired) {
+            // Only record AAA failures for the first 50 elements to avoid bloat
+            if (aaaFailures.length < 50) {
+                const text = (el.textContent ?? '').trim().slice(0, 60);
+                aaaFailures.push({
+                    selector: selectorFor(el),
+                    text,
+                    color: rgbToHex(compositedFg.r, compositedFg.g, compositedFg.b),
+                    background: rgbToHex(bg.r, bg.g, bg.b),
+                    ratio: Math.round(ratio * 100) / 100,
+                    required: aaaRequired,
+                    fontSize,
+                    isLargeText: large,
+                });
+            }
+        }
+    }
+    return { totalChecked, aaFailures, aaaFailures };
+}
+/**
+ * Run contrast measurement on a Playwright page.
+ * Returns ground-truth WCAG contrast failures.
+ */
+export async function measureContrast(page) {
+    try {
+        const result = await page.evaluate(inPageContrastCheck);
+        const totalAaPassed = result.totalChecked - result.aaFailures.length;
+        const totalAaaPassed = result.totalChecked - result.aaFailures.length - result.aaaFailures.length;
+        return {
+            totalChecked: result.totalChecked,
+            aaFailures: result.aaFailures,
+            aaaFailures: result.aaaFailures,
+            summary: {
+                aaPassRate: result.totalChecked > 0 ? totalAaPassed / result.totalChecked : 1,
+                aaaPassRate: result.totalChecked > 0 ? totalAaaPassed / result.totalChecked : 1,
+            },
+        };
+    }
+    catch {
+        return {
+            totalChecked: 0,
+            aaFailures: [],
+            aaaFailures: [],
+            summary: { aaPassRate: 1, aaaPassRate: 1 },
+        };
+    }
+}
+//# sourceMappingURL=contrast.js.map

package/dist/design/audit/measure/contrast.js.map

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

package/dist/design/audit/measure/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Measurement orchestrator — runs all deterministic measurements on a page
+ * and returns a single MeasurementBundle for downstream evaluation.
+ *
+ * Measurements run in parallel where independent. Failures are non-fatal:
+ * the audit continues even if a measurement crashes (it just won't have
+ * data from that source).
+ */
+import type { Page } from 'playwright';
+import type { MeasurementBundle } from '../types.js';
+export { measureContrast } from './contrast.js';
+export { measureA11y, impactToSeverity } from './a11y.js';
+export declare function gatherMeasurements(page: Page): Promise<MeasurementBundle>;
+//# sourceMappingURL=index.d.ts.map

package/dist/design/audit/measure/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/measure/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAIpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAEzD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4B/E"}

package/dist/design/audit/measure/index.js

@@ -0,0 +1,38 @@
+/**
+ * Measurement orchestrator — runs all deterministic measurements on a page
+ * and returns a single MeasurementBundle for downstream evaluation.
+ *
+ * Measurements run in parallel where independent. Failures are non-fatal:
+ * the audit continues even if a measurement crashes (it just won't have
+ * data from that source).
+ */
+import { measureContrast } from './contrast.js';
+import { measureA11y } from './a11y.js';
+export { measureContrast } from './contrast.js';
+export { measureA11y, impactToSeverity } from './a11y.js';
+export async function gatherMeasurements(page) {
+    const [contrast, a11y] = await Promise.all([
+        measureContrast(page).catch(() => ({
+            totalChecked: 0,
+            aaFailures: [],
+            aaaFailures: [],
+            summary: { aaPassRate: 1, aaaPassRate: 1 },
+        })),
+        measureA11y(page).catch(() => ({
+            ran: false,
+            error: 'measurement failed',
+            violations: [],
+            passes: 0,
+        })),
+    ]);
+    // Blocking issues: 5+ critical a11y violations OR > 25% contrast failure rate
+    const criticalA11y = a11y.violations.filter(v => v.impact === 'critical' || v.impact === 'serious').length;
+    const contrastFailRate = 1 - contrast.summary.aaPassRate;
+    const hasBlockingIssues = criticalA11y >= 5 || contrastFailRate > 0.25;
+    return {
+        contrast,
+        a11y,
+        hasBlockingIssues,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/design/audit/measure/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/design/audit/measure/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAEvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAEzD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAU;IACjD,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACzC,eAAe,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACjC,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,EAAE;YACd,WAAW,EAAE,EAAE;YACf,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;SAC3C,CAAC,CAAC;QACH,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YAC7B,GAAG,EAAE,KAAK;YACV,KAAK,EAAE,oBAAoB;YAC3B,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,CAAC;SACV,CAAC,CAAC;KACJ,CAAC,CAAA;IAEF,8EAA8E;IAC9E,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,CACvD,CAAC,MAAM,CAAA;IACR,MAAM,gBAAgB,GAAG,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAA;IACxD,MAAM,iBAAiB,GAAG,YAAY,IAAI,CAAC,IAAI,gBAAgB,GAAG,IAAI,CAAA;IAEtE,OAAO;QACL,QAAQ;QACR,IAAI;QACJ,iBAAiB;KAClB,CAAA;AACH,CAAC"}

package/dist/design/audit/pipeline.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Audit pipeline — orchestrates the full Gen 2 audit for one page.
+ *
+ *   load page → classify → compose rubric → measure → evaluate → result
+ *
+ * The pipeline is the only place that knows about all stages. Each stage is
+ * a pure function elsewhere in this module — easy to unit test in isolation.
+ */
+import type { Page } from 'playwright';
+import type { Brain } from '../../brain/index.js';
+import { PlaywrightDriver } from '../../drivers/playwright.js';
+import type { PageAuditResult } from './types.js';
+export interface AuditOnePageOptions {
+    brain: Brain;
+    driver: PlaywrightDriver;
+    page: Page;
+    url: string;
+    /** When set, skip classification and use this profile fragment directly */
+    profileOverride?: string;
+    /** Directory to save the screenshot (skipped when undefined) */
+    screenshotDir?: string;
+    /** User-supplied rubric fragments directory */
+    userRubricsDir?: string;
+}
+/**
+ * Audit one page through the full Gen 2 pipeline.
+ */
+export declare function auditOnePage(opts: AuditOnePageOptions): Promise<PageAuditResult>;
+/**
+ * Persist a `PageAuditResult` to JSON for downstream tooling.
+ */
+export declare function writeResultJson(result: PageAuditResult, dir: string): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/design/audit/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/design/audit/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAK9D,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAA;AAErE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,EAAE,gBAAgB,CAAA;IACxB,IAAI,EAAE,IAAI,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAqBD;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyEtF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAG1E"}

package/dist/design/audit/pipeline.js

@@ -0,0 +1,109 @@
+/**
+ * Audit pipeline — orchestrates the full Gen 2 audit for one page.
+ *
+ *   load page → classify → compose rubric → measure → evaluate → result
+ *
+ * The pipeline is the only place that knows about all stages. Each stage is
+ * a pure function elsewhere in this module — easy to unit test in isolation.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { classifyPage, defaultClassification } from './classify.js';
+import { composeRubric, composeRubricFromProfile } from './rubric/loader.js';
+import { gatherMeasurements } from './measure/index.js';
+import { evaluatePage } from './evaluate.js';
+const COOKIE_BANNER_SELECTORS = [
+    'button:has-text("Accept all")',
+    'button:has-text("Accept")',
+    'button:has-text("Reject all")',
+    'button:has-text("Got it")',
+    'button:has-text("Close")',
+];
+async function dismissCookieBanners(page) {
+    for (const sel of COOKIE_BANNER_SELECTORS) {
+        const btn = page.locator(sel).first();
+        if (await btn.isVisible({ timeout: 500 }).catch(() => false)) {
+            await btn.click({ timeout: 2000 }).catch(() => null);
+            await page.waitForTimeout(500);
+            return;
+        }
+    }
+}
+/**
+ * Audit one page through the full Gen 2 pipeline.
+ */
+export async function auditOnePage(opts) {
+    const { brain, driver, page, url, profileOverride, screenshotDir, userRubricsDir } = opts;
+    try {
+        // ── 1. Load the page ──
+        await page
+            .goto(url, { waitUntil: 'networkidle', timeout: 20_000 })
+            .catch(() => page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15_000 }));
+        await page.waitForTimeout(2000);
+        await dismissCookieBanners(page);
+        const state = await driver.observe();
+        // ── 2. Save screenshot ──
+        let screenshotPath;
+        if (screenshotDir) {
+            const slug = new URL(url).pathname.replace(/\//g, '_').replace(/^_/, '') || 'index';
+            screenshotPath = path.join(screenshotDir, `${slug}.png`);
+            await page.screenshot({ path: screenshotPath, fullPage: false });
+        }
+        // ── 3. Classify (or use profile override) ──
+        let classification;
+        if (profileOverride) {
+            // Build a synthetic classification matching the explicit profile
+            classification = {
+                ...defaultClassification(),
+                type: profileOverride,
+                confidence: 1,
+            };
+        }
+        else {
+            classification = await classifyPage(brain, state);
+        }
+        // ── 4. Compose rubric ──
+        const rubric = profileOverride
+            ? composeRubricFromProfile(profileOverride)
+            : composeRubric(classification, undefined, userRubricsDir);
+        // Confidence fallback: if classifier isn't confident, fall back to general
+        if (!profileOverride && classification.confidence < 0.5) {
+            // Re-compose with universal-only fragments
+            const fallbackClass = {
+                ...classification,
+                type: 'unknown',
+            };
+            Object.assign(rubric, composeRubric(fallbackClass, undefined, userRubricsDir));
+        }
+        // ── 5. Measure (deterministic, runs in parallel) ──
+        const measurements = await gatherMeasurements(page);
+        // ── 6. Evaluate ──
+        const result = await evaluatePage(brain, {
+            url,
+            state,
+            classification,
+            rubric,
+            measurements,
+            screenshotPath,
+        });
+        return result;
+    }
+    catch (err) {
+        return {
+            url,
+            score: 0,
+            summary: 'Audit failed',
+            strengths: [],
+            findings: [],
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Persist a `PageAuditResult` to JSON for downstream tooling.
+ */
+export function writeResultJson(result, dir) {
+    const slug = new URL(result.url).hostname.replace(/[^a-z0-9.-]/gi, '_');
+    fs.writeFileSync(path.join(dir, `${slug}-${Date.now()}.json`), JSON.stringify(result, null, 2));
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/design/audit/pipeline.js.map

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

package/dist/design/audit/roi.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ROI scoring + cross-page systemic detection.
+ *
+ * Pure functions, no LLM calls. Easy to unit test.
+ *
+ * The LLM produces impact/effort/blast for each finding (in turn 3 of the
+ * audit pipeline). This module:
+ *   1. Computes the final `roi` score from those raw values.
+ *   2. Detects findings that appear on multiple pages and elevates their
+ *      blast to 'system' (with the count of affected pages).
+ *   3. Provides sort + selection helpers for "top fixes" surfacing.
+ */
+import type { DesignFinding } from '../../types.js';
+/**
+ * Compute the ROI score for a single finding from its impact/effort/blast.
+ * Returns a positive number — higher means "fix this first."
+ *
+ * Formula: (impact * blastWeight) / effort
+ *
+ * Edge cases:
+ *   - Missing fields → use defaults (impact=5, effort=5, blast=page) → roi = 1.0
+ *   - effort = 0 is treated as 1 to avoid division by zero
+ */
+export declare function computeRoi(finding: DesignFinding): number;
+/**
+ * Annotate every finding with its computed ROI in place.
+ * Returns the same array for chaining.
+ */
+export declare function annotateRoi(findings: DesignFinding[]): DesignFinding[];
+/**
+ * Cross-page systemic detection.
+ *
+ * Groups findings from across all audited pages by `(category, normalized_description)`.
+ * Any group that appears on 2+ distinct pages becomes a single canonical
+ * finding with `blast: 'system'` and `pageCount` set, replacing the duplicates.
+ *
+ * Normalization: lowercased, first 80 chars only, trimmed.
+ * Conservative on purpose — better to under-merge than to merge unrelated findings.
+ *
+ * @param perPageFindings - array of finding arrays, one per audited page
+ * @returns flat array of findings, with cross-page duplicates collapsed
+ */
+export declare function detectSystemicFindings(perPageFindings: DesignFinding[][]): DesignFinding[];
+/**
+ * Pick the top N findings by ROI (descending).
+ * Stable: ties broken by severity (critical > major > minor), then by description.
+ */
+export declare function topByRoi(findings: DesignFinding[], n: number): DesignFinding[];
+//# sourceMappingURL=roi.d.ts.map

package/dist/design/audit/roi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roi.d.ts","sourceRoot":"","sources":["../../../src/design/audit/roi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAsBnD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAKtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,aAAa,EAAE,EAAE,GACjC,aAAa,EAAE,CA+CjB;AAkBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAgB9E"}

package/dist/design/audit/roi.js

@@ -0,0 +1,157 @@
+/**
+ * ROI scoring + cross-page systemic detection.
+ *
+ * Pure functions, no LLM calls. Easy to unit test.
+ *
+ * The LLM produces impact/effort/blast for each finding (in turn 3 of the
+ * audit pipeline). This module:
+ *   1. Computes the final `roi` score from those raw values.
+ *   2. Detects findings that appear on multiple pages and elevates their
+ *      blast to 'system' (with the count of affected pages).
+ *   3. Provides sort + selection helpers for "top fixes" surfacing.
+ */
+/**
+ * Multipliers for converting blast scope into a leverage factor.
+ *
+ * A system-level fix touches every page that uses that component / token,
+ * so its impact is multiplied. The effect on ROI is asymmetric — these
+ * weights are deliberately conservative; we want ROI to favor systemic
+ * fixes without completely drowning out high-impact page-specific issues.
+ */
+const BLAST_WEIGHT = {
+    page: 1,
+    section: 1.25,
+    component: 1.75,
+    system: 2.5,
+};
+/** Default values when the LLM didn't produce ROI fields. */
+const DEFAULT_IMPACT = 5;
+const DEFAULT_EFFORT = 5;
+const DEFAULT_BLAST = 'page';
+/**
+ * Compute the ROI score for a single finding from its impact/effort/blast.
+ * Returns a positive number — higher means "fix this first."
+ *
+ * Formula: (impact * blastWeight) / effort
+ *
+ * Edge cases:
+ *   - Missing fields → use defaults (impact=5, effort=5, blast=page) → roi = 1.0
+ *   - effort = 0 is treated as 1 to avoid division by zero
+ */
+export function computeRoi(finding) {
+    const impact = finding.impact ?? DEFAULT_IMPACT;
+    const effort = Math.max(1, finding.effort ?? DEFAULT_EFFORT);
+    const blast = finding.blast ?? DEFAULT_BLAST;
+    const weight = BLAST_WEIGHT[blast];
+    return Math.round(((impact * weight) / effort) * 100) / 100;
+}
+/**
+ * Annotate every finding with its computed ROI in place.
+ * Returns the same array for chaining.
+ */
+export function annotateRoi(findings) {
+    for (const f of findings) {
+        f.roi = computeRoi(f);
+    }
+    return findings;
+}
+/**
+ * Cross-page systemic detection.
+ *
+ * Groups findings from across all audited pages by `(category, normalized_description)`.
+ * Any group that appears on 2+ distinct pages becomes a single canonical
+ * finding with `blast: 'system'` and `pageCount` set, replacing the duplicates.
+ *
+ * Normalization: lowercased, first 80 chars only, trimmed.
+ * Conservative on purpose — better to under-merge than to merge unrelated findings.
+ *
+ * @param perPageFindings - array of finding arrays, one per audited page
+ * @returns flat array of findings, with cross-page duplicates collapsed
+ */
+export function detectSystemicFindings(perPageFindings) {
+    // Map of normalized key → { canonical finding, set of page indices it appeared on }
+    const groups = new Map();
+    // Findings that don't dedupe stay in their original page bucket
+    const singletonsByPage = perPageFindings.map(() => []);
+    for (let pageIdx = 0; pageIdx < perPageFindings.length; pageIdx++) {
+        const findings = perPageFindings[pageIdx];
+        for (const finding of findings) {
+            const key = normalizeFindingKey(finding);
+            const existing = groups.get(key);
+            if (existing) {
+                existing.pages.add(pageIdx);
+            }
+            else {
+                groups.set(key, {
+                    canonical: { ...finding },
+                    pages: new Set([pageIdx]),
+                });
+            }
+        }
+    }
+    // For each group: if it appears on 2+ pages, promote to systemic.
+    // Otherwise, return it back to its original page bucket as a singleton.
+    const systemic = [];
+    for (const { canonical, pages } of groups.values()) {
+        if (pages.size >= 2) {
+            const promoted = {
+                ...canonical,
+                blast: 'system',
+                pageCount: pages.size,
+                description: `[appears on ${pages.size} pages] ${canonical.description}`,
+            };
+            promoted.roi = computeRoi(promoted);
+            systemic.push(promoted);
+        }
+        else {
+            const onlyPage = pages.values().next().value;
+            if (onlyPage !== undefined) {
+                singletonsByPage[onlyPage].push(canonical);
+            }
+        }
+    }
+    // Flatten: systemic findings first (higher ROI), then per-page singletons
+    const flat = [...systemic];
+    for (const page of singletonsByPage)
+        flat.push(...page);
+    return flat;
+}
+/**
+ * Normalize a finding into a key for cross-page grouping.
+ *
+ * Uses (category, description-prefix) — conservative enough to avoid
+ * merging unrelated findings, loose enough to catch the same issue
+ * worded slightly differently across pages.
+ */
+function normalizeFindingKey(finding) {
+    const desc = (finding.description ?? '')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 80);
+    return `${finding.category}|${desc}`;
+}
+/**
+ * Pick the top N findings by ROI (descending).
+ * Stable: ties broken by severity (critical > major > minor), then by description.
+ */
+export function topByRoi(findings, n) {
+    const SEVERITY_RANK = {
+        critical: 0,
+        major: 1,
+        minor: 2,
+    };
+    return [...findings]
+        .sort((a, b) => {
+        const roiA = a.roi ?? computeRoi(a);
+        const roiB = b.roi ?? computeRoi(b);
+        if (roiB !== roiA)
+            return roiB - roiA;
+        const sevDiff = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+        if (sevDiff !== 0)
+            return sevDiff;
+        return a.description.localeCompare(b.description);
+    })
+        .slice(0, n);
+}
+//# sourceMappingURL=roi.js.map

package/dist/design/audit/roi.js.map

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