tether-ui 0.2.0 → 0.3.0

package/README.md

@@ -162,6 +162,47 @@ Add intentional values to `contract.json` to accept them globally, or use `tethe
 
 For environments that cannot launch Chromium, `TETHER_BROWSER_ENDPOINT=http://127.0.0.1:9333` connects to a dedicated CDP browser instead. Use an isolated profile, not your everyday browser. tether creates and closes its own contexts and disconnects after each scan. Standard installations need no endpoint setting.
 
+## Component-aware contracts
+
+Global inference remains the default. Opt in to named scopes when component variants need different rules:
+
+```ts
+export default {
+  url: 'http://localhost:3000',
+  scopes: [
+    {
+      name: 'primary-button',
+      variant: 'primary',
+      selector: '[data-component="button"][data-variant="primary"]',
+      minOccurrences: 2,
+      parts: { label: '[data-part="label"]' }
+    },
+    {
+      name: 'card',
+      selector: '.card',
+      parts: { title: '.card-title' },
+      overrides: [
+        { part: 'title', category: 'fontSizes', property: 'font-size', values: ['24px'] }
+      ]
+    }
+  ]
+};
+```
+
+Run `npx tether-ui init --force` after intentionally adding or changing scopes. This replaces the baseline, so review the current UI first. Scope configuration is saved in the contract; subsequent checks reject configuration changes instead of silently changing the rules. Component-aware contracts are available in tether-ui v0.3.0 and later.
+
+- **Membership:** the nearest matching component root wins. Within it, the nearest matching named part wins; a part applies to its descendants until a nested component starts. The root uses the reserved `root` part. Unnamed descendants use global tokens, rather than inheriting container padding and radius rules. Two scopes matching the same root, or two parts matching the same node, are errors. Selectors are explicit; generated class names do not identify component families automatically.
+- **Support:** each scope/category/property/value counts distinct component instances per route. Multiple parts or viewport captures of one instance do not inflate its count. The scope threshold defaults to the global threshold with a minimum of two; configure `minOccurrences` per scope for smaller families. Multiple responsive values can qualify independently. Singleton conventions are never automatically promoted.
+- **Precedence:** a supported scoped rule wins over the global pool. Missing or undersampled rules fall back to global tokens. Partial baselines disable inferred scoped rules, with the reason exposed in findings. Unchanged one-offs remain accepted only on the same matched element, property, and scope/part; they do not transfer to new instances or another component context.
+- **Overrides:** explicit values are normalized and apply only to their scope, part, category, and property. They override inferred values and the unchanged-value exemption, so an intentional correction can expose a baseline inconsistency. Overrides can apply without samples; they are reviewed policy, not learned confidence. Existing layout checks remain independent.
+- **Compatibility:** unscoped projects continue writing v1 contracts and retain their finding IDs and JSON behavior. Scoped projects write v2 contracts. New clients read both; old clients reject v2. Checks never migrate or rewrite baseline/contract files. Reports, agent output, and JSON explain the rule source, support counts, and fallback. The visual contract view includes component rules.
+
+### Accuracy benchmark
+
+Run `npm run benchmark` from the development checkout. The [frozen corpus](tests/fixtures/scoped-benchmark.json) compares the legacy and scoped policies on 16 labeled scenarios across buttons, cards, status colors, and badges. Output includes TP/FP/FN/TN, precision, and recall per family and overall. Color/type families are reserved as held-out checks; no per-family thresholds are tuned.
+
+Both policies use a global threshold of three. The scoped policy explicitly uses two independent component instances; this additional configuration is why legitimate new instances stop being false positives. Merely narrowing the global token pool cannot produce that improvement. On this synthetic corpus, false positives fall from 4 to 0 and detected drift rises from 4/8 to 8/8. [Raw results and benchmark limits](docs/scoped-benchmark.md) describe what these numbers establish; they are not an accuracy claim for arbitrary applications.
+
 ## CI
 
 The frontend **must already be running**. Commit reviewed `contract.json` and `baseline.json` to compare against the same contract on every pull request. Recreate the baseline on the same OS/browser/font environment as CI to avoid platform differences. Include its referenced baseline screenshots if you want baseline images in CI reports; comparison still works when those PNGs are absent.

package/dist/cli/format.js

@@ -1,3 +1,4 @@
+import { ruleDescription } from "../contract/describe.js";
 const code = (value) => "`" + value.replace(/`/g, "\\`").replace(/[\r\n]/g, " ") + "`";
 export function agentMarkdown(issues) {
     const intro = "# tether visual linting\n\n" +
@@ -6,7 +7,7 @@ export function agentMarkdown(issues) {
             : "No visual-system deviations detected.\n");
     return (intro +
         issues
-            .map((i, n) => `\n## ${n + 1}. ${i.title}\n\n- Severity: ${i.severity}\n- Selector: ${code(i.selector)}\n- Property: ${code(i.property)}\n- Current: ${code(i.current)}\n- Expected values: ${i.expected.length ? i.expected.map(code).join(", ") : "No established token; review against the baseline."}\n- Route: ${code(i.route)}\n- Viewports: ${i.viewports.map(code).join(", ")}\n`)
+            .map((i, n) => `\n## ${n + 1}. ${i.title}\n\n- Severity: ${i.severity}\n- Selector: ${code(i.selector)}\n- Property: ${code(i.property)}\n- Current: ${code(i.current)}\n- Expected values: ${i.expected.length ? i.expected.map(code).join(", ") : "No established token; review against the baseline."}\n${i.rule ? `- Rule: ${code(ruleDescription(i.rule))}\n` : ""}- Route: ${code(i.route)}\n- Viewports: ${i.viewports.map(code).join(", ")}\n`)
             .join("\n---\n"));
 }
 export function terminalReport(report, color = !!process.stdout.isTTY) {
@@ -24,7 +25,7 @@ export function terminalReport(report, color = !!process.stdout.isTTY) {
             : "No visual drift detected"),
     ];
     for (const issue of report.issues)
-        lines.push("", `${issue.severity.toUpperCase()}  ${issue.title}`, `  ${issue.current}`, dim(`  Expected: ${issue.expected.join(" · ") || "No established token"}`), `  ${issue.selector}`, dim(`  ${issue.route} · ${issue.viewports.join(", ")} · ${issue.property}`));
+        lines.push("", `${issue.severity.toUpperCase()}  ${issue.title}`, `  ${issue.current}`, dim(`  Expected: ${issue.expected.join(" · ") || "No established token"}`), ...(issue.rule ? [dim(`  Rule: ${ruleDescription(issue.rule)}`)] : []), `  ${issue.selector}`, dim(`  ${issue.route} · ${issue.viewports.join(", ")} · ${issue.property}`));
     lines.push("", `${report.issues.length} deviations found.`, dim("Run: tether report"), "");
     return lines.join("\n");
 }

package/dist/cli/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { readContract } from "../contract/read.js";
+import { validateScopes } from "../contract/scopes.js";
 import { Command } from "commander";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -16,7 +18,7 @@ import { categories, } from "../types.js";
 const program = new Command()
     .name("tether")
     .description("Visual linting for AI-coded interfaces.")
-    .version("0.2.0");
+    .version("0.3.0");
 program.option("--cwd <directory>", "Project directory", process.cwd());
 const cwd = () => resolve(program.opts().cwd);
 const directory = () => join(cwd(), ".tether");
@@ -65,7 +67,7 @@ program
     const config = await loadConfig(cwd(), options.url, options.config);
     console.log(`\ntether\n\nScanning ${config.url}…`);
     const baseline = await scan(config, directory(), `baseline-${randomUUID().slice(0, 8)}`);
-    const contract = inferContract(baseline, config.minOccurrences);
+    const contract = inferContract(baseline, config.minOccurrences, config.scopes);
     // Save the exact scan configuration in the baseline so subsequent checks match it.
     await writeJson(join(directory(), "contract.json"), contract);
     await writeJson(join(directory(), "baseline.json"), {
@@ -78,7 +80,7 @@ program
         await writeFile(join(cwd(), "tether.config.ts"), `export default ${JSON.stringify(config, null, 2)};\n`);
     console.log(`\n✓ Baseline saved\n✓ ${categories.reduce((n, c) => n + contract[c].length, 0)} tokens in your visual contract\n✓ ${report.elementCount} elements inspected across ${baseline.snapshots.length} snapshots\n\nRun: tether check\n`);
     if (report.issues.length)
-        console.log(`Note: ${report.issues.length} existing layout problems are visible in tether report.`);
+        console.log(`Note: ${report.issues.length} existing visual deviations are visible in tether report.`);
     warnTruncated(report);
 });
 program
@@ -94,10 +96,10 @@ program
     if (!(await exists(join(directory(), "baseline.json"))))
         throw new Error("No baseline found. Run tether init first.");
     const baseline = await readJson(join(directory(), "baseline.json"));
-    const contract = await readJson(join(directory(), "contract.json"));
+    const contract = readContract(await readJson(join(directory(), "contract.json")));
     if (baseline.version !== 1 ||
         !Array.isArray(baseline.snapshots) ||
-        contract.version !== 1 ||
+        ![1, 2].includes(contract.version) ||
         categories.some((c) => !Array.isArray(contract[c]) ||
             contract[c].some((t) => typeof t.value !== "string")))
         throw new Error("Unsupported or invalid baseline / contract. Run tether init --force to recreate it.");
@@ -106,6 +108,9 @@ program
         !options.config &&
         !(await exists(join(cwd(), "tether.config.ts"))))
         config.url = baseline.url;
+    if (JSON.stringify(validateScopes(config.scopes ?? [])) !==
+        JSON.stringify(validateScopes(contract.scopes ?? [])))
+        throw new Error("Component scopes or overrides changed since the baseline. Run tether init --force to establish the new contract.");
     const coverage = (s) => `${s.route}|${s.viewport.name}|${s.viewport.width}|${s.viewport.height}`;
     const baselineCoverage = new Set(baseline.snapshots.map(coverage));
     const requested = config.routes.flatMap((route) => config.viewports.map((viewport) => coverage({ route, viewport })));

package/dist/cli/json.d.ts

@@ -13,7 +13,6 @@ export declare function jsonReport(report: Report, baseline: Scan): {
         };
     };
     findings: {
-        id: string;
         identity: string;
         identityConfidence: import("../types.js").IdentityConfidence;
         selector: string;
@@ -36,5 +35,7 @@ export declare function jsonReport(report: Report, baseline: Scan): {
                 screenshotRef: string | null;
             };
         }[];
+        rule?: import("../types.js").RuleProvenance | undefined;
+        id: string;
     }[];
 };

package/dist/cli/json.js

@@ -25,6 +25,7 @@ export function jsonReport(report, baseline) {
         },
         findings: report.issues.map((i) => ({
             id: i.id,
+            ...(i.rule ? { rule: i.rule } : {}),
             identity: i.identity ?? `selector:${i.selector}`,
             identityConfidence: i.identityConfidence ?? "low",
             selector: i.selector,

package/dist/contract/describe.d.ts

@@ -0,0 +1,2 @@
+import type { RuleProvenance } from "../types.js";
+export declare function ruleDescription(rule: RuleProvenance): string;

package/dist/contract/describe.js

@@ -0,0 +1,6 @@
+export function ruleDescription(rule) {
+    const context = rule.scope
+        ? `${rule.scope}${rule.variant ? ` (${rule.variant})` : ""}/${rule.part}`
+        : "unscoped";
+    return `${rule.source} · ${context}${rule.reason ? ` · ${rule.reason}` : ""} · ${rule.samples} component instances · tokens: ${rule.tokens.map((t) => `${t.value} (${t.count})`).join(", ") || "none"}`;
+}

package/dist/contract/infer.d.ts

@@ -1,2 +1,2 @@
-import { type Contract, type Scan } from "../types.js";
-export declare function inferContract(scan: Scan, minOccurrences?: number): Contract;
+import { type Contract, type Scan, type ScopeDefinition } from "../types.js";
+export declare function inferContract(scan: Scan, minOccurrences?: number, scopes?: ScopeDefinition[]): Contract;

package/dist/contract/infer.js

@@ -1,5 +1,6 @@
-import { categories } from "../types.js";
-export function inferContract(scan, minOccurrences = 2) {
+import { validateScopes } from "./scopes.js";
+import { categories, } from "../types.js";
+export function inferContract(scan, minOccurrences = 2, scopes = []) {
     const contract = {
         version: 1,
         createdAt: scan.createdAt,
@@ -23,5 +24,71 @@ export function inferContract(scan, minOccurrences = 2) {
         // A small page still gets one representative token per observed category.
         contract[category] = recurring.length ? recurring : ranked.slice(0, 1);
     }
+    if (scopes.length) {
+        const definitions = validateScopes(scopes);
+        contract.version = 2;
+        contract.scopes = definitions;
+        contract.partial = scan.snapshots.some((s) => s.truncated);
+        const rules = new Map();
+        const key = (scope, part, category, property) => JSON.stringify([scope, part, category, property]);
+        for (const snapshot of scan.snapshots)
+            for (const element of snapshot.elements) {
+                const scope = element.scope;
+                if (!scope || !definitions.some((d) => d.name === scope.name))
+                    continue;
+                const instance = JSON.stringify([snapshot.route, scope.instance]);
+                for (const o of element.observations) {
+                    const k = key(scope.name, scope.part, o.category, o.property);
+                    const entry = rules.get(k) ?? {
+                        rule: {
+                            scope: scope.name,
+                            part: scope.part,
+                            category: o.category,
+                            property: o.property,
+                            samples: 0,
+                            tokens: [],
+                            source: "scope",
+                        },
+                        samples: new Set(),
+                        values: new Map(),
+                    };
+                    entry.samples.add(instance);
+                    const values = entry.values.get(o.value) ?? new Set();
+                    values.add(instance);
+                    entry.values.set(o.value, values);
+                    rules.set(k, entry);
+                }
+            }
+        for (const scope of definitions)
+            for (const override of scope.overrides ?? []) {
+                const k = key(scope.name, override.part ?? "root", override.category, override.property);
+                const old = rules.get(k);
+                rules.set(k, {
+                    rule: {
+                        scope: scope.name,
+                        part: override.part ?? "root",
+                        category: override.category,
+                        property: override.property,
+                        samples: 0,
+                        tokens: [],
+                        source: "override",
+                    },
+                    samples: old?.samples ?? new Set(),
+                    values: new Map(override.values.map((v) => [
+                        v,
+                        old?.values.get(v) ?? new Set(),
+                    ])),
+                });
+            }
+        contract.rules = [...rules.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([, entry]) => ({
+            ...entry.rule,
+            samples: entry.samples.size,
+            tokens: [...entry.values]
+                .map(([value, instances]) => ({ value, count: instances.size }))
+                .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value)),
+        }));
+    }
     return contract;
 }

package/dist/contract/read.d.ts

@@ -0,0 +1,3 @@
+import { type Contract } from "../types.js";
+/** Validate without rewriting legacy data or changing its ordering. */
+export declare function readContract(input: unknown): Contract;

package/dist/contract/read.js

@@ -0,0 +1,67 @@
+import { categories } from "../types.js";
+import { validateScopes, validProperty } from "./scopes.js";
+/** Validate without rewriting legacy data or changing its ordering. */
+export function readContract(input) {
+    const c = input;
+    const fail = () => {
+        throw new Error("Unsupported or invalid contract. Supported versions: 1 (global), 2 (scoped). Restore a valid contract or run tether init --force.");
+    };
+    const tokens = (t) => Array.isArray(t) &&
+        t.every((v) => v &&
+            typeof v.value === "string" &&
+            Number.isInteger(v.count) &&
+            v.count >= 0);
+    if (!c ||
+        ![1, 2].includes(c.version) ||
+        !Number.isInteger(c.minOccurrences) ||
+        c.minOccurrences < 1 ||
+        c.minOccurrences > 1000 ||
+        categories.some((k) => !tokens(c[k])))
+        fail();
+    if (c.version === 2) {
+        const scopes = validateScopes(c.scopes);
+        if (!scopes.length ||
+            !Array.isArray(c.rules) ||
+            typeof c.partial !== "boolean")
+            fail();
+        const keys = new Set();
+        for (const rule of c.rules) {
+            if (!rule || typeof rule !== "object")
+                fail();
+            const scope = scopes.find((s) => s.name === rule.scope);
+            if (!scope ||
+                (rule.part !== "root" &&
+                    !Object.hasOwn(scope.parts ?? {}, rule.part)) ||
+                !categories.includes(rule.category) ||
+                !validProperty(rule.category, rule.property) ||
+                !["scope", "override"].includes(rule.source) ||
+                !Number.isInteger(rule.samples) ||
+                rule.samples < 0 ||
+                !tokens(rule.tokens) ||
+                rule.tokens.some((t) => t.count > rule.samples))
+                fail();
+            const key = JSON.stringify([
+                rule.scope,
+                rule.part,
+                rule.category,
+                rule.property,
+            ]);
+            if (keys.has(key))
+                fail();
+            keys.add(key);
+            const override = scope.overrides?.find((o) => o.part === rule.part &&
+                o.category === rule.category &&
+                o.property === rule.property);
+            if ((rule.source === "override") !== !!override ||
+                (override &&
+                    JSON.stringify([...override.values].sort()) !==
+                        JSON.stringify(rule.tokens.map((t) => t.value).sort())))
+                fail();
+        }
+        for (const scope of scopes)
+            for (const o of scope.overrides ?? [])
+                if (!keys.has(JSON.stringify([scope.name, o.part, o.category, o.property])))
+                    fail();
+    }
+    return c;
+}

package/dist/contract/scopes.d.ts

@@ -0,0 +1,5 @@
+import { type ScopeDefinition, type Contract, type ElementRecord, type Observation, type RuleProvenance } from "../types.js";
+export declare function validProperty(category: string, property: unknown): property is string;
+/** Canonical, serializable declarations. CSS syntax is checked in the browser. */
+export declare function validateScopes(input: unknown): ScopeDefinition[];
+export declare function resolveRule(contract: Contract, element: ElementRecord, observation: Observation): RuleProvenance | undefined;

package/dist/contract/scopes.js

@@ -0,0 +1,150 @@
+import { categories, } from "../types.js";
+import { normalizeValue } from "../utils/normalize.js";
+const name = (s) => typeof s === "string" && /^[a-zA-Z][\w-]{0,63}$/.test(s);
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const selector = (v) => typeof v === "string" && !!v.trim();
+export function validProperty(category, property) {
+    if (typeof property !== "string")
+        return false;
+    const properties = {
+        colors: /^(color|background-color|border-color)$/,
+        fontFamilies: /^font-family$/,
+        fontSizes: /^font-size$/,
+        fontWeights: /^font-weight$/,
+        lineHeights: /^line-height$/,
+        spacing: /^(padding|margin)-(top|right|bottom|left)$|^(row|column)-gap$/,
+        radii: /^border-radius$/,
+        shadows: /^box-shadow$/,
+        borders: /^border$/,
+        elementHeights: /^height$/,
+    };
+    return !!properties[category]?.test(property);
+}
+/** Canonical, serializable declarations. CSS syntax is checked in the browser. */
+export function validateScopes(input) {
+    if (!Array.isArray(input))
+        throw new Error("Config scopes must be an array.");
+    const names = new Set();
+    const selectors = new Set();
+    const result = [];
+    for (const s of input) {
+        if (!object(s) ||
+            !name(s.name) ||
+            !selector(s.selector) ||
+            names.has(s.name) ||
+            selectors.has(s.selector.trim()))
+            throw new Error("Scopes need unique names and distinct, nonempty CSS selectors.");
+        if (Object.keys(s).some((k) => ![
+            "name",
+            "selector",
+            "variant",
+            "minOccurrences",
+            "parts",
+            "overrides",
+        ].includes(k)))
+            throw new Error(`Unknown setting in scope ${s.name}.`);
+        if (s.variant !== undefined && !name(s.variant))
+            throw new Error(`Invalid variant for scope ${s.name}.`);
+        if (s.minOccurrences !== undefined &&
+            (!Number.isInteger(s.minOccurrences) ||
+                Number(s.minOccurrences) < 2 ||
+                Number(s.minOccurrences) > 1000))
+            throw new Error(`Scope ${s.name} minOccurrences must be between 2 and 1000; use an explicit override for a singleton.`);
+        if (s.parts !== undefined &&
+            (!object(s.parts) ||
+                Object.entries(s.parts).some(([k, v]) => !name(k) || k === "root" || !selector(v))))
+            throw new Error(`Scope ${s.name} parts need names (other than root) and CSS selectors.`);
+        const parts = Object.fromEntries(Object.entries(s.parts ?? {}).sort(([a], [b]) => a.localeCompare(b)));
+        if (new Set(Object.values(parts).map((v) => v.trim())).size !==
+            Object.keys(parts).length)
+            throw new Error(`Duplicate part selectors in ${s.name}.`);
+        if (s.overrides !== undefined && !Array.isArray(s.overrides))
+            throw new Error(`Scope ${s.name} overrides must be an array.`);
+        const keys = new Set();
+        const overrides = [];
+        for (const o of (s.overrides ?? [])) {
+            if (!object(o) ||
+                !categories.includes(o.category) ||
+                !validProperty(String(o.category), o.property) ||
+                !Array.isArray(o.values) ||
+                !o.values.length ||
+                o.values.some((v) => typeof v !== "string" || !v.trim()))
+                throw new Error(`Invalid property, category or values in ${s.name} override.`);
+            if (Object.keys(o).some((k) => !["part", "category", "property", "values"].includes(k)))
+                throw new Error(`Unknown override setting in ${s.name}.`);
+            const part = o.part ?? "root";
+            if (typeof part !== "string" ||
+                (part !== "root" && !Object.hasOwn(parts, part)))
+                throw new Error(`Unknown override part in ${s.name}.`);
+            const key = JSON.stringify([part, o.category, o.property]);
+            if (keys.has(key))
+                throw new Error(`Duplicate override for ${s.name}/${part}/${o.property}.`);
+            keys.add(key);
+            const values = [
+                ...new Set(o.values.map((v) => normalizeValue(o.property, v))),
+            ].sort();
+            if (values.some((v) => ["transparent", "0px", "none", "normal", "auto"].includes(v)))
+                throw new Error(`Override for ${s.name} contains a value the scanner does not collect.`);
+            overrides.push({
+                part,
+                category: o.category,
+                property: o.property,
+                values,
+            });
+        }
+        names.add(s.name);
+        selectors.add(s.selector.trim());
+        result.push({
+            name: s.name,
+            selector: s.selector.trim(),
+            ...(s.variant ? { variant: s.variant } : {}),
+            ...(s.minOccurrences !== undefined
+                ? { minOccurrences: Number(s.minOccurrences) }
+                : {}),
+            parts,
+            overrides: overrides.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+        });
+    }
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function resolveRule(contract, element, observation) {
+    if (contract.version === 1)
+        return;
+    const membership = element.scope;
+    const definition = contract.scopes?.find((s) => s.name === membership?.name);
+    const rule = contract.rules?.find((r) => r.scope === membership?.name &&
+        r.part === membership?.part &&
+        r.category === observation.category &&
+        r.property === observation.property);
+    const context = membership
+        ? {
+            scope: membership.name,
+            ...(definition?.variant ? { variant: definition.variant } : {}),
+            part: membership.part,
+        }
+        : {};
+    const threshold = definition?.minOccurrences ?? Math.max(2, contract.minOccurrences);
+    const supported = rule?.tokens.filter((t) => rule.source === "override" || t.count >= threshold) ?? [];
+    if (rule &&
+        supported.length &&
+        (rule.source === "override" || !contract.partial))
+        return {
+            ...context,
+            source: rule.source,
+            samples: rule.samples,
+            tokens: supported,
+        };
+    return {
+        ...context,
+        source: "global",
+        reason: !membership
+            ? "unscoped"
+            : contract.partial
+                ? "partial-baseline"
+                : !rule
+                    ? "missing-rule"
+                    : "insufficient-support",
+        samples: rule?.samples ?? 0,
+        tokens: contract[observation.category],
+    };
+}

package/dist/drift/compare.js

@@ -1,3 +1,4 @@
+import { resolveRule } from "../contract/scopes.js";
 import { createHash } from "node:crypto";
 import { baselineMatcher } from "../scanner/identity.js";
 import { findingEvidence } from "./evidence.js";
@@ -50,7 +51,9 @@ export function compare(contract, baseline, current) {
             issue.identity ?? issue.selector,
             issue.current,
             issue.title,
-        ].join("\0");
+        ]
+            .concat(issue.rule ? [issue.property, JSON.stringify(issue.rule)] : [])
+            .join("\0");
         const previous = issues.get(key);
         if (previous) {
             if (!previous.viewports.includes(viewport))
@@ -77,14 +80,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],
@@ -125,11 +134,20 @@ export function compare(contract, baseline, current) {
         }
     }
     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.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 consistencyScore(issues) {
     return Math.max(0, 100 -

package/dist/scanner/collect.d.ts

@@ -1,9 +1,10 @@
 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, }: {
     maxElements: number;
     ignore: string[];
+    scopes?: ScopeDefinition[];
 }): {
     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 = [], }) {
     for (const selector of ignore) {
         try {
             document.querySelector(selector);
@@ -8,6 +8,49 @@ export function collect({ maxElements, ignore, }) {
             throw new Error(`Invalid ignore selector: ${selector}`);
         }
     }
+    // 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))
@@ -160,7 +203,9 @@ 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,

package/dist/scanner/scan.js

@@ -48,6 +48,7 @@ export async function scan(config, directory, phase) {
                 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.`);