stitch2 0.25.0 → 0.26.0

package/README.md

@@ -283,7 +283,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`…). 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 check [filter] [--shots] [--strict] [--archived] [--locales l,…]` | All checks, in every theme, app state and check language, on every version that is not archived (`--archived` adds the outdated ones); `--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/check.js

@@ -16,6 +16,8 @@
  * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
  *   --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)
+ *   --archived  also check archived versions, which are left out otherwise: they are outdated (superseded or rejected),
+ *             hidden on the canvas, and nothing is built from them, so checking them costs time and reports errors in history
  * Screens run four at a time; reruns only visit screens that changed since design/checks.json (or
  * 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
@@ -43,7 +45,13 @@ const strict = args.includes('--strict');
 const localesFlag = args.indexOf('--locales');
 const locales = checkLocales(localesFlag >= 0 ? args[localesFlag + 1] : undefined);
 const filters = args.filter((a, i) => !a.startsWith('--') && (localesFlag < 0 || i !== localesFlag + 1));
-const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
+const matching = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
+const screens = args.includes('--archived') ? matching : matching.filter((s) => s.status !== 'archived');
+const archivedLeftOut = matching.length - screens.length;
+if (archivedLeftOut)
+    console.log(`${archivedLeftOut} archived screen${archivedLeftOut === 1 ? ' is' : 's are'} not checked (--archived includes ${archivedLeftOut === 1 ? 'it' : 'them'}).`);
+if (!screens.length && matching.length)
+    process.exit(0);
 const levels = typeLevels();
 const themes = designThemes();
 const appModes = modes();

package/dist/shots.js

@@ -13,6 +13,15 @@ import { messagesFile, sourceLocale } from './i18n.js';
 import { ROOT, meta, tag } from './screens.js';
 /** The tallest picture, in CSS px: the same limit as the canvas frames and check's renders. */
 const MAX_HEIGHT = 20000;
+/**
+ * Pictures are drawn at two pixels for each CSS pixel and kept at a high JPEG quality. At one pixel, a laptop screen
+ * (two device pixels for each CSS pixel) shows a picture stretched to twice its size: thin light text on a dark page
+ * comes out soft, grainy and low in contrast next to the live page. Chromium cannot draw a picture much taller than
+ * MAX_DEVICE_PX device pixels, so a page too tall for that is drawn at one pixel for each CSS pixel.
+ */
+const SCALE = 2;
+const MAX_DEVICE_PX = 16000;
+const QUALITY = 92;
 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', 'states', 'node_modules', '.git']);
@@ -53,7 +62,7 @@ function keyOf(r) {
         return null;
     const messages = r.lang && r.lang !== sourceLocale() ? messagesFile(r.lang) : undefined;
     const parts = [
-        'viewport-v2',
+        'viewport-v3',
         r.path,
         statSync(file).mtimeMs,
         sharedStamp(),
@@ -94,39 +103,48 @@ export function shot(base, r) {
         return inFlight;
     const job = slot(async () => {
         browser ??= launch();
-        const page = await (await browser).newPage({ viewport: { width: r.width, height: 844 }, deviceScaleFactor: 1 });
-        try {
-            const viewport = Math.min(4000, Math.max(200, Number(meta(readFileSync(join(ROOT, r.path), 'utf8'), tag('frame-height'))) || 844));
-            await page.setViewportSize({ width: r.width, height: viewport });
-            const query = new URLSearchParams({ canvas: String(viewport) });
-            if (r.lang && r.lang !== sourceLocale())
-                query.set('lang', r.lang);
-            await page.goto(`${base}/${r.path}?${query}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
-            if (r.theme)
-                await page.evaluate((t) => { document.documentElement.dataset.theme = t; }, r.theme);
-            const attributes = Object.entries(r.modes ?? {});
-            if (attributes.length)
-                await page.evaluate((list) => { for (const [name, value] of list)
-                    document.documentElement.setAttribute(name, value); }, attributes);
-            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();
-        }
+        // A page too tall for the sharp scale is drawn again at one pixel for each CSS pixel.
+        const jpg = (await draw(base, r, SCALE)) ?? (await draw(base, r, 1));
+        if (!jpg)
+            throw new Error('no picture of ' + r.path);
+        mkdirSync(DIR, { recursive: true });
+        writeFileSync(file, jpg);
+        return jpg;
     });
     pending.set(key, job);
     const done = () => pending.delete(key);
     job.then(done, done);
     return job;
 }
+/** One picture of a screen at the given scale; null when the page is too tall to be drawn at that scale. */
+async function draw(base, r, scale) {
+    const page = await (await browser).newPage({ viewport: { width: r.width, height: 844 }, deviceScaleFactor: scale });
+    try {
+        const viewport = Math.min(4000, Math.max(200, Number(meta(readFileSync(join(ROOT, r.path), 'utf8'), tag('frame-height'))) || 844));
+        await page.setViewportSize({ width: r.width, height: viewport });
+        const query = new URLSearchParams({ canvas: String(viewport) });
+        if (r.lang && r.lang !== sourceLocale())
+            query.set('lang', r.lang);
+        await page.goto(`${base}/${r.path}?${query}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
+        if (r.theme)
+            await page.evaluate((t) => { document.documentElement.dataset.theme = t; }, r.theme);
+        const attributes = Object.entries(r.modes ?? {});
+        if (attributes.length)
+            await page.evaluate((list) => { for (const [name, value] of list)
+                document.documentElement.setAttribute(name, value); }, attributes);
+        await page.evaluate(() => document.fonts.ready);
+        // Tailwind's browser build and the components settle after load.
+        await page.waitForTimeout(400);
+        const height = Math.min(MAX_HEIGHT, Math.max(844, await page.evaluate(() => Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0))));
+        if (scale > 1 && height * scale > MAX_DEVICE_PX)
+            return null;
+        await page.setViewportSize({ width: r.width, height });
+        return await page.screenshot({ type: 'jpeg', quality: QUALITY });
+    }
+    finally {
+        await page.close();
+    }
+}
 export async function closeShots() {
     const b = await browser?.catch(() => undefined);
     browser = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -53,7 +53,7 @@ References, read before the first screen:
    **stitch2-i18n**). Write the text as **stitch2-copy** says (the reader's outcome, plain words, the product's terms),
    and translate it with **stitch2-translate**. Never add classes to a component to change how it looks, and never write a colour value (hex,
    `rgb()`, `hsl()`): only DESIGN.md's colours, as token classes or `var(--<prefix>-<name>)`.
-5. **Check** `stitch2 check <path> --shots --strict`. Fix every error (overflow, wrapped labels, content under
+5. **Check** `stitch2 check <path> --shots --strict` (archived versions are outdated and are not visited; `--archived` includes them). Fix every error (overflow, wrapped labels, content under
    fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text), a hand-built copy of a
    catalog component (`reuse`: use the component or extend it, never rebuild it), and every warning about type
    (`type-*`), components that differ from the catalog (`consistency`) and colour values (`color`).
@@ -132,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, app state and check language, and at both ends of each variant's widths; `--shots` saves renders |
+| `check [filter] [--shots] [--strict] [--archived] [--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; archived versions are left out unless `--archived` asks for them |
 | `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-app-sync/SKILL.md

@@ -82,7 +82,7 @@ Read the findings as:
 ## Before you call it done
 
 1. Every screen you implemented is approved, and `stitch2 screens --strict` passes: one current version each.
-2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
+2. `stitch2 check --strict` passes on the screens you touched (it leaves archived screens out).
 3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
 4. `stitch2 look` and `stitch2 geometry` report nothing on the screens you touched, except differences you can
    name as data.