tether-ui 0.3.0 → 0.5.0

package/dist/drift/compare.js

@@ -1,3 +1,5 @@
+import { existingLayout } from "./layout-status.js";
+import { safeUrl } from "../utils/scenarios.js";
 import { resolveRule } from "../contract/scopes.js";
 import { createHash } from "node:crypto";
 import { baselineMatcher } from "../scanner/identity.js";
@@ -42,40 +44,53 @@ 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,
-        ]
-            .concat(issue.rule ? [issue.property, JSON.stringify(issue.rule)] : [])
-            .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 previousSnapshots = baseline.snapshots.filter((s) => safeUrl(s.route) === safeUrl(snapshot.route) &&
+            (s.state ?? "default") === state &&
+            (s.colorScheme ?? "light") === (snapshot.colorScheme ?? "light") &&
             s.viewport.name === snapshot.viewport.name &&
             s.viewport.width === snapshot.viewport.width &&
             s.viewport.height === snapshot.viewport.height);
+        const previousSnapshot = previousSnapshots.length === 1 ? previousSnapshots[0] : undefined;
+        const uniqueCapture = current.snapshots.filter((s) => safeUrl(s.route) === safeUrl(snapshot.route) &&
+            (s.state ?? "default") === state &&
+            (s.colorScheme ?? "light") === (snapshot.colorScheme ?? "light") &&
+            s.viewport.name === snapshot.viewport.name &&
+            s.viewport.width === snapshot.viewport.width &&
+            s.viewport.height === snapshot.viewport.height).length === 1;
         const match = baselineMatcher(previousSnapshot?.elements ?? []);
         for (const element of snapshot.elements) {
             const prior = match(element);
@@ -107,13 +122,16 @@ export function compare(contract, baseline, current) {
                     current: o.value,
                     expected,
                     route: snapshot.route,
-                }, snapshot.viewport.name);
+                }, snapshot.viewport);
             }
         }
         for (const problem of snapshot.layout) {
             const element = snapshot.elements.find((e) => e.selector === problem.selector);
             push({
                 category: "layout",
+                baselineStatus: uniqueCapture && existingLayout(snapshot, previousSnapshot, problem)
+                    ? "existing"
+                    : "new-or-changed",
                 severity: problem.severity,
                 title: problem.kind === "overflow"
                     ? "Horizontal overflow"
@@ -130,9 +148,46 @@ 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.baselineStatus === "existing" ? ["baseline:existing"] : [])
+            .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()) {
@@ -142,6 +197,7 @@ export function compare(contract, baseline, current) {
     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) ||
         (contract.version === 2
@@ -149,7 +205,16 @@ export function compare(contract, baseline, current) {
                 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 -
         issues.reduce((sum, i) => sum + { high: 8, medium: 4, low: 2 }[i.severity], 0));
 }
+/** Unknown/legacy findings remain blocking; only verified existing layout is excluded. */
+export function blockingIssues(issues, failOn = "all") {
+    return failOn === "new"
+        ? issues.filter((i) => !(i.category === "layout" && i.baselineStatus === "existing"))
+        : issues;
+}

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/drift/layout-status.d.ts

@@ -0,0 +1,3 @@
+import type { LayoutProblem, Snapshot } from "../types.js";
+/** Existing means an exact, unambiguous observation in complete matching captures. */
+export declare function existingLayout(current: Snapshot, baseline: Snapshot | undefined, problem: LayoutProblem): boolean;

package/dist/drift/layout-status.js

@@ -0,0 +1,42 @@
+import { baselineMatcher } from "../scanner/identity.js";
+/** Existing means an exact, unambiguous observation in complete matching captures. */
+export function existingLayout(current, baseline, problem) {
+    if (!baseline || current.truncated || baseline.truncated)
+        return false;
+    const sameKind = (s, selector) => s.layout.filter((p) => p.selector === selector && p.kind === problem.kind);
+    if (sameKind(current, problem.selector).length !== 1)
+        return false;
+    let selector;
+    if (problem.selector === "html" && problem.kind === "overflow") {
+        selector = "html";
+    }
+    else {
+        const elements = current.elements.filter((e) => e.selector === problem.selector);
+        if (elements.length !== 1)
+            return false;
+        const element = elements[0];
+        if (element.identity &&
+            current.elements.filter((e) => e.identity === element.identity).length !==
+                1)
+            return false;
+        const prior = baselineMatcher(baseline.elements)(element);
+        if (!prior ||
+            prior.tag !== element.tag ||
+            baseline.elements.filter((e) => e.selector === prior.selector).length !==
+                1)
+            return false;
+        // The same rounded overflow amount alone cannot establish unchanged geometry.
+        if (!element.bounds ||
+            !prior.bounds ||
+            element.bounds.width <= 0 ||
+            element.bounds.height <= 0 ||
+            !["x", "y", "width", "height"].every((key) => Number.isFinite(element.bounds[key]) &&
+                element.bounds[key] === prior.bounds[key]))
+            return false;
+        selector = prior.selector;
+    }
+    const previous = sameKind(baseline, selector);
+    return (previous.length === 1 &&
+        previous[0].value === problem.value &&
+        previous[0].severity === problem.severity);
+}

package/dist/scanner/collect.d.ts

@@ -1,10 +1,11 @@
 import type { CollectedElement } from "./identity.js";
 import type { LayoutProblem, ScopeDefinition } from "../types.js";
 /** Pure DOM reader, serialized by Playwright into the page. */
-export declare function collect({ maxElements, ignore, scopes, }: {
+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, scopes = [], }) {
+export function collect({ maxElements, ignore, scopes = [], sensitiveSelectors = [], }) {
     for (const selector of ignore) {
         try {
             document.querySelector(selector);
@@ -8,6 +8,16 @@ export function collect({ maxElements, ignore, scopes = [], }) {
             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 [
@@ -79,6 +89,8 @@ export function collect({ maxElements, ignore, scopes = [], }) {
             .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");
@@ -211,9 +223,9 @@ export function collect({ maxElements, ignore, scopes = [], }) {
             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,90 +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,
-                    scopes: config.scopes,
-                });
-                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[];
@@ -66,6 +78,7 @@ export interface Bounds {
     height: number;
 }
 export interface Evidence {
+    state?: string;
     viewport: Viewport;
     current: {
         screenshot: string;
@@ -92,6 +105,8 @@ export interface LayoutProblem {
     severity: Severity;
 }
 export interface Snapshot {
+    state?: string;
+    colorScheme?: "light" | "dark";
     route: string;
     viewport: Viewport;
     elements: ElementRecord[];
@@ -117,7 +132,50 @@ export type Contract = {
     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 {
+    baselineStatus?: "existing" | "new-or-changed";
+    state?: string;
+    approval?: {
+        id: string;
+        reason: string;
+    };
     rule?: RuleProvenance;
     identity?: string;
     identityConfidence?: IdentityConfidence;
@@ -134,7 +192,9 @@ export interface Issue {
     viewports: string[];
 }
 export interface Report {
-    version: 1;
+    failOn?: "all" | "new";
+    version: 1 | 2;
+    approvals?: ApprovalSummary;
     baselineAt: string;
     scan: Scan;
     contract: Contract;

package/dist/utils/config.js

@@ -1,6 +1,7 @@
 import { validateScopes } from "../contract/scopes.js";
 import { access } from "node:fs/promises";
-import { resolve } from "node:path";
+import { validateScenarios, safeUrl } from "./scenarios.js";
+import { resolve, dirname, sep } from "node:path";
 import { createJiti } from "jiti";
 export const defaults = {
     url: "http://localhost:3000",
@@ -36,7 +37,9 @@ export async function loadConfig(cwd, url, file) {
         throw new Error("Configuration must export an object.");
     const config = { ...defaults, ...input, ...(url ? { url } : {}) };
     try {
-        if (!["http:", "https:"].includes(new URL(config.url).protocol))
+        if (!["http:", "https:"].includes(new URL(config.url).protocol) ||
+            new URL(config.url).username ||
+            new URL(config.url).password)
             throw 0;
     }
     catch {
@@ -76,6 +79,16 @@ export async function loadConfig(cwd, url, file) {
     if (config.scopes !== undefined)
         config.scopes = validateScopes(config.scopes);
     config.routes = [...new Set(config.routes)];
+    validateScenarios(config);
+    if (config.storageState) {
+        config.storageState = resolve(dirname(path), config.storageState);
+        if (config.storageState.startsWith(resolve(cwd, ".tether") + sep))
+            throw new Error("Keep storageState outside .tether; use an ignored .auth directory.");
+        if (config.routes.some((r) => !config.scenarios?.some((s) => s.routes.includes(r))))
+            throw new Error("Every authenticated route needs a scenario with an explicit ready assertion.");
+    }
+    if (new Set(config.routes.map((r) => safeUrl(r))).size !== config.routes.length)
+        throw new Error("Routes must remain distinct after query-value redaction; use named scenarios for variants.");
     return config;
 }
 export function targetUrl(base, route) {

package/dist/utils/coverage.d.ts

@@ -0,0 +1,3 @@
+import type { Config, Contract, Scan } from "../types.js";
+export declare function coverage(scan: Pick<Scan, "snapshots">): string[];
+export declare function validateCoverage(config: Config, contract: Contract, baseline: Scan): void;