tether-ui 0.2.0 → 0.4.0

package/dist/drift/compare.js

@@ -1,3 +1,5 @@
+import { safeUrl } from "../utils/scenarios.js";
+import { resolveRule } from "../contract/scopes.js";
 import { createHash } from "node:crypto";
 import { baselineMatcher } from "../scanner/identity.js";
 import { findingEvidence } from "./evidence.js";
@@ -41,35 +43,42 @@ function equivalent(category, a, b) {
         /^-?[\d.]+px$/.test(b) &&
         Math.abs(parseFloat(a) - parseFloat(b)) <= 0.25);
 }
-export function compare(contract, baseline, current) {
-    const issues = new Map();
+/** Atomic observations are retained until approval matching is complete. */
+export function collectOccurrences(contract, baseline, current) {
+    const occurrences = [];
+    let identities = new Map(), selectors = new Map();
+    let state = "default";
+    let documentOverflowUnique = false, completeSnapshot = true;
     function push(issue, viewport) {
-        const key = [
-            issue.category,
-            issue.route,
-            issue.identity ?? issue.selector,
-            issue.current,
-            issue.title,
-        ].join("\0");
-        const previous = issues.get(key);
-        if (previous) {
-            if (!previous.viewports.includes(viewport))
-                previous.viewports.push(viewport);
-            for (const evidence of issue.evidence ?? [])
-                if (!previous.evidence?.some((e) => e.viewport.name === evidence.viewport.name))
-                    previous.evidence?.push(evidence);
-            if (!previous.property.split(", ").includes(issue.property))
-                previous.property += `, ${issue.property}`;
-        }
-        else
-            issues.set(key, {
-                ...issue,
-                id: createHash("sha256").update(key).digest("hex").slice(0, 12),
-                viewports: [viewport],
-            });
+        occurrences.push({
+            issue: { ...issue, ...(state !== "default" ? { state } : {}) },
+            viewport,
+            state,
+            identityUnique: completeSnapshot &&
+                issue.identityConfidence === "high" &&
+                identities.get(issue.identity ?? "") === 1,
+            selectorUnique: completeSnapshot &&
+                (selectors.get(issue.selector) === 1 ||
+                    (issue.category === "layout" &&
+                        issue.selector === "html" &&
+                        issue.property === "overflow" &&
+                        documentOverflowUnique)),
+        });
     }
     for (const snapshot of current.snapshots) {
-        const previousSnapshot = baseline.snapshots.find((s) => s.route === snapshot.route &&
+        state = snapshot.state ?? "default";
+        completeSnapshot = !snapshot.truncated;
+        identities = new Map();
+        selectors = new Map();
+        for (const element of snapshot.elements) {
+            if (element.identity)
+                identities.set(element.identity, (identities.get(element.identity) ?? 0) + 1);
+            selectors.set(element.selector, (selectors.get(element.selector) ?? 0) + 1);
+        }
+        documentOverflowUnique =
+            snapshot.layout.filter((p) => p.selector === "html" && p.kind === "overflow").length === 1;
+        const previousSnapshot = baseline.snapshots.find((s) => safeUrl(s.route) === safeUrl(snapshot.route) &&
+            (s.state ?? "default") === state &&
             s.viewport.name === snapshot.viewport.name &&
             s.viewport.width === snapshot.viewport.width &&
             s.viewport.height === snapshot.viewport.height);
@@ -77,14 +86,20 @@ export function compare(contract, baseline, current) {
         for (const element of snapshot.elements) {
             const prior = match(element);
             for (const o of element.observations) {
-                const expected = contract[o.category].map((t) => t.value);
+                const rule = resolveRule(contract, element, o);
+                const expected = (rule?.tokens ?? contract[o.category]).map((t) => t.value);
                 if (expected.some((v) => equivalent(o.category, v, o.value)))
                     continue;
-                if (prior?.observations.some((p) => p.category === o.category &&
-                    p.property === o.property &&
-                    equivalent(o.category, p.value, o.value)))
+                if (rule?.source !== "override" &&
+                    (contract.version === 1 ||
+                        (prior?.scope?.name === element.scope?.name &&
+                            prior?.scope?.part === element.scope?.part)) &&
+                    prior?.observations.some((p) => p.category === o.category &&
+                        p.property === o.property &&
+                        equivalent(o.category, p.value, o.value)))
                     continue;
                 push({
+                    ...(rule ? { rule } : {}),
                     category: o.category,
                     severity: severityFor(o.category, o.value, expected),
                     title: labels[o.category],
@@ -98,7 +113,7 @@ export function compare(contract, baseline, current) {
                     current: o.value,
                     expected,
                     route: snapshot.route,
-                }, snapshot.viewport.name);
+                }, snapshot.viewport);
             }
         }
         for (const problem of snapshot.layout) {
@@ -121,15 +136,64 @@ export function compare(contract, baseline, current) {
                 current: problem.value,
                 expected: ["Content fits within the viewport"],
                 route: snapshot.route,
-            }, snapshot.viewport.name);
+            }, snapshot.viewport);
         }
     }
+    return occurrences;
+}
+export function groupOccurrences(contract, occurrences) {
+    const issues = new Map();
+    function push(issue, viewport) {
+        const key = [
+            issue.category,
+            issue.route,
+            issue.identity ?? issue.selector,
+            issue.current,
+            issue.title,
+        ]
+            .concat(issue.state && issue.state !== "default" ? [issue.state] : [])
+            .concat(issue.rule ? [issue.property, JSON.stringify(issue.rule)] : [])
+            .concat(issue.approval ? [issue.property, issue.approval.id] : [])
+            .join("\0");
+        const previous = issues.get(key);
+        if (previous) {
+            if (!previous.viewports.includes(viewport))
+                previous.viewports.push(viewport);
+            for (const evidence of issue.evidence ?? [])
+                if (!previous.evidence?.some((e) => e.viewport.name === evidence.viewport.name))
+                    previous.evidence?.push(evidence);
+            if (!previous.property.split(", ").includes(issue.property))
+                previous.property += `, ${issue.property}`;
+        }
+        else
+            issues.set(key, {
+                ...issue,
+                ...(issue.evidence ? { evidence: [...issue.evidence] } : {}),
+                id: createHash("sha256").update(key).digest("hex").slice(0, 12),
+                viewports: [viewport],
+            });
+    }
+    for (const occurrence of occurrences)
+        push(occurrence.issue, occurrence.viewport.name);
     const rank = { high: 0, medium: 1, low: 2 };
+    if (contract.version === 2)
+        for (const issue of issues.values()) {
+            issue.viewports.sort();
+            issue.evidence?.sort((a, b) => a.viewport.name.localeCompare(b.viewport.name));
+        }
     return [...issues.values()].sort((a, b) => rank[a.severity] - rank[b.severity] ||
         a.category.localeCompare(b.category) ||
         a.route.localeCompare(b.route) ||
+        (a.state ?? "default").localeCompare(b.state ?? "default") ||
         (a.identity ?? a.selector).localeCompare(b.identity ?? b.selector) ||
-        a.current.localeCompare(b.current));
+        a.current.localeCompare(b.current) ||
+        (contract.version === 2
+            ? a.property.localeCompare(b.property) ||
+                JSON.stringify(a.rule ?? null).localeCompare(JSON.stringify(b.rule ?? null))
+            : 0));
+}
+export function compare(contract, baseline, current) {
+    return groupOccurrences(contract, collectOccurrences(contract, baseline, current));
 }
 export function consistencyScore(issues) {
     return Math.max(0, 100 -

package/dist/drift/evidence.js

@@ -24,6 +24,7 @@ export function visibleBounds(bounds, viewport) {
 export function findingEvidence(current, baseline, element, prior) {
     return {
         viewport: current.viewport,
+        ...(current.state ? { state: current.state } : {}),
         current: {
             screenshot: current.screenshot,
             ...(element?.bounds ? { bounds: element.bounds } : {}),

package/dist/scanner/collect.d.ts

@@ -1,9 +1,11 @@
 import type { CollectedElement } from "./identity.js";
-import type { LayoutProblem } from "../types.js";
+import type { LayoutProblem, ScopeDefinition } from "../types.js";
 /** Pure DOM reader, serialized by Playwright into the page. */
-export declare function collect({ maxElements, ignore, }: {
+export declare function collect({ maxElements, ignore, scopes, sensitiveSelectors, }: {
     maxElements: number;
     ignore: string[];
+    scopes?: ScopeDefinition[];
+    sensitiveSelectors?: string[];
 }): {
     elements: CollectedElement[];
     layout: LayoutProblem[];

package/dist/scanner/collect.js

@@ -1,5 +1,5 @@
 /** Pure DOM reader, serialized by Playwright into the page. */
-export function collect({ maxElements, ignore, }) {
+export function collect({ maxElements, ignore, scopes = [], sensitiveSelectors = [], }) {
     for (const selector of ignore) {
         try {
             document.querySelector(selector);
@@ -8,6 +8,59 @@ export function collect({ maxElements, ignore, }) {
             throw new Error(`Invalid ignore selector: ${selector}`);
         }
     }
+    const sensitive = sensitiveSelectors.flatMap((selector) => [
+        ...document.querySelectorAll(selector),
+    ]);
+    function privateElement(el) {
+        return (sensitive.some((s) => s.contains(el) || el.contains(s)) ||
+            (el.getAttribute("aria-labelledby") ?? "").split(/\s+/).some((id) => {
+                const label = document.getElementById(id);
+                return (label && sensitive.some((s) => s.contains(label) || label.contains(s)));
+            }));
+    }
+    // Validate declarations even when the page contains no matching elements.
+    for (const scope of scopes) {
+        for (const selector of [
+            scope.selector,
+            ...Object.values(scope.parts ?? {}),
+        ]) {
+            try {
+                document.querySelector(selector);
+            }
+            catch {
+                throw new Error(`Invalid selector in scope ${scope.name}: ${selector}`);
+            }
+        }
+    }
+    function scopeFor(el) {
+        for (let root = el; root; root = root.parentElement) {
+            const matches = scopes.filter((s) => root.matches(s.selector));
+            if (matches.length > 1)
+                throw new Error(`Ambiguous scopes on ${selectorFor(root)}: ${matches
+                    .map((s) => s.name)
+                    .sort()
+                    .join(", ")}`);
+            if (!matches.length)
+                continue;
+            const scope = matches[0];
+            for (let node = el; node; node = node.parentElement) {
+                const parts = Object.entries(scope.parts ?? {}).filter(([, selector]) => node.matches(selector));
+                if (parts.length > 1)
+                    throw new Error(`Ambiguous parts in ${scope.name} on ${selectorFor(node)}.`);
+                if (parts.length || node === root) {
+                    // Unnamed descendants do not inherit container padding/radius conventions.
+                    if (!parts.length && el !== root)
+                        return;
+                    return {
+                        name: scope.name,
+                        ...(scope.variant ? { variant: scope.variant } : {}),
+                        part: parts[0]?.[0] ?? "root",
+                        instance: selectorFor(root),
+                    };
+                }
+            }
+        }
+    }
     const excluded = ignore.length ? ignore.join(",") : null;
     function visible(el) {
         if (excluded && el.closest(excluded))
@@ -36,6 +89,8 @@ export function collect({ maxElements, ignore, }) {
             .join("");
     }
     function selectorFor(el) {
+        if (privateElement(el))
+            return structureFor(el);
         if (el.id && document.querySelectorAll(`#${escapeCss(el.id)}`).length === 1)
             return `#${escapeCss(el.id)}`;
         const testid = el.getAttribute("data-testid");
@@ -160,15 +215,17 @@ export function collect({ maxElements, ignore, }) {
                 .split(/\s+/)
                 .map((id) => document.getElementById(id)?.textContent ?? "")
                 .join(" ");
+        const scope = scopeFor(el);
         elements.push({
+            ...(scope ? { scope } : {}),
             selector,
             tag: el.tagName.toLowerCase(),
             observations,
             bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
             signals: {
-                attributes,
-                text: el.textContent ?? "",
-                classes: [...el.classList],
+                attributes: privateElement(el) ? {} : attributes,
+                text: privateElement(el) ? "" : (el.textContent ?? ""),
+                classes: privateElement(el) ? [] : [...el.classList],
                 structure: structureFor(el),
             },
         });

package/dist/scanner/scan.js

@@ -1,89 +1,155 @@
 import { openBrowser } from "./browser.js";
 import { assignIdentities } from "./identity.js";
 import { collect } from "./collect.js";
-import { mkdir } from "node:fs/promises";
+import { mkdir, rm, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { normalizeValue } from "../utils/normalize.js";
+import { captures, safeUrl } from "../utils/scenarios.js";
 import { targetUrl } from "../utils/config.js";
 export async function scan(config, directory, phase) {
-    await mkdir(join(directory, "screenshots", phase), { recursive: true });
+    let storageState;
+    if (config.storageState) {
+        try {
+            storageState = JSON.parse(await readFile(config.storageState, "utf8"));
+            if (!storageState ||
+                typeof storageState !== "object" ||
+                Array.isArray(storageState))
+                throw new Error();
+        }
+        catch {
+            const first = captures(config)[0];
+            throw new Error(`Scan failed: route ${safeUrl(first.route)}, state ${first.scenario.id}, viewport ${config.viewports[0].name}, step context. Could not read a valid storage-state file.`);
+        }
+    }
     const browser = await openBrowser();
+    let complete = false;
     const result = {
         version: 1,
         createdAt: new Date().toISOString(),
-        url: config.url,
+        url: safeUrl(config.url),
         snapshots: [],
     };
     try {
-        for (const route of config.routes)
+        await mkdir(join(directory, "screenshots", phase), { recursive: true });
+        for (const { route, scenario } of captures(config))
             for (const viewport of config.viewports) {
-                const context = await browser.newContext({
-                    viewport: { width: viewport.width, height: viewport.height },
-                    deviceScaleFactor: 1,
-                    colorScheme: "light",
-                    reducedMotion: "reduce",
-                });
-                const page = await context.newPage();
-                const url = targetUrl(config.url, route);
+                let context;
+                let step = "context";
+                let timer;
                 try {
-                    const response = await page.goto(url, {
-                        waitUntil: "load",
-                        timeout: 30000,
-                    });
-                    if (response && response.status() >= 400)
-                        throw new Error(`HTTP ${response.status()}`);
+                    await Promise.race([
+                        (async () => {
+                            context = await browser.newContext({
+                                ...(storageState ? { storageState } : {}),
+                                viewport: { width: viewport.width, height: viewport.height },
+                                deviceScaleFactor: 1,
+                                colorScheme: scenario.colorScheme ?? "light",
+                                reducedMotion: "reduce",
+                            });
+                            const page = await context.newPage();
+                            page.setDefaultTimeout(Math.min(10000, scenario.timeoutMs ?? 30000));
+                            page.setDefaultNavigationTimeout(Math.min(30000, scenario.timeoutMs ?? 30000));
+                            step = "setup";
+                            await scenario.setup?.(page, context);
+                            step = "navigation";
+                            const url = targetUrl(config.url, route);
+                            try {
+                                const response = await page.goto(url, {
+                                    waitUntil: "load",
+                                    timeout: 30000,
+                                });
+                                if (response && response.status() >= 400)
+                                    throw new Error(`HTTP ${response.status()}`);
+                            }
+                            catch {
+                                throw new Error("Navigation failed");
+                            }
+                            step = "interaction";
+                            await scenario.interact?.(page);
+                            step = "readiness";
+                            await scenario.ready(page);
+                            step = "capture";
+                            await page.addStyleTag({
+                                content: "*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; }",
+                            });
+                            await page.evaluate(() => Promise.race([
+                                document.fonts.ready,
+                                new Promise((resolve) => setTimeout(resolve, 5000)),
+                            ]));
+                            await page.waitForTimeout(config.settleMs);
+                            const collected = await page.evaluate(collect, {
+                                maxElements: config.maxElements,
+                                ignore: config.ignore,
+                                scopes: config.scopes,
+                                sensitiveSelectors: config.sensitiveSelectors,
+                            });
+                            if (!collected.elements.length)
+                                throw new Error("No visible elements found");
+                            for (const element of collected.elements) {
+                                element.observations = [
+                                    ...new Map(element.observations.map((o) => {
+                                        const normalized = {
+                                            ...o,
+                                            value: normalizeValue(o.property, o.value),
+                                        };
+                                        return [
+                                            `${o.category}\0${o.property}\0${normalized.value}`,
+                                            normalized,
+                                        ];
+                                    })).values(),
+                                ].filter((o) => o.value !== "transparent" && o.value !== "0px");
+                            }
+                            const filename = `${createHash("sha256")
+                                .update(scenario.id === "default"
+                                ? route
+                                : JSON.stringify([route, scenario.id]))
+                                .digest("hex")
+                                .slice(0, 12)}-${viewport.name}.png`;
+                            const screenshot = `screenshots/${phase}/${filename}`;
+                            await page.screenshot({
+                                path: join(directory, screenshot),
+                                fullPage: false,
+                                animations: "disabled",
+                                mask: (config.sensitiveSelectors ?? []).map((selector) => page.locator(selector)),
+                                maskColor: "#000000",
+                            });
+                            result.snapshots.push({
+                                route: safeUrl(route),
+                                ...(scenario.id !== "default" ? { state: scenario.id } : {}),
+                                ...(scenario.colorScheme === "dark"
+                                    ? { colorScheme: "dark" }
+                                    : {}),
+                                viewport,
+                                ...collected,
+                                elements: assignIdentities(collected.elements),
+                                screenshot,
+                            });
+                        })(),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new Error("timeout")), scenario.timeoutMs ?? 30000);
+                        }),
+                    ]);
                 }
                 catch {
-                    throw new Error(`tether couldn't reach ${url}.\nStart your application, check the route, and try again.`);
+                    // Never forward Playwright errors: they can contain locator text, cookies or submitted values.
+                    throw new Error(`Scan failed: route ${safeUrl(route)}, state ${scenario.id}, viewport ${viewport.name}, step ${step}. Check setup/readiness and timeoutMs; previous artifacts were preserved.`);
                 }
-                await page.addStyleTag({
-                    content: "*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; }",
-                });
-                await page.evaluate(() => Promise.race([
-                    document.fonts.ready,
-                    new Promise((resolve) => setTimeout(resolve, 5000)),
-                ]));
-                await page.waitForTimeout(config.settleMs);
-                const collected = await page.evaluate(collect, {
-                    maxElements: config.maxElements,
-                    ignore: config.ignore,
-                });
-                if (!collected.elements.length)
-                    throw new Error(`No visible elements found at ${url} (${viewport.name}). Check your route and ignore selectors.`);
-                for (const element of collected.elements) {
-                    element.observations = [
-                        ...new Map(element.observations.map((o) => {
-                            const normalized = {
-                                ...o,
-                                value: normalizeValue(o.property, o.value),
-                            };
-                            return [
-                                `${o.category}\0${o.property}\0${normalized.value}`,
-                                normalized,
-                            ];
-                        })).values(),
-                    ].filter((o) => o.value !== "transparent" && o.value !== "0px");
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                    await context?.close().catch(() => { });
                 }
-                const filename = `${createHash("sha256").update(route).digest("hex").slice(0, 12)}-${viewport.name}.png`;
-                const screenshot = `screenshots/${phase}/${filename}`;
-                await page.screenshot({
-                    path: join(directory, screenshot),
-                    fullPage: false,
-                    animations: "disabled",
-                });
-                result.snapshots.push({
-                    route,
-                    viewport,
-                    ...collected,
-                    elements: assignIdentities(collected.elements),
-                    screenshot,
-                });
-                await context.close();
             }
+        complete = true;
         return result;
     }
     finally {
         await browser.close();
+        if (!complete)
+            await rm(join(directory, "screenshots", phase), {
+                recursive: true,
+                force: true,
+            });
     }
 }

package/dist/types.d.ts

@@ -6,7 +6,19 @@ export interface Viewport {
     width: number;
     height: number;
 }
+export interface Scenario {
+    id: string;
+    routes: string[];
+    colorScheme?: "light" | "dark";
+    timeoutMs?: number;
+    setup?: (page: import("playwright").Page, context: import("playwright").BrowserContext) => Promise<void>;
+    interact?: (page: import("playwright").Page) => Promise<void>;
+    ready: (page: import("playwright").Page) => Promise<void>;
+}
 export interface Config {
+    scenarios?: Scenario[];
+    storageState?: string;
+    sensitiveSelectors?: string[];
     url: string;
     routes: string[];
     viewports: Viewport[];
@@ -14,6 +26,44 @@ export interface Config {
     maxElements: number;
     settleMs: number;
     ignore: string[];
+    scopes?: ScopeDefinition[];
+}
+export interface ScopeDefinition {
+    name: string;
+    selector: string;
+    variant?: string;
+    minOccurrences?: number;
+    parts?: Record<string, string>;
+    overrides?: {
+        part?: string;
+        category: Category;
+        property: string;
+        values: string[];
+    }[];
+}
+export interface ScopeMembership {
+    name: string;
+    variant?: string;
+    part: string;
+    instance: string;
+}
+export interface ScopedRule {
+    scope: string;
+    part: string;
+    category: Category;
+    property: string;
+    samples: number;
+    tokens: Token[];
+    source: "scope" | "override";
+}
+export interface RuleProvenance {
+    scope?: string;
+    variant?: string;
+    part?: string;
+    source: "scope" | "override" | "global";
+    reason?: "unscoped" | "missing-rule" | "insufficient-support" | "partial-baseline";
+    samples: number;
+    tokens: Token[];
 }
 export interface Observation {
     category: Category;
@@ -28,6 +78,7 @@ export interface Bounds {
     height: number;
 }
 export interface Evidence {
+    state?: string;
     viewport: Viewport;
     current: {
         screenshot: string;
@@ -39,6 +90,7 @@ export interface Evidence {
     };
 }
 export interface ElementRecord {
+    scope?: ScopeMembership;
     identity?: string;
     identityConfidence?: IdentityConfidence;
     bounds?: Bounds;
@@ -53,6 +105,8 @@ export interface LayoutProblem {
     severity: Severity;
 }
 export interface Snapshot {
+    state?: string;
+    colorScheme?: "light" | "dark";
     route: string;
     viewport: Viewport;
     elements: ElementRecord[];
@@ -71,11 +125,57 @@ export interface Token {
     count: number;
 }
 export type Contract = {
-    version: 1;
+    version: 1 | 2;
+    scopes?: ScopeDefinition[];
+    rules?: ScopedRule[];
+    partial?: boolean;
     createdAt: string;
     minOccurrences: number;
 } & Record<Category, Token[]>;
+export interface Approval {
+    id: string;
+    reason: string;
+    route: string;
+    state: string;
+    target: {
+        kind: "identity";
+        value: string;
+    } | {
+        kind: "selector";
+        value: string;
+        identity: string | null;
+    };
+    category: Category | "layout";
+    property: string;
+    current: string;
+    viewport: Viewport;
+    context?: {
+        scope: string;
+        part: string;
+    };
+}
+export interface ApprovalFile {
+    version: 1;
+    approvals: Approval[];
+}
+export interface ApprovalSummary {
+    approved: Issue[];
+    stale: Approval[];
+}
+export interface FindingOccurrence {
+    issue: Omit<Issue, "id" | "viewports">;
+    viewport: Viewport;
+    state: string;
+    identityUnique: boolean;
+    selectorUnique: boolean;
+}
 export interface Issue {
+    state?: string;
+    approval?: {
+        id: string;
+        reason: string;
+    };
+    rule?: RuleProvenance;
     identity?: string;
     identityConfidence?: IdentityConfidence;
     evidence?: Evidence[];
@@ -91,7 +191,8 @@ export interface Issue {
     viewports: string[];
 }
 export interface Report {
-    version: 1;
+    version: 1 | 2;
+    approvals?: ApprovalSummary;
     baselineAt: string;
     scan: Scan;
     contract: Contract;