stitch2 0.13.1 → 0.15.0

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)
@@ -68,17 +70,18 @@ file that already exists. From there the agent spends its effort on the design.
     { "format": "dtcg", "path": "design/tokens.json" }
   ]
   ```
-- **Versions and approval**: every file is a version of a screen for a device, with its status (draft, review,
-  approved, archived) and your note in meta tags, so agents can read what you decided (`stitch2 screens`).
+- **Versions, variants and approval**: a screen has versions (v1, v2, …), and each version has variants, its
+  layouts for mobile and desktop (`mobile-v3.html`, `desktop-v3.html`). The canvas groups them; you approve a
+  version as a whole or one variant at a time, leave notes, and approving archives the previous approved layout.
 - **DESIGN.md builder**: `stitch2 init` writes a complete DESIGN.md from a few choices (brand colour, modes,
   fonts, roundness, density), with colours checked for contrast; `stitch2 extract` measures one from an existing
   site or screens.
-- **Fresh-eyes variants** (`stitch2 sandbox`): a folder with your design system, components and skills but no
+- **Fresh-eyes alternatives** (`stitch2 sandbox`): a folder with your design system, components and skills but no
   screens, where a fresh agent designs from a brief without being anchored to the existing versions;
   `stitch2 sandbox import` brings the result back as the next version for review. Also the way to test a change
   to the skills on output only the rules produced.
 - **Skills** for agents (`skills/`): `stitch2` (the design workflow, principles, typography, components,
-  versions), `stitch2-design-md` (building the design system), `stitch2-variants` (fresh-eyes versions and
+  versions), `stitch2-design-md` (building the design system), `stitch2-alternatives` (fresh-eyes versions and
   testing skill changes), `stitch2-consistency` (verifying and fixing
   consistency), `stitch2-i18n` (screens in every language), `stitch2-app-sync` (keeping the app and the designs in step: design first, then the app) and,
   optional, `stitch2-import-from-google-stitch` (drafting screens in Google Stitch through its MCP server).
@@ -152,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/audit.js

@@ -105,10 +105,20 @@ export async function audit(opts) {
         }
     }
     // 3. Fixed bars (tab bar, rest timer, headers) never cover content: check at both scroll ends.
+    // A fixed element inside a transformed (or filtered, or contained) box is placed in that box, not on the
+    // screen: a catalog showing a tab bar in place, for one. Only bars pinned to the screen count.
+    const pinned = (el) => {
+        for (let a = el.parentElement; a; a = a.parentElement) {
+            const cs = getComputedStyle(a);
+            if (cs.transform !== 'none' || cs.filter !== 'none' || cs.perspective !== 'none' || /paint|layout|strict|content/.test(cs.contain))
+                return false;
+        }
+        return true;
+    };
     const bars = all.filter((el) => {
         const p = getComputedStyle(el).position;
         const r = el.getBoundingClientRect();
-        return (p === 'fixed' || p === 'sticky') && r.height <= 240 && r.width >= W * 0.6;
+        return (p === 'sticky' || (p === 'fixed' && pinned(el))) && r.height <= 240 && r.width >= W * 0.6;
     });
     // Behind an open modal the page is inert and covered, so only the modal's own bars count.
     // An open modal: the element may be 0px itself when everything in it is fixed (Headless UI's Dialog).

package/dist/canvas.html

@@ -15,6 +15,10 @@
   .row-label { align-items: baseline; display: flex; gap: 12px; overflow: hidden; position: absolute; white-space: nowrap; }
   .row-label b { color: var(--text); font-size: 24px; }
   .row-label span { color: var(--muted); font-size: 15px; overflow: hidden; text-overflow: ellipsis; }
+  .version-label { align-items: baseline; border-top: 2px solid var(--edge); display: flex; gap: 10px; overflow: hidden; padding-top: 8px; position: absolute; white-space: nowrap; }
+  .version-label b { color: var(--text); font-size: 18px; }
+  .version-label span { color: var(--muted); font-size: 14px; overflow: hidden; text-overflow: ellipsis; }
+  .version-label.review { border-color: var(--warn); } .version-label.approved { border-color: var(--good); }
   #doc { background: var(--bg); display: none; inset: 0 0 0 var(--side); position: fixed; z-index: 19; }
   #doc.open { display: block; }
   .doc-frame { border: 0; height: 100%; width: 100%; }
@@ -27,13 +31,30 @@
   .seg button { background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; flex: 1; padding: 4px 6px; white-space: nowrap; }
   .seg button.on { background: var(--panel2); color: var(--text); }
   .seg[hidden] { display: none; }
-  #langFilter { background: var(--bg); border: 1px solid var(--edge); border-radius: 8px; color: var(--text); padding: 5px 8px; width: 100%; }
+  .multi { position: relative; }
+  .multi[hidden] { display: none; }
+  .multi summary { align-items: center; background: var(--bg) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='M1 1.5l5 5 5-5' fill='none' stroke='%23a1a1aa' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") no-repeat right 10px center / 12px 8px; border: 1px solid var(--edge); border-radius: 8px; cursor: pointer; display: flex; gap: 8px; list-style: none; padding: 5px 30px 5px 8px; }
+  .multi summary::-webkit-details-marker { display: none; }
+  .multi .menu { background: var(--panel); border: 1px solid var(--edge); border-radius: 8px; box-shadow: 0 12px 32px rgba(0,0,0,.5); left: 0; max-height: 280px; overflow: auto; padding: 4px; position: absolute; right: 0; top: calc(100% + 4px); z-index: 30; }
+  .multi label { align-items: center; border-radius: 6px; color: var(--muted); cursor: pointer; display: flex; gap: 8px; padding: 5px 8px; }
+  .multi label:hover { background: var(--panel2); color: var(--text); }
+  .multi label.all { border-bottom: 1px solid var(--edge); border-radius: 6px 6px 0 0; margin-bottom: 4px; }
+  .multi input { accent-color: var(--accent); margin: 0; }
+  .multi .n { color: var(--faint); margin-left: auto; }
+  /* Theme and language: native dropdowns drawn like the versions and variants ones. */
+  .pick { appearance: none; background: var(--bg) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='M1 1.5l5 5 5-5' fill='none' stroke='%23a1a1aa' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") no-repeat right 10px center / 12px 8px; border: 1px solid var(--edge); border-radius: 8px; color: var(--text); cursor: pointer; font: inherit; padding: 5px 30px 5px 8px; width: 100%; }
+  .pick[hidden] { display: none; }
   #tree { flex: 1; overflow: auto; padding: 6px 8px 16px; }
   #tree h4 { color: var(--faint); font-size: 11px; letter-spacing: .06em; margin: 14px 6px 6px; text-transform: uppercase; }
   .item { align-items: center; background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; display: flex; gap: 8px; padding: 6px 8px; text-align: left; width: 100%; }
   .item:hover { background: var(--panel2); color: var(--text); }
   .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; }
   .screen-name { align-items: center; border-radius: 6px; color: var(--text); cursor: pointer; display: flex; font-weight: 600; gap: 6px; padding: 8px 8px 2px; }
   .screen-name:hover { background: var(--panel2); }
   .screen-name .meta { color: var(--faint); font-size: 11px; font-weight: 400; margin-left: auto; }
@@ -106,9 +127,11 @@
     <b id="labName">stitch2</b>
     <input id="search" placeholder="Search screens… ( / )" />
     <div class="seg" id="statusFilter"><button type="button" data-v="active" class="on" title="Everything except archived versions">Active</button><button type="button" data-v="approved" title="The reference versions agents build on">Approved</button><button type="button" data-v="review" title="Finished by an agent, waiting for your decision">Needs review</button><button type="button" data-v="all" title="Including archived versions">All</button></div>
-    <div class="seg" id="deviceFilter"><button type="button" data-v="all" class="on">All devices</button><button type="button" data-v="mobile">Mobile</button><button type="button" data-v="desktop">Desktop</button></div>
-    <div class="seg" id="themeFilter" hidden title="Show every screen in this theme (T)"></div>
-    <select id="langFilter" title="Show every screen in this language (L)" aria-label="Language"></select>
+    <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>
   <footer>
@@ -165,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 {}
@@ -172,13 +223,15 @@ function applyTheme(f) {
 function setTheme(t) {
   theme = t
   localStorage.setItem('stitch2-theme', t)
-  for (const b of document.querySelectorAll('#themeFilter button')) b.classList.toggle('on', b.dataset.v === t)
+  document.getElementById('themeFilter').value = t
   for (const f of frames.values()) applyTheme(f)
   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 {
@@ -207,9 +260,11 @@ const copyButton = (text, title) => {
   return b
 }
 let view = JSON.parse(localStorage.getItem('stitch2-view') ?? 'null') ?? { x: 40, y: 60, z: 0.4 }
-const filters = JSON.parse(localStorage.getItem('stitch2-filters') ?? 'null') ?? { status: 'active', device: 'all' }
+const filters = JSON.parse(localStorage.getItem('stitch2-filters') ?? 'null') ?? { status: 'active' }
+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 }
 
@@ -230,16 +285,27 @@ const zoomAt = (cx, cy, z) => {
   apply()
 }
 
-// ---- grouping: rows are app screens (components first), frames are versions ----
+// ---- grouping: rows are app screens (components first); in a row, versions (v1, v2, …) in order, and in a
+// version its variants: the layouts for each device (mobile, desktop), files <device>-v<N> sharing N ----
 const rowKey = (s) => (s.kind === 'components' ? '~components' : s.screen)
 const rowRank = (k) => (k === '~components' ? -1 : ORDER.includes(k) ? ORDER.indexOf(k) : 100)
 const sortRows = (keys) => keys.sort((a, b) => rowRank(a) - rowRank(b) || a.localeCompare(b))
+const versionRank = (v) => { const m = /^v(\d+)$/.exec(v); return m ? Number(m[1]) : 0 }
+const DEVICE_RANK = { mobile: 0, tablet: 1, desktop: 2 }
 const sortVersions = (list) =>
-  list.sort((a, b) => (a.device === b.device ? 0 : a.device === 'mobile' ? -1 : 1) || STATUS_RANK[a.status] - STATUS_RANK[b.status] || b.mtime - a.mtime)
+  list.sort((a, b) => versionRank(a.version) - versionRank(b.version) || a.version.localeCompare(b.version) || (DEVICE_RANK[a.device] ?? 9) - (DEVICE_RANK[b.device] ?? 9) || b.mtime - a.mtime)
+/** A version's variants, and one status for all of them: needs review if any does, else the most settled. */
+const versionsOf = (list) => {
+  const by = new Map()
+  for (const s of list) { const k = s.kind === 'components' ? s.path : s.version; by.set(k, [...(by.get(k) ?? []), s]) }
+  return [...by.entries()].map(([version, variants]) => ({ version, variants, status: variants.some((v) => v.status === 'review') ? 'review' : variants.some((v) => v.status === 'draft') ? 'draft' : variants.some((v) => v.status === 'approved') ? 'approved' : 'archived' }))
+}
+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.device !== 'all' && s.kind === 'screen' && s.device !== filters.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'
   if (filters.status === 'all') return true
@@ -258,11 +324,13 @@ function layout() {
   for (const row of rows()) {
     for (const s of row.all) frames.get(s.path).el.style.display = row.visible.includes(s) ? '' : 'none'
     if (!row.visible.length) continue
-    const groupW = row.visible.reduce((w, s) => w + s.width, 0) + GAP_X * (row.visible.length - 1)
+    const groups = versionsOf(row.visible)
+    const widthOf = (g) => g.variants.reduce((w, s) => w + s.width, 0) + GAP_X * (g.variants.length - 1)
+    const groupW = groups.reduce((w, g) => w + widthOf(g), 0) + VERSION_GAP * (groups.length - 1)
     if (x > 0 && x + groupW > LINE_W) { x = 0; y += lineH + GAP_Y; lineH = 0 }
     const label = document.createElement('div')
     label.className = 'row-label'
-    const approved = row.all.filter((s) => s.status === 'approved').map((s) => `${s.device} ${s.version}`)
+    const approved = row.all.filter((s) => s.status === 'approved').map((s) => `${s.version} ${s.device}`)
     label.innerHTML = '<b></b><span></span>'
     label.querySelector('b').textContent = row.key === '~components' ? 'Components' : row.key
     label.querySelector('span').textContent = row.key === '~components' ? 'the catalog every screen is built from' : approved.length ? `approved: ${approved.join(', ')}` : 'nothing approved yet'
@@ -270,19 +338,62 @@ function layout() {
     label.style.maxWidth = `${groupW}px`
     world.append(label)
     let fx = x, tallest = 0
-    for (const s of row.visible) {
-      const f = frames.get(s.path)
-      f.el.style.left = `${fx}px`
-      f.el.style.top = `${y + ROW_LABEL_H}px`
-      fx += s.width + GAP_X
-      tallest = Math.max(tallest, f.height + LABEL_H)
+    const top = row.key === '~components' ? 0 : VERSION_H
+    for (const g of groups) {
+      if (top) {
+        const v = document.createElement('div')
+        v.className = `row-label version-label ${g.status}`
+        v.innerHTML = '<b></b><span></span>'
+        v.querySelector('b').textContent = g.version
+        v.querySelector('span').textContent = `${STATUS_LABEL[g.status]} · ${g.variants.map((s) => s.device).join(', ')}`
+        v.style.transform = `translate(${fx}px, ${y + ROW_LABEL_H}px)`
+        v.style.width = `${widthOf(g)}px`
+        world.append(v)
+      }
+      for (const s of g.variants) {
+        const f = frames.get(s.path)
+        f.el.style.left = `${fx}px`
+        f.el.style.top = `${y + ROW_LABEL_H + top}px`
+        fx += s.width + GAP_X
+        tallest = Math.max(tallest, f.height + LABEL_H + top)
+      }
+      fx += VERSION_GAP - GAP_X
     }
     lineH = Math.max(lineH, ROW_LABEL_H + tallest)
     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 = ''
@@ -304,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
@@ -321,11 +447,17 @@ function tree() {
     const approved = row.all.some((s) => s.status === 'approved')
     name.innerHTML = `<span class="dot ${approved ? 'approved' : row.all.some((s) => s.status === 'review') ? 'review' : 'draft'}"></span><span></span><span class="meta"></span>`
     name.children[1].textContent = row.key
-    name.querySelector('.meta').textContent = `${row.visible.length} version${row.visible.length > 1 ? 's' : ''}`
+    const vs = versionsOf(row.visible)
+    name.querySelector('.meta').textContent = `${vs.length} version${vs.length > 1 ? 's' : ''}`
     name.onclick = () => select(frames.get(row.visible[0].path), true)
     name.append(copyButton(row.key, 'Copy the screen name'))
     nav.append(name)
-    for (const s of row.visible) item(`${s.version} · ${s.device}`, STATUS_LABEL[s.status], selected?.screen.path === s.path, () => select(frames.get(s.path), true), s.status, 'version', ref(s))
+    for (const g of vs) {
+      const one = g.variants.length === 1
+      const first = g.variants[0]
+      item(one ? `${g.version} · ${first.device}` : g.version, one ? STATUS_LABEL[first.status] : `${STATUS_LABEL[g.status]} · ${g.variants.length} variants`, one && selected?.screen.path === first.path, () => select(frames.get(first.path), true), g.status, 'version', one ? ref(first) : `${row.key} ${g.version}`)
+      if (!one) for (const s of g.variants) item(s.device, STATUS_LABEL[s.status], selected?.screen.path === s.path, () => select(frames.get(s.path), true), s.status, 'variant', ref(s))
+    }
   }
 }
 
@@ -354,7 +486,7 @@ function zoomTo(f) {
 function measure(f) {
   try {
     const doc = f.iframe.contentDocument
-    const min = f.screen.width > 700 ? 800 : 844
+    const min = bigFrame(f.screen) ? 800 : 844
     const h = Math.min(6000, Math.max(min, doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0))
     if (Math.abs(h - f.height) > 2) {
       f.height = h
@@ -377,7 +509,7 @@ function badge(f) {
 function paintLabel(f) {
   const s = f.screen
   f.el.className = `frame ${s.device} ${s.status}${selected === f ? ' selected' : ''}`
-  f.el.querySelector('.name').textContent = s.kind === 'components' ? 'Catalog' : `${s.version}`
+  f.el.querySelector('.name').textContent = s.kind === 'components' ? 'Catalog' : s.device
   const pill = f.el.querySelector('.pill')
   pill.className = `pill ${s.status}`
   pill.textContent = s.kind === 'components' ? 'components' : `${STATUS_LABEL[s.status]} · ${s.source}`
@@ -402,9 +534,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') })
@@ -464,7 +596,16 @@ function inspector(f) {
     }
     box.insertBefore(sec, box.querySelector('h4'))
   }
-  box.querySelector('.h').textContent = s.kind === 'components' ? 'Component catalog' : `${s.screen} · ${s.version}`
+  box.querySelector('.h').textContent = s.kind === 'components' ? 'Component catalog' : `${s.screen} · ${s.version} · ${s.device}`
+  const siblings = s.kind === 'screen' ? sortVersions(screens.filter((o) => o.kind === 'screen' && o.screen === s.screen && o.version === s.version)) : []
+  if (siblings.length > 1) {
+    const vrow = document.createElement('div')
+    vrow.className = 'version-actions'
+    vrow.innerHTML = '<span></span><button type="button" data-st="approved" title="Approve every variant of this version">Approve version</button><button type="button" data-st="archived" title="Archive every variant of this version">Archive version</button>'
+    vrow.querySelector('span').textContent = `${s.version}: ${siblings.map((o) => `${o.device} ${STATUS_LABEL[o.status]}`).join(', ')}`
+    for (const b of vrow.querySelectorAll('button')) b.onclick = async () => { for (const o of siblings) if (o.status !== b.dataset.st && !(b.dataset.st === 'approved' && o.status === 'archived')) await setMeta(o.path, { status: b.dataset.st }) }
+    box.querySelector('.status').before(vrow)
+  }
   box.querySelector('.f').textContent = `${s.device} · ${s.source}`
   const a = box.querySelector('.facts a')
   a.href = `/${s.path}`
@@ -488,7 +629,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')
@@ -610,9 +755,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) {
@@ -620,14 +778,18 @@ 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)
 }
 
 // ---- filters ----
-for (const [id, key] of [['statusFilter', 'status'], ['deviceFilter', 'device']]) {
+for (const [id, key] of [['statusFilter', 'status']]) {
   const seg = document.getElementById(id)
   for (const b of seg.querySelectorAll('button')) {
     b.classList.toggle('on', b.dataset.v === filters[key])
@@ -641,6 +803,57 @@ for (const [id, key] of [['statusFilter', 'status'], ['deviceFilter', 'device']]
 }
 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 follows the variant filter only.
+const MULTI = []
+for (const id of ['versionFilter', 'variantFilter']) {
+  const box = document.getElementById(id)
+  MULTI.push(box)
+}
+document.addEventListener('click', (e) => { for (const box of MULTI) if (box.open && !box.contains(e.target)) box.open = false })
+document.addEventListener('keydown', (e) => { const open = MULTI.find((b) => b.open); if (e.key === 'Escape' && open) { open.open = false; e.stopPropagation() } }, true)
+function multiFilter({ id, key, of, sort, all, many, again }) {
+  const box = document.getElementById(id)
+  const counts = new Map()
+  for (const s of screens) if (s.kind === 'screen') counts.set(of(s), (counts.get(of(s)) ?? 0) + 1)
+  const labels = [...counts.keys()].sort(sort)
+  filters[key] = (filters[key] ?? []).filter((v) => labels.includes(v))
+  box.hidden = labels.length < 2
+  const picked = filters[key]
+  box.querySelector('summary').textContent = !picked.length ? all : picked.length <= 3 ? [...picked].sort(sort).join(', ') : `${picked.length} ${many}`
+  const change = (next) => {
+    filters[key] = next
+    localStorage.setItem('stitch2-filters', JSON.stringify(filters))
+    again()
+    layout()
+  }
+  const option = (label, checked, n, onChange, cls = '') => {
+    const l = document.createElement('label')
+    l.className = cls
+    const input = document.createElement('input')
+    input.type = 'checkbox'
+    input.checked = checked
+    input.onchange = onChange
+    const name = document.createElement('span')
+    name.textContent = label
+    const count = document.createElement('span')
+    count.className = 'n'
+    count.textContent = n
+    l.append(input, name, count)
+    return l
+  }
+  box.querySelector('.menu').replaceChildren(
+    option(all, !picked.length, screens.filter((s) => s.kind === 'screen').length, () => change([]), 'all'),
+    ...labels.map((v) => option(v, picked.includes(v), counts.get(v), () => change(picked.includes(v) ? picked.filter((x) => x !== v) : [...picked, v]))),
+  )
+}
+function versionFilter() {
+  multiFilter({ id: 'versionFilter', key: 'versions', of: (s) => s.version, sort: (a, b) => a.localeCompare(b, undefined, { numeric: true }), all: 'All versions', many: 'versions', again: versionFilter })
+}
+function variantFilter() {
+  multiFilter({ id: 'variantFilter', key: 'devices', of: (s) => s.device, sort: (a, b) => (DEVICE_RANK[a] ?? 9) - (DEVICE_RANK[b] ?? 9), all: 'All variants', many: 'variants', again: variantFilter })
+}
+
 // ---- live reload ----
 const events = new EventSource('/events')
 events.onmessage = async (e) => {
@@ -648,6 +861,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.
@@ -709,6 +923,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)
@@ -734,11 +949,14 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   document.getElementById('labName').textContent = c.name
   THEMES = c.themes?.length ? c.themes : ['dark']
   if (!THEMES.includes(theme)) theme = THEMES[0]
-  const seg = document.getElementById('themeFilter')
-  seg.hidden = !themed()
-  seg.innerHTML = THEMES.map((t) => `<button type="button" data-v="${t}">${t[0].toUpperCase()}${t.slice(1)}</button>`).join('')
-  for (const b of seg.querySelectorAll('button')) b.onclick = () => setTheme(b.dataset.v)
+  const pick = document.getElementById('themeFilter')
+  pick.hidden = !themed()
+  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