stitch2 0.0.0-stage → 0.7.2

package/dist/check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/check.js

@@ -0,0 +1,86 @@
+/**
+ * Layout checks for every screen, the bugs we kept hitting in generated designs: content past the screen
+ * edge, labels wrapping onto two lines, content hidden under fixed bars, tiny tap targets, low text
+ * contrast, and text styles that are not one of DESIGN.md's type levels. Writes design/checks.json, which
+ * the canvas shows as badges.
+ * Usage: stitch2 check [path filter…] [--shots] [--strict]
+ *   --shots   also save page-tall renders to design/renders/
+ *   --strict  exit 1 when any screen has errors (for CI and agent loops)
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chromium } from '@playwright/test';
+import { colourIssues } from './colours.js';
+import { config } from './config.js';
+import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
+import { typeLevels } from './design-md.js';
+import { listScreens, ROOT } from './screens.js';
+import { startServer } from './serve.js';
+import { collectText, typeIssues } from './typecheck.js';
+import { audit } from './audit.js';
+const args = process.argv.slice(2);
+const shots = args.includes('--shots');
+const strict = args.includes('--strict');
+const filters = args.filter((a) => !a.startsWith('--'));
+const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
+const levels = typeLevels();
+const collect = collectOptions();
+const server = await startServer(0);
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2 });
+const results = {};
+const components = {};
+for (const s of screens) {
+    await page.setViewportSize({ width: s.width, height: 844 });
+    await page
+        .goto(`http://127.0.0.1:${server.port}/${s.path}`, { waitUntil: 'networkidle', timeout: 30_000 })
+        .catch(() => { });
+    // Tailwind's CDN build, web fonts and the lab components settle after load.
+    await page.waitForTimeout(600);
+    const found = await page.evaluate(collectComponents, collect);
+    components[s.path] = found.components;
+    results[s.path] = [
+        ...(await page.evaluate(audit, { comfortable: config.comfortableTarget })),
+        ...typeIssues(levels, await page.evaluate(collectText)),
+        ...reuseIssues(s.path, found),
+        ...colourIssues(s.path),
+    ];
+    if (shots) {
+        const height = await page.evaluate(() => document.documentElement.scrollHeight);
+        await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, 6000)) });
+        mkdirSync(join(ROOT, 'renders'), { recursive: true });
+        await page.screenshot({
+            path: join(ROOT, 'renders', s.path.replaceAll('/', '__').replace(/\.html$/, '.png')),
+        });
+    }
+}
+await browser.close();
+server.close();
+// Merge with the last results, so a filtered run still compares components with every other screen.
+let previous = {};
+try {
+    previous = JSON.parse(readFileSync(join(ROOT, 'checks.json'), 'utf8'));
+}
+catch { }
+const exists = new Set(listScreens().map((s) => s.path));
+const keep = (o) => Object.fromEntries(Object.entries(o).filter(([p]) => exists.has(p)));
+const allComponents = keep({ ...previous.components, ...components });
+// Archived versions are history: they do not vote on how a component should look.
+const archived = new Set(listScreens()
+    .filter((s) => s.status === 'archived')
+    .map((s) => s.path));
+const consistency = consistencyIssues(Object.fromEntries(Object.entries(allComponents).filter(([p]) => !archived.has(p) || p in results)), Object.keys(results));
+let errors = 0;
+for (const s of screens) {
+    const issues = [...results[s.path], ...(consistency[s.path] ?? [])].sort((x, y) => x.severity === y.severity ? 0 : x.severity === 'error' ? -1 : 1);
+    results[s.path] = issues;
+    const e = issues.filter((i) => i.severity === 'error').length;
+    errors += e;
+    console.log(`${e ? '✗' : '✓'} ${s.path.padEnd(42)} ${e} errors, ${issues.length - e} warnings`);
+    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(), screens: keep({ ...previous.screens, ...results }), components: allComponents }, null, 2)}\n`);
+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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * stitch2: a design canvas, checks and screen versioning for agent-built UI.
+ * Usage: stitch2 <command> [args]   (reads the nearest stitch2.config.json)
+ */
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const COMMANDS = {
+    setup: [
+        'setup.ts',
+        '[--name N --primary #hex] [--prefix p] [--skills-dir .agents/skills,…]  Set a project up: skills, config, template, catalog, starter components',
+    ],
+    init: [
+        'init.ts',
+        '--name N --primary #hex [--modes dark,light --sans Inter --mono … --base 15 --roundness 16]  Write a complete DESIGN.md',
+    ],
+    extract: [
+        'extract.ts',
+        '<url or html file…> [--name N] [--out file]  Write a DESIGN.md measured from an existing site or screen',
+    ],
+    canvas: [
+        'serve.ts',
+        'The canvas at http://localhost:4400 (PORT and HOST to change): screens, versions, DESIGN.md, approval',
+    ],
+    check: ['check.ts', '[filter] [--shots] [--strict]  Layout, type, reuse and consistency checks'],
+    consistency: ['report.ts', '[kind]  Every shared component cropped from every screen, side by side'],
+    type: ['type.ts', '[filter] [--json]  Every text style a screen uses, by type level'],
+    tokens: ['tokens.ts', 'Generate tokens.css and tailwind.tokens.js from DESIGN.md, and the exports in the config'],
+    compare: ['compare.ts', '[screen…] [--strict]  The live app against the approved screens ("app" in the config)'],
+    elements: ['build-elements.ts', '<entry> [--out file]  Bundle the project\'s components (defineElements) for the screens'],
+    lint: ['', "Google's DESIGN.md linter on the project's DESIGN.md"],
+    screens: ['list.ts', '[name] [--status s] [--json]  Screen versions, statuses and notes'],
+    localize: ['assets.ts', '[filter]  Copy remote images a screen uses into its assets/ folder'],
+    sandbox: [
+        'sandbox.ts',
+        'create <dir> <brief.md>… [--context <screen>…] | import <dir>  Fresh-eyes versions from agents that see no other versions',
+    ],
+};
+const [command, ...rest] = process.argv.slice(2);
+const entry = command ? COMMANDS[command] : undefined;
+if (!entry) {
+    console.log('stitch2 <command>\n');
+    for (const [name, [, help]] of Object.entries(COMMANDS))
+        console.log(`  ${name.padEnd(12)} ${help}`);
+    process.exit(command ? 1 : 0);
+}
+if (command === 'lint') {
+    const { ROOT } = await import('./config.js');
+    // The linter's main entry is also its command line (the package only exports for import).
+    const file = fileURLToPath(import.meta.resolve('@google/design.md'));
+    try {
+        execFileSync(process.execPath, [file, 'lint', join(ROOT, 'DESIGN.md'), ...rest], { stdio: 'inherit' });
+    }
+    catch {
+        process.exit(1);
+    }
+}
+else {
+    // Sources run as .ts (Node strips the types); the published build runs as .js.
+    const ext = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+    const script = fileURLToPath(new URL(entry[0].replace(/\.ts$/, ext), import.meta.url));
+    process.argv = [process.argv[0], script, ...rest];
+    await import(__rewriteRelativeImportExtension(script));
+}

package/dist/colours.d.ts

@@ -0,0 +1,2 @@
+import type { Issue } from './typecheck.ts';
+export declare function colourIssues(path: string): Issue[];

package/dist/colours.js

@@ -0,0 +1,57 @@
+/**
+ * Literal colours. On a lab screen every colour comes from DESIGN.md through the generated tokens (token classes
+ * such as bg-surface, or var(--<prefix>-<name>), mixed with color-mix for a shade), so changing a colour in
+ * DESIGN.md and running stitch2 tokens changes it everywhere. A hex, rgb() or hsl() value written into a screen
+ * or a component would not follow. Screens are checked for their own markup; the component catalog is also
+ * checked for the scripts it loads from the design folder (the components), so each literal is reported once.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { config } from './config.js';
+import { familyOf } from './consistency.js';
+import { ROOT } from './screens.js';
+const LITERAL = /(?<![\w&/=-])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b|(?<![a-zA-Z])(?:rgba?|hsla?)\(\s*[\d.][^)]*\)/g;
+/** Lines with a literal colour, comments blanked out (keeping line numbers). */
+function literals(source, js) {
+    let s = source.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
+    if (js)
+        s = s.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' ')).replace(/^\s*\/\/.*$/gm, '');
+    else
+        s = s.replace(/<head[\s>][\s\S]*?<\/head>/i, (m) => m.replace(/[^\n]/g, ' '));
+    const out = [];
+    s.split('\n').forEach((text, i) => {
+        for (const m of text.matchAll(LITERAL)) {
+            if (/href=["']$/.test(text.slice(0, m.index)))
+                continue;
+            out.push({ line: i + 1, value: m[0], text: text.trim().slice(0, 80) });
+        }
+    });
+    return out;
+}
+/** Component scripts already reported in this run (two catalogs load the same file). */
+const seen = new Set();
+export function colourIssues(path) {
+    if (familyOf(path) !== 'screens')
+        return [];
+    const html = readFileSync(join(ROOT, path), 'utf8');
+    const found = literals(html, false).map((l) => ({ ...l, file: `${config.designDir}/${path}` }));
+    if (path.startsWith(`${config.catalogDir}/`))
+        for (const [, src] of html.matchAll(/<script[^>]*\bsrc="\/([^"]+\.js)"/g)) {
+            const file = join(ROOT, src);
+            if (!existsSync(file) || /tokens/.test(src) || seen.has(file))
+                continue;
+            seen.add(file);
+            const js = readFileSync(file, 'utf8');
+            // A bundle from stitch2 elements holds the framework's own code; the project checks its component sources.
+            if (js.startsWith('/* Generated by stitch2 elements'))
+                continue;
+            found.push(...literals(js, true).map((l) => ({ ...l, file: `${config.designDir}/${src}` })));
+        }
+    return found.map((l) => ({
+        severity: 'warning',
+        type: 'color',
+        message: `Colour ${l.value} written into ${l.file}:${l.line}; use a DESIGN.md colour (a token class or var(--${config.prefix}-…)) so it follows DESIGN.md`,
+        selector: `${l.file}:${l.line}`,
+        text: l.text,
+    }));
+}

package/dist/compare.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compare.js

@@ -0,0 +1,185 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The live app against the approved screens. For every approved version whose screen has a route in the config's
+ * "app" section, it opens the approved version and the app page at the same width and compares their structure:
+ * which shared components appear (by their data-<prefix> marker), how many, in what order, and how the measured
+ * ones look. Data differs between a mock-up and the app, so pixels are shown side by side, not diffed.
+ * Writes <design>/compare/index.html (the canvas opens it from its sidebar) and <design>/compare.json.
+ *
+ *   "app": {
+ *     "url": "http://localhost:4321",
+ *     "signIn": "design/app/sign-in.mjs",          // export default async ({ page, url }) => { … }
+ *     "routes": {
+ *       "home": "/app",
+ *       "exercise-detail": { "path": "/app/library", "prepare": "design/app/open-exercise.mjs" },
+ *       "sign-in": { "path": "/login", "signedOut": true }   // a page of its own, never signed in
+ *     }
+ *   }
+ *
+ * Usage: stitch2 compare [screen…] [--strict]
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from '@playwright/test';
+import { audit, LAYOUT_ERRORS } from './audit.js';
+import { BASE, config } from './config.js';
+import { collectComponents, collectOptions } from './consistency.js';
+import { listScreens, ROOT } from './screens.js';
+import { startServer } from './serve.js';
+const app = config.app;
+if (!app?.url || !app.routes) {
+    console.error('stitch2 compare: add an "app" section with "url" and "routes" to stitch2.config.json');
+    process.exit(1);
+}
+const args = process.argv.slice(2);
+const only = args.filter((a) => !a.startsWith('--'));
+const strict = args.includes('--strict');
+const routeOf = (screen) => {
+    const r = app.routes[screen];
+    return typeof r === 'string' ? { path: r } : r;
+};
+const versions = listScreens().filter((s) => s.kind === 'screen' && s.status === 'approved' && routeOf(s.screen) && (!only.length || only.includes(s.screen)));
+const unmapped = [...new Set(listScreens().filter((s) => s.status === 'approved' && !routeOf(s.screen)).map((s) => s.screen))];
+/** Runs in the page: every marked component in document order, and the top-level ones (not inside another). */
+function structure(prefix) {
+    const marker = `data-${prefix}`;
+    const shown = (el) => {
+        const cs = getComputedStyle(el);
+        if (cs.display === 'contents')
+            return [...el.children].some(shown);
+        const r = el.getBoundingClientRect();
+        return cs.display !== 'none' && cs.visibility !== 'hidden' && r.width > 0 && r.height > 0;
+    };
+    const all = [...document.querySelectorAll(`[${marker}]`)].filter(shown);
+    const counts = {};
+    for (const el of all) {
+        const k = el.getAttribute(marker);
+        counts[k] = (counts[k] ?? 0) + 1;
+    }
+    const top = all.filter((el) => !el.parentElement?.closest(`[${marker}]`)).map((el) => el.getAttribute(marker));
+    return { counts, top };
+}
+/** Longest common subsequence length, for how much of the design's order the app keeps. */
+function lcs(a, b) {
+    const d = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++)
+            d[i][j] = a[i - 1] === b[j - 1] ? d[i - 1][j - 1] + 1 : Math.max(d[i - 1][j], d[i][j - 1]);
+    return d[a.length][b.length];
+}
+const load = async (file) => (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(BASE, file)).href))).default;
+const settle = async (page) => {
+    await page.waitForLoadState('networkidle', { timeout: 15_000 }).catch(() => { });
+    await page.waitForTimeout(800);
+};
+const out = join(ROOT, 'compare');
+mkdirSync(out, { recursive: true });
+const server = await startServer(0);
+const browser = await chromium.launch();
+const context = await browser.newContext({ deviceScaleFactor: 2 });
+const signIn = await context.newPage();
+if (app.signIn)
+    await (await load(app.signIn))({ page: signIn, url: app.url });
+await signIn.close();
+const design = await browser.newPage({ deviceScaleFactor: 2 });
+const signedIn = await context.newPage();
+// Sign-in and other public pages often redirect a signed-in visitor, so they get a context of their own.
+const signedOut = await (await browser.newContext({ deviceScaleFactor: 2 })).newPage();
+const results = [];
+const opts = collectOptions();
+for (const s of versions) {
+    const route = routeOf(s.screen);
+    const live = route.signedOut ? signedOut : signedIn;
+    const url = new URL(route.path, app.url).href;
+    const height = s.width > 700 ? 800 : 844;
+    for (const p of [design, live])
+        await p.setViewportSize({ width: s.width, height });
+    await design.goto(`http://127.0.0.1:${server.port}/${s.path}`).catch(() => { });
+    await settle(design);
+    await live.goto(url).catch(() => { });
+    await settle(live);
+    const findings = [];
+    if (route.prepare) {
+        // A failing prepare is this version's error; the run goes on with the others.
+        try {
+            await (await load(route.prepare))({ page: live, url: app.url });
+        }
+        catch (e) {
+            const message = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+            findings.push({ severity: 'error', type: 'prepare', message: `${route.prepare} failed: ${message}` });
+        }
+        await settle(live);
+    }
+    const [d, a] = [await design.evaluate(structure, config.prefix), await live.evaluate(structure, config.prefix)];
+    const [dc, ac] = [
+        (await design.evaluate(collectComponents, opts)).components,
+        (await live.evaluate(collectComponents, opts)).components,
+    ];
+    const missing = Object.keys(d.counts).filter((k) => !a.counts[k]);
+    const extra = Object.keys(a.counts).filter((k) => !d.counts[k]);
+    if (missing.length)
+        findings.push({ severity: 'error', type: 'missing', message: `In the design, not in the app: ${missing.join(', ')}` });
+    if (extra.length)
+        findings.push({ severity: 'warning', type: 'extra', message: `In the app, not in the design: ${extra.join(', ')}` });
+    const kept = lcs(d.top, a.top);
+    if (d.top.length && kept < d.top.length)
+        findings.push({
+            severity: 'warning',
+            type: 'order',
+            message: `Layout differs: ${kept} of ${d.top.length} top-level components in the design's order (design: ${d.top.join(' → ')}; app: ${a.top.join(' → ') || 'none'})`,
+        });
+    for (const [kind, sigs] of Object.entries(dc)) {
+        const mine = ac[kind]?.[0];
+        const ref = sigs[0];
+        if (!mine || !ref || !Object.keys(ref.fields).length)
+            continue;
+        const diffs = Object.keys({ ...ref.fields, ...mine.fields }).filter((f) => ref.fields[f] !== mine.fields[f]);
+        if (diffs.length)
+            findings.push({
+                severity: 'warning',
+                type: 'look',
+                message: `${kind} looks different: ${diffs.map((f) => `${f} ${mine.fields[f] ?? '–'} (design ${ref.fields[f] ?? '–'})`).join('; ')}`,
+            });
+    }
+    // The same layout rules check runs on the screens, on the app: a control squeezed over another shows up here
+    // even when the screen never drew that state.
+    for (const i of await live.evaluate(audit, { comfortable: config.comfortableTarget }))
+        if (i.severity === 'error' && LAYOUT_ERRORS.includes(i.type))
+            findings.push({ severity: 'error', type: i.type, message: `${i.message} (“${i.text}”)` });
+    const kinds = Object.keys(d.counts);
+    const match = kinds.length ? Math.round((100 * kinds.filter((k) => a.counts[k]).length) / kinds.length) : 100;
+    const base = `${s.screen}-${s.device}`;
+    await design.screenshot({ path: join(out, `${base}-design.png`), fullPage: true });
+    await live.screenshot({ path: join(out, `${base}-app.png`), fullPage: true });
+    results.push({ screen: s.screen, device: s.device, version: s.version, design: s.path, url, findings, match });
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    console.log(`${errors ? '✗' : '✓'} ${base.padEnd(30)} ${String(match).padStart(3)}% of the design's components · ${errors} errors, ${findings.length - errors} warnings`);
+    for (const f of findings.filter((f) => f.severity === 'error'))
+        console.log(`    ${f.type}: ${f.message}`);
+}
+await browser.close();
+server.close();
+const esc = (v) => String(v ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const rows = results
+    .map((r) => {
+    const base = `${r.screen}-${r.device}`;
+    const list = r.findings.length
+        ? r.findings.map((f) => `<li class="${f.severity}"><b>${f.type}</b> ${esc(f.message)}</li>`).join('')
+        : '<li class="ok">Matches the design’s structure.</li>';
+    return `<section><h2>${esc(r.screen)} · ${r.device} · ${r.version} <span>${r.match}%</span></h2><p><code>${esc(r.design)}</code> ↔ <a href="${esc(r.url)}">${esc(r.url)}</a></p><ul>${list}</ul><div class="imgs"><figure><figcaption>Approved design</figcaption><img src="${base}-design.png" alt=""></figure><figure><figcaption>App</figcaption><img src="${base}-app.png" alt=""></figure></div></section>`;
+})
+    .join('');
+writeFileSync(join(out, 'index.html'), `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>App comparison</title><style>body{background:#0b0b0d;color:#f4f4f5;font:14px/1.5 system-ui,sans-serif;margin:0}main{margin:0 auto;max-width:1400px;padding:32px}h1{font-size:22px}h2{font-size:17px;margin:32px 0 4px}h2 span{color:#a1a1aa;font-weight:400;margin-left:8px}code,a{color:#a1a1aa}ul{margin:8px 0;padding-left:18px}li.error b{color:#e5484d}li.warning b{color:#e5b54a}li.ok{color:#3fb27f}.imgs{display:flex;gap:16px;align-items:flex-start}figure{margin:0}figcaption{color:#a1a1aa;font-size:12px;margin-bottom:4px}img{border:1px solid #2e2e33;border-radius:8px;max-width:640px;width:100%}</style></head><body><main><h1>App comparison</h1><p>${new Date().toISOString()} · ${results.length} approved versions against ${esc(app.url)}${unmapped.length ? ` · no route for: ${esc(unmapped.join(', '))}` : ''}</p>${rows}</main></body></html>\n`);
+writeFileSync(join(ROOT, 'compare.json'), `${JSON.stringify({ comparedAt: new Date().toISOString(), url: app.url, results, unmapped }, null, 2)}\n`);
+const total = results.reduce((n, r) => n + r.findings.filter((f) => f.severity === 'error').length, 0);
+console.log(`\n${results.length} versions compared, ${total} errors${unmapped.length ? `; no route for ${unmapped.join(', ')}` : ''}. Report: ${config.designDir}/compare/index.html`);
+if (strict && total)
+    process.exit(1);

package/dist/config.d.ts

@@ -0,0 +1,53 @@
+export interface LabConfig {
+    /** Shown on the canvas. */
+    name: string;
+    /** Folder with DESIGN.md, the generated tokens, components and screens. */
+    designDir: string;
+    /** Folders under designDir that hold screens, in canvas order. */
+    screenDirs: string[];
+    /** Folder under designDir whose screens are Stitch exports (their source defaults to "stitch"). */
+    stitchDir: string;
+    /** Folders under designDir with past experiments: archived by default, compared only among themselves. */
+    archiveDirs: string[];
+    /** Folder under designDir with the component catalog screen(s). */
+    catalogDir: string;
+    /**
+     * One prefix for everything the lab writes into screens: meta tags (<prefix>-screen, <prefix>-status…),
+     * component elements and their marker (<prefix>-button, data-<prefix>) and CSS variables (--<prefix>-…).
+     */
+    prefix: string;
+    /** Screen names in canvas order; the rest follow alphabetically. */
+    order: string[];
+    /** Tap targets smaller than this (px) get a warning; under WCAG's 24px they are errors when crowded. */
+    comfortableTarget: number;
+    /** Skill folders a blind-trial sandbox copies. */
+    skills: string[];
+    /** Paths under designDir a sandbox leaves out besides screens (notes that would give the trial away). */
+    sandboxExclude?: string[];
+    /** The live app, for stitch2 compare (see compare.ts): its URL, a sign-in script and a route per screen. */
+    app?: {
+        url: string;
+        signIn?: string;
+        routes: Record<string, string | {
+            path: string;
+            prepare?: string;
+        }>;
+    };
+    /** Token files stitch2 tokens also writes for the app (see exports.ts). */
+    exports?: {
+        format: 'css' | 'tailwind4' | 'dtcg';
+        path: string;
+        aliases?: Record<string, string>;
+        themes?: {
+            dark?: string;
+            light?: string;
+        };
+    }[];
+}
+export declare const CONFIG_NAME = "stitch2.config.json";
+export declare const CONFIG_FILE: string | undefined;
+/** The folder paths in the config are relative to (the project root). */
+export declare const BASE: string;
+export declare const config: LabConfig;
+/** The design folder, with a trailing slash. */
+export declare const ROOT: string;

package/dist/config.js

@@ -0,0 +1,38 @@
+/**
+ * The lab's settings, from stitch2.config.json: the nearest one above the working directory, or the file in
+ * STITCH2_CONFIG. Paths in it are relative to the file. Without a config the lab uses ./design and defaults.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const DEFAULTS = {
+    name: 'stitch2',
+    designDir: 'design',
+    screenDirs: ['screens'],
+    stitchDir: 'stitch',
+    archiveDirs: [],
+    catalogDir: 'screens/components',
+    prefix: 's2',
+    order: [],
+    comfortableTarget: 32,
+    skills: [],
+};
+export const CONFIG_NAME = 'stitch2.config.json';
+function find() {
+    if (process.env.STITCH2_CONFIG)
+        return resolve(process.env.STITCH2_CONFIG);
+    for (let dir = process.cwd();; dir = dirname(dir)) {
+        if (existsSync(join(dir, CONFIG_NAME)))
+            return join(dir, CONFIG_NAME);
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+export const CONFIG_FILE = find();
+/** The folder paths in the config are relative to (the project root). */
+export const BASE = CONFIG_FILE ? dirname(CONFIG_FILE) : process.cwd();
+export const config = {
+    ...DEFAULTS,
+    ...(CONFIG_FILE ? JSON.parse(readFileSync(CONFIG_FILE, 'utf8')) : {}),
+};
+/** The design folder, with a trailing slash. */
+export const ROOT = join(resolve(BASE, config.designDir), '/');

package/dist/consistency.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Component consistency across screens. In each page it finds the shared elements (lab components by their
+ * data-<prefix> marker; in Stitch exports and hand-written markup by how they look: a fixed bottom bar with three or more
+ * buttons, the h1, buttons filled with the primary colour, pill chips, icon-only buttons, caps section labels) and takes a signature of
+ * each: size, radius, label font, icon size, and for the tab bar its centre circle. Screens of one family
+ * (the Stitch folder, an archive folder, or the lab's own screens) should share one signature per component; check reports
+ * the screens that differ from the majority, and lab screens that build a catalog component by hand.
+ */
+import type { Issue } from './typecheck.ts';
+export interface Sig {
+    selector: string;
+    text: string;
+    /** Comparable fields, e.g. { height: '48', font: '15/600/Geist' }. */
+    fields: Record<string, string>;
+}
+export type Components = Record<string, Sig[]>;
+export interface PageComponents {
+    components: Components;
+    handBuilt: {
+        kind: string;
+        selector: string;
+        text: string;
+    }[];
+}
+export interface CollectOptions {
+    /** Component marker: elements with data-<prefix>="name". */
+    prefix: string;
+    /** DESIGN.md's primary colour as [r, g, b]: filled buttons in it are primary buttons. */
+    primary: number[];
+}
+/** The options for collectComponents from the config and DESIGN.md's primary colour. */
+export declare function collectOptions(): CollectOptions;
+/** Runs in the page. Plain JS on purpose: Playwright sends its source to the browser. */
+export declare function collectComponents(opts: CollectOptions): PageComponents;
+export declare function familyOf(path: string): string;
+export declare const nameOf: (kind: string) => string;
+/** Issues for the screens in `paths`, comparing with every screen whose components are known. */
+export declare function consistencyIssues(known: Record<string, Components>, paths: string[]): Record<string, Issue[]>;
+/** Lab screens build catalog components with the components, not by hand. */
+export declare function reuseIssues(path: string, page: PageComponents): Issue[];