stitch2 0.15.3 → 0.17.0

package/README.md

@@ -72,7 +72,8 @@ file that already exists. From there the agent spends its effort on the design.
   ```
 - **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.
+  version as a whole or one variant at a time, and leave notes. The approved version is the one current version:
+  approving it archives every earlier one, and only it gets implemented.
 - **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.
@@ -253,7 +254,8 @@ layout first, then a shorter natural word, never a smaller type size.
 | `stitch2 i18n [filter] [--locale l] [--suggest] [--json]` | Message keys the source or a locale lacks, and screen text with no key |
 | `stitch2 consistency [kind…]` | The consistency report, `<design>/consistency/index.html` |
 | `stitch2 type [filter] [--json]` | The type audit |
-| `stitch2 screens [name] [--status s] [--json]` | Versions, statuses and notes |
+| `stitch2 screens [name] [--status s] [--json] [--strict]` | Versions, statuses and notes; flags a screen whose current version is unclear |
+| `stitch2 approve <path or filter…>` | Approve variants (the user's decision); every earlier version is archived |
 | `stitch2 tokens` | Tokens from DESIGN.md |
 | `stitch2 compare [screen…]` | The live app against the approved screens (`app` in the config) |
 | `stitch2 elements <entry>` | Bundle your components (`stitch2/elements`) for the screens |

package/dist/approve.d.ts

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

package/dist/approve.js

@@ -0,0 +1,24 @@
+/**
+ * Approves screen variants, as the user does on the canvas: each becomes the current version of its screen on its
+ * device, and every earlier version there is archived. Agents run it when the user approves in words ("approve
+ * the v3 screens"), never on their own.
+ * Usage: stitch2 approve <path or filter…>   (a path under the design folder, or part of one: "connect/", "-v3")
+ */
+import { approve, listScreens } from './screens.js';
+const filters = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+if (!filters.length) {
+    console.error('stitch2 approve <path or filter…>: which variants? ("home/mobile-v3", "connect/", "-v3")');
+    process.exit(1);
+}
+const targets = listScreens().filter((s) => s.kind === 'screen' && s.status !== 'archived' && filters.some((f) => s.path.includes(f)));
+if (!targets.length) {
+    console.error(`No screen variant matches ${filters.join(', ')}.`);
+    process.exit(1);
+}
+// Oldest first, so approving several versions of one screen leaves the latest current.
+targets.sort((a, b) => a.path.localeCompare(b.path, undefined, { numeric: true }));
+for (const t of targets) {
+    const archived = approve(t.path);
+    const note = archived.length ? `; archived ${archived.map((s) => s.version).join(', ')}` : '';
+    console.log(`approved ${t.screen} ${t.version} ${t.device}${note}`);
+}

package/dist/audit.js

@@ -36,6 +36,9 @@ export async function audit(opts) {
         if (closed && !closed.querySelector(':scope > summary')?.contains(el))
             return false;
         const r = el.getBoundingClientRect();
+        // Text kept for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
+        if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
+            return false;
         return r.width > 0 && r.height > 0;
     };
     const opacity = (el) => {

package/dist/canvas.html

@@ -58,6 +58,11 @@
   .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; }
+  .page-name .chev { color: var(--faint); display: inline-block; font-size: 10px; transition: transform .15s; width: 10px; }
+  .page-name.open .chev { transform: rotate(90deg); }
+  .screen-name.state { font-weight: 500; padding-left: 26px; }
+  .item.version.nested { padding-left: 30px; }
+  .item.variant.nested { padding-left: 52px; }
   .version { padding-left: 20px; }
   .dot { background: var(--faint); border-radius: 50%; flex: none; height: 8px; width: 8px; }
   .dot.approved { background: var(--good); } .dot.review { background: var(--warn); } .dot.draft { background: var(--muted); } .dot.archived { background: transparent; border: 1px solid var(--faint); }
@@ -151,6 +156,8 @@ const viewport = document.getElementById('viewport')
 const world = document.getElementById('world')
 const SIDE = 288, GAP_X = 72, GAP_Y = 150, GROUP_GAP = 200, LINE_W = 3400, ROW_LABEL_H = 52, LABEL_H = 38
 let ORDER = [] // screen order, from the config
+// Pages whose screens are unfolded in the sidebar.
+const openPages = new Set((() => { try { return JSON.parse(localStorage.getItem('stitch2-open-pages') ?? '[]') } catch { return [] } })())
 const STATUS_RANK = { approved: 0, review: 1, draft: 2, archived: 3 }
 const STATUS_LABEL = { approved: 'approved', review: 'needs review', draft: 'draft', archived: 'archived' }
 const STATUS_HINT = {
@@ -289,7 +296,19 @@ const zoomAt = (cx, cy, z) => {
 // 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))
+/** What a screen is within its page: its name without the page's ("entry" for workout-entry), or "main". */
+const stateOf = (screen, page) => (screen === page ? 'main' : screen.startsWith(`${page}-`) ? screen.slice(page.length + 1) : screen)
+// Pages keep their screens together: a page sorts where the first of its screens (or the page itself) is in the
+// config's order, its main screen first, the rest in order.
+const sortRows = (keys, pageOf) => {
+  const pageRank = new Map()
+  for (const k of keys) { const p = pageOf(k); pageRank.set(p, Math.min(pageRank.get(p) ?? 100, rowRank(k), rowRank(p))) }
+  return keys.sort((a, b) => {
+    const pa = pageOf(a), pb = pageOf(b)
+    if (pa !== pb) return pageRank.get(pa) - pageRank.get(pb) || pa.localeCompare(pb)
+    return (a === pa ? -1 : b === pb ? 1 : 0) || 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) =>
@@ -314,16 +333,31 @@ function shown(s) {
 const rows = () => {
   const by = new Map()
   for (const s of screens) by.set(rowKey(s), [...(by.get(rowKey(s)) ?? []), s])
-  return sortRows([...by.keys()]).map((k) => ({ key: k, all: sortVersions(by.get(k)), visible: sortVersions(by.get(k).filter(shown)) }))
+  const pageOf = (k) => (k === '~components' ? '~components' : by.get(k)[0].page || k)
+  const sizes = new Map()
+  for (const k of by.keys()) sizes.set(pageOf(k), (sizes.get(pageOf(k)) ?? 0) + 1)
+  return sortRows([...by.keys()], pageOf).map((k) => ({
+    key: k,
+    page: pageOf(k),
+    // A page with several screens: each is one of its states (entry, menu, empty…).
+    state: sizes.get(pageOf(k)) > 1 ? stateOf(k, pageOf(k)) : '',
+    all: sortVersions(by.get(k)),
+    visible: sortVersions(by.get(k).filter(shown)),
+  }))
 }
 
 // Screens flow left to right and wrap, like a design canvas; each screen's versions stay together.
 function layout() {
   for (const n of world.querySelectorAll('.row-label')) n.remove()
-  let x = 0, y = 0, lineH = 0
-  for (const row of rows()) {
+  let x = 0, y = 0, lineH = 0, page = ''
+  const all = rows()
+  const paged = new Set(all.filter((r) => r.state).map((r) => r.page))
+  for (const row of all) {
     for (const s of row.all) frames.get(s.path).el.style.display = row.visible.includes(s) ? '' : 'none'
     if (!row.visible.length) continue
+    // Each page with several screens starts its own line, so its states read together.
+    if (x > 0 && row.page !== page && (paged.has(row.page) || paged.has(page))) { x = 0; y += lineH + GAP_Y; lineH = 0 }
+    page = row.page
     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)
@@ -332,7 +366,7 @@ function layout() {
     label.className = 'row-label'
     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('b').textContent = row.key === '~components' ? 'Components' : row.state ? `${row.page} › ${row.state}` : row.key
     label.querySelector('span').textContent = row.key === '~components' ? 'the catalog every screen is built from' : approved.length ? `approved: ${approved.join(', ')}` : 'nothing approved yet'
     label.style.transform = `translate(${x}px, ${y}px)`
     label.style.maxWidth = `${groupW}px`
@@ -438,26 +472,50 @@ function tree() {
   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 all = rows().filter((r) => r.key !== '~components' && r.visible.length)
   head('Screens')
-  for (const row of all) {
-    if (row.key === '~components' || !row.visible.length) continue
+  const dotOf = (list) => (list.some((s) => s.status === 'approved') ? 'approved' : list.some((s) => s.status === 'review') ? 'review' : 'draft')
+  const screenRow = (row, nested) => {
     const name = document.createElement('div')
-    name.className = 'screen-name'
-    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.className = `screen-name${nested ? ' state' : ''}`
+    name.innerHTML = `<span class="dot ${dotOf(row.all)}"></span><span></span><span class="meta"></span>`
+    name.children[1].textContent = nested ? row.state : row.key
     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)
+    const sub = nested ? ' nested' : ''
     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))
+      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${sub}`, 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${sub}`, ref(s))
+    }
+  }
+  // A page with several screens folds them under its name; it opens on a click, while one of them is selected, or
+  // while searching.
+  const searching = !!document.getElementById('search').value.trim()
+  for (let i = 0; i < all.length; ) {
+    const page = all[i].page
+    const group = []
+    while (i < all.length && all[i].page === page) group.push(all[i++])
+    if (!group[0].state) { screenRow(group[0], false); continue }
+    const open = searching || openPages.has(page) || group.some((r) => r.all.some((s) => s.path === selected?.screen.path))
+    const pageRow = document.createElement('div')
+    pageRow.className = `screen-name page-name${open ? ' open' : ''}`
+    pageRow.innerHTML = `<span class="chev">▶</span><span class="dot ${dotOf(group.flatMap((r) => r.all))}"></span><span></span><span class="meta"></span>`
+    pageRow.children[2].textContent = page
+    pageRow.querySelector('.meta').textContent = `${group.length} screens`
+    pageRow.title = group.map((r) => r.state).join(', ')
+    pageRow.onclick = () => {
+      if (openPages.has(page)) openPages.delete(page)
+      else openPages.add(page)
+      localStorage.setItem('stitch2-open-pages', JSON.stringify([...openPages]))
+      tree()
     }
+    nav.append(pageRow)
+    if (open) for (const row of group) screenRow(row, true)
   }
 }
 
@@ -527,8 +585,9 @@ function summary() {
   const review = versions.filter((s) => s.status === 'review').length
   const approved = new Set(versions.filter((s) => s.status === 'approved').map((s) => s.screen)).size
   const names = new Set(versions.map((s) => s.screen)).size
+  const pages = new Set(versions.map((s) => s.page || s.screen)).size
   const bad = versions.filter((s) => forTheme(checks.screens?.[s.path]).some((i) => i.severity === 'error')).length
-  document.getElementById('summary').textContent = `${names} screens · ${approved} approved · ${review} need review${bad ? ` · ${bad} with errors` : ''}`
+  document.getElementById('summary').textContent = `${pages < names ? `${pages} pages · ` : ''}${names} screens · ${approved} approved · ${review} need review${bad ? ` · ${bad} with errors` : ''}`
 }
 
 function frameFor(s) {

package/dist/cli.js

@@ -42,7 +42,8 @@ const COMMANDS = {
         'i18n-report.ts',
         '[filter] [--locale l] [--suggest] [--json]  Keys screens use that a locale lacks, and screen text with no key',
     ],
-    screens: ['list.ts', '[name] [--status s] [--json]  Screen versions, statuses and notes'],
+    screens: ['list.ts', '[name] [--status s] [--json] [--strict]  Screen versions, statuses, notes, and which version is current'],
+    approve: ['approve.ts', '<path or filter…>  Approve variants for the user; earlier versions are archived'],
     localize: ['assets.ts', '[filter]  Copy remote images a screen uses into its assets/ folder'],
     sandbox: [
         'sandbox.ts',

package/dist/list.js

@@ -1,19 +1,39 @@
 /**
  * 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]
+ * Ends with what makes the current version unclear (versionProblems); --strict fails on it.
+ * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json] [--strict]
  */
-import { listScreens } from './screens.js';
+import { listScreens, stateOf, versionProblems } from './screens.js';
 const args = process.argv.slice(2);
 const status = args.includes('--status') ? args[args.indexOf('--status') + 1] : undefined;
 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) ||
+    .filter((s) => s.kind === 'screen' && (!status || s.status === status) && (!name || s.screen === name || s.page === name))
+    .sort((a, b) => a.page.localeCompare(b.page) ||
+    (a.screen === a.page ? -1 : b.screen === b.page ? 1 : 0) ||
+    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.version.padEnd(8)} ${s.device.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);
+else {
+    let page = '';
+    for (const s of rows) {
+        // A page with several screens gets a heading; its screens are listed under it by their state.
+        const several = rows.some((r) => r.page === s.page && r.screen !== s.screen);
+        if (several && s.page !== page)
+            console.log(`\n${s.page} (page)`);
+        page = s.page;
+        const label = several ? `  ${stateOf(s)}` : s.screen;
+        console.log(`${label.padEnd(20)} ${s.version.padEnd(8)} ${s.device.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);
+    }
+}
+const problems = versionProblems().filter((p) => !name || p.startsWith(`${name} `));
+if (problems.length && !args.includes('--json')) {
+    console.log(`\nWhich version is current is unclear (${problems.length}):`);
+    for (const p of problems)
+        console.log(`  ${p}`);
+}
+if (problems.length && args.includes('--strict'))
+    process.exit(1);

package/dist/screens.d.ts

@@ -19,6 +19,12 @@ export interface Screen {
     kind: 'screen' | 'components';
     /** Which app screen this file is a version of (<meta name="<prefix>-screen">), e.g. "home". */
     screen: string;
+    /**
+     * The page it belongs to (<meta name="<prefix>-page">): one place in the app whose states and steps are screens of
+     * their own, e.g. "workout" for workout, workout-entry and workout-menu. A screen's latest version that names one
+     * decides it for all of its versions; without one a screen is its own page.
+     */
+    page: string;
     device: 'mobile' | 'desktop';
     /** Where the version came from: stitch, lab or trial. */
     source: 'stitch' | 'lab' | 'trial';
@@ -30,5 +36,21 @@ export interface Screen {
 }
 export declare const meta: (html: string, name: string) => string | undefined;
 export declare function listScreens(): Screen[];
+/** What a screen is within its page: its name without the page's ("entry" for workout-entry), or "main". */
+export declare const stateOf: (s: Pick<Screen, 'screen' | 'page'>) => string;
 /** Sets (or removes, with undefined) <prefix>-* meta tags in a screen file, keeping the rest of it untouched. */
 export declare function writeMeta(path: string, values: Record<string, string | undefined>): void;
+/**
+ * Approves a variant. Approval makes it the one current version of its screen on its device: every earlier
+ * version there (approved, in review or a draft) and any other approved one become archived, so nobody can mistake
+ * an older one for what is implemented. Later versions (a newer proposal) keep their status.
+ * Returns the variants it archived.
+ */
+export declare function approve(path: string): Screen[];
+/**
+ * What makes it unclear which version of a screen is current: two approved on one device, or an earlier version
+ * still in review or a draft next to an approved later one. One line each; empty when every screen is clear.
+ */
+export declare function versionProblems(screens?: Screen[]): string[];
+/** A version's number: 3 for "v3"; NaN for one without (a Stitch export, a trial). */
+export declare const versionNumber: (s: Pick<Screen, 'version'>) => number;

package/dist/screens.js

@@ -51,6 +51,7 @@ export function listScreens() {
                 mtime: statSync(file).mtimeMs,
                 kind: under(path, config.catalogDir) ? 'components' : 'screen',
                 screen: meta(html, tag('screen')) ?? (versioned ? group.split('/').pop() : name),
+                page: meta(html, tag('page')) ?? '',
                 device: (meta(html, tag('device')) ??
                     (versioned?.[1] || (width >= 768 ? 'desktop' : 'mobile'))),
                 source,
@@ -65,8 +66,17 @@ export function listScreens() {
             });
         }
     }
+    // One page per screen: the latest version that names one.
+    const pages = new Map();
+    for (const s of [...out].sort((a, b) => versionNumber(b) - versionNumber(a) || b.mtime - a.mtime))
+        if (s.page && !pages.has(s.screen))
+            pages.set(s.screen, s.page);
+    for (const s of out)
+        s.page = pages.get(s.screen) ?? s.screen;
     return out;
 }
+/** What a screen is within its page: its name without the page's ("entry" for workout-entry), or "main". */
+export const stateOf = (s) => s.screen === s.page ? 'main' : s.screen.startsWith(`${s.page}-`) ? s.screen.slice(s.page.length + 1) : s.screen;
 /** Sets (or removes, with undefined) <prefix>-* meta tags in a screen file, keeping the rest of it untouched. */
 export function writeMeta(path, values) {
     const file = join(ROOT, path);
@@ -83,3 +93,52 @@ export function writeMeta(path, values) {
     }
     writeFileSync(file, html);
 }
+/**
+ * Approves a variant. Approval makes it the one current version of its screen on its device: every earlier
+ * version there (approved, in review or a draft) and any other approved one become archived, so nobody can mistake
+ * an older one for what is implemented. Later versions (a newer proposal) keep their status.
+ * Returns the variants it archived.
+ */
+export function approve(path) {
+    const all = listScreens();
+    const target = all.find((s) => s.path === path);
+    if (!target || target.kind !== 'screen')
+        throw new Error(`not a screen: ${path}`);
+    writeMeta(path, { [tag('status')]: 'approved' });
+    const n = versionNumber(target);
+    const outdated = all.filter((s) => s.path !== path &&
+        s.kind === 'screen' &&
+        s.screen === target.screen &&
+        s.device === target.device &&
+        s.status !== 'archived' &&
+        (s.status === 'approved' || versionNumber(s) < n));
+    for (const s of outdated)
+        writeMeta(s.path, { [tag('status')]: 'archived' });
+    return outdated;
+}
+/**
+ * What makes it unclear which version of a screen is current: two approved on one device, or an earlier version
+ * still in review or a draft next to an approved later one. One line each; empty when every screen is clear.
+ */
+export function versionProblems(screens = listScreens()) {
+    const out = [];
+    const groups = new Map();
+    for (const s of screens) {
+        if (s.kind !== 'screen' || s.status === 'archived')
+            continue;
+        const key = `${s.screen} ${s.device}`;
+        groups.set(key, [...(groups.get(key) ?? []), s]);
+    }
+    for (const [key, list] of groups) {
+        const approved = list.filter((s) => s.status === 'approved');
+        if (approved.length > 1)
+            out.push(`${key}: ${approved.map((s) => s.version).join(' and ')} are all approved; approve the current one again`);
+        const current = Math.max(...approved.map(versionNumber).filter((n) => !Number.isNaN(n)));
+        for (const s of list)
+            if (s.status !== 'approved' && versionNumber(s) < current)
+                out.push(`${key}: ${s.version} is still ${s.status} although v${current} is approved; archive it (${s.path})`);
+    }
+    return out.sort();
+}
+/** A version's number: 3 for "v3"; NaN for one without (a Stitch export, a trial). */
+export const versionNumber = (s) => Number(/^v(\d+)$/.exec(s.version)?.[1] ?? Number.NaN);

package/dist/serve.js

@@ -28,7 +28,7 @@ function inlineTailwind(html, file) {
         return `<style type="text/tailwindcss">${readFileSync(css, 'utf8').replace(/\s*\n\s*/g, ' ')}</style>`;
     });
 }
-import { listScreens, ROOT, STATUSES, tag, writeMeta } from './screens.js';
+import { listScreens, ROOT, STATUSES, tag, writeMeta, approve } 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
@@ -131,14 +131,9 @@ export function startServer(port) {
                     if (note !== undefined)
                         values[tag('note')] = note.trim() || undefined;
                     writeMeta(path, values);
-                    // One approved version per screen and device: approving archives the previous one.
-                    if (status === 'approved')
-                        for (const s of all)
-                            if (s.path !== path &&
-                                s.screen === target.screen &&
-                                s.device === target.device &&
-                                s.status === 'approved')
-                                writeMeta(s.path, { [tag('status')]: 'archived' });
+                    // One current version per screen and device: approving archives every earlier one (screens.ts).
+                    if (status === 'approved' && target.kind === 'screen')
+                        approve(path);
                     json(listScreens());
                 }
                 catch (e) {

package/dist/setup.js

@@ -92,7 +92,7 @@ ${extra}<meta charset="utf-8" />
 <script src="/components/${prefix}.js" defer></script>
 </head>
 `;
-write(join(design, 'screens/_template.html'), `${head('Screen name', `<meta name="${prefix}-screen" content="screen-name" />\n<meta name="${prefix}-device" content="mobile" />\n<meta name="${prefix}-status" content="draft" />\n`)}<!--
+write(join(design, 'screens/_template.html'), `${head('Screen name', `<meta name="${prefix}-screen" content="screen-name" />\n<meta name="${prefix}-page" content="screen-name" />\n<meta name="${prefix}-device" content="mobile" />\n<meta name="${prefix}-status" content="draft" />\n`)}<!--
   Template for ${name} screens. Copy it to ${design}/screens/<screen>/<device>-v<N>.html and set the ${prefix}-* meta
   tags (desktop: ${prefix}-device desktop and ${prefix}-frame-width 1280); status draft while you work, review when
   done. Files starting with _ are not shown on the canvas. Build with the components in the catalog

package/dist/typecheck.js

@@ -30,6 +30,9 @@ export function collectText() {
         const r = el.getBoundingClientRect();
         if (!r.width || !r.height)
             continue;
+        // Text for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
+        if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
+            continue;
         let opacity = 1;
         for (let e = el; e; e = e.parentElement)
             opacity *= Number(getComputedStyle(e).opacity);

package/package.json

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

@@ -66,7 +66,8 @@ References, read before the first screen:
 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
-   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves.
+   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves; only then
+   does it go into the app (the approved version is the one current version: see screens.md).
 
 ## Commands
 
@@ -80,7 +81,8 @@ References, read before the first screen:
 | `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 |
-| `screens [name] [--status s] [--json]` | Every version with its status and the user's note |
+| `screens [name] [--status s] [--json] [--strict]` | Every version with its status and the user's note, and anything that makes the current version unclear |
+| `approve <path or filter…>` | Approves variants for the user (only on their word); every earlier version of the screen on that device is archived |
 | `compare [screen…]` | The live app against the approved versions: missing or extra components, order, looks; a side-by-side report |
 | `elements <entry>` | Bundles the app's components, turned into elements with `stitch2/elements`, for the screens |
 | `tokens` | `tokens.css` (colours, `.type-*` classes) and `tailwind.tokens.js` from DESIGN.md |

package/skills/stitch2/references/screens.md

@@ -13,10 +13,23 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
   (`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),
+  Its head carries `<p>-screen`, `<p>-page` (see Pages), `<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.
 
+## Pages and their screens
+
+A place in the app often has several states or steps: the workout with its number pad, its menu and its discard
+question; an exercise list with its detail sheet and a three-step form. Each is a **screen** of its own (it has its own
+versions and approval), and they belong to one **page**: `<p>-page` in the head, the page's name (`workout`). The page's
+main screen has the page's name; the others are named `<page>-<state>` (`workout-entry`, `workout-menu`,
+`create-exercise-1`) and carry the same `<p>-page`. The canvas folds a page's screens under its name and lays them out
+together; `stitch2 screens <page>` lists them. A screen without `<p>-page` is a page of its own.
+
+- A new state of an existing place (a sheet, a dialog, an empty, loading or error state, a step) is a new screen in
+  that page, not a new page.
+- Copy `<p>-page` along with the other tags into each new version; the latest version that has it decides the page.
+
 ## New version or edit?
 
 - **New version** for every new attempt: a new direction, a regeneration, an export from a generator, a
@@ -35,8 +48,13 @@ 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 variant archives the previously approved variant of the same device |
+| `approved` | The current version: the reference to build on and match, and the only one the app implements | The user only (on the canvas, or in words: then the agent runs `stitch2 approve`) |
+| `archived` | Outdated: superseded or rejected; hidden on the canvas | Approval: approving a variant archives every earlier version of that screen on that device, whatever its status |
+
+**One current version.** For each screen and device there is at most one approved variant, and it is what the app
+shows. Approving one archives every earlier version there (approved, in review or a draft), so nothing older can be
+mistaken for the current one; a later version, a newer proposal, keeps its status. `stitch2 screens` ends with
+anything that breaks this (two approved, an older version still in review); `--strict` fails on it.
 
 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
@@ -47,8 +65,12 @@ variant can still be approved, archived or noted on its own.
 1. Before designing, run `stitch2 screens` (a name or `--status approved` narrows it) and open the approved
    versions of the screens next to yours.
 2. A note is the user's feedback: address every point in your next version or edit, and say how.
-3. Never set `approved` yourself; never build on an archived version unless asked.
-4. Only approved versions get implemented in the product.
+3. Never approve on your own and never build on an archived version unless asked. When the user approves in words
+   ("approve the v3 screens"), run `stitch2 approve <path or filter…>` rather than editing status tags: it archives the
+   earlier versions as the canvas does.
+4. **Implement only approved versions.** A version in review or a draft is not built in the app, not even partly. If
+   the user asks to implement one that is not approved yet, that request is their approval: run `stitch2 approve` on it
+   first and say so. If the app needs something no approved version shows, design it and hand it over first.
 5. When the user pastes a reference copied from the canvas, such as `home mobile v2
    (design/screens/home/mobile-v2.html)`, open that file: it names exactly the version they mean.
 6. A reference to an element adds its source line, its tag and its text: `home mobile v1
@@ -59,7 +81,7 @@ variant can still be approved, archived or noted on its own.
 
 ## Implementing an approved version
 
-Build the screen in the app from the same components the screens use, in the version's order, with the app's
+Check first with `stitch2 screens <screen>` that the version is approved and is the only approved one on its device. Build the screen in the app from the same components the screens use, in the version's order, with the app's
 own data, strings and behaviour; keep the app's tests passing. Then run `stitch2 compare <screen>` with the app
 running: fix every `missing` component and look at the side-by-side report. `extra` and `order` warnings are
 fine when the app needs them (a desktop-only control, a frame drawn by layout); say so when you hand over. When

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

@@ -19,7 +19,10 @@ a component rebuilt by hand. The checks can only judge what the canvas draws, so
    approved screen if the change is visible there; a catalog entry for a new variant or state), and run
    `stitch2 check <screens> --strict`. Look at the screens yourself: the check finds overlaps and overflow, not
    ugliness.
-3. **Approval**: the user approves the new versions (or the catalog change) as for any design.
+3. **Approval**: the user approves the new versions (or the catalog change) as for any design. Nothing goes into
+   the app before this: a version in review is not implemented, not even partly. When the user asks to implement
+   one in review, run `stitch2 approve` on it first; that archives the earlier versions, so the approved one is the
+   single current version and the app matches it.
 4. **App**: the app picks the component up; wire it, then run `stitch2 compare <screen>`.
 
 Fixing a bug found in the app follows the same path: reproduce it on the canvas (a screen or catalog state that
@@ -62,7 +65,8 @@ Read the findings as:
 
 ## Before you call it done
 
-1. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
-2. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
-3. The user has seen the canvas versions of anything that changed how a component looks.
+1. Every screen you implemented is approved, and `stitch2 screens --strict` passes: one current version each.
+2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
+3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
+4. The user has seen the canvas versions of anything that changed how a component looks.