stitch2 0.13.0 → 0.14.0

package/README.md

@@ -68,17 +68,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).

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).
@@ -212,14 +222,35 @@ export async function audit(opts) {
                 return e;
         return null;
     };
+    // The part of a control its scrolling or clipping ancestors show: a link scrolled out of a nav strip is not drawn
+    // where its box would be.
+    const visibleBox = (el) => {
+        const r = el.getBoundingClientRect();
+        let { left, top, right, bottom } = r;
+        for (let e = el.parentElement; e && e !== document.body; e = e.parentElement) {
+            const cs = getComputedStyle(e);
+            if (cs.overflowX === 'visible' && cs.overflowY === 'visible')
+                continue;
+            const c = e.getBoundingClientRect();
+            if (cs.overflowX !== 'visible') {
+                left = Math.max(left, c.left);
+                right = Math.min(right, c.right);
+            }
+            if (cs.overflowY !== 'visible') {
+                top = Math.max(top, c.top);
+                bottom = Math.min(bottom, c.bottom);
+            }
+        }
+        return { left, top, right, bottom };
+    };
     // Behind an open modal (found above) only the modal's own controls count.
     const solid = interactive.filter((el) => opacity(el) > 0.05 && (!modal || modal.contains(el)));
     for (const [i, a] of solid.entries())
         for (const b of solid.slice(i + 1)) {
             if (a.contains(b) || b.contains(a) || layer(a) !== layer(b))
                 continue;
-            const r = a.getBoundingClientRect();
-            const q = b.getBoundingClientRect();
+            const r = visibleBox(a);
+            const q = visibleBox(b);
             if (Math.min(r.right, q.right) - Math.max(r.left, q.left) > 2 && Math.min(r.bottom, q.bottom) - Math.max(r.top, q.top) > 2)
                 push('error', 'control-overlap', b, `Overlaps another control (“${text(a).slice(0, 30) || a.getAttribute('aria-label') || a.tagName.toLowerCase()}”): give them room`);
         }

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,29 @@
   .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; }
+  #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 +126,10 @@
     <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="langFilter" class="pick" title="Show every screen in this language (L)" aria-label="Language"></select>
   </header>
   <nav id="tree"></nav>
   <footer>
@@ -172,7 +193,7 @@ 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)
@@ -207,7 +228,8 @@ 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 selected = null
@@ -230,16 +252,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 && s.kind === 'screen' && !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 +291,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,12 +305,26 @@ 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
@@ -321,11 +370,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))
+    }
   }
 }
 
@@ -377,7 +432,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}`
@@ -464,7 +519,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}`
@@ -620,6 +684,8 @@ async function load(first, given) {
     if (f) { f.screen = s; paintLabel(f) } else frameFor(s)
   }
   screens = next
+  versionFilter()
+  variantFilter()
   layout()
   await loadChecks()
   if (selected) inspector(selected)
@@ -627,7 +693,7 @@ async function load(first, given) {
 }
 
 // ---- 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 +707,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 always shows.
+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) => {
@@ -734,10 +851,10 @@ 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)
   SOURCE = c.sourceLocale ?? 'en'
   LANGS = c.locales?.length ? c.locales : [SOURCE]

package/dist/consistency.js

@@ -248,7 +248,8 @@ export function consistencyIssues(known, paths) {
         out[path] = issues;
         const peers = (families.get(familyOf(path)) ?? []).filter((p) => p !== path);
         for (const [kind, sigs] of Object.entries(known[path] ?? {})) {
-            if (sigs.length > 1 && MEASURED.has(kind.split(':')[0]))
+            // The catalog shows every variant of a component side by side; a screen shows one.
+            if (sigs.length > 1 && MEASURED.has(kind.split(':')[0]) && !catalogs.includes(path))
                 issues.push({
                     severity: 'warning',
                     type: 'consistency',

package/dist/list.js

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

package/dist/setup.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -24,7 +24,8 @@ References, read before the first screen:
 - [principles.md](references/principles.md): what makes a screen read well, and the review rubric.
 - [typography.md](references/typography.md): type levels and how to combine them; most polish is here.
 - [components.md](references/components.md): build from the shared components; the reuse ladder.
-- [screens.md](references/screens.md): screen names, versions, statuses, the user's approval and notes, desktop.
+- [screens.md](references/screens.md): screen names, versions and their variants (mobile, desktop), statuses,
+  the user's approval and notes.
 - [google.md](references/google.md): Google's guidance (Material, Android, web.dev) as rules with numbers.
 - [guides.md](references/guides.md): the public sources behind the rules.
 
@@ -40,8 +41,9 @@ References, read before the first screen:
 3. **Hierarchy before markup.** Name the one thing the user came for, the single primary action (the only
    accent-filled element in its region), and what is secondary. Give every text element a type level and a
    colour before writing markup.
-4. **Build** the next version, `<screens>/<screen>/<device>-v<N>.html`, from the project's template (status
-   `draft`; never edit an approved version). Assemble it from the components; plain markup only where none
+4. **Build** the next version, `<screens>/<screen>/<device>-v<N>.html`, or a missing variant of an existing
+   version (another device, the same N), from the project's template (status `draft`; never edit an approved
+   variant). Assemble it from the components; plain markup only where none
    applies, with token classes, `.type-<level>` classes for text, the spacing scale, and the states DESIGN.md
    defines. When the config has `i18n`, mark every product string with its message key (`data-t`, see
    **stitch2-i18n**). Never add classes to a component to change how it looks, and never write a colour value (hex,
@@ -82,11 +84,11 @@ References, read before the first screen:
 | `lint` | Google's DESIGN.md linter |
 | `localize [filter]` | Copies remote images a screen uses into its `assets/` folder |
 | `init`, `extract` | Build DESIGN.md from choices, or measure it from an existing site (stitch2-design-md) |
-| `sandbox create <dir> <brief.md>…`, `sandbox import <dir>` | Fresh-eyes versions from agents that see no other versions (stitch2-variants) |
+| `sandbox create <dir> <brief.md>…`, `sandbox import <dir>` | Fresh-eyes versions from agents that see no other versions (stitch2-alternatives) |
 
 ## Alternatives and fresh eyes
 
 When the user wants options or a new direction, or a design is stuck, do not iterate on the existing versions:
-use the **stitch2-variants** skill. Fresh agents in sandboxes design from the brief without seeing the other
+use the **stitch2-alternatives** skill. Fresh agents in sandboxes design from the brief without seeing the other
 versions, and their screens come back as new versions to compare on the canvas. The same skill tests changes to
 the skills or DESIGN.md.

package/skills/stitch2/references/screens.md

@@ -1,14 +1,18 @@
 # Screens, versions and approval
 
-The canvas and the agents share one model: an app **screen** (home, settings, …) has **versions**, each for a
-**device** (mobile or desktop), and each version has a **status**. The user decides; agents read the decision
+The canvas and the agents share one model: an app **screen** (home, settings, …) has **versions**, design
+iterations numbered v1, v2, v3…, and each version has **variants**, its layouts for each device (mobile,
+desktop, later tablet). Each variant has a **status**. The user decides; agents read the decision
 and build on it. Meta tag names below use the project's prefix (`<p>`, from `stitch2.config.json`).
 
 ## Names and files
 
 - Screen names are lowercase with hyphens and name what the user sees; one per step of a flow
   (`checkout-1`, `checkout-2`). Reuse existing names (`stitch2 screens` lists them).
-- A version is one file, `<screens dir>/<screen>/<device>-v<N>.html`, N the next free number for that device.
+- A variant is one file, `<screens dir>/<screen>/<device>-v<N>.html`; the variants of a version share N
+  (`mobile-v3.html` and `desktop-v3.html` are v3). A new version takes the next free N across the screen's
+  variants; a variant added to an existing version takes that version's N (a desktop for v3 is
+  `desktop-v3.html`, never v4). A version may start with one variant and get the others later.
   Its head carries `<p>-screen`, `<p>-device` (mobile | desktop), `<p>-status`, `<p>-source` (stitch | lab),
   `<p>-frame-width` (390 mobile, 1280 desktop) and, written by the user, `<p>-note`. Older files elsewhere
   carry the same tags.
@@ -17,9 +21,11 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
 
 - **New version** for every new attempt: a new direction, a regeneration, an export from a generator, a
   redesign after feedback on an approved screen. It starts as `draft` and ends as `review`.
+- **New variant** for a device the version lacks (its desktop, its tablet): a new file with the version's N,
+  `draft` then `review`, even when the version's other variants are approved.
 - **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` version: copy it to the next number and change the copy.
+- **Never edit** an `approved` or `archived` variant: copy the version to the next number and change the copy.
 
 ## Statuses
 
@@ -28,7 +34,11 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
 | `draft` | Work in progress | The agent, while working |
 | `review` | Finished, waiting for the user ("Needs review") | The agent, when done |
 | `approved` | The reference: build on it, match it, implement it | The user only |
-| `archived` | History: superseded or rejected; hidden on the canvas | The user; approving a version archives the previously approved one |
+| `archived` | History: superseded or rejected; hidden on the canvas | The user; approving a variant archives the previously approved variant of the same device |
+
+The canvas shows each version with its variants side by side under one heading, and one status for the version:
+needs review while any variant does. **Approve version** approves every variant in review at once; a single
+variant can still be approved, archived or noted on its own.
 
 ## How to use them
 
@@ -55,15 +65,15 @@ the page needs a state first (an open sheet, a running workout), add a `prepare`
 
 ## Desktop
 
-Desktop is a device of the same screen, designed after the mobile version is approved: `desktop-v<N>.html`,
-frame width 1280, the same components and type levels, the layout from DESIGN.md (typically a sidebar instead
+Desktop is a variant of a version, designed after the version's mobile variant is approved: `desktop-v<N>.html`
+with the mobile's N, frame width 1280, the same components and type levels, the layout from DESIGN.md (typically a sidebar instead
 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 a medium-width device of the same screen.
+columns for feeds. When a project needs a tablet, it is one more variant, at a medium width.
 
 ## The canvas
 

package/skills/{stitch2-variants → stitch2-alternatives}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: stitch2-variants
+name: stitch2-alternatives
 description: Get fresh-eyes versions of a screen from agents that see no other versions (stitch2 sandbox), so alternatives are not anchored to what exists; or test a change to the skills on output only the rules produced. Use when the user wants alternatives or a new direction, feels stuck with a design, wants several options to choose from, or when a skill or DESIGN.md rule changed and you need evidence it helps.
 ---
 
-# Fresh-eyes variants with stitch2 sandboxes
+# Fresh-eyes alternatives with stitch2 sandboxes
 
 An agent that can see a screen's existing versions copies them, even when asked for something new. A sandbox
 is a folder with the project's design system, components, catalog, template and skills, and none of its screens,
@@ -16,8 +16,8 @@ the user to compare on the canvas.
    and structure only: colours, fonts and shapes come from DESIGN.md. Name the file after the screen
    (`history.md` designs `history`). For several directions, write one brief per direction with one sentence
    on what differs (`history.md` in sandbox A: "a calendar first"; in sandbox B: "a list first").
-2. **Create one sandbox per variant**: `stitch2 sandbox create /tmp/<project>-<screen>-a <brief.md>`.
-   `--context home stats` adds the approved versions of other screens, so the variant stays consistent with
+2. **Create one sandbox per alternative**: `stitch2 sandbox create /tmp/<project>-<screen>-a <brief.md>`.
+   `--context home stats` adds the approved versions of other screens, so the alternative stays consistent with
    them; `--device desktop` for desktop.
 3. **Run a fresh agent in each**, with no shared conversation: a sub-agent started without forked history,
    working only in that folder, told to read its AGENTS.md and follow the skills there. Without sub-agents, give