stitch2 0.15.3 → 0.16.0

package/README.md

@@ -72,7 +72,8 @@ file that already exists. From there the agent spends its effort on the design.
   ```
 - **Versions, variants and approval**: a screen has versions (v1, v2, …), and each version has variants, its
   layouts for mobile and desktop (`mobile-v3.html`, `desktop-v3.html`). The canvas groups them; you approve a
-  version as a whole or one variant at a time, leave notes, and approving archives the previous approved layout.
+  version as a whole or one variant at a time, and leave notes. The approved version is the one current version:
+  approving it archives every earlier one, and only it gets implemented.
 - **DESIGN.md builder**: `stitch2 init` writes a complete DESIGN.md from a few choices (brand colour, modes,
   fonts, roundness, density), with colours checked for contrast; `stitch2 extract` measures one from an existing
   site or screens.
@@ -253,7 +254,8 @@ layout first, then a shorter natural word, never a smaller type size.
 | `stitch2 i18n [filter] [--locale l] [--suggest] [--json]` | Message keys the source or a locale lacks, and screen text with no key |
 | `stitch2 consistency [kind…]` | The consistency report, `<design>/consistency/index.html` |
 | `stitch2 type [filter] [--json]` | The type audit |
-| `stitch2 screens [name] [--status s] [--json]` | Versions, statuses and notes |
+| `stitch2 screens [name] [--status s] [--json] [--strict]` | Versions, statuses and notes; flags a screen whose current version is unclear |
+| `stitch2 approve <path or filter…>` | Approve variants (the user's decision); every earlier version is archived |
 | `stitch2 tokens` | Tokens from DESIGN.md |
 | `stitch2 compare [screen…]` | The live app against the approved screens (`app` in the config) |
 | `stitch2 elements <entry>` | Bundle your components (`stitch2/elements`) for the screens |

package/dist/approve.d.ts

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

package/dist/approve.js

@@ -0,0 +1,24 @@
+/**
+ * Approves screen variants, as the user does on the canvas: each becomes the current version of its screen on its
+ * device, and every earlier version there is archived. Agents run it when the user approves in words ("approve
+ * the v3 screens"), never on their own.
+ * Usage: stitch2 approve <path or filter…>   (a path under the design folder, or part of one: "connect/", "-v3")
+ */
+import { approve, listScreens } from './screens.js';
+const filters = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+if (!filters.length) {
+    console.error('stitch2 approve <path or filter…>: which variants? ("home/mobile-v3", "connect/", "-v3")');
+    process.exit(1);
+}
+const targets = listScreens().filter((s) => s.kind === 'screen' && s.status !== 'archived' && filters.some((f) => s.path.includes(f)));
+if (!targets.length) {
+    console.error(`No screen variant matches ${filters.join(', ')}.`);
+    process.exit(1);
+}
+// 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 note = archived.length ? `; archived ${archived.map((s) => s.version).join(', ')}` : '';
+    console.log(`approved ${t.screen} ${t.version} ${t.device}${note}`);
+}

package/dist/audit.js

@@ -36,6 +36,9 @@ export async function audit(opts) {
         if (closed && !closed.querySelector(':scope > summary')?.contains(el))
             return false;
         const r = el.getBoundingClientRect();
+        // Text kept for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
+        if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
+            return false;
         return r.width > 0 && r.height > 0;
     };
     const opacity = (el) => {

package/dist/cli.js

@@ -42,7 +42,8 @@ const COMMANDS = {
         'i18n-report.ts',
         '[filter] [--locale l] [--suggest] [--json]  Keys screens use that a locale lacks, and screen text with no key',
     ],
-    screens: ['list.ts', '[name] [--status s] [--json]  Screen versions, statuses and notes'],
+    screens: ['list.ts', '[name] [--status s] [--json] [--strict]  Screen versions, statuses, notes, and which version is current'],
+    approve: ['approve.ts', '<path or filter…>  Approve variants for the user; earlier versions are archived'],
     localize: ['assets.ts', '[filter]  Copy remote images a screen uses into its assets/ folder'],
     sandbox: [
         'sandbox.ts',

package/dist/list.js

@@ -1,9 +1,10 @@
 /**
  * Lists every screen version, variant by variant (mobile, 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.
- * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json]
+ * Ends with what makes the current version unclear (versionProblems); --strict fails on it.
+ * Usage: stitch2 screens [screen name] [--status approved|review|draft|archived] [--json] [--strict]
  */
-import { listScreens } from './screens.js';
+import { listScreens, 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');
@@ -17,3 +18,11 @@ if (args.includes('--json'))
 else
     for (const s of rows)
         console.log(`${s.screen.padEnd(20)} ${s.version.padEnd(8)} ${s.device.padEnd(8)} ${s.status.padEnd(9)} ${s.path}${s.note ? `\n${' '.repeat(39)}note: ${s.note}` : ''}`);
+const problems = versionProblems().filter((p) => !name || p.startsWith(`${name} `));
+if (problems.length && !args.includes('--json')) {
+    console.log(`\nWhich version is current is unclear (${problems.length}):`);
+    for (const p of problems)
+        console.log(`  ${p}`);
+}
+if (problems.length && args.includes('--strict'))
+    process.exit(1);

package/dist/screens.d.ts

@@ -32,3 +32,17 @@ export declare const meta: (html: string, name: string) => string | undefined;
 export declare function listScreens(): Screen[];
 /** 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;
+/**
+ * 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.
+ */
+export declare function approve(path: string): Screen[];
+/**
+ * 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.
+ */
+export declare function versionProblems(screens?: Screen[]): string[];
+/** A version's number: 3 for "v3"; NaN for one without (a Stitch export, a trial). */
+export declare const versionNumber: (s: Pick<Screen, 'version'>) => number;

package/dist/screens.js

@@ -83,3 +83,52 @@ export function writeMeta(path, values) {
     }
     writeFileSync(file, html);
 }
+/**
+ * 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.
+ */
+export function approve(path) {
+    const all = listScreens();
+    const target = all.find((s) => s.path === path);
+    if (!target || target.kind !== 'screen')
+        throw new Error(`not a screen: ${path}`);
+    writeMeta(path, { [tag('status')]: 'approved' });
+    const n = versionNumber(target);
+    const outdated = all.filter((s) => s.path !== path &&
+        s.kind === 'screen' &&
+        s.screen === target.screen &&
+        s.device === target.device &&
+        s.status !== 'archived' &&
+        (s.status === 'approved' || versionNumber(s) < n));
+    for (const s of outdated)
+        writeMeta(s.path, { [tag('status')]: 'archived' });
+    return outdated;
+}
+/**
+ * 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.
+ */
+export function versionProblems(screens = listScreens()) {
+    const out = [];
+    const groups = new Map();
+    for (const s of screens) {
+        if (s.kind !== 'screen' || s.status === 'archived')
+            continue;
+        const key = `${s.screen} ${s.device}`;
+        groups.set(key, [...(groups.get(key) ?? []), s]);
+    }
+    for (const [key, list] of groups) {
+        const approved = list.filter((s) => s.status === 'approved');
+        if (approved.length > 1)
+            out.push(`${key}: ${approved.map((s) => s.version).join(' and ')} are all approved; approve the current one again`);
+        const current = Math.max(...approved.map(versionNumber).filter((n) => !Number.isNaN(n)));
+        for (const s of list)
+            if (s.status !== 'approved' && versionNumber(s) < current)
+                out.push(`${key}: ${s.version} is still ${s.status} although v${current} is approved; archive it (${s.path})`);
+    }
+    return out.sort();
+}
+/** A version's number: 3 for "v3"; NaN for one without (a Stitch export, a trial). */
+export const versionNumber = (s) => Number(/^v(\d+)$/.exec(s.version)?.[1] ?? Number.NaN);

package/dist/serve.js

@@ -28,7 +28,7 @@ function inlineTailwind(html, file) {
         return `<style type="text/tailwindcss">${readFileSync(css, 'utf8').replace(/\s*\n\s*/g, ' ')}</style>`;
     });
 }
-import { listScreens, ROOT, STATUSES, tag, writeMeta } from './screens.js';
+import { listScreens, ROOT, STATUSES, tag, writeMeta, approve } from './screens.js';
 /**
  * The consistency report covers every screen that is not archived and the components; the app comparison covers
  * the approved screens. A report is stale once one of those files is newer than it (a status change counts: it
@@ -131,14 +131,9 @@ export function startServer(port) {
                     if (note !== undefined)
                         values[tag('note')] = note.trim() || undefined;
                     writeMeta(path, values);
-                    // One approved version per screen and device: approving archives the previous one.
-                    if (status === 'approved')
-                        for (const s of all)
-                            if (s.path !== path &&
-                                s.screen === target.screen &&
-                                s.device === target.device &&
-                                s.status === 'approved')
-                                writeMeta(s.path, { [tag('status')]: 'archived' });
+                    // One current version per screen and device: approving archives every earlier one (screens.ts).
+                    if (status === 'approved' && target.kind === 'screen')
+                        approve(path);
                     json(listScreens());
                 }
                 catch (e) {

package/dist/typecheck.js

@@ -30,6 +30,9 @@ export function collectText() {
         const r = el.getBoundingClientRect();
         if (!r.width || !r.height)
             continue;
+        // Text for screen readers only (Tailwind's sr-only: a 1px box, clipped away) is not drawn.
+        if (r.width <= 1 && r.height <= 1 && cs.position === 'absolute')
+            continue;
         let opacity = 1;
         for (let e = el; e; e = e.parentElement)
             opacity *= Number(getComputedStyle(e).opacity);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.15.3",
+  "version": "0.16.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

@@ -66,7 +66,8 @@ References, read before the first screen:
 6. **Look and critique.** View the render in `<design>/renders/` (crop the first screenful). Score it with the
    rubric in principles.md, fix what fails, repeat 5–6 at most three times.
 7. **Hand over.** Set the version's status to `review`, point the user to it on the canvas, and report what
-   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves.
+   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves; only then
+   does it go into the app (the approved version is the one current version: see screens.md).
 
 ## Commands
 
@@ -80,7 +81,8 @@ References, read before the first screen:
 | `i18n [filter] [--locale l] [--suggest]` | Message keys screens use that the source or a locale lacks, and text with no key (stitch2-i18n) |
 | `consistency [kind…]` | Every shared component cropped from every screen, next to the catalog's version |
 | `type [filter] [--json]` | Every text style a screen uses and the type level it matches |
-| `screens [name] [--status s] [--json]` | Every version with its status and the user's note |
+| `screens [name] [--status s] [--json] [--strict]` | Every version with its status and the user's note, and anything that makes the current version unclear |
+| `approve <path or filter…>` | Approves variants for the user (only on their word); every earlier version of the screen on that device is archived |
 | `compare [screen…]` | The live app against the approved versions: missing or extra components, order, looks; a side-by-side report |
 | `elements <entry>` | Bundles the app's components, turned into elements with `stitch2/elements`, for the screens |
 | `tokens` | `tokens.css` (colours, `.type-*` classes) and `tailwind.tokens.js` from DESIGN.md |

package/skills/stitch2/references/screens.md

@@ -35,8 +35,13 @@ and build on it. Meta tag names below use the project's prefix (`<p>`, from `sti
 |---|---|---|
 | `draft` | Work in progress | The agent, while working |
 | `review` | Finished, waiting for the user ("Needs review") | The agent, when done |
-| `approved` | The reference: build on it, match it, implement it | The user only |
-| `archived` | History: superseded or rejected; hidden on the canvas | The user; approving a variant archives the previously approved variant of the same device |
+| `approved` | The current version: the reference to build on and match, and the only one the app implements | The user only (on the canvas, or in words: then the agent runs `stitch2 approve`) |
+| `archived` | Outdated: superseded or rejected; hidden on the canvas | Approval: approving a variant archives every earlier version of that screen on that device, whatever its status |
+
+**One current version.** For each screen and device there is at most one approved variant, and it is what the app
+shows. Approving one archives every earlier version there (approved, in review or a draft), so nothing older can be
+mistaken for the current one; a later version, a newer proposal, keeps its status. `stitch2 screens` ends with
+anything that breaks this (two approved, an older version still in review); `--strict` fails on it.
 
 The canvas shows each version with its variants side by side under one heading, and one status for the version:
 needs review while any variant does. **Approve version** approves every variant in review at once; a single
@@ -47,8 +52,12 @@ variant can still be approved, archived or noted on its own.
 1. Before designing, run `stitch2 screens` (a name or `--status approved` narrows it) and open the approved
    versions of the screens next to yours.
 2. A note is the user's feedback: address every point in your next version or edit, and say how.
-3. Never set `approved` yourself; never build on an archived version unless asked.
-4. Only approved versions get implemented in the product.
+3. Never approve on your own and never build on an archived version unless asked. When the user approves in words
+   ("approve the v3 screens"), run `stitch2 approve <path or filter…>` rather than editing status tags: it archives the
+   earlier versions as the canvas does.
+4. **Implement only approved versions.** A version in review or a draft is not built in the app, not even partly. If
+   the user asks to implement one that is not approved yet, that request is their approval: run `stitch2 approve` on it
+   first and say so. If the app needs something no approved version shows, design it and hand it over first.
 5. When the user pastes a reference copied from the canvas, such as `home mobile v2
    (design/screens/home/mobile-v2.html)`, open that file: it names exactly the version they mean.
 6. A reference to an element adds its source line, its tag and its text: `home mobile v1
@@ -59,7 +68,7 @@ variant can still be approved, archived or noted on its own.
 
 ## Implementing an approved version
 
-Build the screen in the app from the same components the screens use, in the version's order, with the app's
+Check first with `stitch2 screens <screen>` that the version is approved and is the only approved one on its device. Build the screen in the app from the same components the screens use, in the version's order, with the app's
 own data, strings and behaviour; keep the app's tests passing. Then run `stitch2 compare <screen>` with the app
 running: fix every `missing` component and look at the side-by-side report. `extra` and `order` warnings are
 fine when the app needs them (a desktop-only control, a frame drawn by layout); say so when you hand over. When

package/skills/stitch2-app-sync/SKILL.md

@@ -19,7 +19,10 @@ a component rebuilt by hand. The checks can only judge what the canvas draws, so
    approved screen if the change is visible there; a catalog entry for a new variant or state), and run
    `stitch2 check <screens> --strict`. Look at the screens yourself: the check finds overlaps and overflow, not
    ugliness.
-3. **Approval**: the user approves the new versions (or the catalog change) as for any design.
+3. **Approval**: the user approves the new versions (or the catalog change) as for any design. Nothing goes into
+   the app before this: a version in review is not implemented, not even partly. When the user asks to implement
+   one in review, run `stitch2 approve` on it first; that archives the earlier versions, so the approved one is the
+   single current version and the app matches it.
 4. **App**: the app picks the component up; wire it, then run `stitch2 compare <screen>`.
 
 Fixing a bug found in the app follows the same path: reproduce it on the canvas (a screen or catalog state that
@@ -62,7 +65,8 @@ Read the findings as:
 
 ## Before you call it done
 
-1. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
-2. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
-3. The user has seen the canvas versions of anything that changed how a component looks.
+1. Every screen you implemented is approved, and `stitch2 screens --strict` passes: one current version each.
+2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
+3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
+4. The user has seen the canvas versions of anything that changed how a component looks.