stitch2 0.14.0 → 0.15.1

package/README.md

@@ -37,6 +37,7 @@ file that already exists. From there the agent spends its effort on the design.
   and status filters, your DESIGN.md drawn as tokens and rules, the component catalog, and an inspector to
   approve, archive or leave a note on a version. Live reload; copyable references to paste to an agent.
   With a light and a dark theme (DESIGN.md's `light-*` colours), a switch (`T`) shows every screen in either one.
+  A width switch (`W`) shows every screen at the narrowest or widest window its layout covers.
   With languages configured, a Language switch (`L`) shows every screen in one of them, and the Languages page
   shows a screen side by side in each.
   Pick mode (`P`) highlights any element of a screen and copies a reference with its source line, such as
@@ -44,7 +45,8 @@ file that already exists. From there the agent spends its effort on the design.
   several to copy at once or add to the version's note.
 - **Checks** (`stitch2 check`): content past the frame edge or out of its card, labels that wrap, text running into
   other text, labels cut short with an ellipsis, content under fixed bars, fixed bars that overlap each other, tap
-  targets (WCAG 2.2), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
+  targets (WCAG 2.2), all of it again at both ends of the window widths each layout covers (360 and 599 px for a
+  phone, 1024 and 1920 for desktop, or your own ranges), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
   large numbers in monospace, components built by hand, components that differ between screens, and colours
   written as values instead of DESIGN.md tokens. Google's guidelines (Material 3, Android's app quality
   guidelines, web.dev, Lighthouse) add warnings for text under 11 px, text closer than 16 px (24 px from 600 px)
@@ -153,7 +155,10 @@ what differs in structure: shared components the design has and the app lacks (o
 order, and how the measured ones look. Mock-ups and the app hold different data, so the screenshots are shown side
 by side in `design/compare/index.html` (the canvas links it) rather than diffed. It also runs check's layout
 rules on the app (content past the edge, fixed bars or controls overlapping), which catches a control the app
-squeezed in although no screen drew it. The `stitch2-app-sync` skill describes the workflow around it: a visible
+squeezed in although no screen drew it. Each version is then compared again at both edges of its variant’s width
+range (`widths` in the config), so a layout that holds at 390 px but breaks at 1023 px shows up as "at 1023px: …".
+Compare and the consistency report run only when you call them; the canvas sidebar shows when each last ran and,
+once screens it covers have changed since, how many (hover for the list). The `stitch2-app-sync` skill describes the workflow around it: a visible
 change goes component, canvas, approval, then app. Configure it in the config:
 
 ```json

package/config.schema.json

@@ -62,6 +62,11 @@
       "description": "Tap targets smaller than this (px) get a warning.",
       "default": 32
     },
+    "widths": {
+      "type": "object",
+      "description": "The window widths each variant covers, [narrowest, widest] in px, by device (mobile, tablet, desktop). check renders every variant at both ends; the canvas shows them. Defaults: mobile 360–599, tablet 600–1023, desktop 1024–1920.",
+      "additionalProperties": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }
+    },
     "themes": {
       "type": "array",
       "items": { "type": "string" },

package/dist/canvas.html

@@ -51,6 +51,7 @@
   .item.on { background: #2a1a12; color: var(--text); }
   .item .meta { color: var(--faint); font-size: 11px; margin-left: auto; white-space: nowrap; }
   .item.variant { padding-left: 30px; }
+  .item.stale .meta { color: var(--warn); }
   #inspector .version-actions { align-items: center; display: flex; flex-wrap: wrap; gap: 6px; margin: 0 0 10px; }
   #inspector .version-actions span { color: var(--muted); }
   #inspector .version-actions button { background: var(--panel2); border: 1px solid var(--edge); border-radius: 8px; cursor: pointer; padding: 3px 8px; }
@@ -129,6 +130,7 @@
     <details id="versionFilter" class="multi" hidden title="Show only the versions you pick (several at once), or all of them"><summary>All versions</summary><div class="menu"></div></details>
     <details id="variantFilter" class="multi" hidden title="Show only the variants you pick: mobile, desktop (several at once), or all of them"><summary>All variants</summary><div class="menu"></div></details>
     <select id="themeFilter" class="pick" hidden title="Show every screen in this theme (T)" aria-label="Theme"></select>
+    <select id="widthFilter" class="pick" title="Show every screen at the narrowest or widest window its variant covers (W)" aria-label="Width"></select>
     <select id="langFilter" class="pick" title="Show every screen in this language (L)" aria-label="Language"></select>
   </header>
   <nav id="tree"></nav>
@@ -186,6 +188,34 @@ function setLang(l) {
   if (selected) inspector(selected)
   summary()
 }
+// Widths: each variant covers a range of windows (config widths); frames show it drawn, at the narrowest or the widest.
+let WIDTHS = {}
+let widthMode = localStorage.getItem('stitch2-width') ?? 'drawn'
+const rangeOf = (s) => WIDTHS[s.device]
+const widthFor = (s) => { const r = rangeOf(s); return !r || widthMode === 'drawn' ? s.drawn : widthMode === 'narrow' ? r[0] : r[1] }
+const bigFrame = (s) => (s.drawn ?? s.width) > 700
+function setWidth(mode) {
+  widthMode = mode
+  localStorage.setItem('stitch2-width', mode)
+  document.getElementById('widthFilter').value = mode
+  for (const f of frames.values()) {
+    f.screen.width = widthFor(f.screen)
+    f.el.style.width = `${f.screen.width}px`
+    f.iframe.style.width = `${f.screen.width}px`
+    setTimeout(() => measure(f), 300)
+    setTimeout(() => measure(f), 1200)
+  }
+  layout()
+  if (selected) inspector(selected)
+}
+/** The width dropdown names the edges of the devices the screens use: "Narrowest: mobile 360, desktop 1024". */
+function widthOptions() {
+  const used = [...new Set(screens.map((s) => s.device))].filter((d) => WIDTHS[d]).sort((a, b) => WIDTHS[a][0] - WIDTHS[b][0])
+  const edge = (k) => used.map((d) => `${d} ${WIDTHS[d][k]}`).join(', ')
+  const wsel = document.getElementById('widthFilter')
+  wsel.innerHTML = `<option value="drawn">Drawn width</option><option value="narrow">Narrowest: ${edge(0)}</option><option value="wide">Widest: ${edge(1)}</option>`
+  wsel.value = widthMode
+}
 function applyTheme(f) {
   if (!themed()) return
   try { f.iframe.contentDocument.documentElement.dataset.theme = theme } catch {}
@@ -198,8 +228,10 @@ function setTheme(t) {
   for (const f of frames.values()) badge(f)
   if (selected) inspector(selected)
   summary()
+  sendFilter()
 }
-const ref = (s) => (s.kind === 'components' ? `component catalog (${designDir}/${s.path})` : `${s.screen} ${s.device} ${s.version}${themeNote()} (${designDir}/${s.path})`)
+const widthNote = (s) => (s.width !== s.drawn ? ` at ${s.width}px` : '')
+const ref = (s) => (s.kind === 'components' ? `component catalog (${designDir}/${s.path})` : `${s.screen} ${s.device} ${s.version}${themeNote()}${widthNote(s)} (${designDir}/${s.path})`)
 let toastTimer
 async function copy(text) {
   try {
@@ -232,6 +264,7 @@ const filters = JSON.parse(localStorage.getItem('stitch2-filters') ?? 'null') ??
 if (typeof filters.device === 'string') { filters.devices = filters.device === 'all' ? [] : [filters.device]; delete filters.device }
 let screens = []
 let checks = { screens: {} }
+let reports = { consistency: null, compare: null }
 let selected = null
 const frames = new Map() // path -> { el, iframe, screen, height }
 
@@ -271,7 +304,7 @@ const VERSION_H = 44, VERSION_GAP = 120
 function shown(s) {
   const q = document.getElementById('search').value.trim().toLowerCase()
   if (q && !`${s.screen} ${s.title} ${s.path} ${s.version} ${s.source}`.toLowerCase().includes(q)) return false
-  if (filters.devices?.length && s.kind === 'screen' && !filters.devices.includes(s.device)) return false
+  if (filters.devices?.length && !filters.devices.includes(s.device)) return false
   if (filters.versions?.length && s.kind === 'screen' && !filters.versions.includes(s.version)) return false
   if (s.kind === 'components') return filters.status !== 'review' && filters.status !== 'approved'
   if (filters.status === 'active') return s.status !== 'archived'
@@ -330,8 +363,37 @@ function layout() {
     x += groupW + GROUP_GAP
   }
   tree()
+  sendFilter()
 }
 
+// ---- reports follow the filters: the open report (consistency, app comparison, languages) gets the files the
+// canvas shows and hides the rest; the catalog follows only the variant filter there, as the reference ----
+function reportPaths() {
+  return screens.filter((s) => (s.kind === 'components' ? !filters.devices?.length || filters.devices.includes(s.device) : shown(s))).map((s) => s.path)
+}
+function filterLabel() {
+  const q = document.getElementById('search').value.trim()
+  return [
+    ...(filters.versions ?? []),
+    ...(filters.devices ?? []),
+    filters.status === 'approved' ? 'approved' : filters.status === 'review' ? 'needs review' : '',
+    q ? `“${q}”` : '',
+  ].filter(Boolean).join(' · ')
+}
+var sentFilter = ''
+function sendFilter(force) {
+  const doc = document.getElementById('doc')
+  if (!doc.classList.contains('open') || !['/consistency/index.html', '/compare/index.html', '/languages'].includes(docUrl)) return
+  const message = { stitch2Filter: { paths: reportPaths(), label: filterLabel(), theme: themed() ? theme : '' } }
+  const key = JSON.stringify(message)
+  if (!force && key === sentFilter) return
+  sentFilter = key
+  doc.querySelector('iframe').contentWindow?.postMessage(message, location.origin)
+}
+// A report asks for the filters as soon as its script runs (its load event waits for every frame inside it).
+addEventListener('message', (e) => { if (e.origin === location.origin && e.data?.stitch2Ready) sendFilter(true) })
+document.querySelector('#doc iframe').addEventListener('load', () => sendFilter(true)) // reports made before stitch2Ready
+
 function tree() {
   const nav = document.getElementById('tree')
   nav.innerHTML = ''
@@ -353,15 +415,30 @@ function tree() {
   head('Design system')
   const docOpen = (url) => document.getElementById('doc').classList.contains('open') && docUrl === url
   item('DESIGN.md', 'tokens · rules', docOpen('/design'), () => openDoc('/design'))
-  item('Consistency report', 'components × screens', docOpen('/consistency/index.html'), () => openDoc('/consistency/index.html'))
-  item('App comparison', 'approved × live app', docOpen('/compare/index.html'), () => openDoc('/compare/index.html'))
+  // One entry for the catalog: the variant filter picks which ones (mobile, desktop); a click steps through them.
+  const catalogs = rows().find((r) => r.key === '~components')?.visible ?? []
+  const onCatalog = selected?.screen.kind === 'components'
+  item('Components', catalogs.length ? `catalog · ${catalogs.map((s) => s.device).join(', ')}` : 'hidden by the filters', onCatalog, () => {
+    if (!catalogs.length) return
+    const i = catalogs.findIndex((s) => s.path === selected?.screen.path)
+    select(frames.get(catalogs[(i + 1) % catalogs.length].path), true)
+  }, '', '', onCatalog ? ref(selected.screen) : catalogs[0] ? ref(catalogs[0]) : '')
+  // Each report says when it ran and how many of the files it covers, among those the filters show, changed
+  // since (then it's stale: run it again).
+  const keep = new Set(reportPaths())
+  const report = (label, url, state, command) => {
+    const changed = state?.changed.filter((p) => keep.has(p) || p.startsWith('components/')) ?? []
+    const n = changed.length
+    const meta = !state ? 'not run yet' : n ? `${n} changed since` : ago(state.at)
+    const b = item(label, meta, docOpen(url), () => openDoc(url), '', n || !state ? 'stale' : '')
+    b.title = !state
+      ? `Run ${command}`
+      : `Made ${new Date(state.at).toLocaleString()}${n ? `. Changed since, run ${command} again:\n${changed.slice(0, 12).join('\n')}${n > 12 ? `\n… and ${n - 12} more` : ''}` : ', up to date'}`
+  }
+  report('Consistency report', '/consistency/index.html', reports.consistency, 'stitch2 consistency')
+  report('App comparison', '/compare/index.html', reports.compare, 'stitch2 compare')
   item('Languages', 'screens × languages', docOpen('/languages'), () => openDoc('/languages'))
   const all = rows()
-  const comp = all.find((r) => r.key === '~components')
-  if (comp?.visible.length) {
-    head('Components')
-    for (const s of comp.visible) item(s.title.replace(/^[^—]+ — /, ''), 'catalog', selected?.screen.path === s.path, () => select(frames.get(s.path), true), '', '', ref(s))
-  }
   head('Screens')
   for (const row of all) {
     if (row.key === '~components' || !row.visible.length) continue
@@ -406,11 +483,15 @@ function zoomTo(f) {
   apply()
 }
 
+/** The tallest a frame is drawn, in CSS px (the same limit as check's renders). */
+const MAX_FRAME_HEIGHT = 20000
+
 function measure(f) {
   try {
     const doc = f.iframe.contentDocument
-    const min = f.screen.width > 700 ? 800 : 844
-    const h = Math.min(6000, Math.max(min, doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0))
+    const min = bigFrame(f.screen) ? 800 : 844
+    // As tall as the page, up to MAX_FRAME_HEIGHT: long landing pages are drawn whole.
+    const h = Math.min(MAX_FRAME_HEIGHT, Math.max(min, doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0))
     if (Math.abs(h - f.height) > 2) {
       f.height = h
       f.iframe.style.height = `${h}px`
@@ -457,9 +538,9 @@ function frameFor(s) {
   el.innerHTML = `<div class="label"><span class="name"></span><span class="pill"></span><span class="title"></span><button class="copy" type="button" title="Copy a reference to paste to an agent">Copy</button><button class="badge" type="button"></button></div><div class="device"><iframe loading="lazy" scrolling="no"></iframe><div class="shield"></div></div>`
   const iframe = el.querySelector('iframe')
   iframe.style.width = `${s.width}px`
-  iframe.style.height = `${s.width > 700 ? 800 : 844}px`
+  iframe.style.height = `${bigFrame(s) ? 800 : 844}px`
   iframe.src = `/${s.path}?pick${langQuery()}`
-  const f = { el, iframe, screen: s, height: s.width > 700 ? 800 : 844 }
+  const f = { el, iframe, screen: s, height: bigFrame(s) ? 800 : 844 }
   iframe.addEventListener('load', () => { applyTheme(f); measure(f); setTimeout(() => measure(f), 800); setTimeout(() => measure(f), 2500) })
   el.querySelector('.shield').addEventListener('click', () => select(f, false))
   el.querySelector('.shield').addEventListener('dblclick', () => { select(f, false); f.el.classList.add('live') })
@@ -552,7 +633,11 @@ function inspector(f) {
     li.querySelector('.sev').textContent = i.severity
     li.querySelector('.msg').textContent = i.message + (i.text ? ` — “${i.text}”` : '')
     li.querySelector('code').textContent = i.selector
-    li.onclick = () => locate(f, i.selector)
+    li.onclick = () => {
+      const r = rangeOf(s)
+      if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : 'wide'); setTimeout(() => locate(f, i.selector), 900) }
+      else locate(f, i.selector)
+    }
     ul.append(li)
   }
   box.classList.add('open')
@@ -674,9 +759,22 @@ async function loadChecks() {
   if (selected) inspector(selected)
   summary()
 }
+async function loadReports() {
+  reports = await fetch('/api/reports').then((r) => r.json()).catch(() => reports)
+  tree()
+}
+setInterval(loadReports, 60_000) // keeps "5 min ago" honest
+function ago(t) {
+  const m = Math.round((Date.now() - t) / 60000)
+  if (m < 1) return 'just now'
+  if (m < 60) return `${m} min ago`
+  const h = Math.round(m / 60)
+  return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`
+}
 
 async function load(first, given) {
   const next = given ?? (await fetch('/api/screens').then((r) => r.json()))
+  for (const s of next) { s.drawn = s.width; s.width = widthFor(s) }
   const keep = new Set(next.map((s) => s.path))
   for (const [p, f] of frames) if (!keep.has(p)) { f.el.remove(); frames.delete(p); if (selected === f) selected = null }
   for (const s of next) {
@@ -684,10 +782,12 @@ async function load(first, given) {
     if (f) { f.screen = s; paintLabel(f) } else frameFor(s)
   }
   screens = next
+  widthOptions()
   versionFilter()
   variantFilter()
   layout()
   await loadChecks()
+  await loadReports()
   if (selected) inspector(selected)
   if (first && !localStorage.getItem('stitch2-view')) setTimeout(fit, 1500)
 }
@@ -708,7 +808,7 @@ for (const [id, key] of [['statusFilter', 'status']]) {
 document.getElementById('search').oninput = layout
 
 // Versions and variants: multi-selects of every label the screens use (v1 … v12 and imports such as "Stitch";
-// mobile, tablet, desktop), with how many screens carry each; none ticked means all. The catalog always shows.
+// mobile, tablet, desktop), with how many screens carry each; none ticked means all. The catalog follows the variant filter only.
 const MULTI = []
 for (const id of ['versionFilter', 'variantFilter']) {
   const box = document.getElementById(id)
@@ -765,6 +865,7 @@ events.onmessage = async (e) => {
   if (paths.some((p) => p === 'checks.json')) await loadChecks()
   const html = paths.filter((p) => p.endsWith('.html'))
   if (html.length) await load(false)
+  else if (paths.some((p) => p.startsWith('components/') || p === 'compare.json')) await loadReports()
   if (paths.includes('DESIGN.md') && document.getElementById('doc').classList.contains('open')) document.querySelector('#doc iframe').contentWindow.location.reload()
   // Stylesheets and scripts are shared: tokens.css, tailwind.tokens.js, token exports the screens link
   // (tokens.tailwind.css), the components.
@@ -826,6 +927,7 @@ addEventListener('keydown', (e) => {
   if (e.key === 'f' || e.key === 'F') fit()
   if ((e.key === 't' || e.key === 'T') && themed()) setTheme(THEMES[(THEMES.indexOf(theme) + 1) % THEMES.length])
   if (e.key === 'l' || e.key === 'L') setLang(LANGS[(LANGS.indexOf(lang) + 1) % LANGS.length])
+  if (e.key === 'w' || e.key === 'W') setWidth(['drawn', 'narrow', 'wide'][(['drawn', 'narrow', 'wide'].indexOf(widthMode) + 1) % 3])
   if (e.key === '0') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, 1)
   if (e.key === '+' || e.key === '=') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, view.z * 1.2)
   if (e.key === '-') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, view.z / 1.2)
@@ -856,6 +958,9 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   pick.innerHTML = THEMES.map((t) => `<option value="${t}">${t[0].toUpperCase()}${t.slice(1)} theme</option>`).join('')
   pick.onchange = () => setTheme(pick.value)
   setTheme(theme)
+  WIDTHS = c.widths ?? {}
+  const wsel = document.getElementById('widthFilter')
+  wsel.onchange = () => setWidth(wsel.value)
   SOURCE = c.sourceLocale ?? 'en'
   LANGS = c.locales?.length ? c.locales : [SOURCE]
   if (!LANGS.includes(lang)) lang = SOURCE

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';
@@ -35,6 +36,8 @@ const levels = typeLevels();
 const themes = designThemes();
 const collect = collectOptions();
 const server = await startServer(0);
+/** The tallest render, in CSS px: a long landing page is shot whole (the canvas draws frames up to the same height). */
+const MAX_RENDER_HEIGHT = 20000;
 const browser = await chromium.launch();
 const page = await browser.newPage({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2 });
 const results = {};
@@ -112,6 +115,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 +150,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)) });
+    await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, MAX_RENDER_HEIGHT)) });
     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);
     }

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/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/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.14.0",
+  "version": "0.15.1",
   "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,8 +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 and their variants (mobile, desktop), statuses,
-  the user's approval and notes.
+- [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.
 
@@ -60,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
@@ -73,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 |

package/skills/stitch2/references/screens.md

@@ -26,6 +26,8 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
 - **Edit in place** only to finish your own draft, or to answer a note on a version still in `review` or
   `draft`.
 - **Never edit** an `approved` or `archived` variant: copy the version to the next number and change the copy.
+  The exception is the user's own request: a fix they ask for on a version they name ("it had to be on v3")
+  goes into that version, which keeps its status; say what changed.
 
 ## Statuses
 
@@ -70,16 +72,32 @@ with the mobile's N, frame width 1280, the same components and type levels, the
 of a tab bar, a content max width, two columns where it helps). Shared components get their desktop form in the
 component, before the first desktop screen.
 
-Widths follow Google's window size classes ([google.md](google.md)): compact under 600 px (the phone frame),
-medium 600–839, expanded 840–1199, large from 1200 (the desktop frame). A desktop screen is a layout for the
-width class, not a stretched phone: a side navigation instead of the bar, list-detail with both panes, extra
-columns for feeds. When a project needs a tablet, it is one more variant, at a medium width.
+## Widths
+
+A variant is drawn at one frame width but covers a range of windows: `widths` in `stitch2.config.json`, by
+device, `[narrowest, widest]` in px. The defaults follow Google's window size classes ([google.md](google.md)):
+mobile 360–599 (compact), tablet 600–1023 (medium), desktop 1024–1920 (expanded and up); a project sets the
+width where its app actually changes layout (gymgym: mobile up to 1023, desktop from 1024).
+
+Widths are a dimension like themes and languages, not more files: `stitch2 check` also renders every variant at
+both ends of its range and reports what breaks there ("at 1024px: …"), and the canvas shows every frame at its
+narrowest or widest (the width dropdown, W).
+
+- A screen that breaks at an edge gets a **responsive rule inside the same variant**: a two-column grid that drops
+  to one, three cards across that become two, a side column that moves under the main one. Use the project's
+  breakpoints (Tailwind's `md:`, `lg:`, `xl:`), so the screen keeps one layout that adapts.
+- Only when the **structure** has to change (a bar becomes a side navigation, one pane becomes list-detail) is it a
+  new variant: `tablet-v<N>` for 600–1023, with its own frame width (768) and range, the same N as the version.
+- A desktop screen is a layout for its range, not a stretched phone: a side navigation instead of the bar,
+  list-detail with both panes, extra columns for feeds.
 
 ## The canvas
 
-`stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), the
-consistency report, the component catalog and every screen with its versions; filters for active, approved,
-needs review or all, and mobile or desktop. Selecting a version opens the inspector: status, note, checks, and
+`stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), Components
+(the catalog for the variants the filter shows; a click steps through them), the consistency report and app
+comparison (each with when it last ran, or how many covered screens changed since), Languages, and every screen
+with its versions. Filters: status (active, approved, needs review, all), versions, variants, theme, width and
+language. The reports and Languages follow the filters too: they show only the screens the canvas shows. Selecting a version opens the inspector: status, note, checks, and
 Copy for its reference. Pick mode (`p`) highlights the element under the pointer; a click copies its reference,
 Shift-click collects several (Copy all, Add to note). Keys: `/` search, `j`/`k` next and previous, `a` approve,
 `p` pick, `f` fit, `0` actual size, double-click to use a frame, `Esc` to leave.

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

@@ -44,7 +44,10 @@ Slots are for wiring. If what goes into a slot changes how the component looks,
   other, **controls overlapping each other**, small tap targets, contrast, type levels, reuse and consistency.
 - `stitch2 compare` (the live app, against every approved version with a route): which components appear, in
   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.
+  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:".
+- 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
   open, a timer running, a form half filled). An unrouted screen is not compared at all.
 

package/skills/stitch2-i18n/SKILL.md

@@ -44,7 +44,8 @@ Use the app's own files. Never copy messages into the design folder: two copies
 ```
 
 A value with braces is a **template**: each `{key}` or `{key|name=value;name=value}` becomes its message and
-the rest stays as written. Use it for lines the app builds from several messages and data (a meta line, a
+the rest stays as written. Templates nest, innermost first, for a message that takes another as an argument:
+`data-t-title="{site.screens.title|workout={nav.workout};history={nav.history}}"`. Use it for lines the app builds from several messages and data (a meta line, a
 list of `label=url` links: `data-t-links="{site.features}=#features,{site.docs}=/docs"`); sample data inside
 it stays literal. Without braces, `data-t-<attr>` on a comma list takes one key per item.