stitch2 0.13.1 → 0.15.0

package/dist/check.js

@@ -7,16 +7,17 @@
  * colours change there, so contrast is checked again, tagged with the theme.
  * Then again in each check language (i18n.ts: the pseudo-languages and the config's): layout problems that
  * show only there (a label running into its neighbour, text cut off, a control drawn backwards right to left),
- * and keys a locale has no translation for, tagged with the locale.
+ * and keys a locale has no translation for, tagged with the locale. Last, each variant at both ends of the widths
+ * it covers (config widths: mobile 360–599, desktop 1024–1920 by default), tagged with the width.
  * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
- *   --shots   also save page-tall renders to design/renders/ (one per theme)
+ *   --shots   also save page-tall renders to design/renders/ (one per theme, language and width edge)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
  */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { chromium } from '@playwright/test';
 import { colourIssues } from './colours.js';
-import { config } from './config.js';
+import { config, widthRange } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
 import { designThemes, typeLevels } from './design-md.js';
 import { checkLocales } from './i18n.js';
@@ -112,6 +113,24 @@ for (const s of screens) {
         if (shots)
             await shoot(s, undefined, locale);
     }
+    // The edges of the widths this variant covers (config widths), in its own theme and language: what breaks
+    // only when the window is narrower or wider than the frame it was drawn in.
+    const range = s.kind === 'screen' ? widthRange(s.device) : undefined;
+    for (const width of range ? [...new Set(range)].filter((w) => w !== s.width) : []) {
+        await page.setViewportSize({ width, height: 844 });
+        await page.goto(`http://127.0.0.1:${server.port}/${s.path}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
+        await page.waitForTimeout(600);
+        for (const i of await page.evaluate(audit, { comfortable: config.comfortableTarget })) {
+            const key = `${i.type} ${i.selector}`;
+            if (i.type === 'contrast' || seen.has(key))
+                continue;
+            seen.add(key);
+            themed.push({ ...i, width, message: `at ${width}px: ${i.message}` });
+        }
+        if (shots)
+            await shoot({ ...s, width }, undefined, undefined, `${width}px`);
+    }
+    await page.setViewportSize({ width: s.width, height: 844 });
     results[s.path] = [
         ...layout,
         ...themed,
@@ -129,11 +148,11 @@ async function setTheme(theme) {
     await page.waitForTimeout(150);
 }
 /** A page-tall render; renders in another theme or language than the screen's own get a --<theme> suffix. */
-async function shoot(s, theme, locale) {
+async function shoot(s, theme, locale, at) {
     const height = await page.evaluate(() => document.documentElement.scrollHeight);
     await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, 6000)) });
     mkdirSync(join(ROOT, 'renders'), { recursive: true });
-    const suffix = theme ?? locale;
+    const suffix = theme ?? locale ?? at;
     const name = s.path.replaceAll('/', '__').replace(/\.html$/, suffix ? `--${suffix}.png` : '.png');
     await page.screenshot({ path: join(ROOT, 'renders', name) });
     await page.setViewportSize({ width: s.width, height: 844 });

package/dist/compare.js

@@ -11,6 +11,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * "app" section, it opens the approved version and the app page at the same width and compares their structure:
  * which shared components appear (by their data-<prefix> marker), how many, in what order, and how the measured
  * ones look. Data differs between a mock-up and the app, so pixels are shown side by side, not diffed.
+ * Each version is compared at the width it is drawn at, then at both edges of its variant's width range (the
+ * config's "widths"): a layout that holds at 390px can still break at 1023px. Findings that only show at an edge
+ * carry that width ("at 1023px: …"); screenshots are taken at the drawn width.
  * Writes <design>/compare/index.html (the canvas opens it from its sidebar) and <design>/compare.json.
  *
  *   "app": {
@@ -30,9 +33,10 @@ import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { chromium } from '@playwright/test';
 import { audit, LAYOUT_ERRORS } from './audit.js';
-import { BASE, config } from './config.js';
+import { BASE, config, widthRange } from './config.js';
 import { collectComponents, collectOptions } from './consistency.js';
 import { listScreens, ROOT } from './screens.js';
+import { filterSnippet } from './report-filter.js';
 import { startServer } from './serve.js';
 const app = config.app;
 if (!app?.url || !app.routes) {
@@ -95,19 +99,27 @@ const signedIn = await context.newPage();
 const signedOut = await (await browser.newContext({ deviceScaleFactor: 2 })).newPage();
 const results = [];
 const opts = collectOptions();
-for (const s of versions) {
+/**
+ * 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 = s.width > 700 ? 800 : 844;
+    const height = width > 700 ? 800 : 844;
     for (const p of [design, live])
-        await p.setViewportSize({ width: s.width, height });
-    await design.goto(`http://127.0.0.1:${server.port}/${s.path}`).catch(() => { });
-    await settle(design);
-    await live.goto(url).catch(() => { });
-    await settle(live);
+        await p.setViewportSize({ width, height });
     const findings = [];
-    if (route.prepare) {
+    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 });
@@ -156,9 +168,25 @@ for (const s of versions) {
             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 };
+}
+for (const s of versions) {
+    const { findings, match, url, live } = 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 });
+    const seen = new Set(findings.map((f) => `${f.type} ${f.message}`));
+    for (const width of widthRange(s.device) ?? []) {
+        if (width === s.width)
+            continue;
+        for (const f of (await compareAt(s, width, false)).findings) {
+            const key = `${f.type} ${f.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            findings.push({ ...f, width, message: `at ${width}px: ${f.message}` });
+        }
+    }
     results.push({ screen: s.screen, device: s.device, version: s.version, design: s.path, url, findings, match });
     const errors = findings.filter((f) => f.severity === 'error').length;
     console.log(`${errors ? '✗' : '✓'} ${base.padEnd(30)} ${String(match).padStart(3)}% of the design's components · ${errors} errors, ${findings.length - errors} warnings`);
@@ -174,10 +202,10 @@ const rows = results
     const list = r.findings.length
         ? r.findings.map((f) => `<li class="${f.severity}"><b>${f.type}</b> ${esc(f.message)}</li>`).join('')
         : '<li class="ok">Matches the design’s structure.</li>';
-    return `<section><h2>${esc(r.screen)} · ${r.device} · ${r.version} <span>${r.match}%</span></h2><p><code>${esc(r.design)}</code> ↔ <a href="${esc(r.url)}">${esc(r.url)}</a></p><ul>${list}</ul><div class="imgs"><figure><figcaption>Approved design</figcaption><img src="${base}-design.png" alt=""></figure><figure><figcaption>App</figcaption><img src="${base}-app.png" alt=""></figure></div></section>`;
+    return `<section data-path="${esc(r.design)}"><h2>${esc(r.screen)} · ${r.device} · ${r.version} <span>${r.match}%</span></h2><p><code>${esc(r.design)}</code> ↔ <a href="${esc(r.url)}">${esc(r.url)}</a></p><ul>${list}</ul><div class="imgs"><figure><figcaption>Approved design</figcaption><img src="${base}-design.png" alt=""></figure><figure><figcaption>App</figcaption><img src="${base}-app.png" alt=""></figure></div></section>`;
 })
     .join('');
-writeFileSync(join(out, 'index.html'), `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>App comparison</title><style>body{background:#0b0b0d;color:#f4f4f5;font:14px/1.5 system-ui,sans-serif;margin:0}main{margin:0 auto;max-width:1400px;padding:32px}h1{font-size:22px}h2{font-size:17px;margin:32px 0 4px}h2 span{color:#a1a1aa;font-weight:400;margin-left:8px}code,a{color:#a1a1aa}ul{margin:8px 0;padding-left:18px}li.error b{color:#e5484d}li.warning b{color:#e5b54a}li.ok{color:#3fb27f}.imgs{display:flex;gap:16px;align-items:flex-start}figure{margin:0}figcaption{color:#a1a1aa;font-size:12px;margin-bottom:4px}img{border:1px solid #2e2e33;border-radius:8px;max-width:640px;width:100%}</style></head><body><main><h1>App comparison</h1><p>${new Date().toISOString()} · ${results.length} approved versions against ${esc(app.url)}${unmapped.length ? ` · no route for: ${esc(unmapped.join(', '))}` : ''}</p>${rows}</main></body></html>\n`);
+writeFileSync(join(out, 'index.html'), `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>App comparison</title><style>body{background:#0b0b0d;color:#f4f4f5;font:14px/1.5 system-ui,sans-serif;margin:0}main{margin:0 auto;max-width:1400px;padding:32px}h1{font-size:22px}h2{font-size:17px;margin:32px 0 4px}h2 span{color:#a1a1aa;font-weight:400;margin-left:8px}code,a{color:#a1a1aa}ul{margin:8px 0;padding-left:18px}li.error b{color:#e5484d}li.warning b{color:#e5b54a}li.ok{color:#3fb27f}.imgs{display:flex;gap:16px;align-items:flex-start}figure{margin:0}figcaption{color:#a1a1aa;font-size:12px;margin-bottom:4px}img{border:1px solid #2e2e33;border-radius:8px;max-width:640px;width:100%}</style></head><body><main><h1>App comparison</h1><p>${new Date().toISOString()} · ${results.length} approved versions against ${esc(app.url)}${unmapped.length ? ` · no route for: ${esc(unmapped.join(', '))}` : ''}</p><p id="stitch2-filter" hidden></p>${rows}</main>${filterSnippet}</body></html>\n`);
 writeFileSync(join(ROOT, 'compare.json'), `${JSON.stringify({ comparedAt: new Date().toISOString(), url: app.url, results, unmapped }, null, 2)}\n`);
 const total = results.reduce((n, r) => n + r.findings.filter((f) => f.severity === 'error').length, 0);
 console.log(`\n${results.length} versions compared, ${total} errors${unmapped.length ? `; no route for ${unmapped.join(', ')}` : ''}. Report: ${config.designDir}/compare/index.html`);

package/dist/config.d.ts

@@ -25,6 +25,12 @@ export interface LabConfig {
      * colours) and "light" when it has light-* colours. The canvas switches between them; check runs in each.
      */
     themes?: string[];
+    /**
+     * The window widths each variant covers, [narrowest, widest] in px, by device. A variant is drawn at its frame
+     * width; stitch2 check also renders it at both ends of its range, and the canvas can show it there. Defaults
+     * follow Google's window size classes: mobile 360–599 (compact), tablet 600–1023 (medium), desktop 1024–1920.
+     */
+    widths?: Record<string, [number, number]>;
     /** Skill folders a blind-trial sandbox copies. */
     skills: string[];
     /** Paths under designDir a sandbox leaves out besides screens (notes that would give the trial away). */
@@ -68,5 +74,9 @@ export declare const CONFIG_FILE: string | undefined;
 /** The folder paths in the config are relative to (the project root). */
 export declare const BASE: string;
 export declare const config: LabConfig;
+/** The widths a variant covers: [narrowest, widest] for its device, from the config or the defaults. */
+export declare const WIDTH_DEFAULTS: Record<string, [number, number]>;
+export declare const widthRanges: () => Record<string, [number, number]>;
+export declare const widthRange: (device: string) => [number, number] | undefined;
 /** The design folder, with a trailing slash. */
 export declare const ROOT: string;

package/dist/config.js

@@ -34,5 +34,9 @@ export const config = {
     ...DEFAULTS,
     ...(CONFIG_FILE ? JSON.parse(readFileSync(CONFIG_FILE, 'utf8')) : {}),
 };
+/** The widths a variant covers: [narrowest, widest] for its device, from the config or the defaults. */
+export const WIDTH_DEFAULTS = { mobile: [360, 599], tablet: [600, 1023], desktop: [1024, 1920] };
+export const widthRanges = () => ({ ...WIDTH_DEFAULTS, ...config.widths });
+export const widthRange = (device) => widthRanges()[device];
 /** The design folder, with a trailing slash. */
 export const ROOT = join(resolve(BASE, config.designDir), '/');

package/dist/consistency.js

@@ -147,7 +147,14 @@ export function collectComponents(opts) {
         if (!visible(el))
             continue;
         const g = el.getAttribute(marker);
-        const kind = g === 'button' ? `button:${el.getAttribute('data-variant') ?? 'primary'}:${el.getAttribute('data-size') ?? 'md'}` : g;
+        // A variant (data-variant, from the component's variant prop) is compared with the same variant only: the
+        // simple tab bar with the simple one, a folder section with folder sections.
+        const variant = el.getAttribute('data-variant');
+        const kind = g === 'button'
+            ? `button:${variant ?? 'primary'}:${el.getAttribute('data-size') ?? 'md'}`
+            : variant
+                ? `${g}:${variant}`
+                : g;
         if (!(g === 'button' && el.hasAttribute('disabled')))
             add(kind, el);
     }
@@ -248,7 +255,8 @@ export function consistencyIssues(known, paths) {
         out[path] = issues;
         const peers = (families.get(familyOf(path)) ?? []).filter((p) => p !== path);
         for (const [kind, sigs] of Object.entries(known[path] ?? {})) {
-            if (sigs.length > 1 && MEASURED.has(kind.split(':')[0]))
+            // The catalog shows every variant of a component side by side; a screen shows one.
+            if (sigs.length > 1 && MEASURED.has(kind.split(':')[0]) && !catalogs.includes(path))
                 issues.push({
                     severity: 'warning',
                     type: 'consistency',

package/dist/i18n-report.js

@@ -65,9 +65,16 @@ export function scan(html) {
         const skip = !!top?.skip || 'data-t-skip' in a || a.translate === 'no';
         for (const [name, value] of Object.entries(a)) {
             const keyed = name === 'data-t' || (name.startsWith('data-t-') && name !== 'data-t-args' && name !== 'data-t-skip');
-            if (keyed && value.includes('{'))
-                for (const m of value.matchAll(/\{([^{}|@][^{}|]*)(?:\|([^}]*))?\}/g))
-                    uses.push({ key: m[1], line, plural: plural || /(^|;)\s*count\s*=/.test(m[2] ?? '') });
+            if (keyed && value.includes('{')) {
+                // Innermost first, as the screens resolve them: {site.title|tab={nav.home}} uses both keys.
+                let rest = value;
+                for (let pass = 0; pass < 5 && rest.includes('{'); pass++)
+                    rest = rest.replace(/\{([^{}|]+)(?:\|([^{}]*))?\}/g, (_m, key, inline) => {
+                        if (!key.startsWith('@'))
+                            uses.push({ key, line, plural: plural || /(^|;)\s*count\s*=/.test(inline ?? '') });
+                        return 'x';
+                    });
+            }
             else if (name === 'data-t')
                 uses.push({ key: value, line, plural });
             else if (keyed && name !== 'data-t-slot')

package/dist/i18n.js

@@ -171,14 +171,22 @@ function runtime(p) {
                 let v;
                 if (a.value.includes('{')) {
                     // A template: each {key} or {key|name=value;name=value} becomes its message, the rest stays as written.
+                    // Templates nest ({site.title|tab={nav.home}}): the innermost resolve first, until none is left.
                     let whole = true;
-                    v = a.value.replace(/\{([^{}|]+)(?:\|([^}]*))?\}/g, (_m, key, inline) => {
-                        keys.push(key);
-                        const r = t(key, { ...args, ...parseArgs(inline, ';') });
-                        if (r === undefined)
-                            whole = false;
-                        return r ?? '';
-                    });
+                    // Resolved text waits as \u0001<n>\u0001, so braces inside a message are never read as keys.
+                    const done = [];
+                    const back = (s) => s.replace(/\u0001(\d+)\u0001/g, (_m, i) => done[Number(i)]);
+                    v = a.value;
+                    for (let pass = 0; pass < 5 && /\{[^{}|]+(?:\|[^{}]*)?\}/.test(v); pass++)
+                        v = v.replace(/\{([^{}|]+)(?:\|([^{}]*))?\}/g, (_m, key, inline) => {
+                            keys.push(key);
+                            const r = t(key, { ...args, ...parseArgs(inline && back(inline), ';') });
+                            if (r === undefined)
+                                whole = false;
+                            done.push(r ?? '');
+                            return `\u0001${done.length - 1}\u0001`;
+                        });
+                    v = back(v);
                     if (!whole)
                         v = undefined;
                 }

package/dist/languages-page.js

@@ -9,7 +9,7 @@ export function languagesPage(only) {
     const screens = listScreens()
         .filter((s) => (only ? s.path === only : s.kind === 'screen' && s.status !== 'archived'))
         .map((s) => ({ path: s.path, label: s.kind === 'components' ? 'Component catalog' : s.screen + ' ' + s.device + ' ' + s.version, width: s.width }));
-    const data = { screens, source: sourceLocale(), check: [sourceLocale(), ...checkLocales()], all: allLocales() };
+    const data = { only: !!only, screens, source: sourceLocale(), check: [sourceLocale(), ...checkLocales()], all: allLocales() };
     return `<!doctype html><html><head><meta charset="utf-8"><title>Languages</title><style>
   body { background: #0f0f11; color: #e4e4e7; font: 13px/1.4 system-ui, sans-serif; margin: 0; }
   header { align-items: center; background: #0f0f11; border-bottom: 1px solid #26262b; display: flex; gap: 12px; padding: 12px 140px 12px 20px; position: sticky; top: 0; z-index: 1; }
@@ -39,7 +39,20 @@ export function languagesPage(only) {
   <main></main>
   <script>
   const D = ${JSON.stringify(data).replaceAll('<', '\\u003c')}
-  const theme = localStorage.getItem('stitch2-theme')
+  let theme = localStorage.getItem('stitch2-theme')
+  // The canvas posts its filters: only the screens it shows, in its theme (see report-filter.ts).
+  let keep = null
+  let sent = ''
+  addEventListener('message', (e) => {
+    const f = e.origin === location.origin && e.data && e.data.stitch2Filter
+    if (!f || D.only || JSON.stringify(f) === sent) return
+    sent = JSON.stringify(f)
+    keep = new Set(f.paths)
+    theme = f.theme || theme
+    document.querySelector('h1').textContent = f.label ? 'Languages · ' + f.label : 'Languages'
+    render()
+  })
+  if (parent !== window) parent.postMessage({ stitch2Ready: true }, location.origin)
   let set = localStorage.getItem('stitch2-lang-set') ?? 'check'
   let zoom = Number(localStorage.getItem('stitch2-lang-zoom') ?? 0.4)
   const name = (l) => l === 'pseudo' ? 'Pseudo: long text' : l === 'pseudo-rtl' ? 'Pseudo: right to left' : (new Intl.DisplayNames([l], { type: 'language' }).of(l) ?? l) + (l === D.source ? ', source' : '')
@@ -52,8 +65,9 @@ export function languagesPage(only) {
     const langs = set === 'all' ? D.all : D.check
     const main = document.querySelector('main')
     main.innerHTML = ''
-    if (!D.screens.length) main.innerHTML = '<section><h2>No screens.</h2></section>'
-    for (const s of D.screens) {
+    const list = D.screens.filter((s) => !keep || keep.has(s.path))
+    if (!list.length) main.innerHTML = '<section><h2>' + (keep ? 'No screens match the canvas filters.' : 'No screens.') + '</h2></section>'
+    for (const s of list) {
       const sec = document.createElement('section')
       sec.innerHTML = '<h2></h2><div class="row"></div>'
       sec.querySelector('h2').textContent = s.label

package/dist/list.js

@@ -1,5 +1,5 @@
 /**
- * Lists every screen version with its status and the reviewer's note, for agents (and anyone without the
+ * Lists every screen version, variant by variant (mobile, desktop), with its status and the reviewer's note, for agents (and anyone without the
  * canvas open). Approved versions are the reference; review versions wait for the user; notes are feedback.
  * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json]
  */
@@ -9,9 +9,11 @@ const status = args.includes('--status') ? args[args.indexOf('--status') + 1] :
 const name = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--status');
 const rows = listScreens()
     .filter((s) => s.kind === 'screen' && (!status || s.status === status) && (!name || s.screen === name))
-    .sort((a, b) => a.screen.localeCompare(b.screen) || a.device.localeCompare(b.device) || b.mtime - a.mtime);
+    .sort((a, b) => a.screen.localeCompare(b.screen) ||
+    a.version.localeCompare(b.version, undefined, { numeric: true }) ||
+    b.device.localeCompare(a.device));
 if (args.includes('--json'))
     console.log(JSON.stringify(rows, null, 2));
 else
     for (const s of rows)
-        console.log(`${s.screen.padEnd(20)} ${s.device.padEnd(8)} ${s.version.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);
+        console.log(`${s.screen.padEnd(20)} ${s.version.padEnd(8)} ${s.device.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);

package/dist/report-filter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reports opened in the canvas follow its filters. The canvas posts { stitch2Filter: { paths, label } } to the
+ * report: every element with data-path outside paths hides, a data-group hides when none of its rows (other than
+ * data-ref ones, the catalog's reference) is left, and #stitch2-filter says what is shown. Opened on its own, a
+ * report shows everything. The report asks for the filters with { stitch2Ready: true } once its script runs.
+ */
+export declare const filterSnippet = "<style>[hidden] { display: none !important; } #stitch2-filter { color: #e5b54a; font-size: 13px; margin: 8px 0 0; }</style>\n<script>\naddEventListener('message', (e) => {\n  const f = e.origin === location.origin && e.data && e.data.stitch2Filter\n  if (!f) return\n  const keep = new Set(f.paths)\n  for (const el of document.querySelectorAll('[data-path]')) el.hidden = !keep.has(el.dataset.path)\n  for (const g of document.querySelectorAll('[data-group]'))\n    g.hidden = ![...g.querySelectorAll('[data-path]:not([data-ref])')].some((el) => !el.hidden)\n  const left = [...document.querySelectorAll('[data-path]:not([data-ref])')].filter((el) => !el.closest('[hidden]')).length\n  const note = document.getElementById('stitch2-filter')\n  if (!note) return\n  note.hidden = !f.label && left > 0\n  note.textContent = left ? 'Filtered as on the canvas: ' + (f.label || 'active screens') : 'Nothing in this report matches the canvas filters' + (f.label ? ': ' + f.label : '') + '.'\n})\nif (parent !== window) parent.postMessage({ stitch2Ready: true }, location.origin)\n</script>";

package/dist/report-filter.js

@@ -0,0 +1,23 @@
+/**
+ * Reports opened in the canvas follow its filters. The canvas posts { stitch2Filter: { paths, label } } to the
+ * report: every element with data-path outside paths hides, a data-group hides when none of its rows (other than
+ * data-ref ones, the catalog's reference) is left, and #stitch2-filter says what is shown. Opened on its own, a
+ * report shows everything. The report asks for the filters with { stitch2Ready: true } once its script runs.
+ */
+export const filterSnippet = `<style>[hidden] { display: none !important; } #stitch2-filter { color: #e5b54a; font-size: 13px; margin: 8px 0 0; }</style>
+<script>
+addEventListener('message', (e) => {
+  const f = e.origin === location.origin && e.data && e.data.stitch2Filter
+  if (!f) return
+  const keep = new Set(f.paths)
+  for (const el of document.querySelectorAll('[data-path]')) el.hidden = !keep.has(el.dataset.path)
+  for (const g of document.querySelectorAll('[data-group]'))
+    g.hidden = ![...g.querySelectorAll('[data-path]:not([data-ref])')].some((el) => !el.hidden)
+  const left = [...document.querySelectorAll('[data-path]:not([data-ref])')].filter((el) => !el.closest('[hidden]')).length
+  const note = document.getElementById('stitch2-filter')
+  if (!note) return
+  note.hidden = !f.label && left > 0
+  note.textContent = left ? 'Filtered as on the canvas: ' + (f.label || 'active screens') : 'Nothing in this report matches the canvas filters' + (f.label ? ': ' + f.label : '') + '.'
+})
+if (parent !== window) parent.postMessage({ stitch2Ready: true }, location.origin)
+</script>`;

package/dist/report.js

@@ -8,6 +8,7 @@ import { join } from 'node:path';
 import { chromium } from '@playwright/test';
 import { config } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, nameOf, } from './consistency.js';
+import { filterSnippet } from './report-filter.js';
 import { listScreens, ROOT } from './screens.js';
 import { startServer } from './serve.js';
 const kinds = process.argv.slice(2).filter((a) => !a.startsWith('--'));
@@ -92,10 +93,11 @@ const sections = Object.keys(crops)
             : note.length
                 ? note.map((i) => `<p class="bad">${esc(i.message)}</p>`).join('')
                 : '<b class="ok">matches</b>';
-        return `<div class="row"><div class="who"><b>${esc(s.kind === 'components' ? 'Component catalog' : `${s.screen} · ${s.device} · ${s.version}`)}</b><code>${esc(path)}</code>${verdict}</div><div class="imgs">${files.map((f) => `<img src="${esc(f)}" alt="" />`).join('')}</div></div>`;
+        const ref = path.startsWith(config.catalogDir) ? ' data-ref' : '';
+        return `<div class="row" data-path="${esc(path)}"${ref}><div class="who"><b>${esc(s.kind === 'components' ? 'Component catalog' : `${s.screen} · ${s.device} · ${s.version}`)}</b><code>${esc(path)}</code>${verdict}</div><div class="imgs">${files.map((f) => `<img src="${esc(f)}" alt="" />`).join('')}</div></div>`;
     })
         .join('');
-    return `<section><h2>${esc(nameOf(kind))} <span>${esc(kind)}</span></h2>${rows}</section>`;
+    return `<section data-group><h2>${esc(nameOf(kind))} <span>${esc(kind)}</span></h2>${rows}</section>`;
 })
     .join('');
 writeFileSync(join(out, 'index.html'), `<!doctype html><html lang="en"><head><meta charset="utf-8" /><title>Consistency report</title><style>
@@ -106,5 +108,5 @@ writeFileSync(join(out, 'index.html'), `<!doctype html><html lang="en"><head><me
   .who { display: grid; gap: 4px; align-content: start; min-width: 0; overflow-wrap: anywhere; } .imgs { display: flex; flex-wrap: wrap; gap: 12px; align-items: flex-start; min-width: 0; }
   img { background: #000; border: 1px solid #2e2e33; border-radius: 8px; max-width: 100%; width: 390px; }
   .ok { color: #3fb27f; } .ref { color: #a1a1aa; } .bad { color: #e5b54a; margin: 0; font-size: 13px; }
-</style></head><body><main><h1>Consistency report</h1><code>${new Date().toISOString()} · ${screens.length} active screens · reference: ${esc(config.catalogDir)}</code>${sections}</main></body></html>\n`);
+</style></head><body><main><h1>Consistency report</h1><code>${new Date().toISOString()} · ${screens.length} active screens · reference: ${esc(config.catalogDir)}</code><p id="stitch2-filter" hidden></p>${sections}</main>${filterSnippet}</body></html>\n`);
 console.log(`consistency report: ${join(out, 'index.html')} (${Object.keys(crops).length} components, ${screens.length} screens)`);

package/dist/serve.d.ts

@@ -1,3 +1,17 @@
+/** When a report was made and which of the files it covers changed after it; null when it has never run. */
+export interface ReportState {
+    at: number;
+    changed: string[];
+}
+/**
+ * The consistency report covers every screen that is not archived and the components; the app comparison covers
+ * the approved screens. A report is stale once one of those files is newer than it (a status change counts: it
+ * changes what the report covers). Only the design side is known: changes in the app itself don't show here.
+ */
+export declare function reportStates(): {
+    consistency: ReportState | null;
+    compare: ReportState | null;
+};
 export declare function startServer(port: number): Promise<{
     port: number;
     close: () => void;

package/dist/serve.js

@@ -1,14 +1,15 @@
 /**
  * The stitch2 server: the canvas at /, DESIGN.md drawn at /design, screens side by side per language at /languages, the screen list at /api/screens
- * (POST /api/screens/meta sets a version's status or note), check results at /api/checks, live-reload events
- * at /events, and every file under design/ by its path. Local only (127.0.0.1).
+ * (POST /api/screens/meta sets a version's status or note), check results at /api/checks, when the reports were
+ * made and what changed since at /api/reports, live-reload events at /events, and every file under design/ by its
+ * path. Local only (127.0.0.1).
  * Usage: stitch2 canvas   (PORT=4400 by default)
  */
-import { existsSync, readFileSync, statSync, watch } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, watch } from 'node:fs';
 import { createServer } from 'node:http';
 import { dirname, extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CONFIG_FILE, config } from './config.js';
+import { CONFIG_FILE, config, widthRanges } from './config.js';
 import { designThemes } from './design-md.js';
 import { allLocales, localeScript, sourceLocale } from './i18n.js';
 import { designPage } from './design-page.js';
@@ -28,6 +29,33 @@ function inlineTailwind(html, file) {
     });
 }
 import { listScreens, ROOT, STATUSES, tag, writeMeta } from './screens.js';
+/**
+ * The consistency report covers every screen that is not archived and the components; the app comparison covers
+ * the approved screens. A report is stale once one of those files is newer than it (a status change counts: it
+ * changes what the report covers). Only the design side is known: changes in the app itself don't show here.
+ */
+export function reportStates() {
+    const screens = listScreens();
+    const components = (() => {
+        const dir = join(ROOT, 'components');
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => /\.(js|mjs|css)$/.test(f))
+            .map((f) => ({ path: `components/${f}`, mtime: statSync(join(dir, f)).mtimeMs }));
+    })();
+    const state = (file, covered) => {
+        const report = join(ROOT, file);
+        if (!existsSync(report))
+            return null;
+        const at = statSync(report).mtimeMs;
+        return { at, changed: covered.filter((f) => f.mtime > at).map((f) => f.path) };
+    };
+    return {
+        consistency: state('consistency/index.html', [...screens.filter((s) => s.status !== 'archived'), ...components]),
+        compare: state('compare/index.html', screens.filter((s) => s.kind === 'screen' && s.status === 'approved')),
+    };
+}
 const CANVAS = fileURLToPath(new URL('./canvas.html', import.meta.url));
 const TYPES = {
     '.html': 'text/html; charset=utf-8',
@@ -121,9 +149,11 @@ export function startServer(port) {
             return;
         }
         if (url.pathname === '/api/config')
-            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale() });
+            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale(), widths: widthRanges() });
         if (url.pathname === '/api/screens')
             return json(listScreens());
+        if (url.pathname === '/api/reports')
+            return json(reportStates());
         if (url.pathname === '/api/checks') {
             const file = join(ROOT, 'checks.json');
             return json(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { screens: {} });

package/dist/setup.js

@@ -6,7 +6,7 @@
  * --name and --primary, DESIGN.md and its tokens. Existing files are never overwritten, so it is safe to re-run.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONFIG_FILE, CONFIG_NAME, config as current } from './config.js';
@@ -42,6 +42,16 @@ const skills = readdirSync(join(pkg, 'skills'));
 const linked = [];
 for (const dir of skillDirs) {
     mkdirSync(resolve(project, dir), { recursive: true });
+    // A skill renamed or removed in a newer stitch2 leaves a link to nothing: remove it.
+    for (const s of readdirSync(resolve(project, dir))) {
+        const at = resolve(project, dir, s);
+        if (!lstatSync(at).isSymbolicLink() || existsSync(at))
+            continue;
+        if (!/(^|[\\/])stitch2[\\/]skills[\\/]/.test(readlinkSync(at)))
+            continue;
+        unlinkSync(at);
+        done.push(`removed ${join(dir, s)} (no longer in stitch2)`);
+    }
     for (const s of skills) {
         const at = join(dir, s);
         linked.push(at);

package/dist/typecheck.d.ts

@@ -13,6 +13,8 @@ export interface Issue {
     theme?: string;
     /** Set when the issue shows only in another language: the locale it was found in. */
     locale?: string;
+    /** Set when the issue shows only at another window width: the edge of its variant's range (config widths). */
+    width?: number;
 }
 export interface TextItem {
     selector: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.13.1",
+  "version": "0.15.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

@@ -24,7 +24,8 @@ References, read before the first screen:
 - [principles.md](references/principles.md): what makes a screen read well, and the review rubric.
 - [typography.md](references/typography.md): type levels and how to combine them; most polish is here.
 - [components.md](references/components.md): build from the shared components; the reuse ladder.
-- [screens.md](references/screens.md): screen names, versions, statuses, the user's approval and notes, desktop.
+- [screens.md](references/screens.md): screen names, versions and their variants (mobile, desktop), the widths
+  each variant covers, statuses, the user's approval and notes.
 - [google.md](references/google.md): Google's guidance (Material, Android, web.dev) as rules with numbers.
 - [guides.md](references/guides.md): the public sources behind the rules.
 
@@ -40,8 +41,9 @@ References, read before the first screen:
 3. **Hierarchy before markup.** Name the one thing the user came for, the single primary action (the only
    accent-filled element in its region), and what is secondary. Give every text element a type level and a
    colour before writing markup.
-4. **Build** the next version, `<screens>/<screen>/<device>-v<N>.html`, from the project's template (status
-   `draft`; never edit an approved version). Assemble it from the components; plain markup only where none
+4. **Build** the next version, `<screens>/<screen>/<device>-v<N>.html`, or a missing variant of an existing
+   version (another device, the same N), from the project's template (status `draft`; never edit an approved
+   variant). Assemble it from the components; plain markup only where none
    applies, with token classes, `.type-<level>` classes for text, the spacing scale, and the states DESIGN.md
    defines. When the config has `i18n`, mark every product string with its message key (`data-t`, see
    **stitch2-i18n**). Never add classes to a component to change how it looks, and never write a colour value (hex,
@@ -58,6 +60,8 @@ References, read before the first screen:
    screens, or in the screen when it is one element. Look at both renders (`--light.png`). With `i18n`, check
    also runs the screen in the pseudo-languages and the config's locales; fix what they flag as the
    **stitch2-i18n** skill says.
+   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).
 6. **Look and critique.** View the render in `<design>/renders/` (crop the first screenful). Score it with the
    rubric in principles.md, fix what fails, repeat 5–6 at most three times.
 7. **Hand over.** Set the version's status to `review`, point the user to it on the canvas, and report what
@@ -71,7 +75,7 @@ References, read before the first screen:
 |---|---|
 | `setup [--name N --primary #hex] [options]` | Sets a project up in one step; keeps every file that exists |
 | `canvas` | The canvas at http://localhost:4400: screens and versions, DESIGN.md, the consistency report, approval and notes |
-| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme and check language; `--shots` saves renders |
+| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme and check language, and at both ends of each variant's widths; `--shots` saves renders |
 | `i18n [filter] [--locale l] [--suggest]` | Message keys screens use that the source or a locale lacks, and text with no key (stitch2-i18n) |
 | `consistency [kind…]` | Every shared component cropped from every screen, next to the catalog's version |
 | `type [filter] [--json]` | Every text style a screen uses and the type level it matches |
@@ -82,11 +86,11 @@ References, read before the first screen:
 | `lint` | Google's DESIGN.md linter |
 | `localize [filter]` | Copies remote images a screen uses into its `assets/` folder |
 | `init`, `extract` | Build DESIGN.md from choices, or measure it from an existing site (stitch2-design-md) |
-| `sandbox create <dir> <brief.md>…`, `sandbox import <dir>` | Fresh-eyes versions from agents that see no other versions (stitch2-variants) |
+| `sandbox create <dir> <brief.md>…`, `sandbox import <dir>` | Fresh-eyes versions from agents that see no other versions (stitch2-alternatives) |
 
 ## Alternatives and fresh eyes
 
 When the user wants options or a new direction, or a design is stuck, do not iterate on the existing versions:
-use the **stitch2-variants** skill. Fresh agents in sandboxes design from the brief without seeing the other
+use the **stitch2-alternatives** skill. Fresh agents in sandboxes design from the brief without seeing the other
 versions, and their screens come back as new versions to compare on the canvas. The same skill tests changes to
 the skills or DESIGN.md.