stitch2 0.23.0 → 0.24.1

package/README.md

@@ -59,7 +59,7 @@ file that already exists. From there the agent spends its effort on the design.
   icon-only controls without a name, more than five bottom-navigation destinations and controls without visible
   focus. Motion: transitions whose length isn't one of DESIGN.md's motion tokens, and anything that still moves
   with reduced motion on. Each screen is also run in long and right-to-left
-  pseudo-languages and your locales (see below).
+  pseudo-languages and your locales (see below), and, with `modes`, in each app state it is not drawn in.
 - **States** (from `stitch2 check` on the component catalog): every control at rest, hovered, focused and
   pressed, forced through Chromium so the components need nothing extra, side by side on one sheet; with
   warnings for a control that gives no feedback and text that loses contrast in a state.
@@ -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 and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.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/config.schema.json

@@ -79,7 +79,7 @@
     },
     "modes": {
       "type": "array",
-      "description": "App states every screen can be shown in, picked from the canvas sidebar: signed in or out, a plan, a role. The pick is an attribute on each screen's <html>, so the screens' own CSS and scripts answer to it. The dropdown also offers the screens as drawn, which leaves each one as its file has it.",
+      "description": "App states every screen can be shown in, picked from the canvas sidebar: signed in or out, a plan, a role. The pick is an attribute on each screen's <html>, so the screens' own CSS and scripts answer to it. The dropdown also offers the screens as drawn, which leaves each one as its file has it. stitch2 check also runs each screen in every value its file does not already have, one mode at a time, and tags what only shows there.",
       "items": {
         "type": "object",
         "additionalProperties": false,

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' : ''}`
@@ -920,7 +928,10 @@ function inspector(f) {
     li.querySelector('code').textContent = i.selector
     li.onclick = () => {
       const r = rangeOf(s)
-      if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : i.width === r[1] ? 'wide' : `at:${i.width}`); setTimeout(() => locate(f, i.selector), 900) }
+      // An issue found in another app state: show every screen in it, then find the element.
+      const [mode, value] = i.mode ? i.mode.split(':') : []
+      if (mode && modePick[mode] !== value) { setMode(mode, value); setTimeout(() => locate(f, i.selector), 600) }
+      else if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : i.width === r[1] ? 'wide' : `at:${i.width}`); setTimeout(() => locate(f, i.selector), 900) }
       else locate(f, i.selector)
     }
     ul.append(li)

package/dist/check.js

@@ -5,24 +5,30 @@
  * the canvas shows as badges.
  * Every screen is checked in its own theme, then again in each other theme DESIGN.md defines (designThemes):
  * colours change there, so contrast is checked again, tagged with the theme.
+ * Then in each app state (config modes), one mode at a time and in the screen's own theme: a screen is checked with
+ * every value its own file does not already have, and what only shows there (a bar that overflows signed in, a control
+ * that crowds another) is tagged with the state.
  * Then again in each check language (i18n.ts: the pseudo-languages and the config's): layout problems that
  * show only there (a label running into its neighbour, text cut off, a control drawn backwards right to left),
  * and keys a locale has no translation for, tagged with the locale. Last, each variant at both ends of the widths
  * it covers (config widths: mobile 360–599, desktop 1024–1920 by default) and at every breakpoint inside them
  * (config breakpoints, Tailwind's by default), tagged with the width.
  * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
- *   --shots   also save page-tall renders to design/renders/ (one per theme, language and width)
+ *   --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';
 import { fingerprintPaths } from './cache.js';
 import { colourIssues } from './colours.js';
-import { CONFIG_FILE, checkWidths, config } from './config.js';
+import { CONFIG_FILE, checkWidths, config, modes } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
 import { designThemes, motionDurations, typeLevels } from './design-md.js';
 import { checkLocales } from './i18n.js';
@@ -40,6 +46,7 @@ const filters = args.filter((a, i) => !a.startsWith('--') && (localesFlag < 0 ||
 const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
 const levels = typeLevels();
 const themes = designThemes();
+const appModes = modes();
 const collect = collectOptions();
 /** What the layout audit needs: the comfortable tap size and DESIGN.md's motion durations. */
 const auditOpts = { comfortable: config.comfortableTarget, durations: (() => { try {
@@ -52,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 };
 };
@@ -89,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
@@ -134,6 +199,23 @@ const checkOne = async (s, worker) => {
         }
         if (themes.length > 1)
             await setTheme(page, base);
+        // The app states: each value the screen is not drawn in, one mode at a time, then the screen's own value again.
+        for (const mode of appModes) {
+            const drawn = await page.evaluate((attribute) => document.documentElement.getAttribute(attribute), mode.attribute);
+            for (const value of mode.values.filter((v) => v.value !== drawn)) {
+                await setAttribute(page, mode.attribute, value.value);
+                for (const i of await page.evaluate(audit, auditOpts)) {
+                    const key = `${i.type} ${i.selector}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    themed.push({ ...i, ...(i.type === 'contrast' ? { theme: base } : {}), mode: `${mode.name}:${value.value}`, message: `${value.label}: ${i.message}` });
+                }
+                if (shots)
+                    await shoot(page, s, undefined, undefined, `${mode.name}-${value.value}`);
+            }
+            await setAttribute(page, mode.attribute, drawn);
+        }
         const typed = typeIssues(levels, await page.evaluate(collectText));
         if (shots)
             await shoot(page, s);
@@ -227,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(() => { });
@@ -251,7 +357,16 @@ async function setTheme(page, theme) {
     }, theme);
     await page.waitForTimeout(150);
 }
-/** A page-tall render; renders in another theme or language than the screen's own get a --<theme> suffix. */
+async function setAttribute(page, attribute, value) {
+    await page.evaluate(([name, to]) => {
+        if (to === null)
+            document.documentElement.removeAttribute(name);
+        else
+            document.documentElement.setAttribute(name, to);
+    }, [attribute, value]);
+    await page.waitForTimeout(150);
+}
+/** A page-tall render; renders in another theme, app state or language than the screen's own get a --<name> suffix. */
 async function shoot(page, s, theme, locale, at) {
     const height = await page.evaluate(() => document.documentElement.scrollHeight);
     await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, MAX_RENDER_HEIGHT)) });
@@ -261,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()
@@ -282,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/dist/config.d.ts

@@ -60,7 +60,8 @@ export interface LabConfig {
     sandboxExclude?: string[];
     /**
      * App states shown across all screens (see ModeConfig). The canvas has a dropdown for each, with the screens as drawn
-     * first; picking a value sets its attribute on every screen, live ones and the pictures of the rest.
+     * first; picking a value sets its attribute on every screen, live ones and the pictures of the rest. stitch2 check also
+     * runs each screen in every value its file does not already have, one mode at a time.
      */
     modes?: ModeConfig[];
     /** The live app, for stitch2 compare (see compare.ts): its URL, a sign-in script and a route per screen. */

package/dist/typecheck.d.ts

@@ -15,6 +15,8 @@ export interface Issue {
     locale?: string;
     /** Set when the issue shows only at another window width: the edge of its variant's range (config widths). */
     width?: number;
+    /** Set when the issue shows only in another app state (config modes): "name:value", as the canvas sidebar names it. */
+    mode?: string;
 }
 export interface TextItem {
     selector: string;

package/package.json

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

@@ -77,6 +77,8 @@ References, read before the first screen:
    An issue tagged with a width ("at 1024px: …") breaks at an edge of the windows the variant covers: fix it with a
    responsive rule in the screen, or a new variant when the layout's structure has to change (screens.md, Widths).
    Widths include the breakpoints inside the range; `narrow-layout` is a phone column left in a wide window.
+   An issue tagged with an app state ("Signed in: …"; `modes` in the config, screens.md) shows only in that state: fix it in
+   the screen's rules for that state, and look at its render (`--auth-user.png`). Clicking it on the canvas shows the state.
    Overlap checks compare the drawn fragments of wrapped inline controls, not the empty corners of their
    bounding boxes. For fixed bars, the browser's paint order decides coverage: a menu painted in front of a
    header is not hidden by it. Native modal dialogs and ARIA modals limit coverage and control comparisons
@@ -106,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).
@@ -127,7 +132,7 @@ References, read before the first screen:
 |---|---|
 | `setup [--name N --primary #hex] [options]` | Sets a project up in one step; keeps every file that exists |
 | `canvas` | The canvas at http://localhost:4400: screens and versions, DESIGN.md, the consistency report, approval and notes |
-| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme and check language, and at both ends of each variant's widths; `--shots` saves renders |
+| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme, app state and check language, and at both ends of each variant's widths; `--shots` saves renders |
 | `i18n [filter] [--locale l] [--suggest]` | Message keys screens use that the source or a locale lacks, and text with no key (stitch2-i18n) |
 | `consistency [kind…]` | Every shared component cropped from every screen, next to the catalog's version |
 | `type [filter] [--json]` | Every text style a screen uses and the type level it matches |

package/skills/stitch2/references/screens.md

@@ -186,8 +186,10 @@ screen per state. Draw it once, let its CSS and scripts answer to an attribute o
 The canvas sidebar then has a dropdown for each mode. A value sets the attribute (`data-auth="user"`; `attribute`
 names another) on every screen, live frames and the pictures of the rest, and "As drawn" puts each screen back to what
 its file says. `m` cycles the first mode. A screen is still written for the state it shows (a signed-in account page has
-`data-auth="user"` in its file); modes show the other states of the same screen. `stitch2 check` runs on the screens as
-drawn, not in each state, so open the other states on the canvas and look at them before hand-over.
+`data-auth="user"` in its file); modes show the other states of the same screen. `stitch2 check` also runs each screen in every
+value its own file does not have, one mode at a time (modes are not combined), and tags what only shows there with the
+state ("Signed in: …"); clicking such an issue on the canvas shows that state. With `--shots` each state is rendered too
+(`<screen>--auth-user.png`): look at it before hand-over.
 
 ## The canvas