tether-ui 0.1.0 → 0.3.0

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,4 +1,7 @@
+import { resolveRule } from "../contract/scopes.js";
 import { createHash } from "node:crypto";
+import { baselineMatcher } from "../scanner/identity.js";
+import { findingEvidence } from "./evidence.js";
 import { colorDistance } from "../utils/normalize.js";
 export const labels = {
     colors: "Unexpected color",
@@ -41,27 +44,23 @@ function equivalent(category, a, b) {
 }
 export function compare(contract, baseline, current) {
     const issues = new Map();
-    const exceptions = new Map();
-    for (const s of baseline.snapshots)
-        for (const e of s.elements)
-            for (const o of e.observations) {
-                const key = `${s.route}\0${s.viewport.name}\0${e.selector}\0${o.property}\0${o.category}`;
-                const values = exceptions.get(key) ?? new Set();
-                values.add(o.value);
-                exceptions.set(key, values);
-            }
     function push(issue, viewport) {
         const key = [
             issue.category,
             issue.route,
-            issue.selector,
+            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))
                 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}`;
         }
@@ -73,26 +72,46 @@ export function compare(contract, baseline, current) {
             });
     }
     for (const snapshot of current.snapshots) {
-        for (const element of snapshot.elements)
+        const previousSnapshot = baseline.snapshots.find((s) => s.route === snapshot.route &&
+            s.viewport.name === snapshot.viewport.name &&
+            s.viewport.width === snapshot.viewport.width &&
+            s.viewport.height === snapshot.viewport.height);
+        const match = baselineMatcher(previousSnapshot?.elements ?? []);
+        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;
-                const prior = exceptions.get(`${snapshot.route}\0${snapshot.viewport.name}\0${element.selector}\0${o.property}\0${o.category}`);
-                if (prior && [...prior].some((v) => equivalent(o.category, v, 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],
                     selector: element.selector,
+                    identity: element.identity ?? `selector:${element.selector}`,
+                    identityConfidence: element.identityConfidence ?? "low",
+                    evidence: [
+                        findingEvidence(snapshot, previousSnapshot, element, prior),
+                    ],
                     property: o.property,
                     current: o.value,
                     expected,
                     route: snapshot.route,
                 }, snapshot.viewport.name);
             }
-        for (const problem of snapshot.layout)
+        }
+        for (const problem of snapshot.layout) {
+            const element = snapshot.elements.find((e) => e.selector === problem.selector);
             push({
                 category: "layout",
                 severity: problem.severity,
@@ -102,18 +121,33 @@ export function compare(contract, baseline, current) {
                         ? "Clipped content"
                         : "Element outside viewport",
                 selector: problem.selector,
+                identity: element?.identity ?? `selector:${problem.selector}`,
+                identityConfidence: element?.identityConfidence ?? "low",
+                evidence: [
+                    findingEvidence(snapshot, previousSnapshot, element, element ? match(element) : undefined),
+                ],
                 property: problem.kind,
                 current: problem.value,
                 expected: ["Content fits within the viewport"],
                 route: snapshot.route,
             }, snapshot.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.selector.localeCompare(b.selector) ||
-        a.current.localeCompare(b.current));
+        (a.identity ?? a.selector).localeCompare(b.identity ?? b.selector) ||
+        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/drift/evidence.d.ts

@@ -0,0 +1,4 @@
+import type { Bounds, ElementRecord, Evidence, Snapshot, Viewport } from "../types.js";
+/** Keep only the visible part; below-fold, invalid and absent bounds have no overlay. */
+export declare function visibleBounds(bounds: Bounds | undefined, viewport: Viewport): Bounds | undefined;
+export declare function findingEvidence(current: Snapshot, baseline?: Snapshot, element?: ElementRecord, prior?: ElementRecord): Evidence;

package/dist/drift/evidence.js

@@ -0,0 +1,41 @@
+/** Keep only the visible part; below-fold, invalid and absent bounds have no overlay. */
+export function visibleBounds(bounds, viewport) {
+    if (!bounds ||
+        ![
+            bounds.x,
+            bounds.y,
+            bounds.width,
+            bounds.height,
+            viewport.width,
+            viewport.height,
+        ].every(Number.isFinite) ||
+        bounds.width <= 0 ||
+        bounds.height <= 0 ||
+        viewport.width <= 0 ||
+        viewport.height <= 0)
+        return;
+    const x = Math.max(0, bounds.x), y = Math.max(0, bounds.y);
+    const right = Math.min(viewport.width, bounds.x + bounds.width);
+    const bottom = Math.min(viewport.height, bounds.y + bounds.height);
+    if (right <= x || bottom <= y)
+        return;
+    return { x, y, width: right - x, height: bottom - y };
+}
+export function findingEvidence(current, baseline, element, prior) {
+    return {
+        viewport: current.viewport,
+        current: {
+            screenshot: current.screenshot,
+            ...(element?.bounds ? { bounds: element.bounds } : {}),
+        },
+        // A baseline capture is useful even when no exact element match is available.
+        ...(baseline
+            ? {
+                baseline: {
+                    screenshot: baseline.screenshot,
+                    ...(prior?.bounds ? { bounds: prior.bounds } : {}),
+                },
+            }
+            : {}),
+    };
+}

package/dist/scanner/collect.d.ts

@@ -1,10 +1,12 @@
-import type { ElementRecord, LayoutProblem } from "../types.js";
+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, }: {
+export declare function collect({ maxElements, ignore, scopes, }: {
     maxElements: number;
     ignore: string[];
+    scopes?: ScopeDefinition[];
 }): {
-    elements: ElementRecord[];
+    elements: CollectedElement[];
     layout: LayoutProblem[];
     truncated: boolean;
 };

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))
@@ -48,6 +91,9 @@ export function collect({ maxElements, ignore, }) {
         for (const name of classes)
             if (document.querySelectorAll(`.${escapeCss(name)}`).length === 1)
                 return `.${escapeCss(name)}`;
+        return structureFor(el);
+    }
+    function structureFor(el) {
         const parts = [];
         let node = el;
         while (node && node !== document.body) {
@@ -140,7 +186,37 @@ export function collect({ maxElements, ignore, }) {
         add("shadows", "box-shadow");
         if (control)
             add("elementHeights", "height", `${rect.height}px`);
-        elements.push({ selector, tag: el.tagName.toLowerCase(), observations });
+        const attributes = Object.fromEntries([
+            "id",
+            "data-testid",
+            "data-test",
+            "data-cy",
+            "role",
+            "aria-label",
+            "name",
+            "alt",
+            "href",
+        ].map((name) => [name, el.getAttribute(name) ?? ""]));
+        const labelledBy = el.getAttribute("aria-labelledby");
+        if (labelledBy)
+            attributes["aria-label"] = labelledBy
+                .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],
+                structure: structureFor(el),
+            },
+        });
         const outside = Math.max(0, rect.right - innerWidth, -rect.left);
         if (outside > 4 &&
             !scrollContainer(el) &&

package/dist/scanner/identity.d.ts

@@ -0,0 +1,15 @@
+import type { ElementRecord, IdentityConfidence } from "../types.js";
+export interface IdentitySignals {
+    attributes: Record<string, string>;
+    text: string;
+    classes: string[];
+    structure?: string;
+}
+export type CollectedElement = ElementRecord & {
+    signals: IdentitySignals;
+};
+export declare function identityCandidates(element: CollectedElement): [string, IdentityConfidence][];
+/** Only unique signals identify an element; ambiguous matches use the selector. */
+export declare function assignIdentities(elements: CollectedElement[]): ElementRecord[];
+/** No selector rescue when two new records have different semantic identities. */
+export declare function baselineMatcher(elements: ElementRecord[]): (current: ElementRecord) => ElementRecord | undefined;

package/dist/scanner/identity.js

@@ -0,0 +1,86 @@
+const concise = (value) => {
+    const text = value.replace(/\s+/g, " ").trim();
+    return text.length <= 80 ? text : "";
+};
+// Obvious counters, framework IDs and CSS module hashes are not semantic anchors.
+const stable = (value) => !!value &&
+    value.length <= 80 &&
+    !/\d{3,}|[a-f\d]{8,}|(^|[-_:])(css|sc|radix|react|uid)[-_:]|__|:[rR]|[a-z][A-Z0-9]{5,}/.test(value);
+export function identityCandidates(element) {
+    const { attributes: a, classes, text } = element.signals;
+    const result = [];
+    const add = (kind, value, confidence) => {
+        if (value)
+            result.push([JSON.stringify([kind, value]), confidence]);
+    };
+    if (stable(a.id ?? ""))
+        add("id", a.id, "high");
+    for (const attr of ["data-testid", "data-test", "data-cy"])
+        if (stable(a[attr] ?? ""))
+            add(attr, a[attr], "high");
+    const role = a.role ||
+        {
+            button: "button",
+            a: "link",
+            input: "input",
+            select: "select",
+            textarea: "textbox",
+            img: "img",
+        }[element.tag] ||
+        element.tag;
+    for (const attr of ["aria-label", "name", "alt"])
+        add(`${role}:${attr}`, concise(a[attr] ?? ""), "medium");
+    if (element.tag === "a" && a.href && !/[?#]/.test(a.href))
+        add("link:href", concise(a.href), "medium");
+    if (/^(button|a|label|h[1-6]|option)$/.test(element.tag)) {
+        const label = concise(text);
+        if (!/\d/.test(label))
+            add(`${role}:text`, label, "medium");
+    }
+    for (const name of [...classes].sort())
+        if (stable(name) && /^[a-zA-Z][\w-]*$/.test(name))
+            add(`${element.tag}:class`, name, "medium");
+    return result;
+}
+/** Only unique signals identify an element; ambiguous matches use the selector. */
+export function assignIdentities(elements) {
+    const candidates = elements.map(identityCandidates);
+    const counts = new Map();
+    for (const list of candidates)
+        for (const key of new Set(list.map(([key]) => key)))
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+    return elements.map(({ signals: _signals, ...element }, index) => {
+        const unique = candidates[index].find(([key]) => counts.get(key) === 1);
+        return {
+            ...element,
+            identity: unique?.[0] ?? `structure:${_signals.structure ?? element.selector}`,
+            identityConfidence: unique?.[1] ?? "low",
+        };
+    });
+}
+/** No selector rescue when two new records have different semantic identities. */
+export function baselineMatcher(elements) {
+    const identities = new Map();
+    const selectors = new Map();
+    for (const element of elements) {
+        if (element.identity)
+            identities.set(element.identity, [
+                ...(identities.get(element.identity) ?? []),
+                element,
+            ]);
+        selectors.set(element.selector, [
+            ...(selectors.get(element.selector) ?? []),
+            element,
+        ]);
+    }
+    return (current) => {
+        const semantic = current.identity
+            ? identities.get(current.identity)
+            : undefined;
+        if (semantic?.length === 1)
+            return semantic[0];
+        const fallback = selectors.get(current.selector);
+        if (fallback?.length === 1 && (!current.identity || !fallback[0].identity))
+            return fallback[0];
+    };
+}

package/dist/scanner/scan.js

@@ -1,4 +1,5 @@
 import { openBrowser } from "./browser.js";
+import { assignIdentities } from "./identity.js";
 import { collect } from "./collect.js";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
@@ -47,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.`);
@@ -71,7 +73,13 @@ export async function scan(config, directory, phase) {
                     fullPage: false,
                     animations: "disabled",
                 });
-                result.snapshots.push({ route, viewport, ...collected, screenshot });
+                result.snapshots.push({
+                    route,
+                    viewport,
+                    ...collected,
+                    elements: assignIdentities(collected.elements),
+                    screenshot,
+                });
                 await context.close();
             }
         return result;

package/dist/types.d.ts

@@ -14,13 +14,73 @@ 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;
     property: string;
     value: string;
 }
+export type IdentityConfidence = "high" | "medium" | "low";
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Evidence {
+    viewport: Viewport;
+    current: {
+        screenshot: string;
+        bounds?: Bounds;
+    };
+    baseline?: {
+        screenshot: string;
+        bounds?: Bounds;
+    };
+}
 export interface ElementRecord {
+    scope?: ScopeMembership;
+    identity?: string;
+    identityConfidence?: IdentityConfidence;
+    bounds?: Bounds;
     selector: string;
     tag: string;
     observations: Observation[];
@@ -50,11 +110,18 @@ 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 Issue {
+    rule?: RuleProvenance;
+    identity?: string;
+    identityConfidence?: IdentityConfidence;
+    evidence?: Evidence[];
     id: string;
     category: Category | "layout";
     severity: Severity;