stitch2 0.22.6 → 0.22.8

package/dist/canvas.html

@@ -300,9 +300,13 @@ let reports = { consistency: null, compare: null, states: null }
 let selected = null
 const frames = new Map() // path -> { el, device, img, iframe (while live), screen, height }
 // Heights measured before, so the layout doesn't jump while pictures and pages load.
-const HEIGHTS = JSON.parse(localStorage.getItem('stitch2-heights-v2') ?? '{}')
+// Height semantics changed when live frames began loading at their authored
+// viewport. Do not carry a pre-fix cache into this layout: one stale 20k page
+// is enough to create a giant gap before its iframe is visited.
+const HEIGHT_KEY = 'stitch2-heights-v3'
+const HEIGHTS = JSON.parse(localStorage.getItem(HEIGHT_KEY) ?? '{}')
 let heightsTimer
-const saveHeights = () => { clearTimeout(heightsTimer); heightsTimer = setTimeout(() => localStorage.setItem('stitch2-heights-v2', JSON.stringify(HEIGHTS)), 1000) }
+const saveHeights = () => { clearTimeout(heightsTimer); heightsTimer = setTimeout(() => localStorage.setItem(HEIGHT_KEY, JSON.stringify(HEIGHTS)), 1000) }
 let layoutQueued = false
 /** Many frames measure themselves at once while loading: one layout per animation frame. */
 const scheduleLayout = () => { if (!layoutQueued) { layoutQueued = true; requestAnimationFrame(() => { layoutQueued = false; layout() }) } }
@@ -630,21 +634,40 @@ function mount(f) {
   const iframe = document.createElement('iframe')
   iframe.setAttribute('scrolling', 'no')
   f.iframe = iframe
+  // A remounted frame can still have a cached full-page height. Start the
+  // document at its authored viewport so vh/svh/dvh rules are evaluated
+  // against the screen, not against the previous page height.
   size(f)
+  iframe.style.height = `${f.screen.viewportHeight ?? 844}px`
+  const waitForStyles = async () => {
+    const doc = iframe.contentDocument
+    if (!doc || doc.readyState !== 'complete') return false
+    try { await doc.fonts?.ready } catch {}
+    // Browser-built Tailwind and late stylesheet links can settle just after
+    // load. Do not measure or reveal the live page until that layout pass.
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+    // `load` also fires for the initial about:blank document. Compare the
+    // loaded document itself with the current iframe target (which may have
+    // changed for a language/theme reload while this mount was pending).
+    return f.iframe === iframe && iframe.contentDocument === doc && doc.readyState === 'complete' && doc.location.href === iframe.src
+  }
   iframe.addEventListener('load', () => {
     if (f.iframe !== iframe) return
-    applyTheme(f)
-    measure(f)
-    clearTimeout(f.reveal)
-    // Tailwind's browser build and the components settle just after load: the picture stays until then.
-    f.reveal = setTimeout(() => {
-      if (f.iframe !== iframe) return
+    void (async () => {
+      if (!(await waitForStyles()) || f.iframe !== iframe) return
+      applyTheme(f)
       measure(f)
-      f.el.classList.add('ready')
-      for (const go of f.waiters.splice(0)) go()
-    }, 350)
-    setTimeout(() => { if (f.iframe === iframe) measure(f) }, 1200)
-    setTimeout(() => { if (f.iframe === iframe) measure(f) }, 2500)
+      clearTimeout(f.reveal)
+      // The picture stays until the complete, styled page has been measured.
+      f.reveal = setTimeout(() => {
+        if (f.iframe !== iframe) return
+        measure(f)
+        f.el.classList.add('ready')
+        for (const go of f.waiters.splice(0)) go()
+      }, 350)
+      setTimeout(() => { if (f.iframe === iframe) measure(f) }, 1200)
+      setTimeout(() => { if (f.iframe === iframe) measure(f) }, 2500)
+    })()
   })
   iframe.src = frameSrc(f.screen)
   f.device.insertBefore(iframe, f.img.nextSibling)

package/dist/consistency.d.ts

@@ -21,12 +21,14 @@ export interface PageComponents {
         selector: string;
         text: string;
     }[];
+    /** Provenance declared by the page. App snapshots are faithful renders, not component implementations. */
+    source?: 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[];
+    primary?: number[];
 }
 /** The options for collectComponents from the config and DESIGN.md's primary colour. */
 export declare function collectOptions(): CollectOptions;

package/dist/consistency.js

@@ -10,8 +10,31 @@ import { config } from './config.js';
 import { readDesign } from './design-md.js';
 /** The options for collectComponents from the config and DESIGN.md's primary colour. */
 export function collectOptions() {
-    const hex = (readDesign().colors.primary ?? '#000000').replace('#', '');
-    return { prefix: config.prefix, primary: [0, 2, 4].map((i) => Number.parseInt(hex.slice(i, i + 2), 16)) };
+    const design = readDesign();
+    // DESIGN.md projects created by stitch2 have `colors.primary`; projects that use a richer palette often name
+    // the same role and reference it from components.button-primary. Resolve that reference here. Falling back to
+    // black made every transparent element look like a primary button.
+    const component = design.components['button-primary']?.backgroundColor;
+    const ref = /^\{colors\.([\w.-]+)\}$/.exec(component ?? '')?.[1];
+    const value = design.colors.primary ?? (ref ? design.colors[ref] : undefined) ?? component;
+    const primary = parseColour(value);
+    return { prefix: config.prefix, ...(primary ? { primary } : {}) };
+}
+/** CSS colours accepted in DESIGN.md, represented as RGB for the page-side detector. */
+function parseColour(value) {
+    if (!value)
+        return undefined;
+    const hex = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(value.trim())?.[1];
+    if (hex) {
+        const expanded = hex.length === 3 ? hex.replace(/./g, (c) => c + c) : hex;
+        return [0, 2, 4].map((i) => Number.parseInt(expanded.slice(i, i + 2), 16));
+    }
+    const rgb = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/i.exec(value.trim());
+    if (!rgb)
+        return undefined;
+    return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])].every(Number.isFinite)
+        ? [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])]
+        : undefined;
 }
 /** Runs in the page. Plain JS on purpose: Playwright sends its source to the browser. */
 export function collectComponents(opts) {
@@ -73,11 +96,37 @@ export function collectComponents(opts) {
     });
     const iconSet = (root) => [...new Set(icons(root).map(([s]) => s))].join('+');
     const box = (el) => el.getBoundingClientRect();
-    const ember = (el) => getComputedStyle(el).backgroundColor.includes(opts.primary.join(', '));
+    const ember = (el) => {
+        if (!opts.primary)
+            return false;
+        const background = getComputedStyle(el).backgroundColor.trim();
+        // Computed sRGB backgrounds are rgb()/rgba() in supported browsers. Do not extract arbitrary numbers from
+        // oklch(), color-mix() or a CSS variable that did not resolve: a false primary match is worse than no match.
+        const values = /^rgba?\(/i.test(background) ? background.match(/[\d.]+/g)?.map(Number) ?? [] : [];
+        const alpha = values.length > 3 ? values[3] : 1;
+        return (alpha >= 0.05 &&
+            values.length >= 3 &&
+            opts.primary.every((value, i) => Math.abs(value - values[i]) <= 2));
+    };
     const visible = (el) => {
         const r = box(el);
         const c = getComputedStyle(el);
-        return r.width > 0 && r.height > 0 && c.visibility !== 'hidden' && c.display !== 'none';
+        if (r.width <= 0 || r.height <= 0 || c.visibility === 'hidden' || c.display === 'none')
+            return false;
+        // A closed <details> exposes only its summary. Its descendants can still have boxes in a static snapshot,
+        // especially when the snapshot was captured at a responsive breakpoint.
+        const closed = el.closest('details:not([open])');
+        if (closed && !closed.querySelector(':scope > summary')?.contains(el))
+            return false;
+        // Match audit/type checks: clipped screen-reader-only nodes and transparent ancestors are not drawn.
+        if (r.width <= 1 && r.height <= 1 && c.position === 'absolute')
+            return false;
+        if (c.clip === 'rect(0px, 0px, 0px, 0px)' || c.clipPath === 'inset(100%)')
+            return false;
+        let opacity = 1;
+        for (let e = el; e; e = e.parentElement)
+            opacity *= Number(getComputedStyle(e).opacity);
+        return opacity >= 0.05;
     };
     const sigOf = (kind, el) => {
         const c = getComputedStyle(el);
@@ -223,7 +272,8 @@ export function collectComponents(opts) {
             el.matches('h2, h3, h4, p, span, div, label'))
             found('section', el);
     }
-    return { components, handBuilt };
+    const source = document.querySelector(`meta[name="${opts.prefix}-source"]`)?.getAttribute('content') ?? undefined;
+    return { components, handBuilt, ...(source ? { source } : {}) };
 }
 /** The components whose look is measured and compared; the rest follow their content (see sigOf). */
 const MEASURED = new Set(['tab-bar', 'header', 'section', 'card', 'button', 'icon-button', 'chip']);
@@ -332,7 +382,9 @@ export function consistencyIssues(known, paths) {
 }
 /** Lab screens build catalog components with the components, not by hand. */
 export function reuseIssues(path, page) {
-    if (familyOf(path) !== 'screens')
+    // App snapshots preserve the exact product markup for visual review. They are not authored by the lab and cannot
+    // truthfully be rewritten to custom elements; only hand-authored lab screens are checked for component reuse.
+    if (familyOf(path) !== 'screens' || page.source === 'app')
         return [];
     return page.handBuilt.slice(0, 10).map((h) => ({
         severity: 'error',

package/dist/design-md.d.ts

@@ -24,6 +24,8 @@ export declare function motionDurations(design?: Design): number[];
  * colours are the dark theme and light-* colours make a light one.
  */
 export declare function designThemes(): string[];
+/** Keep an authored font stack intact, quoting only a single family whose name needs it. */
+export declare function cssFontStack(value: string | undefined): string;
 /** A type level in pixels, for comparing with computed styles. */
 export interface Level {
     name: string;

package/dist/design-md.js

@@ -55,19 +55,51 @@ export function designThemes() {
         return ['dark'];
     }
 }
+/** Convert a CSS length from DESIGN.md to pixels. CSS rem uses the 16px root; em and percentages use `relative`. */
+function cssLength(value, relative, unitless) {
+    if (value === undefined || value === null)
+        return 0;
+    if (typeof value === 'number')
+        return unitless === 'relative' ? value * relative : value;
+    const match = /^(-?(?:\d+|\d*\.\d+))\s*(px|rem|em|%)?$/i.exec(value.trim());
+    if (!match)
+        return 0;
+    const n = Number(match[1]);
+    switch ((match[2] ?? '').toLowerCase()) {
+        case 'rem':
+            return n * 16;
+        case 'em':
+        case '%':
+            return n * relative * (match[2] === '%' ? 0.01 : 1);
+        case 'px':
+            return n;
+        default:
+            return unitless === 'relative' ? n * relative : n;
+    }
+}
+/** Keep an authored font stack intact, quoting only a single family whose name needs it. */
+export function cssFontStack(value) {
+    const stack = value?.trim() ?? '';
+    if (!stack)
+        return '';
+    if (stack.includes(',') || /^['"].*['"]$/.test(stack) || /^[\w-]+$/.test(stack) || /^var\(/i.test(stack))
+        return stack;
+    return `"${stack.replaceAll('"', '\\"')}"`;
+}
 export function typeLevels(design = readDesign()) {
     return Object.entries(design.typography).map(([name, t]) => {
-        const size = Number.parseFloat(String(t.fontSize));
-        const lh = String(t.lineHeight);
+        const size = cssLength(t.fontSize, 16, 'px');
+        const lineHeightValue = t.lineHeight;
+        const lineHeight = typeof lineHeightValue === 'string' && lineHeightValue.trim().toLowerCase() === 'normal'
+            ? size * 1.2
+            : cssLength(lineHeightValue, size, 'relative');
         return {
             name,
             mono: /mono/i.test(t.fontFamily ?? ''),
             size,
             weight: Number(t.fontWeight ?? 400),
-            lineHeight: lh.endsWith('px') ? Number.parseFloat(lh) : Number.parseFloat(lh) * size,
-            tracking: t.letterSpacing?.endsWith('em')
-                ? Number.parseFloat(t.letterSpacing) * size
-                : Number.parseFloat(t.letterSpacing ?? '0') || 0,
+            lineHeight,
+            tracking: cssLength(t.letterSpacing, size, 'px'),
         };
     });
 }

package/dist/screens.d.ts

@@ -28,8 +28,8 @@ export interface Screen {
      */
     page: string;
     device: 'mobile' | 'tablet' | 'desktop';
-    /** Where the version came from: stitch, lab or trial. */
-    source: 'stitch' | 'lab' | 'trial';
+    /** Where the version came from: app snapshot, generated draft or authored design. */
+    source: 'stitch' | 'lab' | 'trial' | 'app';
     /** Short version label: "v3", "Stitch", "Trial 2". */
     version: string;
     status: Status;

package/dist/tokens.js

@@ -10,7 +10,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { argbFromHex, Hct, hexFromArgb, MaterialDynamicColors, SchemeContent, SchemeExpressive, SchemeFidelity, SchemeFruitSalad, SchemeMonochrome, SchemeNeutral, SchemeRainbow, SchemeTonalSpot, SchemeVibrant, } from '@material/material-color-utilities';
 import { config as lab } from './config.js';
-import { readDesign } from './design-md.js';
+import { cssFontStack, readDesign } from './design-md.js';
 import { POINTER, writeExports } from './exports.js';
 import { ROOT } from './screens.js';
 const SCHEMES = {
@@ -71,7 +71,7 @@ const typeDecls = {};
 const typeRules = Object.entries(design.typography).map(([name, t]) => {
     const fallback = `var(--${lab.prefix}-font-${/mono/i.test(t.fontFamily ?? '') ? 'mono' : 'sans'}-fallback)`;
     const decl = [
-        `font: ${t.fontWeight} ${t.fontSize}/${t.lineHeight} "${t.fontFamily}", ${fallback}`,
+        `font: ${t.fontWeight} ${t.fontSize}/${t.lineHeight} ${cssFontStack(t.fontFamily) || 'sans-serif'}, ${fallback}`,
         `letter-spacing: ${t.letterSpacing ?? '0em'}`,
         t.fontFeature ? `font-feature-settings: ${t.fontFeature}` : '',
         name.endsWith('-caps') ? 'text-transform: uppercase' : '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.22.6",
+  "version": "0.22.8",
   "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/references/components.md

@@ -76,6 +76,11 @@ series) is added to DESIGN.md first, with a line in the prose saying where it is
   a primary-filled button, a pill chip, a header icon button, a caps label). A screen that duplicates a
   component instead of using it is not handed over: use the component, or extend it (step 4 of the ladder)
   when it cannot do what the screen needs.
+- The reuse detector reports what is actually drawn: descendants of a closed `<details>`, screen-reader-only or
+  clipped nodes, and elements hidden by a transparent ancestor are ignored. This keeps collapsed menus and
+  accessibility-only labels from becoming false component errors. A faithful app snapshot marked with
+  `<meta name="<prefix>-source" content="app">` is a visual baseline, not a component implementation, so its
+  markup is not reuse-checked; make a new lab-authored version before editing the snapshot.
 - **consistency**: a component whose size, radius, font, icon set or icons differ from the catalog's version
   (or, without a catalog, from the majority of screens in its family), or that appears in two versions on one
   screen. `stitch2 consistency` shows the same as cropped images; see the stitch2-consistency skill.

package/skills/stitch2/references/screens.md

@@ -13,7 +13,7 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
   (`mobile-v3.html` and `desktop-v3.html` are v3). A new version takes the next free N across the screen's
   variants; a variant added to an existing version takes that version's N (a desktop for v3 is
   `desktop-v3.html`, never v4). A version may start with one variant and get the others later.
-  Its head carries `<p>-screen`, `<p>-page` (see Pages), `<p>-device` (mobile | desktop), `<p>-status`, `<p>-source` (stitch | lab),
+  Its head carries `<p>-screen`, `<p>-page` (see Pages), `<p>-device` (mobile | desktop), `<p>-status`, `<p>-source` (stitch | lab | app),
   `<p>-frame-width` (390 mobile, 1280 desktop) and, written by the user, `<p>-note`. Older files elsewhere
   carry the same tags.
 
@@ -22,6 +22,12 @@ It is not the document height: long pages still appear whole. In canvas frames a
 `vh`, `svh`, `dvh` and `lvh` keep this viewport height when the frame grows, so full-height sections
 do not create ever-growing gaps. Width responsiveness stays active.
 
+`source=app` means an unchanged capture of a running application's rendered DOM,
+not a hand-authored design. Layout and visual checks still apply; the `reuse`
+rule does not demand replacing its already-rendered framework components with
+lab elements. Keep the import URL as provenance. A new design based on a capture
+uses `source=lab` and the shared component catalog, not the snapshot exception.
+
 ## Pages and their screens
 
 A place in the app often has several states or steps: the workout with its number pad, its menu and its discard

package/skills/stitch2/references/typography.md

@@ -6,6 +6,9 @@ project's DESIGN.md defines the levels (front matter `typography`); `stitch2 tok
 `.type-<level>` class, `stitch2 check` warns about text that is not one of them, and `stitch2 type` lists every
 style a screen uses.
 
+Use CSS lengths for the type scale (`px`, `rem`, `em`); checks normalize them to rendered pixels
+using a 16px root. A font-family list stays a CSS stack, not one quoted family name.
+
 ## 1. A type scale is a short list of levels
 
 Google's DESIGN.md format suggests 9–15 levels, each fixing family, size, line height, weight and tracking

package/skills/stitch2-consistency/SKILL.md

@@ -40,6 +40,11 @@ majority of screens in the same family.
 | Two versions of one component on a screen | Pick the catalog's; if both are needed, they are two variants: add the variant to the component |
 | The catalog itself is missing the variant a screen needs | Add it to the component and the catalog first, then use it |
 
+The reuse check only considers what is drawn. Descendants of a closed `<details>`, clipped or screen-reader-only
+nodes, and elements hidden by a transparent ancestor are excluded. Screens imported as faithful app snapshots may
+declare `<meta name="<prefix>-source" content="app">`; those baselines are checked visually, but are not expected to
+contain the lab's custom elements. Create a new lab-authored version before changing one.
+
 Never fix consistency by editing one screen to imitate another by hand, and never edit an approved version:
 make the next version.