styleproof 2.0.0 → 2.2.0

package/dist/capture.js

@@ -30,15 +30,12 @@ const FRAMEWORK_IGNORE = [
 export function isUnder(path, roots) {
     return roots.some((r) => path === r || path.startsWith(r + ' > '));
 }
-// Serialized into the browser by page.evaluate; cannot call module helpers.
-// Pre-existing, grandfathered in the health baseline; the content layer adds
-// one small captureText block, not new structure.
-// fallow-ignore-next-line complexity
-function capturePage({ ignore, motionOnly, captureText }) {
-    const MOTION = /^(transition|animation)/;
-    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
-    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
-    const pathOf = (el) => {
+// Defines the structural-path helper on `window` once so the two functions
+// serialized into the page (capturePage, markInteractiveElements) share ONE
+// implementation — page.evaluate can't reference a module-scope helper, so the
+// alternative is an identical copy in each. Injected at the top of captureStyleMap.
+function injectPathOf() {
+    window.__spPathOf = (el) => {
         if (el === document.documentElement)
             return 'html';
         if (el === document.body)
@@ -54,6 +51,16 @@ function capturePage({ ignore, motionOnly, captureText }) {
         }
         return 'body > ' + parts.join(' > ');
     };
+}
+// Serialized into the browser by page.evaluate; cannot call module helpers.
+// Pre-existing, grandfathered in the health baseline; the content layer adds
+// one small captureText block, not new structure.
+// fallow-ignore-next-line complexity
+function capturePage({ ignore, motionOnly, captureText, captureComponent }) {
+    const MOTION = /^(transition|animation)/;
+    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    const pathOf = window.__spPathOf;
     // Per-tag (and per-tag-per-pseudo) UA defaults from a stylesheet-free iframe,
     // used to prune the maps. A pseudo-element's UA defaults are NOT the host
     // element's defaults, so they are measured and cached separately under a
@@ -96,6 +103,53 @@ function capturePage({ ignore, motionOnly, captureText }) {
         }
         return o;
     };
+    // Display name from a fiber `type`: function/class, or a forwardRef/memo wrapper
+    // object; '' for host fibers (string type), which keeps the walk going upward.
+    const nameOfType = (t) => {
+        if (typeof t === 'function') {
+            const f = t;
+            return f.displayName || f.name || '';
+        }
+        if (t && typeof t === 'object') {
+            const w = t;
+            const inner = w.render || w.type;
+            return w.displayName || inner?.displayName || inner?.name || '';
+        }
+        return '';
+    };
+    // Keep only primitive props (drop children/className/style/handlers/objects),
+    // capped — advisory, so never anything that could be huge or non-serializable.
+    const sanitizeProps = (mp) => {
+        const props = {};
+        for (const k of Object.keys(mp)) {
+            if (k === 'children' || k === 'className' || k === 'style')
+                continue;
+            const ty = typeof mp[k];
+            if (ty === 'string' || ty === 'number' || ty === 'boolean')
+                props[k] = String(mp[k]).slice(0, 80);
+        }
+        return props;
+    };
+    const reactComponent = (el) => {
+        const fiberKey = Object.keys(el).find((k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'));
+        if (!fiberKey)
+            return undefined;
+        let fiber = el[fiberKey] ?? null;
+        for (let hops = 0; fiber && hops < 30; fiber = fiber.return, hops++) {
+            const name = nameOfType(fiber.type);
+            if (!name || name === 'Symbol(react.fragment)')
+                continue;
+            const out = { name };
+            const mp = fiber.memoizedProps;
+            if (mp && typeof mp === 'object') {
+                const props = sanitizeProps(mp);
+                if (Object.keys(props).length)
+                    out.props = props;
+            }
+            return out;
+        }
+        return undefined;
+    };
     const elements = {};
     const all = [document.documentElement, document.body, ...document.querySelectorAll('body *')];
     // Surface untraversed shadow roots and same-origin iframes so a refactor
@@ -147,6 +201,16 @@ function capturePage({ ignore, motionOnly, captureText }) {
                 if (t)
                     entry.text = t;
             }
+            if (captureComponent) {
+                try {
+                    const comp = reactComponent(el);
+                    if (comp)
+                        entry.component = comp;
+                }
+                catch {
+                    // non-React node or inaccessible fiber — component stays absent
+                }
+            }
         }
         for (const ps of PSEUDOS) {
             if (ps === '::marker' && getComputedStyle(el).display !== 'list-item')
@@ -233,22 +297,7 @@ const STATE_ID_ATTR = 'data-styleproof-state-id';
  * but different ordering, which produces phantom forced-state diffs.
  */
 function markInteractiveElements({ selector, skipSel, attr }) {
-    const pathOf = (el) => {
-        if (el === document.documentElement)
-            return 'html';
-        if (el === document.body)
-            return 'body';
-        const parts = [];
-        let n = el;
-        while (n && n !== document.body) {
-            const parent = n.parentElement;
-            if (!parent)
-                break;
-            parts.unshift(`${n.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, n) + 1})`);
-            n = parent;
-        }
-        return 'body > ' + parts.join(' > ');
-    };
+    const pathOf = window.__spPathOf;
     let i = 0;
     return [...document.querySelectorAll(selector)].flatMap((el) => {
         if (skipSel && el.matches(skipSel))
@@ -322,7 +371,7 @@ function changedElementPaths(a, b) {
  * Reuses `capturePage` (motion already frozen by the caller), so only
  * content/layout churn — not an animation frame — keeps it from settling.
  */
-async function stabilizePage(page, ignore, interval, quietFor, timeout, captureText) {
+async function stabilizePage(page, ignore, interval, quietFor, timeout, captureText, pending) {
     // captureText is threaded in so text churn participates in settle detection:
     // a clock/ticker whose text changes (with no style change) keeps the map from
     // settling and is excluded as a live region, exactly as style churn already is.
@@ -340,8 +389,16 @@ async function stabilizePage(page, ignore, interval, quietFor, timeout, captureT
             lastChangeAt = Date.now();
             recent = changed;
         }
+        else if (pending() > 0) {
+            // The DOM is momentarily quiet, but data requests are still in flight — this
+            // is the lull BEFORE the response paints, not a settled state. Hold the quiet
+            // window so we wait for the content to ARRIVE (no live-region path to record;
+            // network activity isn't a mutating element). Long-lived streams are excluded
+            // by the caller, so this can't hang on an SSE that never finishes.
+            lastChangeAt = Date.now();
+        }
         else if (Date.now() - lastChangeAt >= quietFor) {
-            return []; // unchanged for the full quiet window → settled
+            return []; // DOM unchanged AND network idle for the full quiet window → settled
         }
     }
     return recent; // never went quiet for quietFor within budget → still-moving paths are live
@@ -374,19 +431,75 @@ function capturePageTokens() {
     probe.remove();
     return tokens;
 }
+/**
+ * Track in-flight DATA requests on `page` so the network-aware settle can wait for
+ * late-loading content to ARRIVE, not just for the DOM to go briefly quiet (the lull
+ * before a response paints). Long-lived streams (EventSource/WebSocket) never finish,
+ * so they're excluded — their painted state is handled by the live-region pass.
+ *
+ * Attach BEFORE navigation to count the page's OWN load fetches: a request already in
+ * flight when you call `captureStyleMap` fired its `request` event before any listener
+ * attached there, so only a tracker armed earlier (the runner does this before `go()`)
+ * can see it.
+ */
+export function trackInflightRequests(page) {
+    const inflight = new Set();
+    const isStream = (r) => {
+        const t = r.resourceType();
+        return t === 'eventsource' || t === 'websocket';
+    };
+    const onStart = (r) => {
+        if (!isStream(r))
+            inflight.add(r);
+    };
+    const onEnd = (r) => {
+        inflight.delete(r);
+    };
+    page.on('request', onStart);
+    page.on('requestfinished', onEnd);
+    page.on('requestfailed', onEnd);
+    return {
+        pending: () => inflight.size,
+        dispose: () => {
+            page.off('request', onStart);
+            page.off('requestfinished', onEnd);
+            page.off('requestfailed', onEnd);
+        },
+    };
+}
 /** Settle the page and return the paths of live regions to exclude. */
-async function detectVolatile(page, ignore, stabilize, captureText) {
+async function detectVolatile(page, ignore, stabilize, captureText, externalPending) {
     if (stabilize === false)
         return [];
     const opt = typeof stabilize === 'object' ? stabilize : {};
-    const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000, captureText);
-    if (volatile.length) {
-        // eslint-disable-next-line no-console
-        console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
-            'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
-            'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+    const waitForRequests = opt.waitForRequests ?? true;
+    // Prefer the runner's pre-navigation tracker (it counts the page's load fetches);
+    // otherwise arm one here as a fallback for requests that fire after this call.
+    let pending = () => 0;
+    let dispose = () => { };
+    if (waitForRequests) {
+        if (externalPending) {
+            pending = externalPending;
+        }
+        else {
+            const t = trackInflightRequests(page);
+            pending = t.pending;
+            dispose = t.dispose;
+        }
+    }
+    try {
+        const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000, captureText, pending);
+        if (volatile.length) {
+            // eslint-disable-next-line no-console
+            console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
+                'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
+                'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+        }
+        return volatile;
+    }
+    finally {
+        dispose();
     }
-    return volatile;
 }
 /** Drop live regions (and their subtrees) from the base capture, in Node so the
  *  serialized capturePage stays a pure snapshot. */
@@ -433,6 +546,7 @@ export async function captureStyleMap(page, options = {}) {
     const maxInteractive = options.maxInteractive ?? 800;
     const stabilize = options.stabilize ?? true;
     const captureText = options.captureText ?? false;
+    const captureComponent = options.captureComponent ?? false;
     // Neutralise real focus the same way FREEZE_CSS neutralises motion: blur
     // whatever element holds focus so every read below is the no-interaction
     // resting state. Real :focus is nondeterministic across runs (autofocus, late
@@ -443,6 +557,11 @@ export async function captureStyleMap(page, options = {}) {
     // deterministic" failure). Interaction states are certified deterministically
     // via CDP forcePseudoState below, never via whatever happened to be focused.
     await page.evaluate(() => document.activeElement?.blur?.());
+    // Inject the structural-path helper once so both capturePage and
+    // markInteractiveElements (each serialized into the page by page.evaluate, which
+    // can't share a module-scope function) call ONE definition — no duplicated source.
+    // It persists on `window` for every evaluate below (no navigation between them).
+    await page.evaluate(injectPathOf);
     // Motion longhands first (FREEZE_CSS would null them), then everything else.
     // Motion never carries text — it's a settled end state of declared motion.
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
@@ -451,8 +570,8 @@ export async function captureStyleMap(page, options = {}) {
     // the same loaded state, and collect any region still changing on its own
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
-    const volatile = await detectVolatile(page, ignore, stabilize, captureText);
-    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText });
+    const volatile = await detectVolatile(page, ignore, stabilize, captureText, options.pendingRequests);
+    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
     dropVolatile(base.elements, volatile);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);
     mergeMotion(base.elements, motion.elements);

package/dist/coverage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Coverage guard for the surface list.
+ *
+ * StyleProof captures exactly the surfaces a spec declares, and the diff matches
+ * surfaces by key — so a route nobody added to `surfaces` is invisible to the
+ * gate: the change it introduces has no baseline capture AND no head capture, so
+ * it never appears in any diff. The gate goes green having never looked at it.
+ * This is the one failure StyleProof can't catch from the captures alone, because
+ * it's about a capture that was never taken.
+ *
+ * `expected` closes the hole: a spec declares its full route/surface universe
+ * (e.g. an app's view registry), and the guard fails when that universe drifts
+ * from what's actually captured — turning a silent coverage hole into a red test,
+ * in the app's own suite, the moment the route is added.
+ */
+export type CoverageGaps = {
+    /** Expected surfaces that are neither captured nor explicitly excluded. */
+    uncovered: string[];
+    /** `exclude` entries absent from `expected` — a renamed or removed route whose
+     *  opt-out has gone stale (the same drift, in reverse). */
+    staleExclusions: string[];
+};
+/**
+ * Compare the captured surface keys against a declared `expected` universe.
+ *
+ * A surface is covered if it's captured OR listed in `exclude` (a deliberate,
+ * documented opt-out — `key → reason`). Captured surfaces NOT in `expected` are
+ * allowed: one route legitimately has several captured states (`landing`,
+ * `landing-nav-open`), and only the routes themselves form the universe.
+ *
+ * Pure and side-effect-free so it's unit-testable; `defineStyleMapCapture` wraps
+ * it in a Playwright test that runs in the normal suite (not gated on a capture
+ * dir), and it's exported so a consumer can assert coverage however it likes.
+ */
+export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;

package/dist/coverage.js

@@ -0,0 +1,35 @@
+/**
+ * Coverage guard for the surface list.
+ *
+ * StyleProof captures exactly the surfaces a spec declares, and the diff matches
+ * surfaces by key — so a route nobody added to `surfaces` is invisible to the
+ * gate: the change it introduces has no baseline capture AND no head capture, so
+ * it never appears in any diff. The gate goes green having never looked at it.
+ * This is the one failure StyleProof can't catch from the captures alone, because
+ * it's about a capture that was never taken.
+ *
+ * `expected` closes the hole: a spec declares its full route/surface universe
+ * (e.g. an app's view registry), and the guard fails when that universe drifts
+ * from what's actually captured — turning a silent coverage hole into a red test,
+ * in the app's own suite, the moment the route is added.
+ */
+/**
+ * Compare the captured surface keys against a declared `expected` universe.
+ *
+ * A surface is covered if it's captured OR listed in `exclude` (a deliberate,
+ * documented opt-out — `key → reason`). Captured surfaces NOT in `expected` are
+ * allowed: one route legitimately has several captured states (`landing`,
+ * `landing-nav-open`), and only the routes themselves form the universe.
+ *
+ * Pure and side-effect-free so it's unit-testable; `defineStyleMapCapture` wraps
+ * it in a Playwright test that runs in the normal suite (not gated on a capture
+ * dir), and it's exported so a consumer can assert coverage however it likes.
+ */
+export function coverageGaps(capturedKeys, expected, exclude = {}) {
+    const captured = new Set(capturedKeys);
+    const expectedList = [...expected];
+    const expectedSet = new Set(expectedList);
+    const uncovered = expectedList.filter((k) => !captured.has(k) && !(k in exclude));
+    const staleExclusions = Object.keys(exclude).filter((k) => !expectedSet.has(k));
+    return { uncovered, staleExclusions };
+}

package/dist/diff.d.ts

@@ -15,6 +15,10 @@ export type Finding = {
     cls: string;
     change: 'added' | 'removed' | 'retagged';
     detail?: string;
+    component?: {
+        name: string;
+        props?: Record<string, string>;
+    };
 } | {
     kind: 'style';
     path: string;

package/dist/diff.js

@@ -35,11 +35,39 @@ export function diffStyleMaps(a, b) {
         const ea = a.elements[p];
         const eb = b.elements[p];
         if (!ea || !eb) {
-            findings.push({ kind: 'dom', path: p, cls: (ea ?? eb).cls, change: !ea ? 'added' : 'removed' });
+            const present = (ea ?? eb);
+            findings.push({
+                kind: 'dom',
+                path: p,
+                cls: present.cls,
+                change: !ea ? 'added' : 'removed',
+                ...(!ea && eb.component ? { component: eb.component } : {}),
+            });
+            // An added element has no "before", so the style loop below is skipped —
+            // surface its full resting computed style (+ pseudos) as (unset)→value so a
+            // new element's styling is reviewable, not just its interaction-state
+            // deltas. Removed elements get none (there is no "after" to show).
+            if (!ea && eb) {
+                const defsB = b.defaults[eb.tag] ?? {};
+                for (const pseudo of [null, ...Object.keys(eb.pseudo ?? {})]) {
+                    const propsB = pseudo ? (eb.pseudo?.[pseudo] ?? {}) : eb.style;
+                    const pdefsB = pseudo ? (b.defaults[eb.tag + pseudo] ?? defsB) : defsB;
+                    const props = diffProps({}, propsB, {}, pdefsB, '(unset)', '(unset)');
+                    if (props.length)
+                        findings.push({ kind: 'style', path: p, cls: eb.cls, pseudo, props });
+                }
+            }
             continue;
         }
         if (ea.tag !== eb.tag) {
-            findings.push({ kind: 'dom', path: p, cls: ea.cls, change: 'retagged', detail: `<${ea.tag}> → <${eb.tag}>` });
+            findings.push({
+                kind: 'dom',
+                path: p,
+                cls: ea.cls,
+                change: 'retagged',
+                detail: `<${ea.tag}> → <${eb.tag}>`,
+                ...(eb.component ? { component: eb.component } : {}),
+            });
             continue;
         }
         const defsA = a.defaults[ea.tag] ?? {};

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export type { StyleMap, CaptureOptions, ElementEntry, Rect } from './capture.js';
 export { defineStyleMapCapture } from './runner.js';
 export type { Surface, DefineOptions } from './runner.js';
+export { coverageGaps } from './coverage.js';
+export type { CoverageGaps } from './coverage.js';
+export { discoverNextRoutes } from './routes.js';
+export type { DiscoveredRoute } from './routes.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export type { Finding, PropChange, SurfaceDiff, DiffCounts, ContentChange } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export { defineStyleMapCapture } from './runner.js';
+export { coverageGaps } from './coverage.js';
+export { discoverNextRoutes } from './routes.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/report.js

@@ -432,12 +432,51 @@ function beforeAfterTable(rows) {
         ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.before)} | ${cell(r.after)} |`),
     ];
 }
+// A brand-new element has no meaningful "before", so its resting style renders
+// value-only (the After column), mirroring the added-element interaction-states table.
+function valueTable(rows) {
+    return ['| Property | Value |', '| --- | --- |', ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.after)} |`)];
+}
+/** `Button (variant=primary, size=sm)` — the React component + sanitized props
+ *  the element captured (advisory; present only with captureComponent). */
+function renderComponent(c) {
+    const entries = Object.entries(c.props ?? {});
+    const props = entries.length ? ` (${entries.map(([k, v]) => `${k}=${v}`).join(', ')})` : '';
+    return `\`${c.name}\`${props}`;
+}
 /** One element's heading + body lines (no leading blank, no ×N suffix). */
+// Base/pseudo style rows. Added elements render value-only (no meaningful before).
+function styleSection(styles, added) {
+    const out = [];
+    for (const s of styles) {
+        const rows = summarizeProps(s.props);
+        if (rows.length)
+            out.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...(added ? valueTable(rows) : beforeAfterTable(rows)));
+    }
+    return out;
+}
+// Forced :hover/:focus/:active rows. Added: value-only; changed: before → after.
+function statesSection(states, added) {
+    const rows = [];
+    for (const st of states)
+        for (const c of summarizeProps(st.props))
+            rows.push(added
+                ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
+                : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
+    if (!rows.length)
+        return [];
+    return [
+        '',
+        added ? 'Interactive states:' : 'Interactive-state changes:',
+        '',
+        added ? '| State | Property | Value |' : '| State | Property | Before → After |',
+        '| --- | --- | --- |',
+        ...rows,
+    ];
+}
 function renderOneElement(group) {
     const label = prettyLabel(group[0].path, group[0].cls);
     const dom = group.find((f) => f.kind === 'dom');
-    const styles = group.filter((f) => f.kind === 'style');
-    const states = group.filter((f) => f.kind === 'state');
     if (dom?.change === 'removed')
         return { head: `**Removed** \`${label}\``, body: [] };
     const added = dom?.change === 'added';
@@ -447,21 +486,12 @@ function renderOneElement(group) {
             ? `**Retagged** \`${label}\` ${dom.detail ?? ''}`
             : `**\`${label}\`**`;
     const body = [];
-    for (const s of styles) {
-        const rows = summarizeProps(s.props);
-        if (rows.length)
-            body.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...beforeAfterTable(rows));
-    }
-    if (states.length) {
-        const rows = [];
-        for (const st of states)
-            for (const c of summarizeProps(st.props))
-                rows.push(added
-                    ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
-                    : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
-        if (rows.length)
-            body.push('', added ? 'Interactive states:' : 'Interactive-state changes:', '', added ? '| State | Property | Value |' : '| State | Property | Before → After |', '| --- | --- | --- |', ...rows);
-    }
+    // React component that rendered the element (added/retagged carry it on the dom
+    // finding) — surfaced first so a reviewer sees `Button (variant=primary)`.
+    if (dom?.component)
+        body.push('', `React component: ${renderComponent(dom.component)}`);
+    body.push(...styleSection(group.filter((f) => f.kind === 'style'), added));
+    body.push(...statesSection(group.filter((f) => f.kind === 'state'), added));
     // Existing element with nothing left to show (all derived) → skip; an
     // added/removed/retagged element always renders its heading.
     if (!dom && !body.length)
@@ -584,6 +614,10 @@ function cleanFindings(findings) {
     for (const group of groupByPath(findings)) {
         const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
         const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
+        // For an ADDED element the base style is a full (unset)→value snapshot, not a
+        // delta — so a forced-state value is never an "echo" of a base *change*; keep
+        // every state row (suppressing them would drop a real :hover/:focus value).
+        const isAdded = group.some((f) => f.kind === 'dom' && f.change === 'added');
         for (const f of group) {
             if (f.kind === 'dom') {
                 out.push(f);
@@ -591,7 +625,9 @@ function cleanFindings(findings) {
             }
             const props = f.kind === 'style'
                 ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
-                : f.props.filter((p) => !STATE_STRIP.has(p.prop) && !baseChanged.has(p.prop) && !(isNonValue(p.before) && isNonValue(p.after)));
+                : f.props.filter((p) => !STATE_STRIP.has(p.prop) &&
+                    (isAdded || !baseChanged.has(p.prop)) &&
+                    !(isNonValue(p.before) && isNonValue(p.after)));
             if (props.length)
                 out.push({ ...f, props });
         }

package/dist/routes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Best-effort route discovery for Next.js projects, so the coverage guard works
+ * out of the box: a generated spec calls this at run time, so `expected` reflects
+ * the app's *current* routes — a newly added page appears automatically, and the
+ * guard fails until it has a surface. No static list to keep in sync (that drift
+ * is the whole bug the guard exists to prevent).
+ *
+ * Covers the App Router (`app/`, `src/app/` — directories with a `page.*`) and the
+ * Pages Router (`pages/`, `src/pages/` — page files, minus `_app`/`_document`/`api`).
+ * Route groups `(group)` and parallel slots `@slot` are stripped; `[param]` /
+ * `[...catchall]` segments mark a route dynamic. It reads the filesystem only —
+ * no framework internals — so it's a heuristic, not a router; edit the generated
+ * spec if your routing does something exotic.
+ */
+export type DiscoveredRoute = {
+    /** Filename-safe surface key (`/` → `index`, `/blog/[slug]` → `blog-slug`). */
+    key: string;
+    /** URL path to navigate (`/`, `/about`, `/blog/[slug]`). */
+    path: string;
+    /** True when a segment is a `[param]` / `[...catchall]` — can't be navigated as-is. */
+    dynamic: boolean;
+};
+/**
+ * Discover a Next.js project's routes under `cwd` (default `process.cwd()`).
+ * Returns one entry per route, deduped by path (App Router wins a tie) and sorted.
+ * Empty array when no `app/` or `pages/` dir is found — the caller decides whether
+ * that means "not a Next project".
+ */
+export declare function discoverNextRoutes(cwd?: string): DiscoveredRoute[];

package/dist/routes.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const APP_PAGE_RE = /^page\.(?:js|jsx|ts|tsx|mdx)$/;
+const PAGES_EXT_RE = /\.(?:js|jsx|ts|tsx)$/;
+const isGroupOrSlot = (seg) => /^\(.*\)$/.test(seg) || seg.startsWith('@');
+const isDynamicSeg = (seg) => /\[.*\]/.test(seg);
+/** Filename-safe, readable key from a route path. */
+function toKey(routePath) {
+    if (routePath === '/')
+        return 'index';
+    const k = routePath
+        .replace(/^\//, '')
+        .replace(/\[\[?\.\.\.([^\]]+)\]\]?/g, 'all-$1') // [...x] / [[...x]] → all-x
+        .replace(/\[([^\]]+)\]/g, '$1') // [x] → x
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return k || 'index';
+}
+function makeRoute(segs) {
+    const routePath = segs.length ? '/' + segs.join('/') : '/';
+    return { key: toKey(routePath), path: routePath, dynamic: segs.some(isDynamicSeg) };
+}
+function readDir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return []; // missing/unreadable dir → no routes, never throw into a spec
+    }
+}
+/** App Router: a directory holding a `page.*` is a route; nest by sub-directory. */
+function appRoutes(appDir) {
+    const out = [];
+    const walk = (dir, segs) => {
+        const entries = readDir(dir);
+        if (entries.some((e) => e.isFile() && APP_PAGE_RE.test(e.name))) {
+            out.push(makeRoute(segs.filter((s) => !isGroupOrSlot(s))));
+        }
+        for (const e of entries)
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), [...segs, e.name]);
+    };
+    walk(appDir, []);
+    return out;
+}
+/** Pages Router: each page file is a route; `index` collapses to its directory. */
+function pagesRoutes(pagesDir) {
+    const out = [];
+    const walk = (dir, segs) => {
+        for (const e of readDir(dir)) {
+            if (e.isDirectory()) {
+                if (segs.length === 0 && e.name === 'api')
+                    continue; // API routes aren't pages
+                walk(path.join(dir, e.name), [...segs, e.name]);
+            }
+            else if (e.isFile() && PAGES_EXT_RE.test(e.name)) {
+                const base = e.name.replace(PAGES_EXT_RE, '');
+                if (base.startsWith('_'))
+                    continue; // _app, _document, _error
+                out.push(makeRoute(base === 'index' ? segs : [...segs, base]));
+            }
+        }
+    };
+    walk(pagesDir, []);
+    return out;
+}
+const firstExisting = (cwd, candidates) => candidates.map((d) => path.join(cwd, d)).find((p) => fs.existsSync(p));
+/**
+ * Discover a Next.js project's routes under `cwd` (default `process.cwd()`).
+ * Returns one entry per route, deduped by path (App Router wins a tie) and sorted.
+ * Empty array when no `app/` or `pages/` dir is found — the caller decides whether
+ * that means "not a Next project".
+ */
+export function discoverNextRoutes(cwd = process.cwd()) {
+    const appDir = firstExisting(cwd, ['app', 'src/app']);
+    const pagesDir = firstExisting(cwd, ['pages', 'src/pages']);
+    const found = [...(appDir ? appRoutes(appDir) : []), ...(pagesDir ? pagesRoutes(pagesDir) : [])];
+    const byPath = new Map();
+    for (const r of found)
+        if (!byPath.has(r.path))
+            byPath.set(r.path, r);
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}