stitch2 0.24.0 → 0.24.1

package/README.md

@@ -262,7 +262,7 @@ layout first, then a shorter natural word, never a smaller type size.
 | `stitch2 init --name N --primary #hex [options]` | Writes a complete DESIGN.md from a few choices |
 | `stitch2 extract <url or file…>` | Writes a DESIGN.md measured from an existing site or screens |
 | `stitch2 canvas` | The canvas at http://localhost:4400 (`PORT` and `HOST` to change) |
-| `stitch2 check [filter] [--shots] [--strict] [--locales l,…]` | All checks, in every theme, app state and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`, `--auth-user.png`…) |
+| `stitch2 check [filter] [--shots] [--strict] [--locales l,…]` | All checks, in every theme, app state and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`, `--auth-user.png`…). Reruns visit only the screens that changed; after a change to stitch2, DESIGN.md, the tokens, the components or the catalog every screen is visited again, which takes minutes on a large project. Progress is printed to stderr, and `checks.json` is saved as screens finish and when the run is stopped (Ctrl-C), so the next run continues where it left off |
 | `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 |

package/dist/canvas.html

@@ -563,7 +563,15 @@ function tree() {
   item('Languages', 'screens × languages', docOpen('/languages'), () => openDoc('/languages'))
   const all = rows().filter((r) => r.key !== '~components' && r.visible.length)
   head('Screens')
-  const dotOf = (list) => (list.some((s) => s.status === 'approved') ? 'approved' : list.some((s) => s.status === 'review') ? 'review' : 'draft')
+  // A rollup is green only when nothing is pending: like versionsOf, review outranks approved, and archived
+  // versions do not count.
+  const dotOf = (list) => {
+    const live = list.filter((s) => s.status !== 'archived')
+    if (live.some((s) => s.status === 'review')) return 'review'
+    if (live.some((s) => s.status !== 'approved')) return 'draft'
+    if (live.some((s) => s.status === 'approved')) return 'approved'
+    return 'draft'
+  }
   const screenRow = (row, nested) => {
     const name = document.createElement('div')
     name.className = `screen-name${nested ? ' state' : ''}`

package/dist/check.js

@@ -17,9 +17,12 @@
  *   --shots   also save page-tall renders to design/renders/ (one per theme, app state, language and width)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
  * Screens run four at a time; reruns only visit screens that changed since design/checks.json (or
- * everything DESIGN.md, the tokens, the components or the catalog changed since).
+ * everything DESIGN.md, the tokens, the components, the catalog or stitch2 itself changed since: a first run after
+ * that visits every screen and takes minutes on a large project). Progress goes to stderr, one line per screen
+ * ("check: 37/588 …, about 14 min left"). design/checks.json is saved as screens finish and when the run is stopped
+ * (Ctrl-C, kill), so the next run continues with the screens that are left instead of starting over.
  */
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { chromium } from '@playwright/test';
@@ -56,7 +59,8 @@ const server = await startServer(0);
 /** The tallest render, in CSS px: a long landing page is shot whole (the canvas draws frames up to the same height). */
 const MAX_RENDER_HEIGHT = 20000;
 const fresh = async () => {
-    const browser = await chromium.launch();
+    // Signals are handled below: a stopped run saves what it has before the browsers close.
+    const browser = await chromium.launch({ handleSIGINT: false, handleSIGTERM: false, handleSIGHUP: false });
     const page = await browser.newPage({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2 });
     return { browser, page, visits: 0 };
 };
@@ -93,6 +97,63 @@ for (const s of screens) {
             components[s.path] = previous.components[s.path];
     }
 }
+const exists = new Set(listScreens().map((s) => s.path));
+const keep = (o) => Object.fromEntries(Object.entries(o).filter(([p]) => exists.has(p)));
+const freshPreviousComponents = Object.fromEntries(Object.entries(previous.components ?? {})
+    .filter(([path]) => previous.cacheKeys?.[path]?.startsWith(`${currentDeps}:`)
+    && previous.cacheKeys[path].endsWith(`:${fingerprintPaths([join(ROOT, path)])}`)));
+// What this run has finished is saved while it runs, not only at the end: a run that is stopped, killed or crashes
+// keeps its screens (their cache keys are current), and the next run visits only the rest. Written to a temporary
+// file and renamed, so the canvas never reads half a file.
+const writeChecks = (data) => {
+    const file = join(ROOT, 'checks.json');
+    writeFileSync(`${file}.tmp`, `${JSON.stringify({ checkedAt: new Date().toISOString(), ...data }, null, 2)}\n`);
+    renameSync(`${file}.tmp`, file);
+};
+/** Screens finished in this run. Catalogs wait for the end: their States sheet is only written then. */
+const finished = [];
+let lastSaved = Date.now();
+const saveProgress = () => {
+    const keys = { ...previous.cacheKeys };
+    const rows = { ...previous.screens };
+    for (const p of finished) {
+        keys[p] = cacheKeys[p];
+        rows[p] = results[p];
+    }
+    writeChecks({ cacheKeys: keep(keys), screens: keep(rows), components: keep({ ...freshPreviousComponents, ...components }) });
+    lastSaved = Date.now();
+};
+const note = (line) => process.stderr.write(`check: ${line}\n`);
+const duration = (seconds) => seconds < 90 ? `${Math.round(seconds)} s` : seconds < 5400 ? `${Math.round(seconds / 60)} min` : `${(seconds / 3600).toFixed(1)} h`;
+const sharedChanged = !!previous.cacheKeys && screens.length > 0 && screens.every((s) => !previous.cacheKeys[s.path]?.startsWith(`${currentDeps}:`));
+if (!todo.length)
+    note(`all ${screens.length} screens are unchanged since the last run`);
+else if (todo.length < screens.length)
+    note(`visiting ${todo.length} of ${screens.length} screens; the others are unchanged since the last run`);
+else
+    note(`visiting all ${screens.length} screens` +
+        (shots
+            ? ' (--shots renders every one)'
+            : sharedChanged
+                ? ' (DESIGN.md, the tokens, the components, the catalog or stitch2 itself changed, which rechecks every screen)'
+                : ''));
+if (todo.length > 40)
+    note('this takes a while: the finished screens are kept, so stopping it (Ctrl-C) loses nothing');
+let stopping = false;
+let finalising = false;
+for (const [signal, code] of [['SIGINT', 130], ['SIGTERM', 143], ['SIGHUP', 129]])
+    process.on(signal, () => {
+        // Everything is visited: the last write below is quick, and a partial save must not replace it.
+        if (finalising)
+            process.exit(code);
+        if (stopping)
+            return;
+        stopping = true;
+        saveProgress();
+        note(`stopped with ${finished.length} of ${todo.length} screens finished; they are kept, run it again to continue`);
+        const closed = Promise.all(pool.map((w) => w.browser.close().catch(() => { })));
+        void Promise.race([closed, new Promise((r) => setTimeout(r, 3000))]).finally(() => process.exit(code));
+    });
 const checkOne = async (s, worker) => {
     if (worker.visits > 0 && worker.visits % 20 === 0) {
         // A check loads each screen several times (themes, languages, widths); a fresh browser keeps long
@@ -248,16 +309,40 @@ const checkOne = async (s, worker) => {
                 message: `check crashed on this screen (${String(e).split('\n')[0]}): rerun to retry`,
             },
         ];
-        console.error(`check: ${s.path} crashed, recorded and continuing`);
+        if (!stopping)
+            console.error(`check: ${s.path} crashed (${String(e).split('\n')[0]}), recorded and continuing`);
     }
 };
 let cursor = 0;
+const startedAt = Date.now();
+let completed = 0;
+const progress = (path, seconds) => {
+    completed++;
+    const left = todo.length - completed;
+    const eta = completed >= 3 && left > 0 ? `, about ${duration(((Date.now() - startedAt) / 1000 / completed) * left)} left` : '';
+    note(`${completed}/${todo.length} ${path} (${duration(seconds)}${eta})`);
+};
 // One screen per worker at a time: workers pull from the queue, so a page is never shared.
 const drive = async (worker) => {
-    while (cursor < todo.length)
-        await checkOne(todo[cursor++], worker);
+    while (cursor < todo.length && !stopping) {
+        const s = todo[cursor++];
+        const began = Date.now();
+        await checkOne(s, worker);
+        // A stopped run closes the browsers under the screens still being checked: those are not results.
+        if (stopping)
+            return;
+        if (s.kind !== 'components')
+            finished.push(s.path);
+        progress(s.path, (Date.now() - began) / 1000);
+        if (Date.now() - lastSaved > 15_000)
+            saveProgress();
+    }
 };
 await Promise.all(pool.map((w) => drive(w)));
+// A stopped run has saved and is closing the browsers; the handler above ends the process.
+if (stopping)
+    await new Promise(() => { });
+finalising = true;
 await Promise.all(pool.map(async (w) => {
     await w.page.close().catch(() => { });
     await w.browser.close().catch(() => { });
@@ -291,11 +376,6 @@ async function shoot(page, s, theme, locale, at) {
     await page.screenshot({ path: join(ROOT, 'renders', name) });
     await page.setViewportSize({ width: s.width, height: 844 });
 }
-const exists = new Set(listScreens().map((s) => s.path));
-const keep = (o) => Object.fromEntries(Object.entries(o).filter(([p]) => exists.has(p)));
-const freshPreviousComponents = Object.fromEntries(Object.entries(previous.components ?? {})
-    .filter(([path]) => previous.cacheKeys?.[path]?.startsWith(`${currentDeps}:`)
-    && previous.cacheKeys[path].endsWith(`:${fingerprintPaths([join(ROOT, path)])}`)));
 const allComponents = keep({ ...freshPreviousComponents, ...components });
 // Archived versions are history: they do not vote on how a component should look.
 const archived = new Set(listScreens()
@@ -312,7 +392,11 @@ for (const s of screens) {
     for (const i of issues.filter((i) => i.severity === 'error'))
         console.log(`    ${i.type}: ${i.message}${i.text ? ` — “${i.text}”` : ''}`);
 }
-writeFileSync(join(ROOT, 'checks.json'), `${JSON.stringify({ checkedAt: new Date().toISOString(), cacheKeys: keep({ ...previous.cacheKeys, ...cacheKeys }), screens: keep({ ...previous.screens, ...results }), components: allComponents }, null, 2)}\n`);
+writeChecks({
+    cacheKeys: keep({ ...previous.cacheKeys, ...cacheKeys }),
+    screens: keep({ ...previous.screens, ...results }),
+    components: allComponents,
+});
 console.log(`\n${screens.length} screens checked, ${errors} errors. Results in design/checks.json (badges on the canvas).`);
 if (strict && errors)
     process.exit(1);

package/package.json

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

@@ -108,6 +108,9 @@ References, read before the first screen:
    create or hide a `label-wraps` issue on the trigger. The actual painted control label is still checked.
    Cached checks are invalidated when shared components, the catalog or the checker change. A filtered
    rerun refreshes only those screens; it must not make unrelated screens' older checks appear current.
+   The first unfiltered run after such a change visits every screen and can take many minutes on a large project:
+   it prints `check: n/total …` with an estimate to stderr, so leave it running and read that, and do not start a
+   second `check` beside it. Stopping it (Ctrl-C, kill) keeps the finished screens; the next run visits only the rest.
    Motion warnings: `motion-token` (a transition length DESIGN.md doesn't name) and `reduced-motion` (something
    still moves when the person asked for less); see motion.md. On the catalog, `state-*` warnings come from the
    States sheet (components.md, States).