stitch2 0.0.0-stage → 0.7.2

package/dist/exports.js

@@ -0,0 +1,86 @@
+/**
+ * Token exports: DESIGN.md's tokens written for the app, so the product and the canvas share one source. Listed
+ * in stitch2.config.json under "exports" and written by stitch2 tokens:
+ *   css        CSS variables for both themes and the .type-<level> classes
+ *   tailwind4  the same, plus an @theme block (bg-<colour>, rounded-<name>, font-sans) and the type levels as
+ *              @utility type-<level>, for a Tailwind v4 stylesheet to @import. Spacing stays out of @theme:
+ *              names like lg or 2xl would also resize max-w-lg and friends; it is --<prefix>-spacing-<name>.
+ *   dtcg       W3C Design Tokens JSON, for Style Dictionary and other platforms (iOS, Android)
+ * "aliases" maps the app's own variable names to DESIGN.md colours ({ "background": "floor" } writes
+ * --background: var(--<prefix>-floor) in each theme), so an existing theme (shadcn's, say) keeps its names.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { BASE, config } from './config.js';
+const p = () => config.prefix;
+function themeBlocks(t, e) {
+    const dark = e.themes?.dark ?? ":root, [data-theme='dark']";
+    const light = e.themes?.light ?? "[data-theme='light']";
+    const alias = (palette) => Object.entries(e.aliases ?? {}).map(([k, v]) => `  --${k}: ${v in palette ? `var(--${p()}-${v})` : v};`);
+    const block = (selector, palette, scheme) => [
+        `${selector} {`,
+        `  color-scheme: ${scheme};`,
+        ...Object.entries(palette).map(([k, v]) => `  --${p()}-${k}: ${v};`),
+        ...alias(palette),
+        '}',
+    ].join('\n');
+    // The block on :root goes first: a theme class (.dark) has the same specificity and must come later to win.
+    const themes = [block(dark, t.dark, 'dark'), block(light, t.light, 'light')];
+    if (/:root/.test(light) && !/:root/.test(dark))
+        themes.reverse();
+    const root = { ...t.root, ...Object.fromEntries(Object.entries(t.design.spacing).map(([k, v]) => [`${p()}-spacing-${k}`, v])) };
+    return [...themes, `:root {\n${Object.entries(root).map(([k, v]) => `  --${k}: ${v};`).join('\n')}\n}`];
+}
+function css(t, e) {
+    const type = Object.entries(t.type).map(([n, d]) => `.type-${n} { ${d.join('; ')}; }`);
+    return [t.header, ...themeBlocks(t, e), ...type, ''].join('\n\n');
+}
+function tailwind4(t, e) {
+    const families = Object.values(t.design.typography).map((x) => x.fontFamily ?? '');
+    const sans = families.find((f) => !/mono/i.test(f));
+    const mono = families.find((f) => /mono/i.test(f));
+    const theme = [
+        ...Object.keys(t.dark).map((k) => `  --color-${k}: var(--${p()}-${k});`),
+        ...Object.entries(t.design.rounded).map(([k, v]) => `  --radius-${k}: ${v};`),
+        ...(sans ? [`  --font-sans: "${sans}", var(--${p()}-font-sans-fallback);`] : []),
+        ...(mono ? [`  --font-mono: "${mono}", var(--${p()}-font-mono-fallback);`] : []),
+    ];
+    const type = Object.entries(t.type).map(([n, d]) => `@utility type-${n} {\n${d.map((x) => `  ${x};`).join('\n')}\n}`);
+    return [t.header, ...themeBlocks(t, e), `@theme inline {\n${theme.join('\n')}\n}`, ...type, ''].join('\n\n');
+}
+function dtcg(t) {
+    const group = (type, o) => Object.fromEntries(Object.entries(o).map(([k, v]) => [k, { $type: type, $value: v }]));
+    const typography = Object.fromEntries(Object.entries(t.design.typography).map(([k, v]) => [
+        k,
+        {
+            $type: 'typography',
+            $value: {
+                fontFamily: v.fontFamily,
+                fontSize: v.fontSize,
+                fontWeight: Number(v.fontWeight ?? 400),
+                lineHeight: v.lineHeight,
+                letterSpacing: v.letterSpacing ?? '0em',
+            },
+        },
+    ]));
+    return `${JSON.stringify({
+        $description: t.header.replace(/^\/\* | \*\/$/g, ''),
+        color: group('color', t.dark),
+        'color-light': group('color', t.light),
+        radius: group('dimension', t.design.rounded),
+        spacing: group('dimension', t.design.spacing),
+        typography,
+    }, null, 2)}\n`;
+}
+/** Writes every export in the config; returns their paths. */
+export function writeExports(t, list = config.exports ?? []) {
+    return list.map((e) => {
+        const file = resolve(BASE, e.path);
+        const body = e.format === 'css' ? css(t, e) : e.format === 'tailwind4' ? tailwind4(t, e) : e.format === 'dtcg' ? dtcg(t) : null;
+        if (body === null)
+            throw new Error(`unknown export format "${e.format}"; use css, tailwind4 or dtcg`);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, body);
+        return e.path;
+    });
+}

package/dist/extract.d.ts

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

package/dist/extract.js

@@ -0,0 +1,197 @@
+/**
+ * Writes a DESIGN.md measured from an existing site or screen, the way Stitch builds a design system from a
+ * website: renders each page at 390px in Chromium, measures the colours (backgrounds by area, text by amount),
+ * the fonts, every text style, corner radii and the page padding, maps them to roles and type levels, and fills
+ * what it could not measure from the generated scale.
+ *   stitch2 extract <url or .html file…> [--name N] [--mood "…"] [--out file] [--force]
+ * Then read the result, correct what was guessed, and refine the prose.
+ */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chromium } from '@playwright/test';
+import { tracking } from './build-design.js';
+import { choicesFrom, parseArgs, writeDesign } from './init.js';
+import { collectText } from './typecheck.js';
+/** Runs in the page. Plain JS on purpose: Playwright sends its source to the browser. */
+function measure() {
+    const hex = (c) => {
+        const m = c.match(/[\d.]+/g);
+        if (!m || (m[3] !== undefined && Number(m[3]) < 0.9))
+            return '';
+        return `#${m
+            .slice(0, 3)
+            .map((v) => Math.round(Number(v)).toString(16).padStart(2, '0'))
+            .join('')}`;
+    };
+    const add = (o, k, n) => {
+        if (k)
+            o[k] = (o[k] ?? 0) + n;
+    };
+    const out = { backgrounds: {}, borders: {}, accents: {}, radii: {}, lefts: {} };
+    add(out.backgrounds, hex(getComputedStyle(document.body).backgroundColor) ||
+        hex(getComputedStyle(document.documentElement).backgroundColor) ||
+        '#ffffff', innerWidth * innerHeight);
+    for (const el of document.body.querySelectorAll('*')) {
+        const cs = getComputedStyle(el);
+        const r = el.getBoundingClientRect();
+        if (!r.width || !r.height || cs.visibility === 'hidden')
+            continue;
+        const bg = hex(cs.backgroundColor);
+        if (bg)
+            add(out.backgrounds, bg, Math.min(r.width * r.height, innerWidth * innerHeight));
+        if (Number.parseFloat(cs.borderTopWidth) >= 1)
+            add(out.borders, hex(cs.borderTopColor), 1);
+        // Filled controls carry the brand colour.
+        if (bg && el.matches('button, a, [role=button]') && (el.textContent ?? '').trim())
+            add(out.accents, bg, 1);
+        const radius = Number.parseFloat(cs.borderTopLeftRadius);
+        if (radius > 0 && radius < 200 && (bg || Number.parseFloat(cs.borderTopWidth) >= 1) && r.width >= 200)
+            add(out.radii, String(Math.round(radius)), 1);
+        // Page padding: where wide surfaces (cards, fields) start.
+        if ((bg || Number.parseFloat(cs.borderTopWidth) >= 1) && r.width >= 200 && r.left > 0 && r.left < 48)
+            add(out.lefts, String(Math.round(r.left)), 1);
+    }
+    return out;
+}
+const args = parseArgs(process.argv.slice(2));
+const sources = process.argv
+    .slice(2)
+    .filter((a, i, all) => !a.startsWith('--') && !(all[i - 1]?.startsWith('--') && !(all[i - 1] === '--force')));
+if (!sources.length) {
+    console.error('usage: stitch2 extract <url or .html file…> [--name N] [--mood "…"] [--out file] [--force]');
+    process.exit(1);
+}
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 390, height: 844 } });
+const m = { backgrounds: {}, borders: {}, accents: {}, radii: {}, lefts: {} };
+const texts = [];
+for (const src of sources) {
+    const url = /^https?:/.test(src) ? src : pathToFileURL(resolve(src)).href;
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 45_000 }).catch(() => { });
+    await page.waitForTimeout(800);
+    const one = await page.evaluate(measure);
+    for (const k of Object.keys(m))
+        for (const [v, n] of Object.entries(one[k]))
+            m[k][v] = (m[k][v] ?? 0) + n;
+    texts.push(...(await page.evaluate(collectText)));
+}
+await browser.close();
+const ranked = (o) => Object.entries(o)
+    .sort((a, b) => b[1] - a[1])
+    .map(([k]) => k);
+const lum = (hex) => {
+    const c = [1, 3, 5]
+        .map((i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255)
+        .map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+    return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+};
+const chroma = (hex) => {
+    const c = [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+    return Math.max(...c) - Math.min(...c);
+};
+// Surfaces: the most-covered backgrounds that are not the brand colour, in order of area.
+const bgs = ranked(m.backgrounds).filter((c) => chroma(c) < 40);
+const background = bgs[0] ?? '#ffffff';
+const mode = lum(background) < 0.4 ? 'dark' : 'light';
+const primary = ranked(m.accents).find((c) => chroma(c) >= 40) ??
+    ranked(m.backgrounds).find((c) => chroma(c) >= 40) ??
+    '#2F6FEB';
+// Text: by amount, plain text colours (alpha-free), the most common is text, the next readable grey is muted.
+const weight = (t) => Math.max(1, t.text.length);
+const textColours = {};
+for (const t of texts)
+    if (!t.color.includes('%'))
+        textColours[t.color] = (textColours[t.color] ?? 0) + weight(t);
+// The two most-used greys: the one with more contrast on the background is text, the other muted.
+const contrastWith = (a, b) => {
+    const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p);
+    return (x + 0.05) / (y + 0.05);
+};
+const greys = ranked(textColours)
+    .filter((c) => chroma(c) < 40)
+    .slice(0, 2)
+    .sort((a, b) => contrastWith(b, background) - contrastWith(a, background));
+const overrides = { background, primary };
+if (bgs[1])
+    overrides.surface = bgs[1];
+if (bgs[2])
+    overrides.raised = bgs[2];
+if (greys[0])
+    overrides.text = greys[0];
+if (greys[1])
+    overrides['text-muted'] = greys[1];
+const border = ranked(m.borders).find((c) => chroma(c) < 40);
+if (border)
+    overrides.border = border;
+// Fonts and type levels from the measured text styles.
+const fam = {};
+for (const t of texts)
+    if (!t.mono)
+        fam[t.family] = (fam[t.family] ?? 0) + weight(t);
+const sans = ranked(fam)[0] ?? 'Inter';
+const mono = texts.find((t) => t.mono)?.family;
+const styles = new Map();
+for (const t of texts) {
+    const k = `${t.mono}/${t.size}/${t.weight}/${t.upper}`;
+    const s = styles.get(k) ?? { t, n: 0 };
+    s.n += weight(t);
+    styles.set(k, s);
+}
+const all = [...styles.values()].sort((a, b) => b.n - a.n);
+const pick = (f) => all.find((s) => f(s.t))?.t;
+const body = pick((t) => !t.mono && !t.upper && t.size >= 14 && t.size <= 17 && t.weight < 500);
+const base = body?.size ?? 15;
+const toLevel = (t) => ({
+    fontFamily: t.family,
+    fontSize: `${t.size}px`,
+    fontWeight: t.weight,
+    lineHeight: `${Math.round(t.lineHeight)}px`,
+    letterSpacing: t.tracking
+        ? `${(t.tracking / t.size).toFixed(3)}em`
+        : t.upper
+            ? `${tracking(t.size, true)}em`
+            : '0em',
+    ...(t.numeric || t.mono ? { fontFeature: '"tnum" 1' } : {}),
+});
+const measuredLevels = {
+    'title-screen': pick((t) => !t.numeric && t.size >= 24),
+    'title-card': pick((t) => !t.numeric && t.size >= 17 && t.size < 24 && t.weight >= 600),
+    'display-stat': pick((t) => t.numeric && t.size >= 30),
+    'number-lg': pick((t) => t.numeric && t.size >= 18 && t.size < 30),
+    body,
+    'body-strong': pick((t) => !t.mono && !t.upper && t.size >= 14 && t.size <= 17 && t.weight >= 500),
+    meta: pick((t) => !t.mono && !t.upper && t.size >= 12 && t.size < base && t.weight < 500),
+    'meta-number': pick((t) => t.mono && t.size <= 14),
+    'label-chip': pick((t) => !t.upper && t.size >= 12 && t.size < base && t.weight >= 500),
+    'label-caps': pick((t) => t.upper && t.size <= 13),
+    caption: pick((t) => !t.upper && t.size <= 12 && t.weight < 500),
+    'label-tab': pick((t) => t.size <= 11),
+};
+const radius = Number(ranked(m.radii)[0] ?? 16);
+// The outermost surfaces start at the page padding; inner rows start further in.
+const padding = Math.min(...Object.entries(m.lefts)
+    .filter(([, n]) => n >= 2)
+    .map(([l]) => Number(l)), 16);
+const choices = choicesFrom(args, {
+    name: typeof args.name === 'string' ? args.name : 'Extracted design',
+    mood: `Measured from ${sources.join(', ')}; refine this line with the product and its mood.`,
+    primary,
+    modes: [mode],
+    sans,
+    mono,
+    base,
+    roundness: Math.round(radius / 1.25),
+    page: padding >= 8 && padding <= 32 ? padding : 16,
+    colorOverrides: { [mode]: overrides },
+});
+// Measured levels win; the rest come from the generated scale for the measured base size and fonts.
+const { typeScale } = await import('./build-design.js');
+const generated = typeScale({ ...choices, levels: undefined });
+choices.levels = Object.fromEntries(Object.entries(generated).map(([k, l]) => [k, measuredLevels[k] ? toLevel(measuredLevels[k]) : l]));
+const found = Object.entries(measuredLevels)
+    .filter(([, t]) => t)
+    .map(([k]) => k);
+console.log(`measured ${texts.length} text elements on ${sources.length} page(s): ${mode} theme, primary ${primary}, ${sans}${mono ? ` + ${mono}` : ''}, body ${base}px, card radius ${radius}px, page padding ${padding}px`);
+console.log(`  type levels measured: ${found.join(', ') || 'none'}; the rest generated`);
+console.log(`  colours measured: ${Object.keys(overrides).join(', ')}; the rest generated from the primary`);
+writeDesign(choices, args);

package/dist/init.d.ts

@@ -0,0 +1,5 @@
+import { type Choices } from './build-design.ts';
+export declare function parseArgs(argv: string[]): Record<string, string | true>;
+export declare function choicesFrom(a: Record<string, string | true>, defaults?: Partial<Choices>): Choices;
+/** Writes the file and prints the contrast of the pairs that matter. */
+export declare function writeDesign(c: Choices, a: Record<string, string | true>): void;

package/dist/init.js

@@ -0,0 +1,83 @@
+/**
+ * Writes a complete DESIGN.md from a few choices (the way Stitch builds a design system from a theme):
+ *   stitch2 init --name "Acme Fit" --primary "#2F6FEB" [--mood "…"] [--modes dark,light] [--sans Inter]
+ *     [--mono "JetBrains Mono"] [--base 15] [--roundness 16] [--page 16] [--icons Lucide]
+ *     [--scheme tonal_spot|neutral|fidelity|vibrant|expressive|content|monochrome] [--out <file>] [--force]
+ * Then refine the prose with the brand's specifics, and run stitch2 lint and stitch2 tokens.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { buildDesignMd, contrast, palette } from './build-design.js';
+import { ROOT } from './config.js';
+export function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--'))
+            out[a.slice(2)] = true;
+        else {
+            out[a.slice(2)] = next;
+            i++;
+        }
+    }
+    return out;
+}
+export function choicesFrom(a, defaults = {}) {
+    const str = (k, d) => (typeof a[k] === 'string' ? a[k] : d);
+    const num = (k, d) => (typeof a[k] === 'string' ? Number(a[k]) : d);
+    const primary = str('primary', defaults.primary ?? '#2F6FEB');
+    if (!/^#[0-9a-f]{6}$/i.test(primary))
+        throw new Error(`--primary must be a #rrggbb colour, got ${primary}`);
+    return {
+        name: str('name', defaults.name ?? 'My app'),
+        mood: str('mood', defaults.mood ?? 'A focused, calm app that gets out of the way.'),
+        primary,
+        modes: str('modes', (defaults.modes ?? ['dark', 'light']).join(','))
+            .split(',')
+            .map((m) => m.trim()),
+        sans: str('sans', defaults.sans ?? 'Inter'),
+        mono: typeof a.mono === 'string' ? a.mono : defaults.mono,
+        base: num('base', defaults.base ?? 15),
+        roundness: num('roundness', defaults.roundness ?? 16),
+        page: num('page', defaults.page ?? 16),
+        icons: str('icons', defaults.icons ?? 'Lucide'),
+        scheme: str('scheme', defaults.scheme ?? 'tonal_spot'),
+        levels: defaults.levels,
+        colorOverrides: defaults.colorOverrides,
+    };
+}
+/** Writes the file and prints the contrast of the pairs that matter. */
+export function writeDesign(c, a) {
+    const out = resolve(typeof a.out === 'string' ? a.out : join(ROOT, 'DESIGN.md'));
+    if (existsSync(out) && !a.force) {
+        console.error(`${out} exists; pass --force to replace it, or --out to write elsewhere`);
+        process.exit(1);
+    }
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, buildDesignMd(c));
+    const tokens = join(dirname(out), 'tokens.config.json');
+    if (!existsSync(tokens))
+        writeFileSync(tokens, `${JSON.stringify({ seed: 'primary', scheme: c.scheme, contrast: 0 }, null, 2)}\n`);
+    console.log(`wrote ${out}`);
+    for (const m of c.modes) {
+        const p = palette(c, m);
+        if (p.primary.toLowerCase() !== c.primary.toLowerCase())
+            console.log(`  ${m}: primary adjusted from ${c.primary} to ${p.primary} so it and its label reach 4.5:1`);
+        const pairs = [
+            ['text on surface', p.text, p.surface],
+            ['text-muted on raised', p['text-muted'], p.raised],
+            ['on-primary on primary', p['on-primary'], p.primary],
+            ['primary on surface', p.primary, p.surface],
+            ['danger on raised', p.danger, p.raised],
+        ];
+        console.log(`  ${m}: ${pairs.map(([n, f, b]) => `${n} ${contrast(f, b).toFixed(1)}:1`).join(' · ')}`);
+    }
+    console.log('next: refine the prose (brand, voice, components), then stitch2 lint and stitch2 tokens');
+}
+if (/init\.[jt]s$/.test(process.argv[1] ?? '')) {
+    const a = parseArgs(process.argv.slice(2));
+    writeDesign(choicesFrom(a), a);
+}

package/dist/list.d.ts

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

package/dist/list.js

@@ -0,0 +1,17 @@
+/**
+ * Lists every screen version with its status and the reviewer's note, for agents (and anyone without the
+ * canvas open). Approved versions are the reference; review versions wait for the user; notes are feedback.
+ * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json]
+ */
+import { listScreens } from './screens.js';
+const args = process.argv.slice(2);
+const status = args.includes('--status') ? args[args.indexOf('--status') + 1] : undefined;
+const name = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--status');
+const rows = listScreens()
+    .filter((s) => s.kind === 'screen' && (!status || s.status === status) && (!name || s.screen === name))
+    .sort((a, b) => a.screen.localeCompare(b.screen) || a.device.localeCompare(b.device) || b.mtime - a.mtime);
+if (args.includes('--json'))
+    console.log(JSON.stringify(rows, null, 2));
+else
+    for (const s of rows)
+        console.log(`${s.screen.padEnd(20)} ${s.device.padEnd(8)} ${s.version.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);

package/dist/pick.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Element picking on the canvas. When the canvas loads a screen (with ?pick), every element in its body gets
+ * data-s2-line, its line in the source file, and a small script carries that attribute over to the markup a
+ * custom element renders in its place (a light-DOM component that replaces itself keeps its source line). The
+ * canvas reads the attribute to highlight an element and copy a reference such as
+ *   home mobile v1 (design/screens/home/mobile-v1.html:37) <gg-button> “Start Push”
+ * The source file is never changed, and nothing is added to the lines above the body.
+ */
+/** The page with source lines on its body's elements and the shim at the start of its head. */
+export declare function annotate(html: string): string;

package/dist/pick.js

@@ -0,0 +1,38 @@
+/**
+ * Element picking on the canvas. When the canvas loads a screen (with ?pick), every element in its body gets
+ * data-s2-line, its line in the source file, and a small script carries that attribute over to the markup a
+ * custom element renders in its place (a light-DOM component that replaces itself keeps its source line). The
+ * canvas reads the attribute to highlight an element and copy a reference such as
+ *   home mobile v1 (design/screens/home/mobile-v1.html:37) <gg-button> “Start Push”
+ * The source file is never changed, and nothing is added to the lines above the body.
+ */
+/** Tags that are never picked by themselves: their nearest picked ancestor stands for them. */
+const SKIP = new Set(['body', 'br', 'i', 'script', 'style', 'template', 'path', 'line', 'polyline', 'polygon', 'circle', 'ellipse', 'rect', 'g', 'defs', 'stop', 'use', 'text', 'tspan']);
+/** Runs in the screen before its own scripts: components that replace themselves pass their line on. */
+const SHIM = `<script>(()=>{const d=customElements.define.bind(customElements);customElements.define=(name,cls,opts)=>{const p=cls.prototype,cb=p.connectedCallback;if(cb)p.connectedCallback=function(...a){const line=this.getAttribute('data-s2-line'),parent=this.parentNode,before=this.previousSibling,after=this.nextSibling;const r=cb.apply(this,a);if(line){if(this.isConnected)this.setAttribute('data-s2-tag',name);else if(parent)for(let n=before?before.nextSibling:parent.firstChild;n&&n!==after;n=n.nextSibling)if(n.nodeType===1&&!n.hasAttribute('data-s2-line')){n.setAttribute('data-s2-line',line);n.setAttribute('data-s2-tag',name)}}return r};return d(name,cls,opts)}})()</script>`;
+/** The page with source lines on its body's elements and the shim at the start of its head. */
+export function annotate(html) {
+    const bodyAt = html.search(/<body[\s>]/i);
+    if (bodyAt < 0)
+        return html;
+    let line = html.slice(0, bodyAt).split('\n').length;
+    let out = html.slice(0, bodyAt);
+    let last = bodyAt;
+    const re = /<!--[\s\S]*?-->|<(script|style|textarea)\b[\s\S]*?<\/\1\s*>|<([a-zA-Z][\w-]*)/g;
+    re.lastIndex = bodyAt;
+    for (let m = re.exec(html); m; m = re.exec(html)) {
+        const chunk = html.slice(last, m.index);
+        line += chunk.split('\n').length - 1;
+        out += chunk;
+        const tag = m[2]?.toLowerCase();
+        if (m[1] === 'textarea')
+            out += m[0].replace(/^<textarea/i, `<textarea data-s2-line="${line}"`);
+        else
+            out += tag && !SKIP.has(tag) ? `${m[0]} data-s2-line="${line}"` : m[0];
+        line += m[0].split('\n').length - 1;
+        last = m.index + m[0].length;
+    }
+    out += html.slice(last);
+    // On the head's own line, so the body's line numbers stay those of the file.
+    return out.replace(/<head(\s[^>]*)?>/i, (h) => h + SHIM);
+}

package/dist/report.d.ts

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

package/dist/report.js

@@ -0,0 +1,110 @@
+/**
+ * Consistency report: every shared component cropped from every active screen, next to the component
+ * catalog's version, with what differs. Writes <design>/consistency/index.html, which the canvas opens from
+ * its sidebar. Usage: stitch2 consistency [kind…]   (kinds: tab-bar, header, icon-button, chip, …)
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chromium } from '@playwright/test';
+import { config } from './config.js';
+import { collectComponents, collectOptions, consistencyIssues, nameOf, } from './consistency.js';
+import { listScreens, ROOT } from './screens.js';
+import { startServer } from './serve.js';
+const kinds = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+const screens = listScreens().filter((s) => s.status !== 'archived');
+const out = join(ROOT, 'consistency');
+mkdirSync(out, { recursive: true });
+const safe = (s) => s.replace(/[^a-z0-9]+/gi, '_');
+const esc = (s) => String(s ?? '')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+const server = await startServer(0);
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2 });
+const known = {};
+const crops = {}; // kind -> path -> image files
+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(() => { });
+    await page.waitForTimeout(600);
+    const found = await page.evaluate(collectComponents, collectOptions());
+    known[s.path] = found.components;
+    for (const [kind, sigs] of Object.entries(found.components)) {
+        if (kinds.length && !kinds.includes(kind.split(':')[0]))
+            continue;
+        const files = [];
+        for (const [i, sig] of sigs.entries()) {
+            const file = `${safe(kind)}/${safe(s.path)}-${i}.png`;
+            mkdirSync(join(out, safe(kind)), { recursive: true });
+            try {
+                // Crop the element plus anything drawn outside it (a raised centre button above a tab bar).
+                const el = page.locator(sig.selector).first();
+                await el.scrollIntoViewIfNeeded({ timeout: 3000 });
+                const clip = await el.evaluate((node) => {
+                    const r = node.getBoundingClientRect();
+                    let top = r.top;
+                    let bottom = r.bottom;
+                    for (const c of node.querySelectorAll('*')) {
+                        const q = c.getBoundingClientRect();
+                        if (q.width && q.height) {
+                            top = Math.min(top, q.top);
+                            bottom = Math.max(bottom, q.bottom);
+                        }
+                    }
+                    return {
+                        x: Math.max(0, r.left),
+                        y: Math.max(0, top),
+                        width: r.width,
+                        height: bottom - Math.max(0, top),
+                    };
+                });
+                if (clip.width < 1 || clip.height < 1)
+                    continue;
+                await page.screenshot({ path: join(out, file), clip });
+                files.push(file);
+            }
+            catch { }
+        }
+        crops[kind] ??= {};
+        crops[kind][s.path] = files;
+    }
+}
+await browser.close();
+server.close();
+const issues = consistencyIssues(known, Object.keys(known));
+const ORDER = ['tab-bar', 'header', 'icon-button', 'button:primary:md', 'chip', 'section'];
+const rank = (k) => (ORDER.includes(k) ? ORDER.indexOf(k) : ORDER.length);
+const byPath = new Map(screens.map((s) => [s.path, s]));
+const sections = Object.keys(crops)
+    .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+    .map((kind) => {
+    const rows = Object.entries(crops[kind])
+        .sort(([a], [b]) => a.startsWith(config.catalogDir) ? -1 : b.startsWith(config.catalogDir) ? 1 : a.localeCompare(b))
+        .map(([path, files]) => {
+        const s = byPath.get(path);
+        const note = (issues[path] ?? []).filter((i) => i.message.startsWith(nameOf(kind)) || i.message.includes(nameOf(kind).toLowerCase()));
+        const verdict = path.startsWith(config.catalogDir)
+            ? '<b class="ref">catalog: the reference</b>'
+            : note.length
+                ? note.map((i) => `<p class="bad">${esc(i.message)}</p>`).join('')
+                : '<b class="ok">matches</b>';
+        return `<div class="row"><div class="who"><b>${esc(s.kind === 'components' ? 'Component catalog' : `${s.screen} · ${s.device} · ${s.version}`)}</b><code>${esc(path)}</code>${verdict}</div><div class="imgs">${files.map((f) => `<img src="${esc(f)}" alt="" />`).join('')}</div></div>`;
+    })
+        .join('');
+    return `<section><h2>${esc(nameOf(kind))} <span>${esc(kind)}</span></h2>${rows}</section>`;
+})
+    .join('');
+writeFileSync(join(out, 'index.html'), `<!doctype html><html lang="en"><head><meta charset="utf-8" /><title>Consistency report</title><style>
+  body { background: #0f0f11; color: #f4f4f5; font: 14px/1.5 system-ui, sans-serif; margin: 0; }
+  main { margin: 0 auto; max-width: 1200px; padding: 32px; }
+  h1 { font-size: 26px; margin: 0 0 4px; } h2 { font-size: 18px; margin: 40px 0 12px; } h2 span, code { color: #71717a; font: 12px ui-monospace, monospace; }
+  .row { border-top: 1px solid #2e2e33; display: grid; gap: 20px; grid-template-columns: 320px 1fr; padding: 14px 0; }
+  .who { display: grid; gap: 4px; align-content: start; min-width: 0; overflow-wrap: anywhere; } .imgs { display: flex; flex-wrap: wrap; gap: 12px; align-items: flex-start; min-width: 0; }
+  img { background: #000; border: 1px solid #2e2e33; border-radius: 8px; max-width: 100%; width: 390px; }
+  .ok { color: #3fb27f; } .ref { color: #a1a1aa; } .bad { color: #e5b54a; margin: 0; font-size: 13px; }
+</style></head><body><main><h1>Consistency report</h1><code>${new Date().toISOString()} · ${screens.length} active screens · reference: ${esc(config.catalogDir)}</code>${sections}</main></body></html>\n`);
+console.log(`consistency report: ${join(out, 'index.html')} (${Object.keys(crops).length} components, ${screens.length} screens)`);

package/dist/sandbox.d.ts

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