tether-ui 0.3.0 → 0.5.0

package/README.md

@@ -127,6 +127,25 @@ Defaults: **1440 × 1000**, **1024 × 900**, **768 × 900**, **390 × 844**. Eac
 
 Intentional horizontal scroll containers and descendants clipped by their parents are excluded from off-screen checks. Text ellipsis and line clamps are not treated as accidental clipping. Screenshots show the viewport; style collection also covers rendered elements below the fold, up to the configured element cap.
 
+### Separate existing layout problems from new findings
+
+**Available in tether-ui v0.5.0 and later.**
+
+Layout findings now indicate whether the same problem was recorded in the baseline. The report keeps them visible and offers a **Baseline status** filter.
+
+By default, `tether check` still fails on every active finding. To fail only on new or changed findings:
+
+```bash
+npx tether-ui check --fail-on new
+npx tether-ui check --fail-on new --json
+```
+
+This excludes only verified unchanged layout findings from the failure decision. Token findings and unverified layout findings still block. Existing layout findings are not approvals: they remain in report totals, evidence, JSON, and a separate review section of the agent brief. With `--json`, `gate.blocking` gives the blocking count and `gate.existing` gives the retained, unapproved existing-layout count. The default `--fail-on all` preserves the existing exit-code policy.
+
+Matching requires complete, unique captures with the same route, state, color scheme, and viewport name and dimensions. An element must match uniquely with the same tag, bounds, layout kind, measured value, and severity. Document overflow is compared by its exact measured value and severity. Missing or ambiguous matches, changed geometry, and partial scans remain blocking. An unchanged measurement does not establish that its underlying cause is unchanged.
+
+Layout findings carry an additive `baselineStatus` field (`existing` or `new-or-changed`); the latter includes findings that cannot be verified unchanged. JSON schema versions 1 and 2 retain their existing fields and counts. With `--fail-on new`, an additive `gate` object records the policy and counts. Existing-layout finding IDs are distinguished from new/changed occurrences so the two cannot merge across viewports. Stored approval tuples remain valid; legacy reports without baseline status remain blocking until rescanned. No rebaseline is required.
+
 ## Configuration
 
 `init` creates `tether.config.ts` when one does not exist. Config is executable local code; load only configs you trust.
@@ -192,17 +211,132 @@ export default {
 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.
+- **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. A single instance is not sufficient by default. Explicitly setting a scope’s `minOccurrences: 1` opts into trusting one reviewed instance (v0.5.0 and later; see below).
 - **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.
 
+### Reuse a reviewed component with one baseline instance
+
+**Available in tether-ui v0.5.0 and later.**
+
+A page may contain only one instance of a reusable control. By default, that one instance does not establish a component rule, so adding another can trigger findings for its rare styles. After reviewing the control, opt in for its specific role:
+
+```ts
+scopes: [
+  {
+    name: 'timer-toggle',
+    selector: 'button[aria-label="Toggle timer"]',
+    minOccurrences: 1
+  }
+]
+```
+
+This accepts another matching control using the observed property values. A changed control is checked against this scope’s values, including when its new value is valid elsewhere on the page. Keep different roles and variants in separate scopes; a broad selector would explicitly authorize sharing their values.
+
+The global threshold and other scopes are unchanged. Counts still represent independent instances: repeat states and viewports do not increase the count. Rules remain specific to scope, part, category, and property; explicit overrides take precedence. Partial baselines still disable inferred component rules. Values observed in different states or viewports are pooled within a scope, as with existing component rules; this setting does not introduce state-specific policy.
+
+Changing this threshold requires reviewing the current UI and intentionally rebaselining with `tether init --force`. The single instance is your chosen reference, not statistical evidence of a convention. Use explicit overrides when you want to specify values instead of learning them. Older tether versions reject scoped contracts configured with a threshold of one.
+
 ### 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.
 
+## REAL-WORLD BENCHMARK
+
+Across **45 labeled scenarios** on [Pomo](https://github.com/krau5/pomo), [Focus Timer](https://github.com/mvareva/focus-timer), and [Kardinal](https://github.com/Andreeoak/Kardinal), tether measured **85.7% precision, 75.0% recall, and 80.0% F1** at the scenario level. All 45 evaluated; no infrastructure failures. The corpus includes controlled source mutations and legitimate variants, with pinned revisions and exact target matching.
+
+[![Real-world benchmark: precision, recall, F1 and false-positive rate](docs/real-world/overview.svg)](docs/real-world/README.md)
+
+Run `npm run benchmark:real` after `npm ci` and `npm run browser:install`. Regenerate reports from saved measurements with `npm run benchmark:real:report`.
+
+[Full report](docs/real-world/README.md) · [Individual outcomes](docs/real-world/README.md#individual-outcomes) · [Methodology](docs/real-world/methodology.md) · [Interactive dashboard](docs/real-world/dashboard.html) · [Raw JSON](docs/real-world/results.json)
+
+Download and open `docs/real-world/dashboard.html` locally for filters and diagnostic details; GitHub does not execute HTML dashboards. This small, purposive sample includes three false alarms and six missed violations. It is not a population accuracy claim; finding-level metrics and unjudged additional findings are reported separately.
+
+## Interactive states and authenticated pages
+
+Available in v0.4.0. Define named scenarios in `tether.config.ts` to capture a modal, menu, form, or authenticated view. Scenario IDs are stable baseline keys, not display descriptions.
+
+```ts
+export default {
+  url: 'http://localhost:3000',
+  routes: ['/account'],
+  storageState: '.auth/session.json', // optional; relative to this config file
+  sensitiveSelectors: ['[data-private]', 'input[type="password"]'],
+  scenarios: [
+    {
+      id: 'default',
+      routes: ['/account'],
+      ready: async (page) => {
+        await page.locator('[data-testid="account"]')
+          .waitFor({ state: 'visible' });
+      },
+    },
+    {
+      id: 'open-settings',
+      routes: ['/account'],
+      colorScheme: 'light', // or 'dark'; independent of your browser
+      timeoutMs: 30000,
+      setup: async (page, context) => {
+        // Optional pre-navigation setup, such as an init script.
+      },
+      interact: async (page) => {
+        await page.getByRole('button', { name: 'Settings' }).click();
+      },
+      ready: async (page) => {
+        await page.getByRole('dialog').waitFor({ state: 'visible' });
+      },
+    },
+  ],
+};
+```
+
+Each route/state/viewport starts in a fresh browser context. The lifecycle is **load storage state → setup → navigate → interact → ready → settle → collect and mask screenshot → close**. A route with scenarios captures only those scenarios; include `default` explicitly if you want it too. Routes without scenarios retain their initial-load capture. `ready` is required on every explicit scenario; for authentication, assert an element only present after successful sign-in. Every route using `storageState` must have an explicit scenario.
+
+Create the Playwright storage-state file externally using a test account. Keep `.auth/` ignored by Git and outside `.tether/`; tether reads the file but never copies or rewrites it. It contains session credentials. Config hooks execute trusted local code and must not log secrets. They receive Playwright Page/BrowserContext objects; they are not a sandbox. Asynchronous work is bounded by `timeoutMs` (default 30 seconds, maximum 120 seconds), with action/navigation timeouts and no automatic retries. Synchronous blocking code inside a hook cannot be interrupted; avoid it.
+
+Failed navigation, interactions, readiness, or capture exit **2**, identify the route/state/viewport/step without printing the original error, remove incomplete captures, and preserve the last complete baseline/report. Different state or color-scheme coverage requires `init --force`. Old snapshots remain the `default` state with their existing finding IDs. Named-state findings include optional `state` fields in JSON/evidence and state labels in the report and agent brief; they never merge across states. Approvals include the exact state ID.
+
+All URL query **values** and fragments are removed from saved/displayed URLs; use non-secret paths, query names, scenario IDs and configuration labels. Raw URLs remain available only during navigation. If `init --url` contains query values, its generated config reads the URL from `TETHER_URL` instead of embedding those values. Hooks, authentication paths and storage contents are omitted from persisted configuration.
+
+`sensitiveSelectors` masks matching screenshot rectangles and removes semantic identity signals from sensitive elements, their descendants, ancestors and elements labelled by them. Layout measurements remain available; masked targets use structural selectors. This is not automatic secret detection: use sanitized test data and mask every sensitive region, including any labels or duplicate values elsewhere. Review screenshots before sharing them. Masking does not add iframe or shadow-DOM coverage.
+
+## Approving intentional changes
+
+Available in tether-ui v0.4.0 and later.
+
+An approval accepts one finding occurrence without changing the visual contract or baseline. Start with a fresh check and take the finding ID from its JSON output:
+
+```bash
+npx tether-ui check --json
+npx tether-ui approve <finding-id> --property padding-left --viewport desktop --reason "Reviewed compact card spacing"
+```
+
+The second command prints a preview and writes nothing. Review the exact element, property, normalized value, route, viewport dimensions, and component context, then repeat with `--yes` to save it:
+
+```bash
+npx tether-ui approve <finding-id> --property padding-left --viewport desktop --reason "Reviewed compact card spacing" --yes
+npx tether-ui check
+npx tether-ui approvals list
+npx tether-ui approvals revoke <approval-id>
+npx tether-ui check
+```
+
+Commit `tether.approvals.json` in the project root. Its versioned records contain an ID, reason, route, exact state ID, target, category, individual property, exact normalized value, viewport name/dimensions, and optional component context. There are no timestamps, screenshot paths, wildcard matching rules, or baseline updates. Use `approvals list --json` for machine-readable records. If checks use a custom configuration, pass the same `--config` to `approve` or `approvals list`.
+
+- A grouped finding can contain several properties and viewport occurrences. Both `--property` and `--viewport` are required; approving left padding on desktop never approves right padding or mobile. Each additional occurrence needs its own reviewed record.
+- Unique, high-confidence semantic identities are preferred. A weak or legacy identity requires explicitly adding `--selector`; this pins both the exact saved selector and its identity. Ambiguous or partial snapshots cannot be approved. Changes to weak identity, target, value, viewport dimensions, route, or component context leave the new finding active.
+- Values use normal CSS normalization, followed by exact matching—not the drift detector's near-color/subpixel tolerance. Layout approvals pin the problem kind and measured value, so worsening overflow remains active. Missing state in a hand-authored record means only `default`, never every future state.
+- `approve` reads the saved scan; it does not inspect unsaved code or perform a new scan. Preview, creation, listing, and revocation leave baseline/contract/report files untouched. Run `check` after edits to refresh status. Listing without a saved report shows `unknown`; otherwise `matched`/`stale` refers to that saved scan.
+- Unmatched approvals remain visible as stale; they are never deleted automatically. Revoke a stale record when it is no longer needed. Reasons are editable; duplicate tuples/IDs, overlapping matches, invalid files, and concurrent edits fail with an actionable error.
+
+Checks exit **0** when no active findings remain, **1** for active drift, and **2** for invalid configuration/approvals or scan failures. Approved findings retain their evidence and reasons in the report's **Approved findings** filter and in agent output; they are not repair instructions. The overview and severity counts describe active findings, with separate approved/stale counts.
+
+Without an approvals file, existing finding IDs and v1 machine output remain unchanged. With the file present (even empty), report/JSON output uses **version 2**: `report.issues` holds active findings; `report.approvals.approved` and `.stale` preserve reviewed and unmatched records. `check --json` includes `status` on every finding and `summary.active`/`summary.approved` totals, severity/category counts, and `summary.staleApprovals`. `summary.total` counts displayed active plus approved findings; splitting a previously grouped finding can increase this total. Consumers must branch on the schema version. Older clients do not apply approvals and should not be used for approval-aware CI.
+
 ## 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.
@@ -239,8 +373,8 @@ The [Next.js static export](https://nextjs.org/docs/app/guides/static-exports) s
 ## Limitations
 
 - This checks computed styles and basic geometry, not pixel-perfect appearance, semantic design intent, accessibility, or image content.
-- No pseudo-elements, shadow DOM, iframe traversal, hover/focus states, authentication sessions, or interaction scripting yet. Lazy-rendered UI requires it to be present at scan time.
-- Screenshots use light mode with reduced motion. Browser defaults are filtered heuristically, not traced back to authored stylesheets.
+- No pseudo-elements, shadow DOM or iframe traversal, multi-tab workflows, MFA automation, or automatic secret discovery. Named scenarios can capture hover/focus and lazy-rendered content through explicit interactions and readiness checks.
+- Screenshots use light mode by default (scenarios can select dark mode), with reduced motion. Browser defaults are filtered heuristically, not traced back to authored stylesheets.
 - Semantic identities survive small DOM refactors when unique stable signals remain. Dynamic labels, ambiguous elements, and structural fallbacks can still produce noisy matches. This is not a component identity guarantee.
 - Legitimate new design tokens still need human review. Font metrics, OS rendering, dynamic content, and CSS values beyond RGB/hex can affect results.
 - Large DOMs are capped and visibly marked as partial scans. A huge number of findings can reduce the heuristic score to zero.

package/dist/approvals/match.d.ts

@@ -0,0 +1,14 @@
+import { type Approval, type ApprovalFile, type Contract, type FindingOccurrence, type Scan } from "../types.js";
+export declare function normalized(category: string, property: string, value: string): string;
+/** Matching keys never use display finding IDs, merged properties, or screenshot paths. */
+export declare function approvalKey(a: Omit<Approval, "id" | "reason">): string;
+export declare function validateApprovals(input: unknown): ApprovalFile;
+export declare function approvalFor(o: FindingOccurrence, reason: string, selector?: boolean): Approval;
+export declare function matchApproval(o: FindingOccurrence, a: Approval): boolean;
+export declare function applyApprovals(contract: Contract, baseline: Scan, current: Scan, file: ApprovalFile): {
+    issues: import("../types.js").Issue[];
+    approvals: {
+        approved: import("../types.js").Issue[];
+        stale: Approval[];
+    };
+};

package/dist/approvals/match.js

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+import { categories, } from "../types.js";
+import { normalizeValue } from "../utils/normalize.js";
+import { validProperty } from "../contract/scopes.js";
+import { collectOccurrences, groupOccurrences } from "../drift/compare.js";
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const text = (v) => typeof v === "string" && !!v.trim() && !/[\u0000-\u001f]/.test(v);
+const fields = (v, keys) => Object.keys(v).every((k) => keys.includes(k));
+export function normalized(category, property, value) {
+    return category === "layout" ? value : normalizeValue(property, value);
+}
+/** Matching keys never use display finding IDs, merged properties, or screenshot paths. */
+export function approvalKey(a) {
+    return JSON.stringify([
+        a.route,
+        a.state,
+        a.target.kind,
+        a.target.value,
+        a.target.kind === "selector" ? a.target.identity : null,
+        a.category,
+        a.property,
+        normalized(a.category, a.property, a.current),
+        a.viewport.name,
+        a.viewport.width,
+        a.viewport.height,
+        a.context?.scope ?? null,
+        a.context?.part ?? null,
+    ]);
+}
+export function validateApprovals(input) {
+    const fail = (detail) => {
+        throw new Error(`Invalid tether.approvals.json: ${detail}`);
+    };
+    if (!object(input) ||
+        !fields(input, ["version", "approvals"]) ||
+        input.version !== 1 ||
+        !Array.isArray(input.approvals))
+        return fail("expected version 1 and an approvals array.");
+    const ids = new Set(), keys = new Set();
+    const approvals = [];
+    for (const a of input.approvals) {
+        if (!object(a) ||
+            !fields(a, [
+                "id",
+                "reason",
+                "route",
+                "state",
+                "target",
+                "category",
+                "property",
+                "current",
+                "viewport",
+                "context",
+            ]) ||
+            !text(a.id) ||
+            !/^[\w-]{1,80}$/.test(a.id) ||
+            !text(a.reason) ||
+            a.reason.length > 1000 ||
+            !text(a.route) ||
+            !a.route.startsWith("/") ||
+            a.route.startsWith("//") ||
+            (a.state !== undefined &&
+                (typeof a.state !== "string" ||
+                    !/^[a-zA-Z0-9_-]{1,64}$/.test(a.state))) ||
+            !text(a.current))
+            return fail("each record needs an ID, reason, local route, exact value, and valid state ID.");
+        if (!object(a.target) ||
+            !text(a.target.value) ||
+            !["identity", "selector"].includes(String(a.target.kind)) ||
+            (a.target.kind === "identity"
+                ? !fields(a.target, ["kind", "value"])
+                : !fields(a.target, ["kind", "value", "identity"]) ||
+                    (a.target.identity !== null && !text(a.target.identity))))
+            return fail(`invalid target in ${a.id}.`);
+        if (a.category === "layout"
+            ? !["overflow", "offscreen", "clipped"].includes(String(a.property))
+            : !categories.includes(a.category) ||
+                !validProperty(String(a.category), a.property))
+            return fail(`invalid category/property in ${a.id}; properties must be individual, not grouped.`);
+        const v = a.viewport;
+        if (!object(v) ||
+            !fields(v, ["name", "width", "height"]) ||
+            typeof v.name !== "string" ||
+            !/^[a-zA-Z0-9_-]+$/.test(v.name) ||
+            !Number.isInteger(v.width) ||
+            !Number.isInteger(v.height) ||
+            Number(v.width) < 200 ||
+            Number(v.width) > 7680 ||
+            Number(v.height) < 200 ||
+            Number(v.height) > 7680)
+            return fail(`invalid viewport in ${a.id}.`);
+        if (a.context !== undefined &&
+            (!object(a.context) ||
+                !fields(a.context, ["scope", "part"]) ||
+                !text(a.context.scope) ||
+                !text(a.context.part)))
+            return fail(`invalid component context in ${a.id}.`);
+        const record = {
+            id: a.id,
+            reason: a.reason.trim(),
+            route: a.route,
+            state: a.state ?? "default",
+            target: a.target,
+            category: a.category,
+            property: a.property,
+            current: normalized(String(a.category), String(a.property), a.current),
+            viewport: {
+                name: v.name,
+                width: Number(v.width),
+                height: Number(v.height),
+            },
+            ...(a.context ? { context: a.context } : {}),
+        };
+        const key = approvalKey(record);
+        if (ids.has(record.id) || keys.has(key))
+            return fail(`duplicate ID or matching tuple: ${record.id}.`);
+        ids.add(record.id);
+        keys.add(key);
+        approvals.push(record);
+    }
+    return {
+        version: 1,
+        approvals: approvals.sort((a, b) => a.id.localeCompare(b.id)),
+    };
+}
+function tupleFor(o, selector) {
+    const i = o.issue;
+    const target = selector
+        ? { kind: "selector", value: i.selector, identity: i.identity ?? null }
+        : { kind: "identity", value: i.identity };
+    return {
+        route: i.route,
+        state: o.state,
+        target,
+        category: i.category,
+        property: i.property,
+        current: normalized(i.category, i.property, i.current),
+        viewport: o.viewport,
+        ...(i.rule?.scope
+            ? { context: { scope: i.rule.scope, part: i.rule.part } }
+            : {}),
+    };
+}
+export function approvalFor(o, reason, selector = false) {
+    if (!reason.trim())
+        throw new Error("An approval requires a reason.");
+    if (selector ? !o.selectorUnique : !o.identityUnique)
+        throw new Error(selector
+            ? "The selector is ambiguous in the saved snapshot; cannot approve."
+            : "This finding lacks a unique high-confidence identity. Review its selector and use --selector explicitly.");
+    const tuple = tupleFor(o, selector);
+    return {
+        id: `ap_${createHash("sha256").update(approvalKey(tuple)).digest("hex").slice(0, 16)}`,
+        reason: reason.trim(),
+        ...tuple,
+    };
+}
+export function matchApproval(o, a) {
+    if (a.target.kind === "identity" ? !o.identityUnique : !o.selectorUnique)
+        return false;
+    // This builds the occurrence's exact tuple, not a wildcard selector or identity query.
+    const candidate = tupleFor(o, a.target.kind === "selector");
+    return approvalKey(candidate) === approvalKey(a);
+}
+export function applyApprovals(contract, baseline, current, file) {
+    const active = [], approved = [], used = new Set();
+    file = validateApprovals(file);
+    const index = new Map(file.approvals.map((a) => [approvalKey(a), a]));
+    for (const o of collectOccurrences(contract, baseline, current)) {
+        const matches = [];
+        for (const selector of [false, true]) {
+            if (selector ? !o.selectorUnique : !o.identityUnique)
+                continue;
+            const match = index.get(approvalKey(tupleFor(o, selector)));
+            if (match)
+                matches.push(match);
+        }
+        if (matches.length > 1)
+            throw new Error(`Conflicting approvals match one occurrence: ${matches
+                .map((a) => a.id)
+                .sort()
+                .join(", ")}. Revoke the overlapping record.`);
+        if (matches[0]) {
+            const a = matches[0];
+            used.add(a.id);
+            approved.push({
+                ...o,
+                issue: { ...o.issue, approval: { id: a.id, reason: a.reason } },
+            });
+        }
+        else
+            active.push(o);
+    }
+    const sort = (items) => items.sort((a, b) => JSON.stringify([
+        a.issue.route,
+        a.state,
+        a.issue.identity,
+        a.issue.property,
+        a.issue.current,
+        a.viewport.name,
+    ]).localeCompare(JSON.stringify([
+        b.issue.route,
+        b.state,
+        b.issue.identity,
+        b.issue.property,
+        b.issue.current,
+        b.viewport.name,
+    ])));
+    return {
+        issues: groupOccurrences(contract, sort(active)),
+        approvals: {
+            approved: groupOccurrences(contract, sort(approved)),
+            stale: file.approvals.filter((a) => !used.has(a.id)),
+        },
+    };
+}

package/dist/approvals/storage.d.ts

@@ -0,0 +1,4 @@
+import type { ApprovalFile } from "../types.js";
+export declare function readApprovals(cwd: string): Promise<ApprovalFile | undefined>;
+/** Serialize updates and reject a preview that became stale before the write. */
+export declare function saveApprovals(cwd: string, before: ApprovalFile | undefined, after: ApprovalFile): Promise<void>;

package/dist/approvals/storage.js

@@ -0,0 +1,44 @@
+import { readFile, open, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { writeJson } from "../utils/storage.js";
+import { validateApprovals } from "./match.js";
+const pathFor = (cwd) => join(cwd, "tether.approvals.json");
+export async function readApprovals(cwd) {
+    let raw;
+    try {
+        raw = await readFile(pathFor(cwd), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return;
+        throw new Error("Could not read tether.approvals.json. Check file permissions.");
+    }
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Invalid JSON in tether.approvals.json. Fix it before checking or modifying approvals.");
+    }
+    return validateApprovals(input);
+}
+/** Serialize updates and reject a preview that became stale before the write. */
+export async function saveApprovals(cwd, before, after) {
+    const lock = pathFor(cwd) + ".lock";
+    let handle;
+    try {
+        handle = await open(lock, "wx");
+    }
+    catch {
+        throw new Error("Cannot lock tether.approvals.json. Another approval edit may be running; check permissions or remove a stale .lock file after verifying no edit is active.");
+    }
+    try {
+        if (JSON.stringify(await readApprovals(cwd)) !== JSON.stringify(before))
+            throw new Error("Approvals changed since the preview. Retry against the latest file.");
+        await writeJson(pathFor(cwd), validateApprovals(after));
+    }
+    finally {
+        await handle.close();
+        await rm(lock, { force: true });
+    }
+}

package/dist/cli/approvals.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function approvalCommands(program: Command, cwd: () => string): void;

package/dist/cli/approvals.js

@@ -0,0 +1,113 @@
+import { join } from "node:path";
+import { exists, loadConfig } from "../utils/config.js";
+import { readJson } from "../utils/storage.js";
+import { readContract } from "../contract/read.js";
+import { coverage, validateCoverage } from "../utils/coverage.js";
+import { collectOccurrences, groupOccurrences } from "../drift/compare.js";
+import { applyApprovals, approvalFor, validateApprovals, } from "../approvals/match.js";
+import { readApprovals, saveApprovals } from "../approvals/storage.js";
+async function saved(cwd, configFile) {
+    const data = join(cwd, ".tether");
+    const report = await readJson(join(data, "report.json"));
+    const baseline = await readJson(join(data, "baseline.json"));
+    const contract = readContract(await readJson(join(data, "contract.json")));
+    if (![1, 2].includes(report.version) ||
+        report.scan?.version !== 1 ||
+        !Array.isArray(report.scan?.snapshots) ||
+        baseline.version !== 1 ||
+        !Array.isArray(baseline.snapshots) ||
+        report.baselineAt !== baseline.createdAt ||
+        JSON.stringify(report.contract) !== JSON.stringify(contract) ||
+        JSON.stringify(coverage(report.scan)) !== JSON.stringify(coverage(baseline)))
+        throw new Error("Saved report does not match the current baseline/contract coverage. Run tether check before approving.");
+    validateCoverage(await loadConfig(cwd, undefined, configFile), contract, baseline);
+    return { report, baseline, contract };
+}
+export function approvalCommands(program, cwd) {
+    program
+        .command("approve <finding-id>")
+        .description("Preview an exact approval from the saved scan; --yes writes it")
+        .requiredOption("--property <property>", "One individual CSS property or layout kind")
+        .requiredOption("--viewport <name>", "One saved viewport name (dimensions are pinned)")
+        .requiredOption("--reason <reason>", "Why this visual change is intentional")
+        .option("--selector", "Explicitly accept a selector-scoped target instead of semantic identity")
+        .option("--yes", "Persist the previewed approval")
+        .option("--config <path>", "Config file used by the saved scan")
+        .action(async (id, options) => {
+        const before = await readApprovals(cwd());
+        const { report, baseline, contract } = await saved(cwd(), options.config);
+        const classified = applyApprovals(contract, baseline, report.scan, before ?? { version: 1, approvals: [] });
+        if (!classified.issues.some((i) => i.id === id))
+            throw new Error("No active saved finding has that ID. Run tether check --json and inspect the finding; it may already be approved.");
+        const occurrences = collectOccurrences(contract, baseline, report.scan).filter((o) => groupOccurrences(contract, [o])[0].id === id &&
+            o.issue.property === options.property &&
+            o.viewport.name === options.viewport);
+        if (occurrences.length !== 1)
+            throw new Error("Expected exactly one occurrence for this finding/property/viewport. Inspect the saved scan for missing or ambiguous targets.");
+        if (report.scan.snapshots.some((s) => s.route === occurrences[0].issue.route &&
+            (s.state ?? "default") === occurrences[0].state &&
+            s.viewport.name === options.viewport &&
+            s.truncated))
+            throw new Error("Cannot approve a partial snapshot. Increase maxElements and run tether check first.");
+        const record = approvalFor(occurrences[0], options.reason, !!options.selector);
+        const after = validateApprovals({
+            version: 1,
+            approvals: [...(before?.approvals ?? []), record],
+        });
+        // Reject overlapping identity/selector approvals before any write.
+        applyApprovals(contract, baseline, report.scan, after);
+        console.log("Approval preview (saved scan only):\n" +
+            JSON.stringify(record, null, 2));
+        if (!options.yes) {
+            console.log("No files changed. Re-run with --yes to save this exact scope.");
+            return;
+        }
+        await saveApprovals(cwd(), before, after);
+        console.log("Saved tether.approvals.json. Run tether check to refresh findings and CI status.");
+    });
+    const command = program
+        .command("approvals")
+        .description("Inspect or revoke version-controlled visual approvals");
+    command
+        .command("list")
+        .option("--json", "Machine-readable records and saved-scan status")
+        .option("--config <path>", "Config file")
+        .action(async (options) => {
+        const file = (await readApprovals(cwd())) ?? {
+            version: 1,
+            approvals: [],
+        };
+        let stale;
+        if (file.approvals.length &&
+            (await exists(join(cwd(), ".tether/report.json")))) {
+            const { report, baseline, contract } = await saved(cwd(), options.config);
+            stale = new Set(applyApprovals(contract, baseline, report.scan, file).approvals.stale.map((a) => a.id));
+        }
+        const records = file.approvals.map((a) => ({
+            ...a,
+            status: !stale ? "unknown" : stale.has(a.id) ? "stale" : "matched",
+        }));
+        if (options.json)
+            console.log(JSON.stringify({ version: 1, basis: "saved scan", approvals: records }, null, 2));
+        else {
+            console.log("Approvals (status reflects saved scan only):");
+            for (const a of records)
+                console.log(`${a.id} · ${a.status} · ${a.route} · ${a.state} · ${a.viewport.name} ${a.viewport.width}×${a.viewport.height} · ${a.target.value} · ${a.property} = ${a.current}\n  ${a.reason}`);
+            if (!records.length)
+                console.log("No approvals.");
+        }
+    });
+    command
+        .command("revoke <approval-id>")
+        .description("Remove one approval; the next check restores its finding")
+        .action(async (id) => {
+        const before = await readApprovals(cwd());
+        if (!before?.approvals.some((a) => a.id === id))
+            throw new Error(`Approval not found: ${id}`);
+        await saveApprovals(cwd(), before, {
+            version: 1,
+            approvals: before.approvals.filter((a) => a.id !== id),
+        });
+        console.log(`Revoked ${id}. Run tether check to refresh the report.`);
+    });
+}

package/dist/cli/format.d.ts

@@ -1,3 +1,3 @@
-import type { Issue, Report } from "../types.js";
-export declare function agentMarkdown(issues: Issue[]): string;
+import type { Issue, Report, ApprovalSummary } from "../types.js";
+export declare function agentMarkdown(issues: Issue[], approvals?: ApprovalSummary, failOn?: "all" | "new"): string;
 export declare function terminalReport(report: Report, color?: boolean): string;