stitch2 0.17.0 → 0.18.1

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

@@ -85,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; }
@@ -190,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 = {}
@@ -208,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)
   }
@@ -224,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) {
@@ -236,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})`)
@@ -273,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})`
@@ -283,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))
@@ -398,6 +412,7 @@ function layout() {
   }
   tree()
   sendFilter()
+  scheduleSync()
 }
 
 // ---- reports follow the filters: the open report (consistency, app comparison, languages) gets the files the
@@ -545,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 }
@@ -570,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}`
@@ -594,15 +719,13 @@ 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)
@@ -618,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) {
@@ -709,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
@@ -733,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()
@@ -929,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 ----
@@ -990,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
@@ -1003,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/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/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.17.0",
+  "version": "0.18.1",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -38,6 +38,9 @@ References, read before the first screen:
 2. **Inventory.** List every element the brief names, in order, with its real data. That list is the screen:
    add nothing (status bars, step labels, tips, helper text, extra buttons), drop nothing. Next to each element
    write the catalog component that shows it; adapt or extend components rather than inventing markup.
+   Then list the page's **states**. A page that shows data gets an empty screen and a loading screen, designed
+   with its main screen in the same version; a page that loads or saves data that can fail also gets an error
+   state. Build them with the main screen; they are part of the page (screens.md, Empty, loading and error).
 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.
@@ -66,7 +69,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; only then
+   changed, how you answered their notes, and any rubric item you could not satisfy. The page's empty and loading
+   screens go to review with it; for a page without them (a form, a static page), say why. The user approves; only then
    does it go into the app (the approved version is the one current version: see screens.md).
 
 ## Commands

package/skills/stitch2/references/principles.md

@@ -56,7 +56,8 @@ short labels never wrap **(check)**.
   axis or month labels, a legend for a colour scale, captions under figures. They add no new facts.
 - Icons that stand for different things look different; one generic glyph repeated down a list says nothing.
 - Charts: one series in the accent, thin lines, few gridlines; label a single line directly instead of a legend.
-- Empty and loading states are designed too: one sentence and one action; skeletons the size of the content.
+- Empty and loading states are designed with every page that shows data: one sentence and one action; skeletons
+  the size of the content (screens.md, Empty, loading and error).
 
 ## Touch and mobile
 
@@ -86,3 +87,5 @@ Score each pass or fail from the render; done when all pass or the failures are
 8. **Data realism:** names, numbers and dates look like a real person's data.
 9. **Consistency:** built from the catalog components; no `reuse` or `consistency` warnings.
 10. **Checks:** `stitch2 check --strict` reports no errors.
+11. **States:** the page has its empty and loading screens (and error when data can fail), built from the same
+    components and layout as the main screen; or the hand-over says why it needs none.

package/skills/stitch2/references/screens.md

@@ -30,6 +30,32 @@ together; `stitch2 screens <page>` lists them. A screen without `<p>-page` is a
   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.
 
+## Empty, loading and error
+
+Every page that shows data has these states, and the app shows them on most first visits: a new user sees the
+empty screen before any other, and every user sees the loading one. Design them with the page's main screen,
+not after it.
+
+- **Which pages:** any page that lists, counts or charts the user's data, or loads it from a server. A form, a
+  dialog, a static page (sign-in, a landing page) needs none; say so in the hand-over.
+- **Names:** `<page>-empty` and `<page>-loading` (`history-empty`, `history-loading`), `<page>-error` when it
+  has one, with the page's `<p>-page`. Same version number and same variants (mobile, desktop) as the main
+  screen. A page whose main screen is a new version gets new versions of its states when they change.
+- **Empty:** the page's header and navigation stay where they are. In place of the content: what this place is
+  for in one sentence, and the one action that fills it ("Create your first routine"). Use the page's own
+  components where they help (a suggested program as a list row), not a large illustration. An empty search or
+  filter result is a different empty: it says nothing matched and how to widen it (clear the filter), and keeps
+  the search field and filters.
+- **Loading:** the same layout as the main screen, with skeletons in place of the data: blocks the size and
+  shape of the rows, cards and numbers that will arrive (typography.md, Text in each state). The header,
+  navigation and buttons that need no data stay real and usable. No spinner in the middle of the page and no
+  "Loading…" text; a spinner belongs only inside a button or a row that is saving. Build skeletons from a
+  catalog component, so every page loads the same way.
+- **Error:** the page's frame stays; where the data would be, one sentence on what failed and a Retry action.
+  Data already shown stays on screen; a failed save says so next to what failed and keeps the user's input.
+- **Partial states** follow the same rules inside a section: an empty list in a page that has other data shows
+  one line and an action in that section only.
+
 ## New version or edit?
 
 - **New version** for every new attempt: a new direction, a regeneration, an export from a generator, a

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

@@ -25,6 +25,11 @@ a component rebuilt by hand. The checks can only judge what the canvas draws, so
    single current version and the app matches it.
 4. **App**: the app picks the component up; wire it, then run `stitch2 compare <screen>`.
 
+A page in the app is its main screen and its states: implement its approved empty, loading and error screens with
+it. The app's loader is the loading screen's skeleton, shown until the data arrives, never a blank page or a lone
+spinner; data appearing all at once with no loading state is a bug. A page whose states were never designed goes
+back to the canvas for them first.
+
 Fixing a bug found in the app follows the same path: reproduce it on the canvas (a screen or catalog state that
 shows it), fix the component, check, then the app. If the canvas cannot show the bug, the canvas is missing a
 state: add it.
@@ -69,4 +74,3 @@ Read the findings as:
 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.
-