stitch2 0.16.0 → 0.18.0

package/README.md

@@ -36,6 +36,8 @@ file that already exists. From there the agent spends its effort on the design.
 - **Canvas** (`stitch2 canvas`): every screen and its versions on a pan-and-zoom board, a sidebar with search
   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.
+  Only the screens in view are live pages; the rest, and every screen when you zoom out, are pictures the
+  canvas renders with Playwright and keeps on disk, so a project with hundreds of screens stays fast.
   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

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); }
@@ -80,7 +85,11 @@
   .frame.desktop .device { border-radius: 12px; }
   .frame.selected .device { outline: 3px solid var(--accent); }
   .frame.archived { opacity: .55; }
-  .device iframe { background: #fff; border: 0; display: block; }
+  /* A frame shows its picture (rendered by the server) until its live page is ready; only frames in view are live. */
+  .device iframe { background: #fff; border: 0; display: block; left: 0; position: absolute; top: 0; visibility: hidden; }
+  .frame.ready .device iframe { visibility: visible; }
+  .device .shot { display: block; left: 0; pointer-events: none; position: absolute; top: 0; user-select: none; }
+  .device .shot:not([src]) { display: none; }
   .device .shield { cursor: pointer; inset: 0; position: absolute; }
   .frame.live .shield { display: none; }
   .frame.changed .device { animation: flash 900ms ease-out; }
@@ -151,6 +160,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 = {
@@ -183,10 +194,11 @@ function setLang(l) {
   lang = l
   localStorage.setItem('stitch2-lang', l)
   document.getElementById('langFilter').value = l
-  for (const f of frames.values()) f.iframe.src = `/${f.screen.path}?pick${langQuery()}`
+  for (const f of frames.values()) if (f.iframe) { f.el.classList.remove('ready'); f.iframe.src = frameSrc(f.screen) }
   for (const f of frames.values()) badge(f)
   if (selected) inspector(selected)
   summary()
+  scheduleSync()
 }
 // Widths: each variant covers a range of windows (config widths); frames show it drawn, at the narrowest or the widest.
 let WIDTHS = {}
@@ -201,7 +213,7 @@ function setWidth(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`
+    size(f)
     setTimeout(() => measure(f), 300)
     setTimeout(() => measure(f), 1200)
   }
@@ -217,7 +229,7 @@ function widthOptions() {
   wsel.value = widthMode
 }
 function applyTheme(f) {
-  if (!themed()) return
+  if (!themed() || !f.iframe) return
   try { f.iframe.contentDocument.documentElement.dataset.theme = theme } catch {}
 }
 function setTheme(t) {
@@ -229,6 +241,7 @@ function setTheme(t) {
   if (selected) inspector(selected)
   summary()
   sendFilter()
+  scheduleSync()
 }
 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})`)
@@ -266,7 +279,14 @@ let screens = []
 let checks = { screens: {} }
 let reports = { consistency: null, compare: null }
 let selected = null
-const frames = new Map() // path -> { el, iframe, screen, height }
+const frames = new Map() // path -> { el, device, img, iframe (while live), screen, height }
+// Heights measured before, so the layout doesn't jump while pictures and pages load.
+const HEIGHTS = JSON.parse(localStorage.getItem('stitch2-heights') ?? '{}')
+let heightsTimer
+const saveHeights = () => { clearTimeout(heightsTimer); heightsTimer = setTimeout(() => localStorage.setItem('stitch2-heights', JSON.stringify(HEIGHTS)), 1000) }
+let layoutQueued = false
+/** Many frames measure themselves at once while loading: one layout per animation frame. */
+const scheduleLayout = () => { if (!layoutQueued) { layoutQueued = true; requestAnimationFrame(() => { layoutQueued = false; layout() }) } }
 
 const apply = () => {
   world.style.transform = `translate(${view.x}px, ${view.y}px) scale(${view.z})`
@@ -276,6 +296,7 @@ const apply = () => {
   viewport.style.backgroundPosition = `${view.x}px ${view.y}px`
   document.getElementById('zoom').textContent = `${Math.round(view.z * 100)}%`
   localStorage.setItem('stitch2-view', JSON.stringify(view))
+  scheduleSync()
 }
 const zoomAt = (cx, cy, z) => {
   z = Math.min(4, Math.max(0.03, z))
@@ -289,7 +310,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 +347,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 +380,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`
@@ -364,6 +412,7 @@ function layout() {
   }
   tree()
   sendFilter()
+  scheduleSync()
 }
 
 // ---- reports follow the filters: the open report (consistency, app comparison, languages) gets the files the
@@ -438,26 +487,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)
   }
 }
 
@@ -487,19 +560,128 @@ function zoomTo(f) {
 const MAX_FRAME_HEIGHT = 20000
 
 function measure(f) {
+  if (!f.iframe) return
   try {
     const doc = f.iframe.contentDocument
-    const min = bigFrame(f.screen) ? 800 : 844
     // As tall as the page, up to MAX_FRAME_HEIGHT: long landing pages are drawn whole.
-    const h = Math.min(MAX_FRAME_HEIGHT, Math.max(min, doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0))
-    if (Math.abs(h - f.height) > 2) {
-      f.height = h
-      f.iframe.style.height = `${h}px`
-      layout()
-    }
+    setHeight(f, Math.max(doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0))
   } catch {}
 }
 
+const minHeight = (s) => (bigFrame(s) ? 800 : 844)
+function setHeight(f, h) {
+  h = Math.min(MAX_FRAME_HEIGHT, Math.max(minHeight(f.screen), h))
+  HEIGHTS[`${f.screen.path}@${f.screen.width}`] = h
+  saveHeights()
+  if (Math.abs(h - f.height) <= 2) return
+  f.height = h
+  size(f)
+  scheduleLayout()
+}
+/** The device box, the picture and the live page all take the frame's width and height. */
+function size(f) {
+  const w = `${f.screen.width}px`, h = `${f.height}px`
+  Object.assign(f.device.style, { width: w, height: h })
+  f.img.style.width = w
+  if (f.iframe) Object.assign(f.iframe.style, { width: w, height: h })
+}
+const frameSrc = (s) => `/${s.path}?pick${langQuery()}`
+
+// ---- live frames: a screen is a whole page, so only the frames in view, at a zoom where you can work with them,
+// are live (at most MAX_LIVE, nearest the middle first), plus the selected one and those with picked elements.
+// The rest show the picture the server renders (/api/shot). Without pictures (no Chromium), frames in view stay
+// live at any zoom, still at most MAX_LIVE. ----
+const LIVE_ZOOM = 0.3, MAX_LIVE = 12, SHOTS_AT_ONCE = 3
+let shotRev = 0, shotErrors = 0, syncTimer
+const shotsFailed = () => shotErrors > 2
+const scheduleSync = () => { clearTimeout(syncTimer); syncTimer = setTimeout(syncLive, 120) }
+function shotUrl(s) {
+  const q = new URLSearchParams({ path: s.path, width: String(s.width), m: String(Math.round(s.mtime)), r: String(shotRev) })
+  if (themed()) q.set('theme', theme)
+  if (lang !== SOURCE) q.set('lang', lang)
+  return `/api/shot?${q}`
+}
+const pinned = (f) => f === selected || f.el.classList.contains('live') || picked.some((p) => p.f === f)
+function mount(f) {
+  if (f.iframe) return
+  const iframe = document.createElement('iframe')
+  iframe.setAttribute('scrolling', 'no')
+  f.iframe = iframe
+  size(f)
+  iframe.addEventListener('load', () => {
+    if (f.iframe !== iframe) return
+    applyTheme(f)
+    measure(f)
+    clearTimeout(f.reveal)
+    // Tailwind's browser build and the components settle just after load: the picture stays until then.
+    f.reveal = setTimeout(() => {
+      if (f.iframe !== iframe) return
+      measure(f)
+      f.el.classList.add('ready')
+      for (const go of f.waiters.splice(0)) go()
+    }, 350)
+    setTimeout(() => measure(f), 1200)
+    setTimeout(() => measure(f), 2500)
+  })
+  iframe.src = frameSrc(f.screen)
+  f.device.insertBefore(iframe, f.img.nextSibling)
+}
+function unmount(f) {
+  if (!f.iframe) return
+  clearTimeout(f.reveal)
+  // Cleared first: a page still loading can fire its load event as it's removed.
+  const iframe = f.iframe
+  f.iframe = null
+  iframe.remove()
+  f.el.classList.remove('ready', 'live')
+}
+/** Resolves once the frame's live page is ready: for what reads its document (locating an issue). */
+function whenLive(f) {
+  mount(f)
+  return f.el.classList.contains('ready') ? Promise.resolve() : new Promise((go) => f.waiters.push(go))
+}
+let shotsLoading = 0
+let shotQueue = [] // [frame, url], nearest the middle first
+function pumpShots() {
+  while (shotsLoading < SHOTS_AT_ONCE && shotQueue.length) {
+    const [f, url] = shotQueue.shift()
+    if (f.img.dataset.loading || f.img.getAttribute('src') === url || !frames.has(f.screen.path)) continue
+    shotsLoading++
+    f.img.dataset.loading = url
+    f.img.src = url
+  }
+}
+function shotDone(f, ok) {
+  if (!f.img.dataset.loading) return
+  delete f.img.dataset.loading
+  shotsLoading--
+  if (ok) { shotErrors = 0; if (!f.iframe) setHeight(f, f.img.naturalHeight) } else if (++shotErrors > 2) scheduleSync()
+  pumpShots()
+}
+function syncLive() {
+  const vw = innerWidth - SIDE, vh = innerHeight
+  const near = [], kept = new Set()
+  for (const f of frames.values()) {
+    if (f.el.style.display === 'none') { if (!pinned(f)) unmount(f); continue }
+    const x = view.x + parseFloat(f.el.style.left) * view.z, y = view.y + parseFloat(f.el.style.top) * view.z
+    const w = f.screen.width * view.z, h = (f.height + LABEL_H) * view.z
+    const beyond = (m) => x + w < -vw * m || x > vw * (1 + m) || y + h < -vh * m || y > vh * (1 + m)
+    if (!beyond(0.5)) near.push({ f, d: Math.hypot(x + w / 2 - vw / 2, y + Math.min(h, vh) / 2 - vh / 2) })
+    if (!beyond(1)) kept.add(f)
+  }
+  near.sort((a, b) => a.d - b.d)
+  const live = new Set([...frames.values()].filter(pinned))
+  if (view.z >= LIVE_ZOOM || shotsFailed()) {
+    for (const { f } of near) { if (live.size >= MAX_LIVE) break; live.add(f) }
+    // Frames just out of view stay live while there's room, so panning back and forth doesn't reload them.
+    for (const f of kept) { if (live.size >= MAX_LIVE) break; if (f.iframe) live.add(f) }
+  }
+  for (const f of frames.values()) if (f.iframe && !live.has(f)) unmount(f)
+  for (const f of live) mount(f)
+  shotQueue = near.filter(({ f }) => !f.el.classList.contains('ready')).map(({ f }) => [f, shotUrl(f.screen)])
+  pumpShots()
+}
+
 function badge(f) {
   const b = f.el.querySelector('.badge')
   if (!checks.screens?.[f.screen.path]) { b.className = 'badge'; b.textContent = 'not checked'; return }
@@ -512,7 +694,8 @@ function badge(f) {
 
 function paintLabel(f) {
   const s = f.screen
-  f.el.className = `frame ${s.device} ${s.status}${selected === f ? ' selected' : ''}`
+  const kept = ['ready', 'live', 'changed'].filter((c) => f.el.classList.contains(c))
+  f.el.className = ['frame', s.device, s.status, selected === f ? 'selected' : '', ...kept].filter(Boolean).join(' ')
   f.el.querySelector('.name').textContent = s.kind === 'components' ? 'Catalog' : s.device
   const pill = f.el.querySelector('.pill')
   pill.className = `pill ${s.status}`
@@ -527,23 +710,22 @@ 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) {
   const el = document.createElement('div')
   // The frame is exactly as wide as its device; a long title is cut, never widens it.
   el.style.width = `${s.width}px`
-  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 = `${bigFrame(s) ? 800 : 844}px`
-  iframe.src = `/${s.path}?pick${langQuery()}`
-  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.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"><img class="shot" alt="" decoding="async" draggable="false"><div class="shield"></div></div>`
+  const img = el.querySelector('.shot')
+  const f = { el, device: el.querySelector('.device'), img, iframe: null, screen: s, height: HEIGHTS[`${s.path}@${s.width}`] ?? minHeight(s), waiters: [] }
+  img.addEventListener('load', () => shotDone(f, true))
+  img.addEventListener('error', () => shotDone(f, false))
+  size(f)
   el.querySelector('.shield').addEventListener('click', () => select(f, false))
-  el.querySelector('.shield').addEventListener('dblclick', () => { select(f, false); f.el.classList.add('live') })
   el.querySelector('.label').addEventListener('click', () => select(f, true))
   el.querySelector('.label .copy').addEventListener('click', (e) => { e.stopPropagation(); copy(ref(f.screen)) })
   world.append(el)
@@ -559,10 +741,11 @@ function select(f, zoom) {
   const prev = selected
   selected = f
   if (prev) paintLabel(prev)
-  if (f) { paintLabel(f); inspector(f); if (zoom) zoomTo(f) }
+  if (f) { mount(f); paintLabel(f); inspector(f); if (zoom) zoomTo(f) }
   else document.getElementById('inspector').classList.remove('open')
   closeDoc()
   tree()
+  scheduleSync()
 }
 
 function inspector(f) {
@@ -650,7 +833,8 @@ async function setMeta(path, body) {
 }
 
 /** Outline the element in its frame and bring it to the middle of the canvas. */
-function locate(f, selector) {
+async function locate(f, selector) {
+  await whenLive(f)
   let el
   try { el = f.iframe.contentDocument.querySelector(selector) } catch {}
   if (!el) return
@@ -674,7 +858,7 @@ let hoverBox = null
 function elementAt(e) {
   const hit = document.elementsFromPoint(e.clientX, e.clientY).find((n) => n.classList?.contains('shield'))
   const f = hit && [...frames.values()].find((g) => g.el.contains(hit))
-  if (!f) return null
+  if (!f?.iframe) return null
   let doc
   try { doc = f.iframe.contentDocument } catch { return null }
   const r = f.iframe.getBoundingClientRect()
@@ -870,12 +1054,14 @@ events.onmessage = async (e) => {
   // Stylesheets and scripts are shared: tokens.css, tailwind.tokens.js, token exports the screens link
   // (tokens.tailwind.css), the components.
   const shared = paths.some((p) => /\.(css|js|mjs)$/.test(p) || p.startsWith('components/'))
+  if (shared) shotRev++
   for (const f of frames.values()) {
     if (shared || html.includes(f.screen.path)) {
-      f.iframe.contentWindow?.location.reload()
+      f.iframe?.contentWindow?.location.reload()
       f.el.classList.remove('changed'); void f.el.offsetWidth; f.el.classList.add('changed')
     }
   }
+  scheduleSync()
 }
 
 // ---- pan, zoom, keys ----
@@ -931,7 +1117,7 @@ addEventListener('keydown', (e) => {
   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)
-  if (e.key === 'r' || e.key === 'R') for (const f of frames.values()) f.iframe.contentWindow?.location.reload()
+  if (e.key === 'r' || e.key === 'R') reloadAll()
   if (['j', 'k', 'ArrowDown', 'ArrowUp'].includes(e.key)) {
     const list = visibleFrames()
     if (!list.length) return
@@ -944,7 +1130,13 @@ addEventListener('keydown', (e) => {
 })
 document.getElementById('fit').onclick = fit
 document.getElementById('pick').onclick = () => setPicking(!picking)
-document.getElementById('reload').onclick = () => { for (const f of frames.values()) f.iframe.contentWindow?.location.reload() }
+/** Reload the live frames and draw fresh pictures of the rest. */
+function reloadAll() {
+  shotRev++
+  for (const f of frames.values()) f.iframe?.contentWindow?.location.reload()
+  scheduleSync()
+}
+document.getElementById('reload').onclick = reloadAll
 
 apply()
 fetch('/api/config').then((r) => r.json()).then((c) => {

package/dist/i18n.d.ts

@@ -9,6 +9,7 @@ export declare const isRtl: (locale: string) => boolean;
 export declare const allLocales: () => string[];
 /** The locales check runs: with an i18n block, the pseudo-languages plus the configured ones; else only --locales. */
 export declare function checkLocales(override?: string): string[];
+export declare function messagesFile(locale: string): string | undefined;
 /**
  * A locale's messages: JSON, or a JS/TS module (its default export, else its first exported object; Node strips
  * the types). Re-read when the file changes. Empty when the file is missing.

package/dist/i18n.js

@@ -49,7 +49,7 @@ export function checkLocales(override) {
     const c = i18nConfig().check;
     return [...PSEUDO, ...(c === 'all' ? realLocales() : (c ?? []))];
 }
-function messagesFile(locale) {
+export function messagesFile(locale) {
     const m = i18nConfig().messages;
     if (!m)
         return undefined;

package/dist/list.js

@@ -4,20 +4,31 @@
  * 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, versionProblems } 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}):`);

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,6 +36,8 @@ 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;
 /**

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);

package/dist/serve.js

@@ -15,6 +15,7 @@ import { allLocales, localeScript, sourceLocale } from './i18n.js';
 import { designPage } from './design-page.js';
 import { languagesPage } from './languages-page.js';
 import { annotate } from './pick.js';
+import { closeShots, sharedChanged, shot } from './shots.js';
 /**
  * Inlines <link rel="stylesheet" type="text/tailwindcss" href="…">: the Tailwind v4 browser build reads @theme and
  * @utility only from inline <style type="text/tailwindcss"> blocks. On one line, so source line numbers hold.
@@ -63,17 +64,21 @@ const TYPES = {
     '.js': 'text/javascript; charset=utf-8',
     '.json': 'application/json',
     '.png': 'image/png',
+    '.jpg': 'image/jpeg',
     '.svg': 'image/svg+xml',
     '.md': 'text/markdown; charset=utf-8',
 };
 export function startServer(port) {
     const clients = new Set();
     const changed = new Set();
+    let base = '';
     let timer;
     // Editors write files in bursts; one event per quiet moment is enough.
     const watcher = watch(ROOT, { recursive: true }, (_event, file) => {
         if (!file || file.startsWith('renders'))
             return;
+        if (!file.toString().endsWith('.html'))
+            sharedChanged();
         changed.add(file.toString());
         clearTimeout(timer);
         timer = setTimeout(() => {
@@ -149,6 +154,29 @@ export function startServer(port) {
             return json(listScreens());
         if (url.pathname === '/api/reports')
             return json(reportStates());
+        // A picture of a screen, for the frames the canvas doesn't keep live (off screen, or too small to read).
+        if (url.pathname === '/api/shot') {
+            const q = url.searchParams;
+            const job = shot(base, {
+                path: q.get('path') ?? '',
+                width: Math.min(4000, Math.max(200, Number(q.get('width')) || 390)),
+                theme: q.get('theme') || undefined,
+                lang: q.get('lang') || undefined,
+            });
+            if (!job) {
+                res.writeHead(404, { 'content-type': 'text/plain' });
+                return res.end('not found');
+            }
+            job.then((jpg) => {
+                // The canvas puts the screen's change time in the address, so a picture never changes under it.
+                res.writeHead(200, { 'content-type': TYPES['.jpg'], 'cache-control': 'private, max-age=86400' });
+                res.end(jpg);
+            }, (e) => {
+                res.writeHead(503, { 'content-type': 'text/plain' });
+                res.end(`no picture: ${String(e)}. Install Chromium for Playwright: npx playwright install chromium`);
+            });
+            return;
+        }
         if (url.pathname === '/api/checks') {
             const file = join(ROOT, 'checks.json');
             return json(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { screens: {} });
@@ -195,6 +223,9 @@ export function startServer(port) {
         server.listen(port, host, () => {
             const address = server.address();
             const actual = typeof address === 'object' && address ? address.port : port;
+            // The renderer for pictures reaches the server where it listens; on every interface, through loopback.
+            const at = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host.includes(':') ? `[${host}]` : host;
+            base = `http://${at}:${actual}`;
             if (!process.env.HOST) {
                 v6 = createServer((req, res) => server.emit('request', req, res));
                 v6.on('error', () => { }).listen(actual, '::1');
@@ -206,6 +237,7 @@ export function startServer(port) {
                     clearInterval(keepAlive);
                     for (const c of clients)
                         c.end();
+                    void closeShots();
                     server.close();
                     v6?.close();
                 },

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/shots.d.ts

@@ -0,0 +1,11 @@
+export interface ShotRequest {
+    path: string;
+    width: number;
+    theme?: string;
+    lang?: string;
+}
+/** The server's file watcher calls this: the next picture looks at the shared files again. */
+export declare function sharedChanged(): void;
+/** A JPEG of the screen as the canvas would show it, page-tall up to MAX_HEIGHT; null when the file is gone. */
+export declare function shot(base: string, r: ShotRequest): Promise<Buffer> | null;
+export declare function closeShots(): Promise<void>;

package/dist/shots.js

@@ -0,0 +1,131 @@
+/**
+ * Pictures of screens for the canvas. A live screen is a whole page (Tailwind's browser build, fonts, icons, the
+ * components), so a canvas with a hundred of them stalls the browser; the canvas keeps only the screens in view live
+ * and draws the rest from these. One headless Chromium renders them, three at a time, and they are kept on disk
+ * (os.tmpdir()/stitch2-shots), keyed by everything that changes the picture: the screen file, the files screens
+ * share (tokens, components, stylesheets), the theme, the language and its messages, and the width.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { messagesFile, sourceLocale } from './i18n.js';
+import { ROOT } from './screens.js';
+/** The tallest picture, in CSS px: the same limit as the canvas frames and check's renders. */
+const MAX_HEIGHT = 20000;
+const DIR = join(tmpdir(), 'stitch2-shots');
+/** Folders under the design directory that hold outputs, not inputs: they never change a picture. */
+const OUTPUTS = new Set(['renders', 'consistency', 'compare', 'node_modules', '.git']);
+const REPORTS = new Set(['checks.json', 'compare.json', 'type-audit.json']);
+let shared;
+/** The newest of the files screens share: anything under the design directory that isn't a screen or an output. */
+function sharedStamp() {
+    if (shared !== undefined)
+        return shared;
+    let newest = 0;
+    const walk = (dir, depth) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.isDirectory()) {
+                if (depth === 0 && OUTPUTS.has(e.name))
+                    continue;
+                if (depth < 4)
+                    walk(join(dir, e.name), depth + 1);
+            }
+            else if (!e.name.endsWith('.html') && !(depth === 0 && REPORTS.has(e.name)))
+                newest = Math.max(newest, statSync(join(dir, e.name)).mtimeMs);
+        }
+    };
+    walk(ROOT, 0);
+    return (shared = newest);
+}
+/** The server's file watcher calls this: the next picture looks at the shared files again. */
+export function sharedChanged() {
+    shared = undefined;
+}
+function keyOf(r) {
+    const file = join(ROOT, r.path);
+    if (!existsSync(file))
+        return null;
+    const messages = r.lang && r.lang !== sourceLocale() ? messagesFile(r.lang) : undefined;
+    const parts = [
+        r.path,
+        statSync(file).mtimeMs,
+        sharedStamp(),
+        r.theme ?? '',
+        r.lang ?? '',
+        messages && existsSync(messages) ? statSync(messages).mtimeMs : '',
+        r.width,
+    ];
+    return createHash('sha1').update(parts.join('|')).digest('hex');
+}
+let browser;
+let busy = 0;
+const waiting = [];
+const pending = new Map();
+async function slot(work) {
+    while (busy >= 3)
+        await new Promise((go) => waiting.push(go));
+    busy++;
+    try {
+        return await work();
+    }
+    finally {
+        busy--;
+        waiting.shift()?.();
+    }
+}
+/** A JPEG of the screen as the canvas would show it, page-tall up to MAX_HEIGHT; null when the file is gone. */
+export function shot(base, r) {
+    const key = keyOf(r);
+    if (!key)
+        return null;
+    const file = join(DIR, `${key}.jpg`);
+    if (existsSync(file))
+        return Promise.resolve(readFileSync(file));
+    const inFlight = pending.get(key);
+    if (inFlight)
+        return inFlight;
+    const job = slot(async () => {
+        browser ??= launch();
+        const page = await (await browser).newPage({ viewport: { width: r.width, height: 844 }, deviceScaleFactor: 1 });
+        try {
+            const lang = r.lang && r.lang !== sourceLocale() ? `?lang=${encodeURIComponent(r.lang)}` : '';
+            await page.goto(`${base}/${r.path}${lang}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
+            if (r.theme)
+                await page.evaluate((t) => { document.documentElement.dataset.theme = t; }, r.theme);
+            await page.evaluate(() => document.fonts.ready);
+            // Tailwind's browser build and the components settle after load.
+            await page.waitForTimeout(400);
+            const height = await page.evaluate(() => Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0));
+            await page.setViewportSize({ width: r.width, height: Math.min(MAX_HEIGHT, Math.max(844, height)) });
+            const jpg = await page.screenshot({ type: 'jpeg', quality: 80 });
+            mkdirSync(DIR, { recursive: true });
+            writeFileSync(file, jpg);
+            return jpg;
+        }
+        finally {
+            await page.close();
+        }
+    });
+    pending.set(key, job);
+    const done = () => pending.delete(key);
+    job.then(done, done);
+    return job;
+}
+export async function closeShots() {
+    const b = await browser?.catch(() => undefined);
+    browser = undefined;
+    await b?.close();
+}
+/**
+ * Playwright's own signal handlers close the browser but leave the process running; the canvas would outlive
+ * Ctrl-C. Here a signal closes Chromium, then exits.
+ */
+async function launch() {
+    const { chromium } = await import('@playwright/test');
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+        process.once(signal, () => {
+            void closeShots().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+        });
+    return chromium.launch({ handleSIGINT: false, handleSIGTERM: false, handleSIGHUP: false });
+}

package/package.json

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