styleproof 3.20.0 → 4.0.0

package/dist/capture.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { classifyInventory, collectNavAffordances } from './inventory.js';
+import { endpointOf, residueKey } from './data-residue.js';
 import { isMapFile } from './map-store.js';
 const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"], [tabindex]';
 // Freeze motion so every captured value is a settled end state, not a frame
@@ -598,6 +599,93 @@ export function trackInflightRequests(page) {
         },
     };
 }
+/**
+ * Watch the data boundary (`url`, the same `replayUrl` glob record/replay uses) for
+ * requests that FAIL during capture — a network-level failure or a 4xx/5xx response.
+ * A failing data request means the captured state renders that endpoint's FALLBACK
+ * branch; the response-driven state is uncaptured and unproven (issue #205).
+ *
+ * Matches purely by listening to `requestfailed`/`response` and testing the URL against
+ * the boundary glob — NOT via a `page.route`. A passive route can't be used to tag: the
+ * tracker is armed before `go()`, and a route the surface itself adds in `go()` (an abort
+ * fixture, the HAR replay route) runs first and never falls through to a tag route added
+ * earlier, so tagged requests would be missed. Listeners see every request regardless of
+ * routing, which is exactly what a residue observer needs. Arm BEFORE navigation, like
+ * {@link trackInflightRequests}, so the page's own load fetches are seen; deduped per
+ * `<surface>·<endpoint>` so the same failure across widths / a self-check re-run is one entry.
+ *
+ * ONLY failures are recorded — never a 2xx that merely wasn't fixtured: in recording mode
+ * every live 2xx is legitimately recorded, so a blanket "uncontrolled" flag would fire on
+ * every healthy record run (issue #205, "deliberately out of scope").
+ */
+export function trackDataResidue(page, url, surface) {
+    const byKey = new Map();
+    const inBoundary = urlMatcher(url);
+    const record = (request, reason) => {
+        if (!inBoundary(request.url()))
+            return;
+        const endpoint = endpointOf(request.url());
+        const key = residueKey(surface, endpoint);
+        if (!byKey.has(key))
+            byKey.set(key, { key, surface, endpoint, reason });
+    };
+    const onFailed = (r) => record(r, r.failure()?.errorText ?? 'request failed');
+    // A completed response's status is synchronous here, so a 4xx/5xx is recorded before
+    // capture reads the residue. A >=400 is a fallback-branch trigger just like a net failure.
+    const onResponse = (resp) => {
+        if (resp.status() >= 400)
+            record(resp.request(), `HTTP ${resp.status()}`);
+    };
+    page.on('requestfailed', onFailed);
+    page.on('response', onResponse);
+    return {
+        residue: () => Array.from(byKey.values()).sort((a, b) => a.key.localeCompare(b.key)),
+        dispose: () => {
+            page.off('requestfailed', onFailed);
+            page.off('response', onResponse);
+        },
+    };
+}
+/**
+ * A predicate matching a URL against a Playwright-style URL glob — the same micro-syntax
+ * `page.route`/`routeFromHAR` accept for `replayUrl`, replicated because Playwright exposes
+ * no public matcher and reaching into its bundled internals is fragile across versions.
+ * `**` spans path separators, `*` matches within a segment (not `/`), `?` is a literal
+ * (URL globs, unlike shell globs, treat `?` as the query delimiter), and `{a,b}` alternates.
+ * A plain (glob-char-free) string is treated as a substring match, matching Playwright's
+ * own "contains" fallback for non-glob route URLs.
+ */
+export function urlMatcher(glob) {
+    if (!/[*?{}[\]]/.test(glob))
+        return (url) => url.includes(glob);
+    const specials = new Set(['.', '+', '^', '$', '|', '(', ')']);
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                re += '.*';
+                i++;
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '\\?';
+        else if (c === '{')
+            re += '(';
+        else if (c === '}')
+            re += ')';
+        else if (c === ',')
+            re += '|';
+        else if (specials.has(c))
+            re += `\\${c}`;
+        else
+            re += c;
+    }
+    const compiled = new RegExp(`^${re}$`);
+    return (url) => compiled.test(url);
+}
 /** Settle the page and return the paths of live regions to exclude. */
 async function detectVolatile(page, ignore, stabilize, captureText, externalPending) {
     if (stabilize === false)
@@ -793,15 +881,49 @@ export function loadStyleMap(filePath) {
             'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.', { cause: e });
     }
 }
+/** Every surface map in a capture dir, loaded — the shared reader behind the
+ *  per-field extractors below. */
+function loadDirMaps(dir) {
+    return fs
+        .readdirSync(dir)
+        .filter(isMapFile)
+        .map((f) => loadStyleMap(path.join(dir, f)));
+}
 /**
  * Read every surface map's navigable inventory from a capture dir, in the shape the
  * inventory audit consumes. One home for "read the inventories out of a dir", shared
  * by the diff CLI and the report (was duplicated in both).
  */
 export function readInventories(dir) {
-    return fs
-        .readdirSync(dir)
-        .filter(isMapFile)
-        .map((f) => loadStyleMap(path.join(dir, f)))
-        .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
+    return loadDirMaps(dir).map((m) => (m.inventory ? { inventory: m.inventory } : {}));
+}
+/**
+ * Read every surface map's `dataResidue` from a capture dir, in the shape the
+ * data-residue audit consumes. Lives here (not in data-residue.ts) so that module
+ * stays a pure leaf — it must not import `loadStyleMap` back from this file.
+ */
+export function readResidue(dir) {
+    return loadDirMaps(dir).map((m) => (m.dataResidue ? { dataResidue: m.dataResidue } : {}));
+}
+/**
+ * Each captured surface key → the set of element paths it renders, unioned across
+ * the given dirs (so an element present on only one side still "belongs" to the
+ * surface). Feeds the shared-chrome tier, which needs to know, per surface, which
+ * paths exist to tell a frame-wide change from one view's content. Shared by the
+ * report and the diff CLI (both already read maps this way).
+ */
+export function surfaceElementPaths(...dirs) {
+    const bySurface = new Map();
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const file of fs.readdirSync(dir).filter(isMapFile)) {
+            const surface = file.replace(/\.json(\.gz)?$/, '');
+            const set = bySurface.get(surface) ?? new Set();
+            for (const p of Object.keys(loadStyleMap(path.join(dir, file)).elements))
+                set.add(p);
+            bySurface.set(surface, set);
+        }
+    }
+    return bySurface;
 }

package/dist/change-groups.d.ts

@@ -0,0 +1,91 @@
+import { type Finding, type PropChange } from './diff.js';
+export declare const isNonValue: (v: string) => boolean;
+export declare function summarizeProps(props: PropChange[]): PropChange[];
+/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
+export declare function prettyLabel(p: string, cls: string): string;
+export declare const safeKey: (s: string) => string;
+export declare const surfaceBase: (s: string) => string;
+export declare const surfaceWidth: (s: string) => number;
+export declare function pushSurfaceWidth(byBase: Map<string, number[]>, base: string, surface: string): void;
+export declare function renderSurfaceGroups(byBase: Map<string, number[]>): string;
+/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
+export declare function formatSurfaceList(surfaces: string[]): string;
+/** Group findings by their element path (one group per changed element). */
+export declare function groupByPath(findings: Finding[]): Finding[][];
+/** Canonical signature of a surface's findings: surfaces that changed in the
+ *  same way collapse into one section + one image (the rects differ per width;
+ *  the change itself does not). */
+export declare function signatureOf(findings: Finding[]): string;
+/** A one-line heading for a change group: "1 element added", "2 elements restyled". */
+export declare function groupTitle(findings: Finding[]): string;
+/** How many of a surface's summarised props are derived/box longhands — the count
+ *  the CLI folds behind `(+N derived longhands)`. Counts on the RAW finding props
+ *  (before cleaning) so the CLI can advertise exactly what it suppressed. */
+export declare function derivedLonghandCount(findings: Finding[]): number;
+/**
+ * Strip the noise the visual report shouldn't carry, cross-referencing each
+ * element's layers so the forced-state layer stops echoing the base:
+ *   - base/pseudo styles: drop size/position-derived longhands (reflow casualties);
+ *   - forced states: drop derived + grid-track props, drop a delta the BASE
+ *     already changed (a `:hover color` that just follows a recoloured base is an
+ *     echo, not a dropped variant), and drop non-value↔non-value rows;
+ *   - any finding left with no props is removed entirely.
+ */
+export declare function cleanFindings(findings: Finding[]): Finding[];
+/** A surface's diff distilled to just what grouping needs: its key and the
+ *  findings kept after noise-cleaning. */
+export type SurfaceFindings = {
+    surface: string;
+    findings: Finding[];
+};
+/** Surfaces that changed the SAME way, collapsed to one group + a representative. */
+export type SignatureGroup = {
+    surfaces: string[];
+    rep: SurfaceFindings;
+    findings: Finding[];
+};
+/**
+ * Group surfaces that changed identically (same signature) into one group each,
+ * keeping the widest surface as the representative. The rects differ per width;
+ * the change itself does not. Callers pass the already-prepared per-surface
+ * findings (missing/one-sided surfaces excluded upstream).
+ */
+export declare function groupBySignature(prepared: SurfaceFindings[]): SignatureGroup[];
+/**
+ * The set of element paths that changed as SHARED CHROME — a persistent frame
+ * element (nav rail, header, footer) that every view renders and that moved on
+ * every view that renders it.
+ *
+ * The rule is STRUCTURAL, deliberately NOT a tunable percentage. For each changed
+ * path we compare two base-key sets:
+ *   - `hosting`  — the surface bases whose style map contains the path at all;
+ *   - `changed`  — the surface bases where the path appears in a finding.
+ * The path is chrome iff it is hosted on MORE THAN ONE base and it changed on
+ * EVERY base that hosts it (`changed ⊇ hosting`). "Every surface that has this
+ * element changed it" is exactly what shared chrome means; it needs no threshold
+ * to tune or defend. A content element (hosted on one base) fails the >1 guard; a
+ * partial change (some hosting bases unchanged) fails the coverage guard.
+ *
+ * Widths of one base collapse to the base key, so a nav present at @1280 and @390
+ * counts once. `surfacePaths` maps each captured surface key → the element paths
+ * it renders (union of both sides from the caller).
+ */
+export declare function chromePaths(changedOnSurfaces: Array<{
+    path: string;
+    surfaces: string[];
+}>, surfacePaths: Map<string, Set<string>>): Set<string>;
+/**
+ * Split signature groups into the shared-chrome tier and the rest. A group is
+ * promoted only when EVERY one of its affected element paths is a chrome path
+ * (see `chromePaths`) — a group that entangles a frame change with a view's own
+ * content change stays in `rest` and renders in place, so we never hide a
+ * content change under a chrome banner.
+ */
+export declare function classifyChrome<G extends {
+    surfaces: string[];
+    findings: Finding[];
+}>(groups: G[], surfacePaths: Map<string, Set<string>>): {
+    chrome: G[];
+    rest: G[];
+    chromePaths: Set<string>;
+};