stitch2 0.20.0 → 0.21.0

package/dist/approve.js

@@ -18,7 +18,8 @@ if (!targets.length) {
 // Oldest first, so approving several versions of one screen leaves the latest current.
 targets.sort((a, b) => a.path.localeCompare(b.path, undefined, { numeric: true }));
 for (const t of targets) {
-    const archived = approve(t.path);
+    const { archived, relinked } = approve(t.path);
     const note = archived.length ? `; archived ${archived.map((s) => s.version).join(', ')}` : '';
-    console.log(`approved ${t.screen} ${t.version} ${t.device}${note}`);
+    const links = relinked.length ? `; relinked ${relinked.join(', ')}` : '';
+    console.log(`approved ${t.screen} ${t.version} ${t.device}${note}${links}`);
 }

package/dist/audit.js

@@ -218,6 +218,14 @@ export async function audit(opts) {
     window.scrollTo(0, 0);
     // 4. Tap targets: WCAG 2.2 asks for at least 24px; smaller than the config's comfortableTarget is a warning.
     const interactive = all.filter((el) => el.matches('button, a[href], input:not([type=hidden]), select, textarea, [role=button], [role=tab], [role=switch], [role=checkbox]'));
+    // Fixed and sticky layers float over the scrolling page (a running-workout panel over cards): content slides
+    // under them while scrolling, so they never crowd in-flow targets. Tap spacing (6d) already compares layers.
+    const layerOf = (el) => {
+        for (let e = el; e; e = e.parentElement)
+            if (['fixed', 'sticky'].includes(getComputedStyle(e).position))
+                return e;
+        return null;
+    };
     for (const el of interactive) {
         if (interactive.some((o) => o !== el && o.contains(el)))
             continue;
@@ -229,7 +237,7 @@ export async function audit(opts) {
         const cx = r.left + r.width / 2;
         const cy = r.top + r.height / 2;
         const crowded = interactive.some((o) => {
-            if (o === el || o.contains(el) || el.contains(o))
+            if (o === el || o.contains(el) || el.contains(o) || layerOf(o) !== layerOf(el))
                 return false;
             const q = o.getBoundingClientRect();
             const dx = Math.max(q.left - cx, 0, cx - q.right);
@@ -250,12 +258,8 @@ export async function audit(opts) {
     // 4b. Controls never overlap one another (a button squeezed over its neighbour). Controls inside one another
     // and invisible overlays (a native picker laid over a row) are fine; fixed and sticky layers (a docked timer,
     // a sticky Save bar floating over a list) are compared apart from the scrolling page.
-    const layer = (el) => {
-        for (let e = el; e; e = e.parentElement)
-            if (['fixed', 'sticky'].includes(getComputedStyle(e).position))
-                return e;
-        return null;
-    };
+    // layerOf is defined with the tap targets above; fixed and sticky layers are compared apart here too.
+    const layer = layerOf;
     // The part of a control its scrolling or clipping ancestors show: a link scrolled out of a nav strip is not drawn
     // where its box would be.
     const visibleBox = (el) => {

package/dist/list.js

@@ -1,10 +1,11 @@
 /**
  * Lists every screen version, variant by variant (mobile, tablet, desktop), 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.
- * Ends with what makes the current version unclear (versionProblems); --strict fails on it.
+ * Ends with what makes the current version unclear (versionProblems) and links to a previous variant
+ * (staleLinks); --strict fails on either.
  * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json] [--strict]
  */
-import { listScreens, stateOf, versionProblems } from './screens.js';
+import { listScreens, staleLinks, stateOf, versionProblems } 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');
@@ -35,5 +36,11 @@ if (problems.length && !args.includes('--json')) {
     for (const p of problems)
         console.log(`  ${p}`);
 }
-if (problems.length && args.includes('--strict'))
+const links = staleLinks().filter((p) => !name || p.startsWith(`${name}/`) || p.includes(` ${name} `));
+if (links.length && !args.includes('--json')) {
+    console.log(`\nLinks to a previous variant (${links.length}):`);
+    for (const p of links)
+        console.log(`  ${p}`);
+}
+if ((problems.length || links.length) && args.includes('--strict'))
     process.exit(1);

package/dist/screens.d.ts

@@ -40,13 +40,43 @@ export declare function listScreens(): Screen[];
 export declare const stateOf: (s: Pick<Screen, 'screen' | 'page'>) => string;
 /** Sets (or removes, with undefined) <prefix>-* meta tags in a screen file, keeping the rest of it untouched. */
 export declare function writeMeta(path: string, values: Record<string, string | undefined>): void;
+/**
+ * Links between screens: a screen embeds or points at another screen's variant,
+ * `src="/screens/workout/mobile-v3.html"`. Such a link always names the current approved version of that
+ * screen on that device; approval moves every link that names an earlier version to the approved one.
+ */
+/** Every src/href reference to a screen variant inside a screen file. */
+export interface ScreenRef {
+    screen: string;
+    device: 'mobile' | 'tablet' | 'desktop';
+    version: number;
+}
+export declare function findScreenRefs(html: string): ScreenRef[];
+/** Bumps every reference to an earlier version of one screen variant to the given version. */
+export declare function rewriteScreenRefs(html: string, screen: string, device: string, version: number): string;
+/**
+ * Moves every link that names an earlier version of the target's screen on its device to the target's
+ * version, in every screen file. Returns the files it changed.
+ */
+export declare function rewriteStaleLinks(target: Pick<Screen, 'screen' | 'device' | 'version'>): string[];
+/**
+ * Links that name a variant which is not current: the file is gone, the variant is archived, or a newer
+ * version is approved on that screen and device. A link to a version still in review or a draft is a
+ * deliberate preview of a proposal, not stale. One line each; empty when every link is current.
+ */
+export declare function staleLinks(screens?: Screen[]): string[];
 /**
  * Approves a variant. Approval makes it the one current version of its screen on its device: every earlier
  * version there (approved, in review or a draft) and any other approved one become archived, so nobody can mistake
  * an older one for what is implemented. Later versions (a newer proposal) keep their status.
- * Returns the variants it archived.
+ * Links from other screens to an earlier version of this screen on this device move to the approved one,
+ * so no screen keeps pointing at a previous variant.
+ * Returns the variants it archived and the files whose links moved.
  */
-export declare function approve(path: string): Screen[];
+export declare function approve(path: string): {
+    archived: Screen[];
+    relinked: string[];
+};
 /**
  * What makes it unclear which version of a screen is current: two approved on one device, or an earlier version
  * still in review or a draft next to an approved later one. One line each; empty when every screen is clear.

package/dist/screens.js

@@ -93,11 +93,85 @@ export function writeMeta(path, values) {
     }
     writeFileSync(file, html);
 }
+const refRe = /(?:src|href)="[^"]*?(?:screens\/)?([a-z0-9-]+)\/(mobile|tablet|desktop)-v(\d+)\.html/g;
+export function findScreenRefs(html) {
+    const out = [];
+    for (const m of html.matchAll(refRe))
+        out.push({ screen: m[1], device: m[2], version: Number(m[3]) });
+    return out;
+}
+/** Bumps every reference to an earlier version of one screen variant to the given version. */
+export function rewriteScreenRefs(html, screen, device, version) {
+    return html.replace(refRe, (m, s, d, v) => s === screen && d === device && Number(v) < version ? m.replace(`-v${v}.html`, `-v${version}.html`) : m);
+}
+/**
+ * Moves every link that names an earlier version of the target's screen on its device to the target's
+ * version, in every screen file. Returns the files it changed.
+ */
+export function rewriteStaleLinks(target) {
+    const n = versionNumber(target);
+    if (Number.isNaN(n))
+        return [];
+    const changed = [];
+    for (const dir of config.screenDirs) {
+        for (const file of htmlFiles(join(ROOT, dir))) {
+            const html = readFileSync(file, 'utf8');
+            const next = rewriteScreenRefs(html, target.screen, target.device, n);
+            if (next !== html) {
+                writeFileSync(file, next);
+                changed.push(relative(ROOT, file));
+            }
+        }
+    }
+    return changed.sort();
+}
+/**
+ * Links that name a variant which is not current: the file is gone, the variant is archived, or a newer
+ * version is approved on that screen and device. A link to a version still in review or a draft is a
+ * deliberate preview of a proposal, not stale. One line each; empty when every link is current.
+ */
+export function staleLinks(screens = listScreens()) {
+    const out = [];
+    const current = new Map();
+    for (const s of screens) {
+        if (s.kind !== 'screen' || s.status !== 'approved')
+            continue;
+        const key = `${s.screen} ${s.device}`;
+        const n = versionNumber(s);
+        if (!Number.isNaN(n))
+            current.set(key, Math.max(current.get(key) ?? -1, n));
+    }
+    const byVariant = new Map(screens.map((s) => [`${s.screen} ${s.device} v${versionNumber(s)}`, s]));
+    const seen = new Set();
+    for (const dir of config.screenDirs) {
+        for (const file of htmlFiles(join(ROOT, dir))) {
+            const rel = relative(ROOT, file);
+            const html = readFileSync(file, 'utf8');
+            for (const r of findScreenRefs(html)) {
+                const key = `${r.screen} ${r.device}`;
+                const cur = current.get(key);
+                if (cur === undefined || r.version >= cur)
+                    continue;
+                const hit = byVariant.get(`${key} v${r.version}`);
+                if (hit && hit.status !== 'approved' && hit.status !== 'archived')
+                    continue;
+                const line = `${rel}: points at ${r.screen} ${r.device}-v${r.version} (${hit ? hit.status : 'missing'}); current is v${cur}`;
+                if (!seen.has(line)) {
+                    seen.add(line);
+                    out.push(line);
+                }
+            }
+        }
+    }
+    return out.sort();
+}
 /**
  * Approves a variant. Approval makes it the one current version of its screen on its device: every earlier
  * version there (approved, in review or a draft) and any other approved one become archived, so nobody can mistake
  * an older one for what is implemented. Later versions (a newer proposal) keep their status.
- * Returns the variants it archived.
+ * Links from other screens to an earlier version of this screen on this device move to the approved one,
+ * so no screen keeps pointing at a previous variant.
+ * Returns the variants it archived and the files whose links moved.
  */
 export function approve(path) {
     const all = listScreens();
@@ -114,7 +188,7 @@ export function approve(path) {
         (s.status === 'approved' || versionNumber(s) < n));
     for (const s of outdated)
         writeMeta(s.path, { [tag('status')]: 'archived' });
-    return outdated;
+    return { archived: outdated, relinked: rewriteStaleLinks(target) };
 }
 /**
  * What makes it unclear which version of a screen is current: two approved on one device, or an earlier version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.20.0",
+  "version": "0.21.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/references/screens.md

@@ -86,6 +86,15 @@ The canvas shows each version with its variants side by side under one heading,
 needs review while any variant does. **Approve version** approves every variant in review at once; a single
 variant can still be approved, archived or noted on its own.
 
+## Links between screens
+
+A screen that embeds or points at another screen names its file
+(`src="/screens/workout/mobile-v3.html"`): always the current approved version of that screen on that
+device, never a previous one. Approving a variant moves every such link to it at once (the canvas Approve
+does the same as `stitch2 approve`), and `stitch2 screens` lists any link that still names a previous variant
+— fix it, or move it to the current version yourself when the link was deliberate. A link to a version still
+in review or a draft is a preview of a proposal and stays.
+
 ## How to use them
 
 1. Before designing, run `stitch2 screens` (a name or `--status approved` narrows it) and open the approved