stitch2 0.20.1 → 0.22.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/consistency.js

@@ -335,7 +335,7 @@ export function reuseIssues(path, page) {
     if (familyOf(path) !== 'screens')
         return [];
     return page.handBuilt.slice(0, 10).map((h) => ({
-        severity: 'warning',
+        severity: 'error',
         type: 'reuse',
         message: `${nameOf(h.kind)} built by hand; use <${NAMES[h.kind]?.[1] ?? 'the catalog component'}> (see the component catalog, ${config.catalogDir})`,
         selector: h.selector,

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.1",
+  "version": "0.22.0",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -54,8 +54,9 @@ References, read before the first screen:
    and translate it with **stitch2-translate**. Never add classes to a component to change how it looks, and never write a colour value (hex,
    `rgb()`, `hsl()`): only DESIGN.md's colours, as token classes or `var(--<prefix>-<name>)`.
 5. **Check** `stitch2 check <path> --shots --strict`. Fix every error (overflow, wrapped labels, content under
-   fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text) and every warning about type (`type-*`), hand-built
-   components (`reuse`), components that differ from the catalog (`consistency`) and colour values (`color`).
+   fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text), a hand-built copy of a
+   catalog component (`reuse`: use the component or extend it, never rebuild it), and every warning about type
+   (`type-*`), components that differ from the catalog (`consistency`) and colour values (`color`).
    Text running into other text (`text-overlap`) or out of its card (`overflow`) is an error; a short label cut
    short with an ellipsis (`truncated`) is a warning to fix with room, not a smaller size. Google's rules are
    warnings too (`text-small`, `edge-margin`, `measure`, `tap-spacing`, `placeholder-label`, `unnamed-control`,

package/skills/stitch2/references/components.md

@@ -11,6 +11,8 @@ colour, icons and states. Users learn an element once; every variant costs atten
 
 ## The ladder
 
+Open the catalog first (on the canvas, or its render under `<design>/renders/`): every element of the
+screen is mapped to a component before any markup is written, and the mapping is part of the hand-over.
 Go down only when the step above cannot work:
 
 1. **Use** a component as it is.
@@ -69,9 +71,11 @@ series) is added to DESIGN.md first, with a line in the prose saying where it is
 
 ## What the checks report
 
-- **reuse**: on a lab screen, an element that looks like a catalog component but was built by hand (a bottom
-  bar with three or more buttons, an h1, a primary-filled button, a pill chip, a header icon button, a caps
-  label).
+- **reuse** (an error: it fails `check --strict` and blocks the hand-over): on a lab screen, an element that
+  looks like a catalog component but was built by hand (a bottom bar with three or more buttons, an h1,
+  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.
 - **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

@@ -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