stitch2 0.22.8 → 0.22.10

package/dist/audit.js

@@ -27,6 +27,27 @@ export async function audit(opts) {
             return;
         out.push({ severity, type, message, selector: sel(el), text: text(el) });
     };
+    const overflowClips = (el, ancestor) => {
+        // Overflow does not clip an absolutely/fixed positioned descendant whose containing block lies
+        // outside that ancestor. This differs from clip-path and matters for overlays in zero-sized wrappers.
+        for (let e = el; e && e !== ancestor; e = e.parentElement) {
+            const position = getComputedStyle(e).position;
+            if (position !== 'absolute' && position !== 'fixed')
+                continue;
+            let block = null;
+            for (let p = e.parentElement; p; p = p.parentElement) {
+                const c = getComputedStyle(p);
+                if ((position === 'absolute' && c.position !== 'static') || c.transform !== 'none' || c.filter !== 'none' || c.perspective !== 'none' ||
+                    /paint|layout|strict|content/.test(c.contain) || /transform|filter|perspective/.test(c.willChange)) {
+                    block = p;
+                    break;
+                }
+            }
+            if (!block || !ancestor.contains(block))
+                return false;
+        }
+        return true;
+    };
     const shown = (el) => {
         const cs = getComputedStyle(el);
         if (cs.display === 'none' || cs.visibility === 'hidden')
@@ -39,6 +60,23 @@ export async function audit(opts) {
         // Text kept for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
         if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
             return false;
+        // Opacity, clipping and content-visibility belong to ancestors too. These nodes can have large boxes
+        // outside the page without painting anything there (a tooltip at rest or an accessible file input).
+        if (!el.checkVisibility({ opacityProperty: true, visibilityProperty: true, contentVisibilityAuto: true }))
+            return false;
+        const topLayer = el.closest(':modal, :popover-open');
+        for (let e = el; e; e = e.parentElement) {
+            const c = getComputedStyle(e);
+            if (c.clip === 'rect(0px, 0px, 0px, 0px)' || /^inset\((50|100)%\)$/.test(c.clipPath))
+                return false;
+            if (e !== el && (c.overflowX !== 'visible' || c.overflowY !== 'visible')) {
+                const q = e.getBoundingClientRect();
+                if (((c.overflowX !== 'visible' && q.width <= 0) || (c.overflowY !== 'visible' && q.height <= 0)) && overflowClips(el, e))
+                    return false;
+            }
+            if (e === topLayer)
+                break;
+        }
         return r.width > 0 && r.height > 0;
     };
     const opacity = (el) => {
@@ -51,6 +89,86 @@ export async function audit(opts) {
     const inSvg = (el) => !!el.closest('svg') && el.tagName.toLowerCase() !== 'svg';
     const all = [...document.body.querySelectorAll('*')].filter((el) => shown(el) && !inSvg(el));
     const frame = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+    const intersect = (a, b) => ({
+        left: Math.max(a.left, b.left), top: Math.max(a.top, b.top),
+        right: Math.min(a.right, b.right), bottom: Math.min(a.bottom, b.bottom),
+    });
+    const area = (r, minimum = 0) => r.right - r.left > minimum && r.bottom - r.top > minimum;
+    // Inline controls have one rectangle per line; their bounding rectangle includes empty corners between
+    // lines. Compare the fragments the browser draws, clipped on each axis by their scrolling ancestors.
+    const visibleRects = (el) => {
+        let rects = [...el.getClientRects()];
+        const topLayer = el.closest(':modal, :popover-open');
+        if (topLayer === el)
+            return rects.filter((r) => area(r));
+        for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {
+            const c = getComputedStyle(e);
+            if ((c.overflowX !== 'visible' || c.overflowY !== 'visible') && overflowClips(el, e)) {
+                const r = e.getBoundingClientRect();
+                rects = rects.map((q) => intersect(q, {
+                    left: c.overflowX === 'visible' ? -Infinity : r.left,
+                    right: c.overflowX === 'visible' ? Infinity : r.right,
+                    top: c.overflowY === 'visible' ? -Infinity : r.top,
+                    bottom: c.overflowY === 'visible' ? Infinity : r.bottom,
+                }));
+            }
+            // Top-layer elements escape their ancestors' overflow, but their own scrolling still clips children.
+            if (e === topLayer)
+                break;
+        }
+        return rects.filter((r) => area(r));
+    };
+    const proseLink = (el) => {
+        if (!el.matches('a') || getComputedStyle(el).display !== 'inline' || el.closest('nav, header, [role=navigation], [role=tablist], [role=menu]'))
+            return false;
+        const context = el.closest('p, li, blockquote, dd, figcaption');
+        if (!context)
+            return false;
+        // WCAG's inline-target exception is for links within a sentence, not a list of standalone links.
+        const walker = document.createTreeWalker(context, NodeFilter.SHOW_TEXT);
+        for (let n = walker.nextNode(); n; n = walker.nextNode())
+            if (n.textContent.trim() && !n.parentElement?.closest('a, button'))
+                return true;
+        return false;
+    };
+    const verticalNavigationLink = (el) => {
+        if (!el.matches('a') || !el.closest('nav, [role=navigation]'))
+            return false;
+        const row = el.closest('li');
+        const list = row?.parentElement ?? el.parentElement;
+        if (!list)
+            return false;
+        const c = getComputedStyle(list);
+        // A vertical contents/menu list can contain sentence-length titles. Horizontal bars and tab rows
+        // retain their one-line label rule; wrapping them is not a substitute for responsive navigation.
+        return (c.display === 'block' && (row ? !getComputedStyle(row).display.startsWith('inline') : getComputedStyle(el).display === 'block')) ||
+            (c.display.includes('flex') && c.flexDirection.startsWith('column')) ||
+            (c.display.includes('grid') && c.gridTemplateColumns.split(/\s+/).length === 1);
+    };
+    const disclosureTextFits = (el) => {
+        if (!el.matches('button[aria-expanded]:not([aria-haspopup])'))
+            return false;
+        const c = getComputedStyle(el);
+        if (!['left', 'start'].includes(c.textAlign))
+            return false;
+        const r = el.getBoundingClientRect();
+        const top = r.top + parseFloat(c.borderTopWidth) + parseFloat(c.paddingTop);
+        const bottom = r.bottom - parseFloat(c.borderBottomWidth) - parseFloat(c.paddingBottom);
+        const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+        let found = false;
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            if (!n.textContent.trim() || !n.parentElement || !shown(n.parentElement))
+                continue;
+            const range = document.createRange();
+            range.selectNodeContents(n);
+            for (const q of range.getClientRects()) {
+                found = true;
+                if (q.top < top - 1 || q.bottom > bottom + 1)
+                    return false;
+            }
+        }
+        return found;
+    };
     // 1. Nothing past the screen edge, except inside deliberate horizontal scrollers (chip rows).
     if (document.documentElement.scrollWidth > W + 1)
         push('error', 'page-overflow', document.body, `The page scrolls sideways (${document.documentElement.scrollWidth}px wide)`);
@@ -111,6 +229,10 @@ export async function audit(opts) {
     for (const el of all) {
         if (!isLabel(el) || text(el).length > 40 || el.querySelector('p, div, li, ul, br'))
             continue;
+        // Prose links flow with their sentence; vertical contents titles and fitted disclosure headings can
+        // also wrap. Horizontal navigation, tabs and ordinary button labels retain their one-line rule.
+        if (proseLink(el) || verticalNavigationLink(el) || disclosureTextFits(el))
+            continue;
         // A control whose text sits in two or more elements (a list row's title and its meta line) is a composite
         // control, not a label: its lines are laid out on purpose.
         const holders = new Set();
@@ -156,15 +278,57 @@ export async function audit(opts) {
     });
     // Behind an open modal the page is inert and covered, so only the modal's own bars count.
     // An open modal: the element may be 0px itself when everything in it is fixed (Headless UI's Dialog).
-    const modal = [...document.querySelectorAll('[aria-modal="true"]')].find((m) => {
+    const modals = [...document.querySelectorAll('dialog:modal, [aria-modal="true"]')].filter((m) => {
         const cs = getComputedStyle(m);
         return cs.display !== 'none' && cs.visibility !== 'hidden' && [m, ...m.querySelectorAll('*')].some(shown);
     });
+    // Native dialogs enter the top layer in opening order, which need not match document order. Hit-testing
+    // their centres identifies the active one; focus also covers zero-sized ARIA modal wrappers.
+    const modal = modals.find((m) => {
+        const r = m.getBoundingClientRect();
+        const hit = document.elementFromPoint(Math.max(0, Math.min(W - 1, r.left + r.width / 2)), Math.max(0, Math.min(innerHeight - 1, r.top + r.height / 2)));
+        return hit?.closest('dialog:modal, [aria-modal="true"]') === m;
+    }) ?? document.activeElement?.closest('dialog:modal, [aria-modal="true"]') ?? modals.at(-1);
     const outer = bars.filter((b) => !bars.some((o) => o !== b && o.contains(b)) && (!modal || modal.contains(b)));
     const content = all.filter((el) => !outer.some((b) => b.contains(el)) &&
         (!modal || modal.contains(el)) &&
         (ownText(el) || el.matches('button, input, select, textarea, img, svg, canvas, video')) &&
         opacity(el) > 0.5);
+    const painted = (el) => {
+        const cs = getComputedStyle(el);
+        return (ownText(el) ||
+            el.matches('svg, img, button, input') ||
+            !/rgba\(0, 0, 0, 0\)|transparent/.test(cs.backgroundColor) ||
+            Number.parseFloat(cs.borderTopWidth) > 0);
+    };
+    const paintedParts = (bar) => [bar, ...bar.querySelectorAll('*')].filter((e) => shown(e) && !inSvg(e) && painted(e));
+    const barCovers = (bar, el, rect) => {
+        // Geometry alone cannot tell which thing is on top: a menu or a modal can overlap a header while
+        // painting in front of it. Sample the actual intersection and ask the browser about paint order.
+        // Pointer-events:none must not hide a genuinely covering bar from that test.
+        const styles = [bar, el].map((e) => ({ e: e, value: e.style.getPropertyValue('pointer-events'), priority: e.style.getPropertyPriority('pointer-events') }));
+        for (const { e } of styles)
+            e.style.setProperty('pointer-events', 'auto', 'important');
+        try {
+            for (const fx of [0.1, 0.5, 0.9])
+                for (const fy of [0.1, 0.5, 0.9]) {
+                    const x = rect.left + (rect.right - rect.left) * fx;
+                    const y = rect.top + (rect.bottom - rect.top) * fy;
+                    const hits = document.elementsFromPoint(x, y);
+                    const first = hits[0];
+                    if (first && bar.contains(first) && hits.some((hit) => el === hit || el.contains(hit)))
+                        return true;
+                }
+            return false;
+        }
+        finally {
+            for (const { e, value, priority } of styles)
+                if (value)
+                    e.style.setProperty('pointer-events', value, priority);
+                else
+                    e.style.removeProperty('pointer-events');
+        }
+    };
     const covered = async (edge) => {
         window.scrollTo(0, edge === 'bottom' ? document.documentElement.scrollHeight : 0);
         await frame();
@@ -174,28 +338,23 @@ export async function audit(opts) {
             const atEdge = edge === 'bottom' ? b.bottom >= H - 4 && b.top > H / 2 : b.top <= 4 && b.bottom < H / 2;
             if (!atEdge)
                 continue;
+            const drawn = paintedParts(bar).flatMap(visibleRects);
             for (const el of content) {
                 if (el.contains(bar))
                     continue;
-                const r = el.getBoundingClientRect();
-                const overlapY = Math.min(r.bottom, b.bottom) - Math.max(r.top, b.top);
-                const overlapX = Math.min(r.right, b.right) - Math.max(r.left, b.left);
-                if (overlapY > 4 && overlapX > 4)
+                const hidden = visibleRects(el).some((r) => drawn.some((q) => {
+                    const overlap = intersect(intersect(r, q), { left: 0, top: 0, right: W, bottom: H });
+                    return area(overlap, 4) && barCovers(bar, el, overlap);
+                }));
+                if (hidden)
                     push('error', `under-${edge}-bar`, el, `Hidden under the fixed ${edge} bar (“${text(bar).slice(0, 30) || bar.tagName.toLowerCase()}”) when scrolled to the ${edge} (add padding)`);
             }
         }
     };
     // 3b. Fixed bars never overlap one another, including what sticks out of them (a raised tab-bar button
     // reaching into a docked timer). Compares the painted parts: backgrounds, borders, text, icons, controls.
-    const painted = (el) => {
-        const cs = getComputedStyle(el);
-        return (ownText(el) ||
-            el.matches('svg, img, button, input') ||
-            !/rgba\(0, 0, 0, 0\)|transparent/.test(cs.backgroundColor) ||
-            Number.parseFloat(cs.borderTopWidth) > 0);
-    };
     const fixedBars = outer.filter((b) => getComputedStyle(b).position === 'fixed' && b.getBoundingClientRect().height < window.innerHeight * 0.8);
-    const parts = (bar) => [bar, ...bar.querySelectorAll('*')].filter((e) => shown(e) && !inSvg(e) && painted(e)).map((e) => e.getBoundingClientRect());
+    const parts = (bar) => paintedParts(bar).flatMap(visibleRects);
     for (const [i, a] of fixedBars.entries())
         for (const b of fixedBars.slice(i + 1)) {
             const hit = parts(a).some((r) => parts(b).some((q) => Math.min(r.right, q.right) - Math.max(r.left, q.left) > 2 && Math.min(r.bottom, q.bottom) - Math.max(r.top, q.top) > 2));
@@ -229,7 +388,7 @@ export async function audit(opts) {
     for (const el of interactive) {
         if (interactive.some((o) => o !== el && o.contains(el)))
             continue;
-        if (el.matches('a') && el.closest('p'))
+        if (proseLink(el))
             continue;
         const r = el.getBoundingClientRect();
         const min = Math.min(r.width, r.height);
@@ -262,34 +421,73 @@ export async function audit(opts) {
     const layer = layerOf;
     // The part of a control its scrolling or clipping ancestors show: a link scrolled out of a nav strip is not drawn
     // where its box would be.
-    const visibleBox = (el) => {
-        const r = el.getBoundingClientRect();
-        let { left, top, right, bottom } = r;
-        for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {
-            const cs = getComputedStyle(e);
-            if (cs.overflowX === 'visible' && cs.overflowY === 'visible')
-                continue;
-            const c = e.getBoundingClientRect();
-            if (cs.overflowX !== 'visible') {
-                left = Math.max(left, c.left);
-                right = Math.min(right, c.right);
-            }
-            if (cs.overflowY !== 'visible') {
-                top = Math.max(top, c.top);
-                bottom = Math.min(bottom, c.bottom);
-            }
+    const isEmptyOverlay = (el) => {
+        if (!['absolute', 'fixed'].includes(getComputedStyle(el).position) || text(el) || el.querySelector('svg, img, canvas, video, input'))
+            return false;
+        const c = getComputedStyle(el);
+        if (!/rgba\(0, 0, 0, 0\)|transparent/.test(c.backgroundColor) || c.backgroundImage !== 'none' || c.boxShadow !== 'none' ||
+            [c.borderTopWidth, c.borderRightWidth, c.borderBottomWidth, c.borderLeftWidth].some((v) => parseFloat(v) > 0))
+            return false;
+        for (const pseudo of ['::before', '::after']) {
+            const p = getComputedStyle(el, pseudo);
+            if (p.content !== 'none' && p.content !== 'normal' && p.display !== 'none')
+                return false;
+        }
+        return true;
+    };
+    const emptyOverlay = (el, other) => {
+        if (!emptyOverlays.has(el))
+            return false;
+        const r = el.getBoundingClientRect(), q = other.getBoundingClientRect();
+        // A stretched card/row action underneath its own secondary link is intentional. An empty control
+        // merely colliding with a neighbour, or a painted button covering another control, is still an error.
+        if (!(r.left <= q.left && r.right >= q.right && r.top <= q.top && r.bottom >= q.bottom && (r.width > q.width + 2 || r.height > q.height + 2)))
+            return false;
+        // Transparency alone does not prove that this pattern works: an invisible action above the link
+        // blocks it. Ask the browser whether the secondary control is actually reachable. Scroll the window
+        // only when necessary to hit-test an offscreen row; leave nested scroll positions and final scroll intact.
+        const before = { x: scrollX, y: scrollY };
+        try {
+            if (q.bottom <= 0 || q.top >= innerHeight)
+                window.scrollTo({ top: scrollY + q.top - innerHeight / 2, behavior: 'instant' });
+            return visibleRects(other).some((box) => {
+                const onScreen = intersect(box, { left: 0, top: 0, right: W, bottom: innerHeight });
+                if (!area(onScreen))
+                    return false;
+                const hit = document.elementFromPoint((onScreen.left + onScreen.right) / 2, (onScreen.top + onScreen.bottom) / 2);
+                return !!hit && other.contains(hit);
+            });
+        }
+        finally {
+            if (scrollX !== before.x || scrollY !== before.y)
+                window.scrollTo({ left: before.x, top: before.y, behavior: 'instant' });
         }
-        return { left, top, right, bottom };
+    };
+    const reservedInputAction = (field, action) => {
+        if (!field.matches('input') || !action.matches('button, [role=button]') || !field.parentElement?.contains(action))
+            return false;
+        if (!['text', 'search', 'email', 'url', 'tel', 'password', 'number'].includes(field.type))
+            return false;
+        const r = field.getBoundingClientRect(), q = action.getBoundingClientRect();
+        if (q.left < r.left - 1 || q.right > r.right + 1 || q.top < r.top - 1 || q.bottom > r.bottom + 1)
+            return false;
+        const c = getComputedStyle(field);
+        const left = r.left + parseFloat(c.borderLeftWidth) + parseFloat(c.paddingLeft);
+        const right = r.right - parseFloat(c.borderRightWidth) - parseFloat(c.paddingRight);
+        // A clear/reveal/list toggle may occupy padding reserved for it, but never the editable text area.
+        return q.right <= left + 1 || q.left >= right - 1;
     };
     // Behind an open modal (found above) only the modal's own controls count.
     const solid = interactive.filter((el) => opacity(el) > 0.05 && (!modal || modal.contains(el)));
+    const emptyOverlays = new Set(solid.filter(isEmptyOverlay));
+    const controlRects = new Map(solid.map((el) => [el, visibleRects(el)]));
     for (const [i, a] of solid.entries())
         for (const b of solid.slice(i + 1)) {
             if (a.contains(b) || b.contains(a) || layer(a) !== layer(b))
                 continue;
-            const r = visibleBox(a);
-            const q = visibleBox(b);
-            if (Math.min(r.right, q.right) - Math.max(r.left, q.left) > 2 && Math.min(r.bottom, q.bottom) - Math.max(r.top, q.top) > 2)
+            if (reservedInputAction(a, b) || reservedInputAction(b, a) || emptyOverlay(a, b) || emptyOverlay(b, a))
+                continue;
+            if (controlRects.get(a).some((r) => controlRects.get(b).some((q) => area(intersect(r, q), 2))))
                 push('error', 'control-overlap', b, `Overlaps another control (“${text(a).slice(0, 30) || a.getAttribute('aria-label') || a.tagName.toLowerCase()}”): give them room`);
         }
     // 4c. Text never collides with other text: labels of two controls overlapping (a long translation spilling into
@@ -508,7 +706,7 @@ export async function audit(opts) {
     // Compared like overlaps (4b): behind an open modal only its own controls, and within one layer.
     if (W < 600)
         for (const el of solid) {
-            if (solid.some((o) => o !== el && o.contains(el)) || (el.matches('a') && el.closest('p')))
+            if (solid.some((o) => o !== el && o.contains(el)) || proseLink(el))
                 continue;
             const r = el.getBoundingClientRect();
             if (r.width >= 48 && r.height >= 48)

package/dist/cache.d.ts

@@ -0,0 +1,2 @@
+/** Content, not a directory's mtime: editing an imported stylesheet must invalidate its consumers. */
+export declare function fingerprintPaths(paths: string[]): string;

package/dist/cache.js

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/** Content, not a directory's mtime: editing an imported stylesheet must invalidate its consumers. */
+export function fingerprintPaths(paths) {
+    const hash = createHash('sha256');
+    const visited = new Set();
+    const visit = (path) => {
+        path = resolve(path);
+        if (visited.has(path))
+            return;
+        visited.add(path);
+        hash.update(JSON.stringify(path));
+        try {
+            const stat = statSync(path);
+            if (stat.isDirectory()) {
+                hash.update('directory');
+                for (const name of readdirSync(path).sort()) {
+                    if (name.startsWith('.') || name === 'node_modules')
+                        continue;
+                    visit(join(path, name));
+                }
+            }
+            else if (stat.isFile()) {
+                hash.update('file');
+                hash.update(readFileSync(path));
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            hash.update('missing');
+        }
+    };
+    paths.forEach(visit);
+    return hash.digest('hex');
+}

package/dist/check.js

@@ -16,9 +16,11 @@
  * Screens run four at a time; reruns only visit screens that changed since design/checks.json (or
  * everything DESIGN.md, the tokens, the components or the catalog changed since).
  */
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { chromium } from '@playwright/test';
+import { fingerprintPaths } from './cache.js';
 import { colourIssues } from './colours.js';
 import { CONFIG_FILE, checkWidths, config } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
@@ -61,36 +63,25 @@ const components = {};
 const stateRows = {};
 // Screens unchanged since the last green run keep their results when nothing they depend on changed
 // (DESIGN.md, tokens, components, the catalog): reruns then only visit what actually changed.
-const depFiles = ['DESIGN.md', 'tokens.css', 'tokens.json'];
-const depMtime = (p) => {
-    try {
-        return statSync(join(ROOT, p)).mtimeMs;
-    }
-    catch {
-        return 0;
-    }
-};
 let previous = {};
 try {
     previous = JSON.parse(readFileSync(join(ROOT, 'checks.json'), 'utf8'));
 }
 catch { }
-const currentDeps = Math.max(...depFiles.map(depMtime), depMtime(config.catalogDir), depMtime(join(config.catalogDir, 'catalog.html')), ...(CONFIG_FILE ? [depMtime(CONFIG_FILE)] : []));
-const depsChanged = !previous.checkedAt || (previous.depsMtime ?? 0) < currentDeps;
+const currentDeps = fingerprintPaths([
+    ...['DESIGN.md', 'tokens.css', 'tokens.json', 'components', config.catalogDir].map((p) => join(ROOT, p)),
+    ...(CONFIG_FILE ? [CONFIG_FILE] : []),
+    fileURLToPath(new URL('.', import.meta.url)),
+]);
 // Renders are the point of --shots: every screen is visited, nothing is skipped.
 // ...as are explicit locales: different flags check different things.
 const runKey = JSON.stringify({ locales, shots });
-const skipping = !shots && !depsChanged && previous.runKey !== undefined && previous.runKey === runKey;
-const screenMtime = (path) => {
-    try {
-        return statSync(join(ROOT, path)).mtimeMs;
-    }
-    catch {
-        return Infinity;
-    }
-};
-const checkedAt = previous.checkedAt ? Date.parse(previous.checkedAt) : 0;
-const todo = screens.filter((s) => !skipping || !previous.screens?.[s.path] || screenMtime(s.path) >= checkedAt);
+// Each screen remembers its own inputs. A filtered run cannot bless unvisited screens after a shared edit.
+const cacheKeys = Object.fromEntries(screens.map((s) => [
+    s.path, `${currentDeps}:${runKey}:${fingerprintPaths([join(ROOT, s.path)])}`,
+]));
+const todo = screens.filter((s) => shots || !previous.screens?.[s.path] || previous.cacheKeys?.[s.path] !== cacheKeys[s.path]
+    || previous.screens[s.path].some((i) => i.type === 'check-crashed'));
 for (const s of screens) {
     if (!todo.includes(s)) {
         results[s.path] = previous.screens[s.path];
@@ -272,7 +263,10 @@ async function shoot(page, s, theme, locale, at) {
 }
 const exists = new Set(listScreens().map((s) => s.path));
 const keep = (o) => Object.fromEntries(Object.entries(o).filter(([p]) => exists.has(p)));
-const allComponents = keep({ ...previous.components, ...components });
+const freshPreviousComponents = Object.fromEntries(Object.entries(previous.components ?? {})
+    .filter(([path]) => previous.cacheKeys?.[path]?.startsWith(`${currentDeps}:`)
+    && previous.cacheKeys[path].endsWith(`:${fingerprintPaths([join(ROOT, path)])}`)));
+const allComponents = keep({ ...freshPreviousComponents, ...components });
 // Archived versions are history: they do not vote on how a component should look.
 const archived = new Set(listScreens()
     .filter((s) => s.status === 'archived')
@@ -288,7 +282,7 @@ for (const s of screens) {
     for (const i of issues.filter((i) => i.severity === 'error'))
         console.log(`    ${i.type}: ${i.message}${i.text ? ` — “${i.text}”` : ''}`);
 }
-writeFileSync(join(ROOT, 'checks.json'), `${JSON.stringify({ checkedAt: new Date().toISOString(), depsMtime: currentDeps, runKey, screens: keep({ ...previous.screens, ...results }), components: allComponents }, null, 2)}\n`);
+writeFileSync(join(ROOT, 'checks.json'), `${JSON.stringify({ checkedAt: new Date().toISOString(), cacheKeys: keep({ ...previous.cacheKeys, ...cacheKeys }), screens: keep({ ...previous.screens, ...results }), components: allComponents }, null, 2)}\n`);
 console.log(`\n${screens.length} screens checked, ${errors} errors. Results in design/checks.json (badges on the canvas).`);
 if (strict && errors)
     process.exit(1);

package/dist/elements.js

@@ -37,14 +37,22 @@ export const screenLocale = () => globalThis.__stitch2?.lang;
  */
 let idCount = 0;
 const ID_REFS = ['for', 'aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns', 'aria-activedescendant', 'list'];
-function uniqueIds(content) {
+function uniqueIds(content, replacing) {
+    // The element's children are about to be replaced, not duplicated. Their IDs may also be
+    // referenced from outside the component (labels, descriptions and navigation anchors).
+    const occupied = new Set(Array.from(document.querySelectorAll('[id]'))
+        .filter((el) => !replacing.contains(el)).map((el) => el.id));
     const renamed = new Map();
     for (const el of Array.from(content.querySelectorAll('[id]'))) {
-        if (!document.getElementById(el.id))
+        if (!occupied.has(el.id))
             continue;
-        const next = el.id + '-s2-' + ++idCount;
+        let next;
+        do
+            next = el.id + '-s2-' + ++idCount;
+        while (occupied.has(next) || content.getElementById(next));
         renamed.set(el.id, next);
         el.id = next;
+        occupied.add(next);
     }
     if (!renamed.size)
         return;
@@ -95,7 +103,7 @@ export function defineElements(components, options) {
                         if (typeof props[key] === 'string' && !root.hasAttribute(`data-${key}`))
                             root.setAttribute(`data-${key}`, props[key]);
                 }
-                uniqueIds(t.content);
+                uniqueIds(t.content, this);
                 this.replaceWith(t.content);
                 if (options.after && !pending++)
                     queueMicrotask(() => {

package/dist/report.js

@@ -7,8 +7,10 @@
  */
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { chromium } from '@playwright/test';
-import { config } from './config.js';
+import { fingerprintPaths } from './cache.js';
+import { CONFIG_FILE, config } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, nameOf, } from './consistency.js';
 import { filterSnippet } from './report-filter.js';
 import { listScreens, ROOT } from './screens.js';
@@ -27,18 +29,17 @@ const KNOWN_FILE = join(out, 'known.json');
 const cached = existsSync(KNOWN_FILE)
     ? JSON.parse(readFileSync(KNOWN_FILE, 'utf8'))
     : {};
+const deps = fingerprintPaths([
+    ...['DESIGN.md', 'tokens.css', 'tokens.json', 'components', config.catalogDir].map((p) => join(ROOT, p)),
+    ...(CONFIG_FILE ? [CONFIG_FILE] : []),
+    fileURLToPath(new URL('.', import.meta.url)),
+]);
+const sourceKeys = Object.fromEntries(screens.map((s) => [s.path, fingerprintPaths([join(ROOT, s.path)])]));
 // A screen needs a visit when it is new, changed, or lacks crops for the requested kinds.
 const needsVisit = (path) => {
     const hit = cached[path];
-    if (!hit)
+    if (!hit || hit.deps !== deps || hit.sourceKey !== sourceKeys[path])
         return true;
-    try {
-        if (statSync(join(ROOT, path)).mtimeMs !== hit.mtime)
-            return true;
-    }
-    catch {
-        return true;
-    }
     if (!kinds.length)
         return !hit.kinds.includes('all');
     return !kinds.every((k) => hit.kinds.includes(k) || hit.kinds.includes('all'));
@@ -132,7 +133,8 @@ const runOne = async (s, worker) => {
             crops[kind] ??= {};
             crops[kind][s.path] = files;
         }
-        visitedKinds[s.path].add('all');
+        if (!kinds.length)
+            visitedKinds[s.path].add('all');
     }
     catch (e) {
         // A dead page must not kill the other workers: the screen keeps no cache entry and is retried next run.
@@ -163,7 +165,7 @@ for (const s of todo) {
         if (byPath[s.path])
             screenCrops[kind] = byPath[s.path];
     }
-    const prev = cached[s.path];
+    const prev = cached[s.path]?.deps === deps && cached[s.path]?.sourceKey === sourceKeys[s.path] ? cached[s.path] : undefined;
     const families = new Set([...(prev?.kinds ?? []), ...(visitedKinds[s.path] ?? [])]);
     if (!kinds.length)
         families.add('all');
@@ -173,6 +175,8 @@ for (const s of todo) {
     try {
         next[s.path] = {
             mtime: statSync(join(ROOT, s.path)).mtimeMs,
+            deps,
+            sourceKey: sourceKeys[s.path],
             components: known[s.path],
             kinds: [...families],
             crops: { ...(prev?.crops ?? {}), ...screenCrops },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.22.8",
+  "version": "0.22.10",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -69,6 +69,22 @@ References, read before the first screen:
    An issue tagged with a width ("at 1024px: …") breaks at an edge of the windows the variant covers: fix it with a
    responsive rule in the screen, or a new variant when the layout's structure has to change (screens.md, Widths).
    Widths include the breakpoints inside the range; `narrow-layout` is a phone column left in a wide window.
+   Overlap checks compare the drawn fragments of wrapped inline controls, not the empty corners of their
+   bounding boxes. For fixed bars, the browser's paint order decides coverage: a menu painted in front of a
+   header is not hidden by it. Native modal dialogs and ARIA modals limit coverage and control comparisons
+   to the active dialog. Transparent hints, fully clipped accessible inputs and content in zero-sized
+   overflow-clipped wrappers are not drawn controls. Positioned descendants whose containing block lies
+   outside that wrapper, and top-layer dialogs, remain checked because the wrapper does not clip them.
+   An empty, transparent stretched row/card action may sit under a secondary link; painted controls or
+   partially colliding neighbours still fail. Do not silence an overlap by hiding content or removing its
+   accessible label: inspect the visible state and fix actual collisions in the shared component.
+   Inline links within a prose sentence may wrap and receive WCAG's inline-target exception, including
+   sentences inside list items; standalone links do not. Titles in vertical contents/menu lists may wrap,
+   unlike horizontal navigation labels. An in-page disclosure (`aria-expanded`, without `aria-haspopup`)
+   may have a multiline heading when its height and padding fit the complete text. A text input's clear,
+   reveal or list-toggle button may overlap only padding reserved for it, never the editable text area.
+   Cached checks are invalidated when shared components, the catalog or the checker change. A filtered
+   rerun refreshes only those screens; it must not make unrelated screens' older checks appear current.
    Motion warnings: `motion-token` (a transition length DESIGN.md doesn't name) and `reduced-motion` (something
    still moves when the person asked for less); see motion.md. On the catalog, `state-*` warnings come from the
    States sheet (components.md, States).

package/skills/stitch2/references/components.md

@@ -61,6 +61,10 @@ never patch the bundle or restyle the element on a screen. Props are the element
 an empty attribute is true) and its content is children. A component the screens need but the app lacks is
 added to the app first, with the same name.
 
+Keep native field IDs and their external label, ARIA and fragment references stable when nesting components.
+`stitch2/elements` preserves IDs from the element being replaced; only real collisions outside that element
+are renamed, together with references inside the component. Test both cases when changing a shared form.
+
 ## Colours come from DESIGN.md
 
 Every colour on a screen and in a component is one of DESIGN.md's: a token class (`bg-surface`,

package/skills/stitch2-consistency/SKILL.md

@@ -52,6 +52,8 @@ make the next version.
 
 1. Re-run `stitch2 check` and `stitch2 consistency`: the fixed screens show "matches" in the report and no
    `reuse`/`consistency` warnings.
+   Changes to shared components or the catalog invalidate their cached checks. A filtered check does not
+   refresh screens it did not visit; run the full check before making a whole-project consistency claim.
 2. Tell the user, per component, which screens matched, which you fixed (and how: component used, component
    extended, new version), and which differ on purpose (drafts you left, with the reason). Point to the report
    on the canvas so they can see it.