stitch2 0.24.3 → 0.25.0

package/README.md

@@ -191,6 +191,27 @@ put a page into the state the design shows (open a sheet, start a workout). The
 an error on that version and the run goes on. When it opens a modal, wait for something inside it (a marked
 component): dialog roots are often zero-sized wrappers, which Playwright reports as hidden.
 
+### Does it look the same, and sit in the same place?
+
+Compare says which components are there. Two more commands take the same routes and ask what that cannot see: the
+words inside them, and where they land.
+
+- `stitch2 look [screen…]` pairs the texts of a screen and its app page by their words and reports the ones drawn
+  differently: font, size, weight, letter spacing, line height, colour, case, alignment, decoration. The same
+  difference on many texts is one line with a count and the app's tag and classes, so it can be found in the source.
+  Text on one side only (data differs between a mock-up and the app) is counted, not reported.
+- `stitch2 geometry [screen…]` pairs the boxes of shared components and texts the same way and reports a box that
+  has another size or left edge, two neighbours with another space between them, and a pair arranged differently
+  (a title beside its icon in the design, under it in the app). Vertical position alone is not compared, because
+  data of another length moves everything below it. A box in a row that holds text only one page has is not blamed
+  for being pushed sideways, and boxes of a list that shows the same items in another order are left out.
+
+Both run each version at the width it is drawn at, at both ends of its variant's width range and at every
+breakpoint inside it (the widths `check` renders): a title that fits at 1440px and wraps under its icon at 1024px
+shows up. `--width 360,1280` picks the widths, `--drawn` uses only the drawn width (a quick pass over everything),
+and `--strict` exits with an error when anything differs. Results are also written to `look.json` and
+`geometry.json` in the design folder.
+
 ### In your own tests: every language, every width
 
 The layout rules are a plain function you can run on any page, so an app's own Playwright tests can check what
@@ -270,6 +291,8 @@ layout first, then a shorter natural word, never a smaller type size.
 | `stitch2 approve <path or filter…>` | Approve variants (the user's decision); every earlier version is archived |
 | `stitch2 tokens` | Tokens from DESIGN.md |
 | `stitch2 compare [screen…]` | The live app against the approved screens (`app` in the config) |
+| `stitch2 look [screen…] [--width N,N \| --drawn]` | Text in the live app against the approved screens: font, size, weight, colour |
+| `stitch2 geometry [screen…] [--width N,N \| --drawn]` | Where things sit in the live app against the approved screens, at every width |
 | `stitch2 elements <entry>` | Bundle your components (`stitch2/elements`) for the screens |
 | `stitch2 lint` | Google's DESIGN.md linter |
 | `stitch2 localize [filter]` | Copies a screen's remote images into its `assets/` folder |

package/dist/boxes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Where things sit on a page, for stitch2 geometry: the box of every shared component (by its data-<prefix> marker)
+ * and of every piece of text, and the comparison of two pages' boxes. Boxes are paired by what they hold, not by
+ * where they are in the markup, so a wrapper the app adds does not matter and data that differs is skipped.
+ */
+/** A piece of a page that can be found again on another page with the same words in it. */
+export interface Box {
+    /** What it is, without its place: a component's marker and its first words, or a text's own words. */
+    sig: string;
+    /** "component" or "text". */
+    kind: 'component' | 'text';
+    /** For the report: “Save” or button “Save”. */
+    label: string;
+    /** A figure or a symbol on its own (3, 93.1%, ←): data, which the other page may hold in another place or not at all. */
+    data?: boolean;
+    /** Position on the page (scroll included) and size, in px. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Runs in the page: the box of every visible component and every element's own text, in document order. Self-contained. */
+export declare function boxes(prefix: string): Box[];
+export interface Mismatch {
+    /** What differs: the size of a box, its left edge, the space to its neighbour, or how the two are arranged. */
+    type: 'size' | 'position' | 'gap' | 'arrangement';
+    message: string;
+}
+export interface Compared {
+    mismatches: Mismatch[];
+    /** How many boxes were found on both pages. */
+    matched: number;
+    onlyDesign: number;
+    onlyApp: number;
+}
+/** How far apart two measurements may be before they differ: sub-pixel layout and rounding. */
+/** A text's width also takes in the space before or after it in its text node, which differs with how the markup is written. */
+export declare const TOLERANCE: {
+    place: number;
+    size: number;
+    textWidth: number;
+    height: number;
+    gap: number;
+};
+/**
+ * Pairs the boxes of two pages (the nth box with a given content on one is the nth on the other) and lists where
+ * the pairs differ: size, left edge, and the space between neighbours. Vertical position alone is not compared,
+ * because data of another length moves everything below it; the space between two neighbours is.
+ * Across a row, text that only one page has (a name, a balance) pushes its row-mates sideways for good reason, so
+ * left edges and sideways gaps are compared only where no such text shares the row.
+ */
+export declare function compareBoxes(design: Box[], app: Box[]): Compared;

package/dist/boxes.js

@@ -0,0 +1,195 @@
+/**
+ * Where things sit on a page, for stitch2 geometry: the box of every shared component (by its data-<prefix> marker)
+ * and of every piece of text, and the comparison of two pages' boxes. Boxes are paired by what they hold, not by
+ * where they are in the markup, so a wrapper the app adds does not matter and data that differs is skipped.
+ */
+/** Runs in the page: the box of every visible component and every element's own text, in document order. Self-contained. */
+export function boxes(prefix) {
+    const marker = `data-${prefix}`;
+    const out = [];
+    const flat = (s) => s.replace(/\s+/g, ' ').trim();
+    // Text kept for screen readers sits in a box a pixel wide with its overflow cut away: it is not drawn.
+    const clipped = (el) => {
+        for (let e = el; e && e !== document.body; e = e.parentElement) {
+            if (getComputedStyle(e).overflow === 'visible')
+                continue;
+            const r = e.getBoundingClientRect();
+            if (r.width < 2 || r.height < 2)
+                return true;
+        }
+        return false;
+    };
+    for (const el of document.body.querySelectorAll('*')) {
+        if (el.closest('script, style, noscript, template, option, svg'))
+            continue;
+        if (!el.checkVisibility({ opacityProperty: true, visibilityProperty: true }) || clipped(el))
+            continue;
+        const kind = el.getAttribute(marker);
+        if (kind) {
+            const r = el.getBoundingClientRect();
+            if (r.width >= 1 && r.height >= 1) {
+                const words = flat(el.textContent ?? '').slice(0, 24);
+                out.push({
+                    sig: `${kind}|${words}`,
+                    kind: 'component',
+                    label: words ? `${kind} “${words}”` : kind,
+                    x: r.left + window.scrollX,
+                    y: r.top + window.scrollY,
+                    w: r.width,
+                    h: r.height,
+                });
+            }
+        }
+        let words = '';
+        let left = Number.POSITIVE_INFINITY;
+        let top = Number.POSITIVE_INFINITY;
+        let right = Number.NEGATIVE_INFINITY;
+        let bottom = Number.NEGATIVE_INFINITY;
+        for (const n of el.childNodes) {
+            if (n.nodeType !== Node.TEXT_NODE || !flat(n.textContent ?? ''))
+                continue;
+            words += `${n.textContent ?? ''} `;
+            const range = document.createRange();
+            range.selectNodeContents(n);
+            const r = range.getBoundingClientRect();
+            if (r.width < 1 || r.height < 1)
+                continue;
+            left = Math.min(left, r.left);
+            top = Math.min(top, r.top);
+            right = Math.max(right, r.right);
+            bottom = Math.max(bottom, r.bottom);
+        }
+        words = flat(words);
+        if (!words || !Number.isFinite(left))
+            continue;
+        out.push({
+            sig: words.slice(0, 40),
+            kind: 'text',
+            data: !/\p{L}/u.test(words),
+            label: `“${words.slice(0, 28)}”`,
+            x: left + window.scrollX,
+            y: top + window.scrollY,
+            w: right - left,
+            h: bottom - top,
+        });
+    }
+    // A component with no words of its own (a picture, an icon) is known by the text that follows it: the title under it.
+    for (const [i, b] of out.entries()) {
+        if (b.kind !== 'component' || !b.sig.endsWith('|'))
+            continue;
+        const after = out.slice(i + 1).find((o) => o.kind === 'text');
+        if (!after)
+            continue;
+        b.sig = `${b.sig}→${after.sig.slice(0, 24)}`;
+        b.label = `${b.label} before ${after.label}`;
+    }
+    return out;
+}
+/** How far apart two measurements may be before they differ: sub-pixel layout and rounding. */
+/** A text's width also takes in the space before or after it in its text node, which differs with how the markup is written. */
+export const TOLERANCE = { place: 2, size: 2, textWidth: 4, height: 3, gap: 3 };
+const px = (v) => Math.round(v);
+/** How a box sits to the one before it: inside it (a component and what it holds), beside it or below it. */
+function relation(a, b) {
+    const inside = a.kind === 'component' && b.x >= a.x - 1 && b.y >= a.y - 1 && b.x + b.w <= a.x + a.w + 1 && b.y + b.h <= a.y + a.h + 1;
+    if (inside)
+        return { how: 'inside', dx: b.x - a.x, dy: b.y - a.y };
+    if (b.y >= a.y + a.h - 1)
+        return { how: 'below', dx: 0, dy: b.y - (a.y + a.h) };
+    if (b.x >= a.x + a.w - 1)
+        return { how: 'beside', dx: b.x - (a.x + a.w), dy: 0 };
+    return { how: 'overlap', dx: 0, dy: 0 };
+}
+/**
+ * Of the indexes a list of pairs points to, the ones that keep their order: the longest run that only goes up. A
+ * list that shows the same items in another order (recent runs, a feed) pairs many boxes with ones in other places;
+ * only the pairs in the same order are comparable, the rest are data.
+ */
+function keepOrdered(pair) {
+    const at = pair.flatMap((p, i) => (p === undefined ? [] : [i]));
+    const best = at.map(() => 1);
+    const from = at.map(() => -1);
+    let end = -1;
+    for (const [x, i] of at.entries()) {
+        for (let y = 0; y < x; y++)
+            if (pair[at[y]] < pair[i] && best[y] + 1 > best[x]) {
+                best[x] = best[y] + 1;
+                from[x] = y;
+            }
+        if (end < 0 || best[x] > best[end])
+            end = x;
+    }
+    const keep = new Set();
+    for (let x = end; x >= 0; x = from[x])
+        keep.add(at[x]);
+    return pair.map((p, i) => (keep.has(i) ? p : undefined));
+}
+/**
+ * Pairs the boxes of two pages (the nth box with a given content on one is the nth on the other) and lists where
+ * the pairs differ: size, left edge, and the space between neighbours. Vertical position alone is not compared,
+ * because data of another length moves everything below it; the space between two neighbours is.
+ * Across a row, text that only one page has (a name, a balance) pushes its row-mates sideways for good reason, so
+ * left edges and sideways gaps are compared only where no such text shares the row.
+ */
+export function compareBoxes(design, app) {
+    const key = (list) => {
+        const seen = new Map();
+        return list.map((b) => {
+            const i = seen.get(b.sig) ?? 0;
+            seen.set(b.sig, i + 1);
+            return `${b.sig}#${i}`;
+        });
+    };
+    const [dk, ak] = [key(design), key(app)];
+    const inApp = new Map(ak.map((k, i) => [k, i]));
+    const pair = keepOrdered(dk.map((k, i) => (design[i].data ? undefined : inApp.get(k))));
+    const paired = new Set(pair);
+    const loose = (list, keep) => list.filter((b, i) => b.kind === 'text' && !keep(i));
+    const looseDesign = loose(design, (i) => pair[i] !== undefined);
+    const looseApp = loose(app, (i) => paired.has(i));
+    /** Whether text only one page has shares the row of this box, outside it: it can move the box sideways. */
+    const crowded = (list, b) => list.some((u) => u.y < b.y + b.h && u.y + u.h > b.y && !(u.x >= b.x - 1 && u.x + u.w <= b.x + b.w + 1));
+    const inside = (list, b) => list.some((u) => u.x >= b.x - 1 && u.y >= b.y - 1 && u.x + u.w <= b.x + b.w + 1 && u.y + u.h <= b.y + b.h + 1);
+    const mismatches = [];
+    let matched = 0;
+    for (const [i, d] of design.entries()) {
+        const j = pair[i];
+        if (j === undefined)
+            continue;
+        matched++;
+        const a = app[j];
+        // What a component holds sets its height: where one page has text the other lacks, only its width is compared.
+        const holds = d.kind === 'component' && (inside(looseDesign, d) || inside(looseApp, a));
+        const wide = d.kind === 'text' ? TOLERANCE.textWidth : TOLERANCE.size;
+        if (Math.abs(d.w - a.w) > wide || (!holds && Math.abs(d.h - a.h) > TOLERANCE.height))
+            mismatches.push({ type: 'size', message: `${d.label} is ${px(a.w)}×${px(a.h)} in the app, ${px(d.w)}×${px(d.h)} in the design` });
+        if (Math.abs(d.x - a.x) > TOLERANCE.place && !crowded(looseDesign, d) && !crowded(looseApp, a))
+            mismatches.push({ type: 'position', message: `${d.label} starts ${px(a.x)}px from the left in the app, ${px(d.x)}px in the design` });
+        const next = design[i + 1];
+        const k = pair[i + 1];
+        if (!next || k === undefined || k !== j + 1)
+            continue;
+        const [rd, ra] = [relation(d, next), relation(a, app[k])];
+        if (rd.how === 'overlap' || ra.how === 'overlap')
+            continue;
+        if (rd.how !== ra.how) {
+            mismatches.push({ type: 'arrangement', message: `${next.label} sits ${rd.how} ${d.label} in the design, ${ra.how} it in the app` });
+            continue;
+        }
+        if (rd.how === 'inside') {
+            const sideways = !crowded(looseDesign, next) && !crowded(looseApp, app[k]) && Math.abs(rd.dx - ra.dx) > TOLERANCE.gap;
+            if (sideways || Math.abs(rd.dy - ra.dy) > TOLERANCE.gap)
+                mismatches.push({
+                    type: 'gap',
+                    message: `${next.label} sits ${px(ra.dx)}px across and ${px(ra.dy)}px down inside ${d.label} in the app, ${px(rd.dx)}px and ${px(rd.dy)}px in the design`,
+                });
+            continue;
+        }
+        const [gd, ga] = rd.how === 'beside' ? [rd.dx, ra.dx] : [rd.dy, ra.dy];
+        if (rd.how === 'beside' && (crowded(looseDesign, d) || crowded(looseApp, a)))
+            continue;
+        if (Math.abs(gd - ga) > TOLERANCE.gap)
+            mismatches.push({ type: 'gap', message: `between ${d.label} and ${next.label}: ${px(ga)}px in the app, ${px(gd)}px in the design` });
+    }
+    return { mismatches, matched, onlyDesign: design.length - matched, onlyApp: app.length - matched };
+}

package/dist/canvas.html

@@ -654,6 +654,33 @@ function measure(f) {
 }
 
 const minHeight = (s) => (bigFrame(s) ? 800 : 844)
+/** Whether two addresses are the same page: the same place, whatever their query or hash say. */
+function samePage(a, b) {
+  try { const x = new URL(a), y = new URL(b); return x.origin === y.origin && x.pathname === y.pathname } catch { return false }
+}
+/**
+ * A page keeps growing after it loads: a table fetches its rows, an image arrives, a font swaps in. The measurements at load and in the first
+ * seconds catch what is there by then; this watches the page itself, so the frame is as tall as its page whenever the page changes size. The
+ * observer belongs to the loaded document and is replaced when the page reloads.
+ */
+function watchSize(f, iframe) {
+  f.sizeWatch?.disconnect()
+  f.sizeWatch = null
+  try {
+    const doc = iframe.contentDocument
+    const Observer = iframe.contentWindow?.ResizeObserver
+    if (!doc || !Observer) return
+    let queued
+    const watch = new Observer(() => {
+      clearTimeout(queued)
+      // Wait for the page to settle: a table draws many rows in a few frames, and one measure after them is enough.
+      queued = setTimeout(() => { if (f.sizeWatch === watch && f.iframe === iframe) measure(f) }, 80)
+    })
+    watch.observe(doc.documentElement)
+    if (doc.body) watch.observe(doc.body)
+    f.sizeWatch = watch
+  } catch {}
+}
 function setHeight(f, h) {
   h = Math.min(MAX_FRAME_HEIGHT, Math.max(minHeight(f.screen), h))
   HEIGHTS[`${f.screen.path}@${f.screen.width}`] = h
@@ -712,7 +739,9 @@ function mount(f) {
     // `load` also fires for the initial about:blank document. Compare the
     // loaded document itself with the current iframe target (which may have
     // changed for a language/theme reload while this mount was pending).
-    return f.iframe === iframe && iframe.contentDocument === doc && doc.readyState === 'complete' && doc.location.href === iframe.src
+    // The address is compared without its query: a page may rewrite its own
+    // (a table that keeps its state there), and that is still the same page.
+    return f.iframe === iframe && iframe.contentDocument === doc && doc.readyState === 'complete' && samePage(doc.location.href, iframe.src)
   }
   iframe.addEventListener('load', () => {
     if (f.iframe !== iframe) return
@@ -731,6 +760,7 @@ function mount(f) {
       }, 350)
       setTimeout(() => { if (f.iframe === iframe) measure(f) }, 1200)
       setTimeout(() => { if (f.iframe === iframe) measure(f) }, 2500)
+      watchSize(f, iframe)
     })()
   })
   iframe.src = frameSrc(f.screen)
@@ -739,6 +769,8 @@ function mount(f) {
 function unmount(f) {
   if (!f.iframe) return
   clearTimeout(f.reveal)
+  f.sizeWatch?.disconnect()
+  f.sizeWatch = null
   // Cleared first: a page still loading can fire its load event as it's removed.
   const iframe = f.iframe
   f.iframe = null

package/dist/cli.js

@@ -36,6 +36,8 @@ const COMMANDS = {
     type: ['type.ts', '[filter] [--json]  Every text style a screen uses, by type level'],
     tokens: ['tokens.ts', 'Generate tokens.css and tailwind.tokens.js from DESIGN.md, and the exports in the config'],
     compare: ['compare.ts', '[screen…] [--strict]  The live app against the approved screens ("app" in the config)'],
+    look: ['look.ts', '[screen…] [--width N,N | --drawn] [--strict]  Text in the live app against the approved screens: font, size, weight, colour…'],
+    geometry: ['geometry.ts', '[screen…] [--width N,N | --drawn] [--strict]  Where things sit in the live app against the approved screens, at every width'],
     elements: ['build-elements.ts', '<entry> [--out file]  Bundle the project\'s components (defineElements) for the screens'],
     lint: ['', "Google's DESIGN.md linter on the project's DESIGN.md"],
     i18n: [

package/dist/compare.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 /**
  * The live app against the approved screens. For every approved version whose screen has a route in the config's
  * "app" section, it opens the approved version and the app page at the same width and compares their structure:
@@ -29,29 +21,19 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * Usage: stitch2 compare [screen…] [--strict]
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { chromium } from '@playwright/test';
+import { join } from 'node:path';
 import { audit, LAYOUT_ERRORS } from './audit.js';
-import { BASE, config, widthRange } from './config.js';
+import { config, widthRange } from './config.js';
 import { collectComponents, collectOptions } from './consistency.js';
-import { listScreens, ROOT } from './screens.js';
+import { openLive } from './live.js';
+import { ROOT } from './screens.js';
 import { filterSnippet } from './report-filter.js';
-import { startServer } from './serve.js';
-const app = config.app;
-if (!app?.url || !app.routes) {
-    console.error('stitch2 compare: add an "app" section with "url" and "routes" to stitch2.config.json');
-    process.exit(1);
-}
 const args = process.argv.slice(2);
 const only = args.filter((a) => !a.startsWith('--'));
 const strict = args.includes('--strict');
-const routeOf = (screen) => {
-    const r = app.routes[screen];
-    return typeof r === 'string' ? { path: r } : r;
-};
-const versions = listScreens().filter((s) => s.kind === 'screen' && s.status === 'approved' && routeOf(s.screen) && (!only.length || only.includes(s.screen)));
-const unmapped = [...new Set(listScreens().filter((s) => s.status === 'approved' && !routeOf(s.screen)).map((s) => s.screen))];
+const live = await openLive('compare', only, 2);
+const { versions, unmapped } = live;
+const app = { url: live.appUrl };
 /** Runs in the page: every marked component in document order, and the top-level ones (not inside another). */
 function structure(prefix) {
     const marker = `data-${prefix}`;
@@ -79,61 +61,30 @@ function lcs(a, b) {
             d[i][j] = a[i - 1] === b[j - 1] ? d[i - 1][j - 1] + 1 : Math.max(d[i - 1][j], d[i][j - 1]);
     return d[a.length][b.length];
 }
-const load = async (file) => (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(BASE, file)).href))).default;
-const settle = async (page) => {
-    await page.waitForLoadState('networkidle', { timeout: 15_000 }).catch(() => { });
-    await page.waitForTimeout(800);
-};
 const out = join(ROOT, 'compare');
 mkdirSync(out, { recursive: true });
-const server = await startServer(0);
-const browser = await chromium.launch();
-const context = await browser.newContext({ deviceScaleFactor: 2 });
-const signIn = await context.newPage();
-if (app.signIn)
-    await (await load(app.signIn))({ page: signIn, url: app.url });
-await signIn.close();
-const design = await browser.newPage({ deviceScaleFactor: 2 });
-const signedIn = await context.newPage();
-// Sign-in and other public pages often redirect a signed-in visitor, so they get a context of their own.
-const signedOut = await (await browser.newContext({ deviceScaleFactor: 2 })).newPage();
 const results = [];
 const opts = collectOptions();
+/** The version that is open: its design page and its app page. */
+let pair;
 /**
  * One version against its app page at one width. The first call opens both pages (and runs prepare); the edges
  * then only resize them, which reflows the layout, keeps the prepared state (a sheet open) and saves the reloads.
  */
 async function compareAt(s, width, open) {
-    const route = routeOf(s.screen);
-    const live = route.signedOut ? signedOut : signedIn;
-    const url = new URL(route.path, app.url).href;
-    const height = width > 700 ? 800 : 844;
-    for (const p of [design, live])
-        await p.setViewportSize({ width, height });
     const findings = [];
-    if (!open)
-        await live.waitForTimeout(500);
-    else {
-        await design.goto(`http://127.0.0.1:${server.port}/${s.path}`).catch(() => { });
-        await settle(design);
-        await live.goto(url).catch(() => { });
-        await settle(live);
-    }
-    if (open && route.prepare) {
-        // A failing prepare is this version's error; the run goes on with the others.
-        try {
-            await (await load(route.prepare))({ page: live, url: app.url });
-        }
-        catch (e) {
-            const message = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            findings.push({ severity: 'error', type: 'prepare', message: `${route.prepare} failed: ${message}` });
-        }
-        await settle(live);
+    if (open) {
+        pair = await live.open(s);
+        if (pair.prepareError)
+            findings.push({ severity: 'error', type: 'prepare', message: pair.prepareError });
     }
-    const [d, a] = [await design.evaluate(structure, config.prefix), await live.evaluate(structure, config.prefix)];
+    else
+        await live.resize(width);
+    const { design, live: page, url } = pair;
+    const [d, a] = [await design.evaluate(structure, config.prefix), await page.evaluate(structure, config.prefix)];
     const [dc, ac] = [
         (await design.evaluate(collectComponents, opts)).components,
-        (await live.evaluate(collectComponents, opts)).components,
+        (await page.evaluate(collectComponents, opts)).components,
     ];
     const missing = Object.keys(d.counts).filter((k) => !a.counts[k]);
     const extra = Object.keys(a.counts).filter((k) => !d.counts[k]);
@@ -163,18 +114,18 @@ async function compareAt(s, width, open) {
     }
     // The same layout rules check runs on the screens, on the app: a control squeezed over another shows up here
     // even when the screen never drew that state.
-    for (const i of await live.evaluate(audit, { comfortable: config.comfortableTarget }))
+    for (const i of await page.evaluate(audit, { comfortable: config.comfortableTarget }))
         if (i.severity === 'error' && LAYOUT_ERRORS.includes(i.type))
             findings.push({ severity: 'error', type: i.type, message: `${i.message} (“${i.text}”)` });
     const kinds = Object.keys(d.counts);
     const match = kinds.length ? Math.round((100 * kinds.filter((k) => a.counts[k]).length) / kinds.length) : 100;
-    return { findings, match, url, live };
+    return { findings, match, url };
 }
 for (const s of versions) {
-    const { findings, match, url, live } = await compareAt(s, s.width, true);
+    const { findings, match, url } = await compareAt(s, s.width, true);
     const base = `${s.screen}-${s.device}`;
-    await design.screenshot({ path: join(out, `${base}-design.png`), fullPage: true });
-    await live.screenshot({ path: join(out, `${base}-app.png`), fullPage: true });
+    await pair.design.screenshot({ path: join(out, `${base}-design.png`), fullPage: true });
+    await pair.live.screenshot({ path: join(out, `${base}-app.png`), fullPage: true });
     const seen = new Set(findings.map((f) => `${f.type} ${f.message}`));
     for (const width of widthRange(s.device) ?? []) {
         if (width === s.width)
@@ -193,8 +144,7 @@ for (const s of versions) {
     for (const f of findings.filter((f) => f.severity === 'error'))
         console.log(`    ${f.type}: ${f.message}`);
 }
-await browser.close();
-server.close();
+await live.close();
 const esc = (v) => String(v ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 const rows = results
     .map((r) => {

package/dist/geometry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/geometry.js

@@ -0,0 +1,55 @@
+/**
+ * Where things sit in the live app against the approved screens. look compares how text is drawn; geometry compares
+ * where it and the shared components land: the size of each box, its left edge, and the space between neighbours
+ * (a title that wraps under its icon, a button pushed against the text above, a card a few pixels narrower). Boxes
+ * are paired by what they hold, so data that differs is skipped, and the page is measured at every width a layout can
+ * change at, not only the one the screen is drawn at.
+ *
+ * Each version is measured at the width it is drawn at, at both ends of its variant's width range and at every
+ * breakpoint inside it (the widths check renders); --width narrows that to the widths you give, and --drawn to the
+ * width each version is drawn at. The first differences in document order are shown (what sits further down often
+ * moves because of them); all are in <design>/geometry.json.
+ *
+ * Usage: stitch2 geometry [screen…] [--width 360,1280 | --drawn] [--strict]
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { boxes, compareBoxes } from './boxes.js';
+import { config, ROOT } from './config.js';
+import { openLive, screenArgs, scrollThrough, widthsFor } from './live.js';
+const SHOWN = 6;
+const args = process.argv.slice(2);
+const strict = args.includes('--strict');
+const live = await openLive('geometry', screenArgs(args));
+const results = [];
+let total = 0;
+const started = Date.now();
+for (const s of live.versions) {
+    const opened = await live.open(s);
+    const base = `${s.screen}-${s.device}`;
+    if (opened.prepareError) {
+        console.log(`✗ ${base}: ${opened.prepareError}`);
+        total++;
+    }
+    let at = s.width;
+    for (const width of widthsFor(s, args)) {
+        if (width !== at)
+            await live.resize(width);
+        at = width;
+        await scrollThrough(opened.design);
+        await scrollThrough(opened.live);
+        const found = compareBoxes(await opened.design.evaluate(boxes, config.prefix), await opened.live.evaluate(boxes, config.prefix));
+        total += found.mismatches.length;
+        results.push({ screen: s.screen, device: s.device, version: s.version, width, ...found });
+        console.log(`${found.mismatches.length ? '✗' : '✓'} ${`${base} @${width}`.padEnd(34)} ${found.matched} boxes matched${found.mismatches.length ? `, ${found.mismatches.length} differ` : ''}`);
+        for (const m of found.mismatches.slice(0, SHOWN))
+            console.log(`    ${m.type}: ${m.message}`);
+        if (found.mismatches.length > SHOWN)
+            console.log(`    … and ${found.mismatches.length - SHOWN} more`);
+    }
+}
+await live.close();
+writeFileSync(join(ROOT, 'geometry.json'), `${JSON.stringify({ measuredAt: new Date().toISOString(), url: live.appUrl, results }, null, 2)}\n`);
+console.log(`\n${live.versions.length} versions measured, ${total} differences, ${Math.round((Date.now() - started) / 1000)}s. Details: ${config.designDir}/geometry.json`);
+if (strict && total)
+    process.exit(1);

package/dist/live.d.ts

@@ -0,0 +1,55 @@
+import { type Page } from '@playwright/test';
+import { type Screen } from './screens.ts';
+export type Route = string | {
+    path: string;
+    prepare?: string;
+    signedOut?: boolean;
+};
+export interface Opened {
+    /** The approved version, served by the lab. */
+    design: Page;
+    /** The app page, signed in (or not, for a signedOut route) and prepared. */
+    live: Page;
+    /** The app page's address. */
+    url: string;
+    /** Set when the route's prepare script threw: the page is open, but not in the state the screen draws. */
+    prepareError?: string;
+}
+export interface Live {
+    /** The approved versions that have a route, narrowed to the screens named on the command line. */
+    versions: Screen[];
+    /** Screens with an approved version and no route: not compared at all. */
+    unmapped: string[];
+    /** The app's address from the config. */
+    appUrl: string;
+    /** Opens a version and its app page at the width the version is drawn at, and runs the route's prepare script. */
+    open(version: Screen): Promise<Opened>;
+    /** Resizes the pages that are open to another width; the layout reflows and the prepared state stays. */
+    resize(width: number): Promise<void>;
+    close(): Promise<void>;
+}
+/** Waits for the network to go quiet, then a little longer for what scripts draw after that. */
+export declare const settle: (page: Page) => Promise<void>;
+/** The viewport height a width is drawn at: a phone is taller than a window. */
+export declare const heightAt: (width: number) => 800 | 844;
+/**
+ * The widths a version is looked at: the width it is drawn at, both ends of its variant's range and every breakpoint
+ * inside it (the widths check renders). --width narrows them to the ones asked for, --drawn to the width each version
+ * is drawn at.
+ */
+export declare function widthsFor(s: Pick<Screen, 'width' | 'device'>, args?: string[]): number[];
+/** The numbers after --width (360,1280 or two flags), for widthsFor. */
+export declare function widthArgs(args: string[]): number[];
+/** The screens named on the command line: the words that are neither flags nor the value of --width. */
+export declare function screenArgs(args: string[]): string[];
+/**
+ * Walks a page from top to bottom and back, so what loads on scroll is there when it is measured, and takes the pointer
+ * off the page: a prepare script that clicked something leaves it there, and after a resize a button can end up under it
+ * and be measured in its hover colours.
+ */
+export declare function scrollThrough(page: Page): Promise<void>;
+/**
+ * Starts the lab server and a browser, signs in to the app and returns the pair opener. Exits with a message when the
+ * config has no "app" section; `command` names the command in it.
+ */
+export declare function openLive(command: string, only: string[], scale?: number): Promise<Live>;

package/dist/live.js

@@ -0,0 +1,147 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The pair the app commands work on: an approved screen and its live page, open side by side at the same width.
+ * compare, look and geometry all start here, so a route, its sign-in and its prepare script mean the same in each.
+ *
+ *   "app": {
+ *     "url": "http://localhost:4321",
+ *     "signIn": "design/app/sign-in.mjs",          // export default async ({ page, url }) => { … }
+ *     "routes": {
+ *       "home": "/app",
+ *       "exercise-detail": { "path": "/app/library", "prepare": "design/app/open-exercise.mjs" },
+ *       "sign-in": { "path": "/login", "signedOut": true }   // a page of its own, never signed in
+ *     }
+ *   }
+ */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from '@playwright/test';
+import { BASE, checkWidths, config } from './config.js';
+import { listScreens } from './screens.js';
+import { startServer } from './serve.js';
+const load = async (file) => (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(BASE, file)).href))).default;
+/** Waits for the network to go quiet, then a little longer for what scripts draw after that. */
+export const settle = async (page) => {
+    await page.waitForLoadState('networkidle', { timeout: 15_000 }).catch(() => { });
+    await page.waitForTimeout(800);
+};
+/** The viewport height a width is drawn at: a phone is taller than a window. */
+export const heightAt = (width) => (width > 700 ? 800 : 844);
+/**
+ * The widths a version is looked at: the width it is drawn at, both ends of its variant's range and every breakpoint
+ * inside it (the widths check renders). --width narrows them to the ones asked for, --drawn to the width each version
+ * is drawn at.
+ */
+export function widthsFor(s, args = []) {
+    const only = widthArgs(args);
+    if (only.length)
+        return only;
+    if (args.includes('--drawn'))
+        return [s.width];
+    return [...new Set([s.width, ...checkWidths(s.device)])].sort((a, b) => a - b);
+}
+/** The numbers after --width (360,1280 or two flags), for widthsFor. */
+export function widthArgs(args) {
+    const out = [];
+    for (const [i, a] of args.entries())
+        if (a === '--width' || a.startsWith('--width='))
+            for (const v of (a.includes('=') ? a.split('=')[1] : (args[i + 1] ?? '')).split(','))
+                if (Number(v) > 0)
+                    out.push(Number(v));
+    return out;
+}
+/** The screens named on the command line: the words that are neither flags nor the value of --width. */
+export function screenArgs(args) {
+    return args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--width');
+}
+/**
+ * Walks a page from top to bottom and back, so what loads on scroll is there when it is measured, and takes the pointer
+ * off the page: a prepare script that clicked something leaves it there, and after a resize a button can end up under it
+ * and be measured in its hover colours.
+ */
+export async function scrollThrough(page) {
+    await page.mouse.move(-1, -1);
+    await page.evaluate(async () => {
+        for (let y = 0; y < document.body.scrollHeight; y += 700) {
+            window.scrollTo(0, y);
+            await new Promise((r) => setTimeout(r, 60));
+        }
+        window.scrollTo(0, 0);
+    });
+    await page.waitForTimeout(300);
+}
+/**
+ * Starts the lab server and a browser, signs in to the app and returns the pair opener. Exits with a message when the
+ * config has no "app" section; `command` names the command in it.
+ */
+export async function openLive(command, only, scale = 1) {
+    const app = config.app;
+    if (!app?.url || !app.routes) {
+        console.error(`stitch2 ${command}: add an "app" section with "url" and "routes" to stitch2.config.json`);
+        process.exit(1);
+    }
+    const routeOf = (screen) => {
+        const r = app.routes[screen];
+        return typeof r === 'string' ? { path: r } : r;
+    };
+    const all = listScreens();
+    const versions = all.filter((s) => s.kind === 'screen' && s.status === 'approved' && routeOf(s.screen) && (!only.length || only.includes(s.screen)));
+    const unmapped = [...new Set(all.filter((s) => s.status === 'approved' && !routeOf(s.screen)).map((s) => s.screen))];
+    const server = await startServer(0);
+    const browser = await chromium.launch();
+    const context = await browser.newContext({ deviceScaleFactor: scale });
+    const signIn = await context.newPage();
+    if (app.signIn)
+        await (await load(app.signIn))({ page: signIn, url: app.url });
+    await signIn.close();
+    const design = await browser.newPage({ deviceScaleFactor: scale });
+    const signedIn = await context.newPage();
+    // Sign-in and other public pages often redirect a signed-in visitor, so they get a context of their own.
+    const signedOut = await (await browser.newContext({ deviceScaleFactor: scale })).newPage();
+    let current = signedIn;
+    return {
+        versions,
+        unmapped,
+        appUrl: app.url,
+        async open(s) {
+            const route = routeOf(s.screen);
+            const live = route.signedOut ? signedOut : signedIn;
+            current = live;
+            const url = new URL(route.path, app.url).href;
+            for (const p of [design, live])
+                await p.setViewportSize({ width: s.width, height: heightAt(s.width) });
+            await design.goto(`http://127.0.0.1:${server.port}/${s.path}`).catch(() => { });
+            await settle(design);
+            await live.goto(url).catch(() => { });
+            await settle(live);
+            let prepareError;
+            if (route.prepare) {
+                // A failing prepare is this version's error; the run goes on with the others.
+                try {
+                    await (await load(route.prepare))({ page: live, url: app.url });
+                }
+                catch (e) {
+                    prepareError = `${route.prepare} failed: ${(e instanceof Error ? e.message : String(e)).split('\n')[0]}`;
+                }
+                await settle(live);
+            }
+            return { design, live, url, ...(prepareError ? { prepareError } : {}) };
+        },
+        async resize(width) {
+            for (const p of [design, current])
+                await p.setViewportSize({ width, height: heightAt(width) });
+            await current.waitForTimeout(500);
+        },
+        async close() {
+            await browser.close();
+            server.close();
+        },
+    };
+}

package/dist/look.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/look.js

@@ -0,0 +1,55 @@
+/**
+ * How the live app's text looks against the approved screens. compare says which components are there; look says
+ * whether the words in them are drawn the same: for every piece of text the screen and the app share, the font,
+ * size, weight, letter spacing, line height, case, alignment, decoration and colour. Text is matched by its words
+ * (the nth time a phrase appears on the screen is the nth time it appears in the app), so data that differs between
+ * a mock-up and the app is left out: a phrase on one side only is counted, not reported.
+ *
+ * Each version is looked at the width it is drawn at, at both ends of its variant's width range and at every
+ * breakpoint inside it (the widths check renders); --width narrows that to the widths you give, and --drawn to the
+ * width each version is drawn at. The same difference on many texts is one line with a count. Writes
+ * <design>/look.json.
+ *
+ * Usage: stitch2 look [screen…] [--width 360,1280 | --drawn] [--strict]
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { config, ROOT } from './config.js';
+import { openLive, screenArgs, scrollThrough, widthsFor } from './live.js';
+import { lookAt, texts } from './looks.js';
+const args = process.argv.slice(2);
+const strict = args.includes('--strict');
+const live = await openLive('look', screenArgs(args));
+const results = [];
+let total = 0;
+const started = Date.now();
+for (const s of live.versions) {
+    const opened = await live.open(s);
+    const base = `${s.screen}-${s.device}`;
+    if (opened.prepareError) {
+        console.log(`✗ ${base}: ${opened.prepareError}`);
+        total++;
+    }
+    let at = s.width;
+    for (const width of widthsFor(s, args)) {
+        if (width !== at)
+            await live.resize(width);
+        at = width;
+        await scrollThrough(opened.design);
+        await scrollThrough(opened.live);
+        const found = lookAt(await opened.design.evaluate(texts, config.prefix), await opened.live.evaluate(texts, config.prefix));
+        total += found.differences.length;
+        results.push({ screen: s.screen, device: s.device, version: s.version, width, ...found });
+        const extra = found.onlyApp.length || found.onlyDesign.length ? ` (${found.onlyApp.length} only in the app, ${found.onlyDesign.length} only in the design)` : '';
+        console.log(`${found.differences.length ? '✗' : '✓'} ${`${base} @${width}`.padEnd(34)} ${found.matched} texts matched${extra}`);
+        for (const d of found.differences.slice(0, 8))
+            console.log(`    ${d.count > 1 ? `×${d.count} ` : ''}${d.what} — ${d.texts.map((t) => `“${t.slice(0, 28)}”`).join(', ')} (app: ${d.at})`);
+        if (found.differences.length > 8)
+            console.log(`    … and ${found.differences.length - 8} more kinds of difference`);
+    }
+}
+await live.close();
+writeFileSync(join(ROOT, 'look.json'), `${JSON.stringify({ lookedAt: new Date().toISOString(), url: live.appUrl, results }, null, 2)}\n`);
+console.log(`\n${live.versions.length} versions looked at, ${total} differences, ${Math.round((Date.now() - started) / 1000)}s. Details: ${config.designDir}/look.json`);
+if (strict && total)
+    process.exit(1);

package/dist/looks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Text as a page draws it, for stitch2 look: every element's own words with the font, size, weight, spacing, line
+ * height, colour, case, alignment and decoration they are drawn in, and the pairing of two pages' texts by their words.
+ */
+/** One piece of text and how it is drawn. */
+export interface Text {
+    text: string;
+    /** The first font family only: the fallbacks after it differ between a page and a component for good reason. */
+    family: string;
+    size: string;
+    weight: string;
+    style: string;
+    spacing: string;
+    leading: string;
+    colour: string;
+    transform: string;
+    align: string;
+    decoration: string;
+    /** The shared component it is in (its data-<prefix> value), or empty: the same words in two roles are two texts. */
+    inside: string;
+    /** A short description of the element, for the report: tag and classes. */
+    at: string;
+}
+/** Runs in the page: every element's own text, as drawn. Self-contained: Playwright sends this function's source. */
+export declare function texts(prefix: string): Text[];
+export interface Difference {
+    /** What differs, for every property that does: "size 14px in the design, 16px in the app". */
+    what: string;
+    /** How many texts differ in exactly this way. */
+    count: number;
+    /** Some of them. */
+    texts: string[];
+    /** The element in the app (tag and classes) of the first one, to find it in the source. */
+    at: string;
+}
+interface Looked {
+    differences: Difference[];
+    matched: number;
+    onlyDesign: string[];
+    onlyApp: string[];
+}
+/** Pairs the texts of the two pages by their words and lists how the pairs are drawn differently. */
+export declare function lookAt(design: Text[], app: Text[]): Looked;
+export {};

package/dist/looks.js

@@ -0,0 +1,147 @@
+/**
+ * Text as a page draws it, for stitch2 look: every element's own words with the font, size, weight, spacing, line
+ * height, colour, case, alignment and decoration they are drawn in, and the pairing of two pages' texts by their words.
+ */
+/** Runs in the page: every element's own text, as drawn. Self-contained: Playwright sends this function's source. */
+export function texts(prefix) {
+    const out = [];
+    const marker = '[data-' + prefix + ']';
+    const range = document.createRange();
+    // Text kept for screen readers sits in a box a pixel wide with its overflow cut away: it is not drawn.
+    const clipped = (el) => {
+        for (let e = el; e && e !== document.body; e = e.parentElement) {
+            if (getComputedStyle(e).overflow === 'visible')
+                continue;
+            const r = e.getBoundingClientRect();
+            if (r.width < 2 || r.height < 2)
+                return true;
+        }
+        return false;
+    };
+    // Colours come back in the form they were written in (rgb, color(srgb …), oklch…): the canvas turns each into rgba.
+    const canvas = document.createElement('canvas');
+    canvas.width = canvas.height = 1;
+    const paint = canvas.getContext('2d', { willReadFrequently: true });
+    const rgba = (c) => {
+        paint.clearRect(0, 0, 1, 1);
+        paint.fillStyle = '#000';
+        paint.fillStyle = c;
+        paint.fillRect(0, 0, 1, 1);
+        const [r, g, b, a] = paint.getImageData(0, 0, 1, 1).data;
+        return `rgba(${r}, ${g}, ${b}, ${Math.round(((a ?? 255) / 255) * 100) / 100})`;
+    };
+    for (const el of document.body.querySelectorAll('*')) {
+        if (el.closest('script, style, noscript, template, option'))
+            continue;
+        let own = '';
+        for (const n of el.childNodes)
+            if (n.nodeType === Node.TEXT_NODE)
+                own += `${n.textContent ?? ''} `;
+        const text = own.replace(/\s+/g, ' ').trim();
+        // A number or a symbol on its own (93.1%, $12, 3/4) is data: the same figure can stand in another place on the other page.
+        if (text.length < 2 || !/\p{L}/u.test(text))
+            continue;
+        if (!el.checkVisibility({ opacityProperty: true, visibilityProperty: true }) || clipped(el))
+            continue;
+        const r = el.getBoundingClientRect();
+        if (r.width < 2 || r.height < 2)
+            continue;
+        const cs = getComputedStyle(el);
+        // Alignment shows only where text runs over more than one line; on a single line, where it sits is geometry's.
+        let [top, bottom] = [Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY];
+        for (const n of el.childNodes) {
+            if (n.nodeType !== Node.TEXT_NODE || !(n.textContent ?? '').trim())
+                continue;
+            range.selectNodeContents(n);
+            const q = range.getBoundingClientRect();
+            top = Math.min(top, q.top);
+            bottom = Math.max(bottom, q.bottom);
+        }
+        const line = Number.parseFloat(cs.lineHeight) || Number.parseFloat(cs.fontSize) * 1.3;
+        const align = bottom - top > line * 1.5 ? { left: 'start', right: 'end' }[cs.textAlign] ?? cs.textAlign : '';
+        const classes = String(el.getAttribute('class') ?? '').trim().split(/\s+/).filter(Boolean).slice(0, 4).join('.');
+        out.push({
+            text: text.slice(0, 60),
+            family: cs.fontFamily.split(',')[0].replace(/["']/g, '').trim(),
+            size: cs.fontSize,
+            weight: cs.fontWeight,
+            style: cs.fontStyle,
+            spacing: cs.letterSpacing,
+            leading: cs.lineHeight,
+            colour: rgba(cs.color),
+            transform: cs.textTransform,
+            align,
+            decoration: cs.textDecorationLine,
+            inside: el.closest(marker)?.getAttribute('data-' + prefix) ?? '',
+            at: el.tagName.toLowerCase() + (classes ? `.${classes}` : ''),
+        });
+    }
+    return out;
+}
+const PROPS = [
+    ['family', 'font'],
+    ['size', 'size'],
+    ['weight', 'weight'],
+    ['style', 'font style'],
+    ['spacing', 'letter spacing'],
+    ['leading', 'line height'],
+    ['colour', 'colour'],
+    ['transform', 'case'],
+    ['align', 'alignment'],
+    ['decoration', 'decoration'],
+];
+const px = (v) => (v === 'normal' ? 0 : Number.parseFloat(v));
+const channels = (v) => (v.match(/[\d.]+/g) ?? []).map(Number);
+/** Whether two computed values are the same drawing: lengths within a hair, "normal" spacing as 0px. */
+function same(prop, a, b) {
+    if (a === b)
+        return true;
+    // Alignment is read only where the text runs over several lines; a text that wraps on one page and not on the other has none to compare.
+    if (prop === 'align' && (!a || !b))
+        return true;
+    if (prop === 'colour') {
+        const [x, y] = [channels(a), channels(b)];
+        return x.length === 4 && y.length === 4 && x.every((v, i) => Math.abs(v - y[i]) <= (i === 3 ? 0.02 : 1));
+    }
+    if (prop === 'size' || prop === 'spacing')
+        return Math.abs(px(a) - px(b)) < 0.06;
+    if (prop === 'leading')
+        return a !== 'normal' && b !== 'normal' && Math.abs(px(a) - px(b)) < 0.6;
+    return false;
+}
+/** Pairs the texts of the two pages by their words and lists how the pairs are drawn differently. */
+export function lookAt(design, app) {
+    const byText = new Map();
+    const key = (t) => t.inside + '|' + t.text;
+    for (const t of design)
+        byText.set(key(t), [...(byText.get(key(t)) ?? []), t]);
+    const used = new Map();
+    const groups = new Map();
+    const onlyApp = [];
+    let matched = 0;
+    for (const a of app) {
+        const n = used.get(key(a)) ?? 0;
+        const d = byText.get(key(a))?.[n];
+        if (!d) {
+            onlyApp.push(a.text);
+            continue;
+        }
+        used.set(key(a), n + 1);
+        matched++;
+        const what = PROPS.filter(([k]) => !same(k, d[k], a[k]))
+            .map(([k, label]) => `${label} ${d[k]} in the design, ${a[k]} in the app`)
+            .join('; ');
+        if (!what)
+            continue;
+        const g = groups.get(what) ?? { what, count: 0, texts: [], at: a.at };
+        g.count++;
+        if (g.texts.length < 4)
+            g.texts.push(a.text);
+        groups.set(what, g);
+    }
+    const onlyDesign = [];
+    for (const [k, list] of byText)
+        for (let i = used.get(k) ?? 0; i < list.length; i++)
+            onlyDesign.push(list[i].text);
+    return { differences: [...groups.values()].sort((x, y) => y.count - x.count), matched, onlyDesign, onlyApp };
+}

package/package.json

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

@@ -139,6 +139,8 @@ References, read before the first screen:
 | `screens [name] [--status s] [--json] [--strict]` | Every version with its status and the user's note, and anything that makes the current version unclear |
 | `approve <path or filter…>` | Approves variants for the user (only on their word); every earlier version of the screen on that device is archived |
 | `compare [screen…]` | The live app against the approved versions: missing or extra components, order, looks; a side-by-side report |
+| `look [screen…] [--width N,N \| --drawn]` | How the app's text is drawn against the approved versions (font, size, weight, spacing, colour), at every width |
+| `geometry [screen…] [--width N,N \| --drawn]` | Where the app's components and text sit against the approved versions: size, left edge, space between neighbours, arrangement |
 | `elements <entry>` | Bundles the app's components, turned into elements with `stitch2/elements`, for the screens |
 | `tokens` | `tokens.css` (colours, `.type-*` classes) and `tailwind.tokens.js` from DESIGN.md |
 | `lint` | Google's DESIGN.md linter |

package/skills/stitch2-app-sync/SKILL.md

@@ -54,6 +54,13 @@ Slots are for wiring. If what goes into a slot changes how the component looks,
   what order, how the measured ones look, **and the same layout errors as check** (overflow, fixed-overlap,
   control-overlap), so a control squeezed in the app shows up even when no screen drew it. Each version runs at
   its drawn width and at both edges of its width range; a finding seen only at an edge starts with "at <width>px:".
+- `stitch2 look` (the same routes): the words the screen and the app share, one by one, in the font, size, weight,
+  letter spacing, line height, colour, case, alignment and decoration they are drawn in. Text on one side only is
+  data and is counted, not reported.
+- `stitch2 geometry` (the same routes): the size and left edge of every shared component and text, the space
+  between neighbours, and whether two things sit beside each other or one under the other. It runs at the drawn
+  width, both ends of the range and every breakpoint inside it, so a title that wraps under its icon at 1024px
+  shows up. `--width 360,1280` picks widths and `--drawn` uses only the drawn one.
 - Both reports are snapshots that run only when called. The canvas sidebar says "N changed since" once the
   screens they cover have changed; run them again before relying on them.
 - Give every approved screen a route, and every state a `prepare` module that puts the app into it (a sheet
@@ -67,10 +74,16 @@ Read the findings as:
 | `extra` in compare | The app shows a component the design does not | Fine if it is a kept feature the design leaves out; otherwise design it first |
 | `control-overlap` / `overflow` in compare only | The app draws a state or control the canvas never showed | Show it on the canvas, fix the component there, then re-run both |
 | `look` differences | The component is styled differently in the app | The app is overriding the component: remove the override, or change the component |
+| `stitch2 look` reports a size, weight or colour | The app draws the words in a style the screen does not | Find the element from the tag and classes it prints; use the component's or the type level's class, not a hard-coded value |
+| `stitch2 geometry` reports `size` or `position` | A component is wider, narrower or shifted against the screen | A wrapper, padding or width in the app's markup; the component carries its own |
+| `stitch2 geometry` reports `gap` or `arrangement` | The space between two things, or how they are arranged, is not the screen's | The app's spacing or wrapping around the component; at one width only, a breakpoint is missing |
+| A difference on text that is data (a name, a count, a list in another order) | The mock-up and the app hold different data | Not a bug: make the route's `prepare` put the same data on screen, or read it as noise |
 
 ## Before you call it done
 
 1. Every screen you implemented is approved, and `stitch2 screens --strict` passes: one current version each.
 2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
 3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
-4. The user has seen the canvas versions of anything that changed how a component looks.
+4. `stitch2 look` and `stitch2 geometry` report nothing on the screens you touched, except differences you can
+   name as data.
+5. The user has seen the canvas versions of anything that changed how a component looks.