stitch2 0.22.7 → 0.22.9

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/consistency.d.ts

@@ -21,12 +21,14 @@ export interface PageComponents {
         selector: string;
         text: string;
     }[];
+    /** Provenance declared by the page. App snapshots are faithful renders, not component implementations. */
+    source?: string;
 }
 export interface CollectOptions {
     /** Component marker: elements with data-<prefix>="name". */
     prefix: string;
     /** DESIGN.md's primary colour as [r, g, b]: filled buttons in it are primary buttons. */
-    primary: number[];
+    primary?: number[];
 }
 /** The options for collectComponents from the config and DESIGN.md's primary colour. */
 export declare function collectOptions(): CollectOptions;

package/dist/consistency.js

@@ -10,8 +10,31 @@ import { config } from './config.js';
 import { readDesign } from './design-md.js';
 /** The options for collectComponents from the config and DESIGN.md's primary colour. */
 export function collectOptions() {
-    const hex = (readDesign().colors.primary ?? '#000000').replace('#', '');
-    return { prefix: config.prefix, primary: [0, 2, 4].map((i) => Number.parseInt(hex.slice(i, i + 2), 16)) };
+    const design = readDesign();
+    // DESIGN.md projects created by stitch2 have `colors.primary`; projects that use a richer palette often name
+    // the same role and reference it from components.button-primary. Resolve that reference here. Falling back to
+    // black made every transparent element look like a primary button.
+    const component = design.components['button-primary']?.backgroundColor;
+    const ref = /^\{colors\.([\w.-]+)\}$/.exec(component ?? '')?.[1];
+    const value = design.colors.primary ?? (ref ? design.colors[ref] : undefined) ?? component;
+    const primary = parseColour(value);
+    return { prefix: config.prefix, ...(primary ? { primary } : {}) };
+}
+/** CSS colours accepted in DESIGN.md, represented as RGB for the page-side detector. */
+function parseColour(value) {
+    if (!value)
+        return undefined;
+    const hex = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(value.trim())?.[1];
+    if (hex) {
+        const expanded = hex.length === 3 ? hex.replace(/./g, (c) => c + c) : hex;
+        return [0, 2, 4].map((i) => Number.parseInt(expanded.slice(i, i + 2), 16));
+    }
+    const rgb = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/i.exec(value.trim());
+    if (!rgb)
+        return undefined;
+    return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])].every(Number.isFinite)
+        ? [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])]
+        : undefined;
 }
 /** Runs in the page. Plain JS on purpose: Playwright sends its source to the browser. */
 export function collectComponents(opts) {
@@ -73,11 +96,37 @@ export function collectComponents(opts) {
     });
     const iconSet = (root) => [...new Set(icons(root).map(([s]) => s))].join('+');
     const box = (el) => el.getBoundingClientRect();
-    const ember = (el) => getComputedStyle(el).backgroundColor.includes(opts.primary.join(', '));
+    const ember = (el) => {
+        if (!opts.primary)
+            return false;
+        const background = getComputedStyle(el).backgroundColor.trim();
+        // Computed sRGB backgrounds are rgb()/rgba() in supported browsers. Do not extract arbitrary numbers from
+        // oklch(), color-mix() or a CSS variable that did not resolve: a false primary match is worse than no match.
+        const values = /^rgba?\(/i.test(background) ? background.match(/[\d.]+/g)?.map(Number) ?? [] : [];
+        const alpha = values.length > 3 ? values[3] : 1;
+        return (alpha >= 0.05 &&
+            values.length >= 3 &&
+            opts.primary.every((value, i) => Math.abs(value - values[i]) <= 2));
+    };
     const visible = (el) => {
         const r = box(el);
         const c = getComputedStyle(el);
-        return r.width > 0 && r.height > 0 && c.visibility !== 'hidden' && c.display !== 'none';
+        if (r.width <= 0 || r.height <= 0 || c.visibility === 'hidden' || c.display === 'none')
+            return false;
+        // A closed <details> exposes only its summary. Its descendants can still have boxes in a static snapshot,
+        // especially when the snapshot was captured at a responsive breakpoint.
+        const closed = el.closest('details:not([open])');
+        if (closed && !closed.querySelector(':scope > summary')?.contains(el))
+            return false;
+        // Match audit/type checks: clipped screen-reader-only nodes and transparent ancestors are not drawn.
+        if (r.width <= 1 && r.height <= 1 && c.position === 'absolute')
+            return false;
+        if (c.clip === 'rect(0px, 0px, 0px, 0px)' || c.clipPath === 'inset(100%)')
+            return false;
+        let opacity = 1;
+        for (let e = el; e; e = e.parentElement)
+            opacity *= Number(getComputedStyle(e).opacity);
+        return opacity >= 0.05;
     };
     const sigOf = (kind, el) => {
         const c = getComputedStyle(el);
@@ -223,7 +272,8 @@ export function collectComponents(opts) {
             el.matches('h2, h3, h4, p, span, div, label'))
             found('section', el);
     }
-    return { components, handBuilt };
+    const source = document.querySelector(`meta[name="${opts.prefix}-source"]`)?.getAttribute('content') ?? undefined;
+    return { components, handBuilt, ...(source ? { source } : {}) };
 }
 /** The components whose look is measured and compared; the rest follow their content (see sigOf). */
 const MEASURED = new Set(['tab-bar', 'header', 'section', 'card', 'button', 'icon-button', 'chip']);
@@ -332,7 +382,9 @@ export function consistencyIssues(known, paths) {
 }
 /** Lab screens build catalog components with the components, not by hand. */
 export function reuseIssues(path, page) {
-    if (familyOf(path) !== 'screens')
+    // App snapshots preserve the exact product markup for visual review. They are not authored by the lab and cannot
+    // truthfully be rewritten to custom elements; only hand-authored lab screens are checked for component reuse.
+    if (familyOf(path) !== 'screens' || page.source === 'app')
         return [];
     return page.handBuilt.slice(0, 10).map((h) => ({
         severity: 'error',

package/dist/design-md.d.ts

@@ -24,6 +24,8 @@ export declare function motionDurations(design?: Design): number[];
  * colours are the dark theme and light-* colours make a light one.
  */
 export declare function designThemes(): string[];
+/** Keep an authored font stack intact, quoting only a single family whose name needs it. */
+export declare function cssFontStack(value: string | undefined): string;
 /** A type level in pixels, for comparing with computed styles. */
 export interface Level {
     name: string;

package/dist/design-md.js

@@ -55,19 +55,51 @@ export function designThemes() {
         return ['dark'];
     }
 }
+/** Convert a CSS length from DESIGN.md to pixels. CSS rem uses the 16px root; em and percentages use `relative`. */
+function cssLength(value, relative, unitless) {
+    if (value === undefined || value === null)
+        return 0;
+    if (typeof value === 'number')
+        return unitless === 'relative' ? value * relative : value;
+    const match = /^(-?(?:\d+|\d*\.\d+))\s*(px|rem|em|%)?$/i.exec(value.trim());
+    if (!match)
+        return 0;
+    const n = Number(match[1]);
+    switch ((match[2] ?? '').toLowerCase()) {
+        case 'rem':
+            return n * 16;
+        case 'em':
+        case '%':
+            return n * relative * (match[2] === '%' ? 0.01 : 1);
+        case 'px':
+            return n;
+        default:
+            return unitless === 'relative' ? n * relative : n;
+    }
+}
+/** Keep an authored font stack intact, quoting only a single family whose name needs it. */
+export function cssFontStack(value) {
+    const stack = value?.trim() ?? '';
+    if (!stack)
+        return '';
+    if (stack.includes(',') || /^['"].*['"]$/.test(stack) || /^[\w-]+$/.test(stack) || /^var\(/i.test(stack))
+        return stack;
+    return `"${stack.replaceAll('"', '\\"')}"`;
+}
 export function typeLevels(design = readDesign()) {
     return Object.entries(design.typography).map(([name, t]) => {
-        const size = Number.parseFloat(String(t.fontSize));
-        const lh = String(t.lineHeight);
+        const size = cssLength(t.fontSize, 16, 'px');
+        const lineHeightValue = t.lineHeight;
+        const lineHeight = typeof lineHeightValue === 'string' && lineHeightValue.trim().toLowerCase() === 'normal'
+            ? size * 1.2
+            : cssLength(lineHeightValue, size, 'relative');
         return {
             name,
             mono: /mono/i.test(t.fontFamily ?? ''),
             size,
             weight: Number(t.fontWeight ?? 400),
-            lineHeight: lh.endsWith('px') ? Number.parseFloat(lh) : Number.parseFloat(lh) * size,
-            tracking: t.letterSpacing?.endsWith('em')
-                ? Number.parseFloat(t.letterSpacing) * size
-                : Number.parseFloat(t.letterSpacing ?? '0') || 0,
+            lineHeight,
+            tracking: cssLength(t.letterSpacing, size, 'px'),
         };
     });
 }

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/dist/screens.d.ts

@@ -28,8 +28,8 @@ export interface Screen {
      */
     page: string;
     device: 'mobile' | 'tablet' | 'desktop';
-    /** Where the version came from: stitch, lab or trial. */
-    source: 'stitch' | 'lab' | 'trial';
+    /** Where the version came from: app snapshot, generated draft or authored design. */
+    source: 'stitch' | 'lab' | 'trial' | 'app';
     /** Short version label: "v3", "Stitch", "Trial 2". */
     version: string;
     status: Status;

package/dist/tokens.js

@@ -10,7 +10,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { argbFromHex, Hct, hexFromArgb, MaterialDynamicColors, SchemeContent, SchemeExpressive, SchemeFidelity, SchemeFruitSalad, SchemeMonochrome, SchemeNeutral, SchemeRainbow, SchemeTonalSpot, SchemeVibrant, } from '@material/material-color-utilities';
 import { config as lab } from './config.js';
-import { readDesign } from './design-md.js';
+import { cssFontStack, readDesign } from './design-md.js';
 import { POINTER, writeExports } from './exports.js';
 import { ROOT } from './screens.js';
 const SCHEMES = {
@@ -71,7 +71,7 @@ const typeDecls = {};
 const typeRules = Object.entries(design.typography).map(([name, t]) => {
     const fallback = `var(--${lab.prefix}-font-${/mono/i.test(t.fontFamily ?? '') ? 'mono' : 'sans'}-fallback)`;
     const decl = [
-        `font: ${t.fontWeight} ${t.fontSize}/${t.lineHeight} "${t.fontFamily}", ${fallback}`,
+        `font: ${t.fontWeight} ${t.fontSize}/${t.lineHeight} ${cssFontStack(t.fontFamily) || 'sans-serif'}, ${fallback}`,
         `letter-spacing: ${t.letterSpacing ?? '0em'}`,
         t.fontFeature ? `font-feature-settings: ${t.fontFeature}` : '',
         name.endsWith('-caps') ? 'text-transform: uppercase' : '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.22.7",
+  "version": "0.22.9",
   "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

@@ -76,6 +76,11 @@ series) is added to DESIGN.md first, with a line in the prose saying where it is
   a primary-filled button, a pill chip, a header icon button, a caps label). A screen that duplicates a
   component instead of using it is not handed over: use the component, or extend it (step 4 of the ladder)
   when it cannot do what the screen needs.
+- The reuse detector reports what is actually drawn: descendants of a closed `<details>`, screen-reader-only or
+  clipped nodes, and elements hidden by a transparent ancestor are ignored. This keeps collapsed menus and
+  accessibility-only labels from becoming false component errors. A faithful app snapshot marked with
+  `<meta name="<prefix>-source" content="app">` is a visual baseline, not a component implementation, so its
+  markup is not reuse-checked; make a new lab-authored version before editing the snapshot.
 - **consistency**: a component whose size, radius, font, icon set or icons differ from the catalog's version
   (or, without a catalog, from the majority of screens in its family), or that appears in two versions on one
   screen. `stitch2 consistency` shows the same as cropped images; see the stitch2-consistency skill.

package/skills/stitch2/references/screens.md

@@ -13,7 +13,7 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
   (`mobile-v3.html` and `desktop-v3.html` are v3). A new version takes the next free N across the screen's
   variants; a variant added to an existing version takes that version's N (a desktop for v3 is
   `desktop-v3.html`, never v4). A version may start with one variant and get the others later.
-  Its head carries `<p>-screen`, `<p>-page` (see Pages), `<p>-device` (mobile | desktop), `<p>-status`, `<p>-source` (stitch | lab),
+  Its head carries `<p>-screen`, `<p>-page` (see Pages), `<p>-device` (mobile | desktop), `<p>-status`, `<p>-source` (stitch | lab | app),
   `<p>-frame-width` (390 mobile, 1280 desktop) and, written by the user, `<p>-note`. Older files elsewhere
   carry the same tags.
 
@@ -22,6 +22,12 @@ It is not the document height: long pages still appear whole. In canvas frames a
 `vh`, `svh`, `dvh` and `lvh` keep this viewport height when the frame grows, so full-height sections
 do not create ever-growing gaps. Width responsiveness stays active.
 
+`source=app` means an unchanged capture of a running application's rendered DOM,
+not a hand-authored design. Layout and visual checks still apply; the `reuse`
+rule does not demand replacing its already-rendered framework components with
+lab elements. Keep the import URL as provenance. A new design based on a capture
+uses `source=lab` and the shared component catalog, not the snapshot exception.
+
 ## Pages and their screens
 
 A place in the app often has several states or steps: the workout with its number pad, its menu and its discard

package/skills/stitch2/references/typography.md

@@ -6,6 +6,9 @@ project's DESIGN.md defines the levels (front matter `typography`); `stitch2 tok
 `.type-<level>` class, `stitch2 check` warns about text that is not one of them, and `stitch2 type` lists every
 style a screen uses.
 
+Use CSS lengths for the type scale (`px`, `rem`, `em`); checks normalize them to rendered pixels
+using a 16px root. A font-family list stays a CSS stack, not one quoted family name.
+
 ## 1. A type scale is a short list of levels
 
 Google's DESIGN.md format suggests 9–15 levels, each fixing family, size, line height, weight and tracking

package/skills/stitch2-consistency/SKILL.md

@@ -40,6 +40,11 @@ majority of screens in the same family.
 | Two versions of one component on a screen | Pick the catalog's; if both are needed, they are two variants: add the variant to the component |
 | The catalog itself is missing the variant a screen needs | Add it to the component and the catalog first, then use it |
 
+The reuse check only considers what is drawn. Descendants of a closed `<details>`, clipped or screen-reader-only
+nodes, and elements hidden by a transparent ancestor are excluded. Screens imported as faithful app snapshots may
+declare `<meta name="<prefix>-source" content="app">`; those baselines are checked visually, but are not expected to
+contain the lab's custom elements. Create a new lab-authored version before changing one.
+
 Never fix consistency by editing one screen to imitate another by hand, and never edit an approved version:
 make the next version.
 
@@ -47,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.