stitch2 0.22.12 → 0.24.0

package/README.md

@@ -42,6 +42,8 @@ file that already exists. From there the agent spends its effort on the design.
   A width switch (`W`) shows every screen at the narrowest or widest window its layout covers.
   With languages configured, a Language switch (`L`) shows every screen in one of them, and the Languages page
   shows a screen side by side in each.
+  With app states configured (`modes`: signed in or out, a plan, a role), a dropdown for each (`M` cycles the first)
+  shows every screen in one of them, live pages and pictures alike, or as drawn.
   Pick mode (`P`) highlights any element of a screen and copies a reference with its source line, such as
   `home mobile v1 (design/screens/home/mobile-v1.html:36) <gg-button> “Start Push”`; Shift-click collects
   several to copy at once or add to the version's note.
@@ -57,7 +59,7 @@ file that already exists. From there the agent spends its effort on the design.
   icon-only controls without a name, more than five bottom-navigation destinations and controls without visible
   focus. Motion: transitions whose length isn't one of DESIGN.md's motion tokens, and anything that still moves
   with reduced motion on. Each screen is also run in long and right-to-left
-  pseudo-languages and your locales (see below).
+  pseudo-languages and your locales (see below), and, with `modes`, in each app state it is not drawn in.
 - **States** (from `stitch2 check` on the component catalog): every control at rest, hovered, focused and
   pressed, forced through Chromium so the components need nothing extra, side by side on one sheet; with
   warnings for a control that gives no feedback and text that loses contrast in a state.
@@ -260,7 +262,7 @@ layout first, then a shorter natural word, never a smaller type size.
 | `stitch2 init --name N --primary #hex [options]` | Writes a complete DESIGN.md from a few choices |
 | `stitch2 extract <url or file…>` | Writes a DESIGN.md measured from an existing site or screens |
 | `stitch2 canvas` | The canvas at http://localhost:4400 (`PORT` and `HOST` to change) |
-| `stitch2 check [filter] [--shots] [--strict] [--locales l,…]` | All checks, in every theme and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`…) |
+| `stitch2 check [filter] [--shots] [--strict] [--locales l,…]` | All checks, in every theme, app state and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`, `--auth-user.png`…) |
 | `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 |

package/config.schema.json

@@ -77,6 +77,31 @@
       "items": { "type": "string" },
       "description": "The themes every screen must work in, by their data-theme value. Defaults to DESIGN.md's: dark (the plain colours), plus light when it has light-* colours. The canvas switches between them and check runs in each."
     },
+    "modes": {
+      "type": "array",
+      "description": "App states every screen can be shown in, picked from the canvas sidebar: signed in or out, a plan, a role. The pick is an attribute on each screen's <html>, so the screens' own CSS and scripts answer to it. The dropdown also offers the screens as drawn, which leaves each one as its file has it. stitch2 check also runs each screen in every value its file does not already have, one mode at a time, and tags what only shows there.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "values"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "The id: lowercase letters, digits and hyphens. The canvas remembers the pick under it." },
+          "label": { "type": "string", "description": "Shown before each value in the dropdown. Defaults to the name, capitalized." },
+          "attribute": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "The attribute on the screen's <html> that carries the value. Defaults to data-<name>." },
+          "values": {
+            "type": "array",
+            "minItems": 1,
+            "description": "What the canvas can show every screen as: a value, or a value with its label.",
+            "items": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "object", "additionalProperties": false, "required": ["value"], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } }
+              ]
+            }
+          }
+        }
+      }
+    },
     "i18n": {
       "type": "object",
       "additionalProperties": false,

package/dist/canvas.html

@@ -44,6 +44,7 @@
   /* Theme and language: native dropdowns drawn like the versions and variants ones. */
   .pick { appearance: none; background: var(--bg) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='M1 1.5l5 5 5-5' fill='none' stroke='%23a1a1aa' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") no-repeat right 10px center / 12px 8px; border: 1px solid var(--edge); border-radius: 8px; color: var(--text); cursor: pointer; font: inherit; padding: 5px 30px 5px 8px; width: 100%; }
   .pick[hidden] { display: none; }
+  #modeFilters { display: contents; }
   #tree { flex: 1; overflow: auto; padding: 6px 8px 16px; }
   #tree h4 { color: var(--faint); font-size: 11px; letter-spacing: .06em; margin: 14px 6px 6px; text-transform: uppercase; }
   .item { align-items: center; background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; display: flex; gap: 8px; padding: 6px 8px; text-align: left; width: 100%; }
@@ -142,6 +143,7 @@
     <details id="versionFilter" class="multi" hidden title="Show only the versions you pick (several at once), or all of them"><summary>All versions</summary><div class="menu"></div></details>
     <details id="variantFilter" class="multi" hidden title="Show only the variants you pick: mobile, tablet, desktop (several at once), or all of them"><summary>All variants</summary><div class="menu"></div></details>
     <select id="themeFilter" class="pick" hidden title="Show every screen in this theme (T)" aria-label="Theme"></select>
+    <div id="modeFilters"></div>
     <select id="widthFilter" class="pick" title="Show every screen at the narrowest or widest window its variant covers, or at one breakpoint (W)" aria-label="Width"></select>
     <select id="langFilter" class="pick" title="Show every screen in this language (L)" aria-label="Language"></select>
   </header>
@@ -179,13 +181,20 @@ let designDir = 'design'
 let THEMES = ['dark']
 let theme = localStorage.getItem('stitch2-theme') ?? 'dark'
 const themed = () => THEMES.length > 1
+// Modes: app states (signed in or out, a plan, a role) every screen can be shown in. Each sets an attribute on the
+// screen's document, like the theme; "As drawn" leaves a screen as its file has it. Pictures of the screens that are
+// not live ask the server for the same states (?mode=name:value).
+let MODES = []
+const modePick = {} // mode name -> picked value, '' for as drawn
+const modeValueLabel = (m, v) => (v ? (m.values.find((x) => x.value === v)?.label ?? v) : 'As drawn')
+const modeNotes = () => MODES.filter((m) => modePick[m.name]).map((m) => `${m.label}: ${modeValueLabel(m, modePick[m.name])}`)
 // Languages: screens reload in the one picked (?lang=…); the source language shows them as written.
 let LANGS = ['en']
 let SOURCE = 'en'
 let lang = localStorage.getItem('stitch2-lang') ?? 'en'
 const langQuery = () => (lang === SOURCE ? '' : `&lang=${encodeURIComponent(lang)}`)
 const themeNote = () =>
-  [themed() && theme !== THEMES[0] ? `in the ${theme} theme` : '', lang !== SOURCE ? `in ${lang}` : '']
+  [themed() && theme !== THEMES[0] ? `in the ${theme} theme` : '', lang !== SOURCE ? `in ${lang}` : '', ...modeNotes()]
     .filter(Boolean)
     .map((s) => ' ' + s)
     .join(',')
@@ -245,6 +254,33 @@ function widthOptions() {
   if (!widthModes().includes(widthMode)) widthMode = 'drawn'
   wsel.value = widthMode
 }
+// The document's own value is kept the first time, so "As drawn" puts it back.
+const authored = new WeakMap()
+function applyModes(f) {
+  if (!f.iframe) return
+  let root
+  try { root = f.iframe.contentDocument.documentElement } catch { return }
+  if (!root) return
+  const was = authored.get(root) ?? authored.set(root, {}).get(root)
+  for (const m of MODES) {
+    if (!(m.attribute in was)) was[m.attribute] = root.getAttribute(m.attribute)
+    const value = modePick[m.name] || was[m.attribute]
+    if (value == null) root.removeAttribute(m.attribute)
+    else root.setAttribute(m.attribute, value)
+  }
+}
+function setMode(name, value) {
+  const m = MODES.find((x) => x.name === name)
+  if (!m) return
+  modePick[name] = m.values.some((x) => x.value === value) ? value : ''
+  localStorage.setItem(`stitch2-mode-${name}`, modePick[name])
+  const sel = document.querySelector(`#modeFilters [data-mode="${name}"]`)
+  if (sel) sel.value = modePick[name]
+  for (const f of frames.values()) applyModes(f)
+  if (selected) inspector(selected)
+  summary()
+  scheduleSync()
+}
 function applyTheme(f) {
   if (!themed() || !f.iframe) return
   try { f.iframe.contentDocument.documentElement.dataset.theme = theme } catch {}
@@ -640,6 +676,7 @@ function shotUrl(s) {
   const q = new URLSearchParams({ path: s.path, width: String(s.width), m: String(Math.round(s.mtime)), r: String(shotRev) })
   if (themed()) q.set('theme', theme)
   if (lang !== SOURCE) q.set('lang', lang)
+  for (const m of MODES) if (modePick[m.name]) q.append('mode', `${m.name}:${modePick[m.name]}`)
   return `/api/shot?${q}`
 }
 const pinned = (f) => f === selected || f.el.classList.contains('live') || picked.some((p) => p.f === f)
@@ -670,6 +707,7 @@ function mount(f) {
     void (async () => {
       if (!(await waitForStyles()) || f.iframe !== iframe) return
       applyTheme(f)
+      applyModes(f)
       measure(f)
       clearTimeout(f.reveal)
       // The picture stays until the complete, styled page has been measured.
@@ -882,7 +920,10 @@ function inspector(f) {
     li.querySelector('code').textContent = i.selector
     li.onclick = () => {
       const r = rangeOf(s)
-      if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : i.width === r[1] ? 'wide' : `at:${i.width}`); setTimeout(() => locate(f, i.selector), 900) }
+      // An issue found in another app state: show every screen in it, then find the element.
+      const [mode, value] = i.mode ? i.mode.split(':') : []
+      if (mode && modePick[mode] !== value) { setMode(mode, value); setTimeout(() => locate(f, i.selector), 600) }
+      else if (i.width && r && i.width !== s.width) { setWidth(i.width === r[0] ? 'narrow' : i.width === r[1] ? 'wide' : `at:${i.width}`); setTimeout(() => locate(f, i.selector), 900) }
       else locate(f, i.selector)
     }
     ul.append(li)
@@ -1176,6 +1217,7 @@ addEventListener('keydown', (e) => {
   if (e.key === 'Escape') { closeDoc(); select(null) }
   if (e.key === 'f' || e.key === 'F') fit()
   if ((e.key === 't' || e.key === 'T') && themed()) setTheme(THEMES[(THEMES.indexOf(theme) + 1) % THEMES.length])
+  if ((e.key === 'm' || e.key === 'M') && MODES.length) { const m = MODES[0], all = ['', ...m.values.map((v) => v.value)]; setMode(m.name, all[(all.indexOf(modePick[m.name]) + 1) % all.length]) }
   if (e.key === 'l' || e.key === 'L') setLang(LANGS[(LANGS.indexOf(lang) + 1) % LANGS.length])
   if (e.key === 'w' || e.key === 'W') { const m = widthModes(); setWidth(m[(m.indexOf(widthMode) + 1) % m.length]) }
   if (e.key === '0') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, 1)
@@ -1214,6 +1256,20 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   pick.innerHTML = THEMES.map((t) => `<option value="${t}">${t[0].toUpperCase()}${t.slice(1)} theme</option>`).join('')
   pick.onchange = () => setTheme(pick.value)
   setTheme(theme)
+  MODES = c.modes ?? []
+  MODES.forEach((m, i) => {
+    const stored = localStorage.getItem(`stitch2-mode-${m.name}`) ?? ''
+    modePick[m.name] = m.values.some((v) => v.value === stored) ? stored : ''
+    const sel = document.createElement('select')
+    sel.className = 'pick'
+    sel.dataset.mode = m.name
+    sel.setAttribute('aria-label', m.label)
+    sel.title = `Show every screen with ${m.label.toLowerCase()} set to one of these, or as drawn${i === 0 ? ' (M)' : ''}`
+    for (const v of ['', ...m.values.map((x) => x.value)]) sel.add(new Option(`${m.label}: ${modeValueLabel(m, v)}`, v))
+    sel.value = modePick[m.name]
+    sel.onchange = () => setMode(m.name, sel.value)
+    document.getElementById('modeFilters').append(sel)
+  })
   WIDTHS = c.widths ?? {}
   BREAKPOINTS = c.breakpoints ?? {}
   const wsel = document.getElementById('widthFilter')

package/dist/check.js

@@ -5,13 +5,16 @@
  * the canvas shows as badges.
  * Every screen is checked in its own theme, then again in each other theme DESIGN.md defines (designThemes):
  * colours change there, so contrast is checked again, tagged with the theme.
+ * Then in each app state (config modes), one mode at a time and in the screen's own theme: a screen is checked with
+ * every value its own file does not already have, and what only shows there (a bar that overflows signed in, a control
+ * that crowds another) is tagged with the state.
  * Then again in each check language (i18n.ts: the pseudo-languages and the config's): layout problems that
  * show only there (a label running into its neighbour, text cut off, a control drawn backwards right to left),
  * and keys a locale has no translation for, tagged with the locale. Last, each variant at both ends of the widths
  * it covers (config widths: mobile 360–599, desktop 1024–1920 by default) and at every breakpoint inside them
  * (config breakpoints, Tailwind's by default), tagged with the width.
  * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
- *   --shots   also save page-tall renders to design/renders/ (one per theme, language and width)
+ *   --shots   also save page-tall renders to design/renders/ (one per theme, app state, language and width)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
  * Screens run four at a time; reruns only visit screens that changed since design/checks.json (or
  * everything DESIGN.md, the tokens, the components or the catalog changed since).
@@ -22,7 +25,7 @@ import { fileURLToPath } from 'node:url';
 import { chromium } from '@playwright/test';
 import { fingerprintPaths } from './cache.js';
 import { colourIssues } from './colours.js';
-import { CONFIG_FILE, checkWidths, config } from './config.js';
+import { CONFIG_FILE, checkWidths, config, modes } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
 import { designThemes, motionDurations, typeLevels } from './design-md.js';
 import { checkLocales } from './i18n.js';
@@ -40,6 +43,7 @@ const filters = args.filter((a, i) => !a.startsWith('--') && (localesFlag < 0 ||
 const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
 const levels = typeLevels();
 const themes = designThemes();
+const appModes = modes();
 const collect = collectOptions();
 /** What the layout audit needs: the comfortable tap size and DESIGN.md's motion durations. */
 const auditOpts = { comfortable: config.comfortableTarget, durations: (() => { try {
@@ -134,6 +138,23 @@ const checkOne = async (s, worker) => {
         }
         if (themes.length > 1)
             await setTheme(page, base);
+        // The app states: each value the screen is not drawn in, one mode at a time, then the screen's own value again.
+        for (const mode of appModes) {
+            const drawn = await page.evaluate((attribute) => document.documentElement.getAttribute(attribute), mode.attribute);
+            for (const value of mode.values.filter((v) => v.value !== drawn)) {
+                await setAttribute(page, mode.attribute, value.value);
+                for (const i of await page.evaluate(audit, auditOpts)) {
+                    const key = `${i.type} ${i.selector}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    themed.push({ ...i, ...(i.type === 'contrast' ? { theme: base } : {}), mode: `${mode.name}:${value.value}`, message: `${value.label}: ${i.message}` });
+                }
+                if (shots)
+                    await shoot(page, s, undefined, undefined, `${mode.name}-${value.value}`);
+            }
+            await setAttribute(page, mode.attribute, drawn);
+        }
         const typed = typeIssues(levels, await page.evaluate(collectText));
         if (shots)
             await shoot(page, s);
@@ -251,7 +272,16 @@ async function setTheme(page, theme) {
     }, theme);
     await page.waitForTimeout(150);
 }
-/** A page-tall render; renders in another theme or language than the screen's own get a --<theme> suffix. */
+async function setAttribute(page, attribute, value) {
+    await page.evaluate(([name, to]) => {
+        if (to === null)
+            document.documentElement.removeAttribute(name);
+        else
+            document.documentElement.setAttribute(name, to);
+    }, [attribute, value]);
+    await page.waitForTimeout(150);
+}
+/** A page-tall render; renders in another theme, app state or language than the screen's own get a --<name> suffix. */
 async function shoot(page, s, theme, locale, at) {
     const height = await page.evaluate(() => document.documentElement.scrollHeight);
     await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, MAX_RENDER_HEIGHT)) });

package/dist/config.d.ts

@@ -1,3 +1,20 @@
+/**
+ * An app state every screen can be shown in, picked from the canvas sidebar: signed in or out, a plan, a role. The pick
+ * is an attribute on each screen's <html> (data-auth="user"), so the screens' own CSS and scripts answer to it.
+ */
+export interface ModeConfig {
+    /** The id: lowercase letters, digits and hyphens. The canvas remembers the pick under it. */
+    name: string;
+    /** Shown before each value in the dropdown; defaults to the name, capitalized. */
+    label?: string;
+    /** The attribute on the screen's <html> that carries the value; defaults to data-<name>. */
+    attribute?: string;
+    /** What the canvas can show every screen as: a value, or a value with its label. "As drawn" is always offered too. */
+    values: (string | {
+        value: string;
+        label?: string;
+    })[];
+}
 export interface LabConfig {
     /** Shown on the canvas. */
     name: string;
@@ -41,6 +58,12 @@ export interface LabConfig {
     skills: string[];
     /** Paths under designDir a sandbox leaves out besides screens (notes that would give the trial away). */
     sandboxExclude?: string[];
+    /**
+     * App states shown across all screens (see ModeConfig). The canvas has a dropdown for each, with the screens as drawn
+     * first; picking a value sets its attribute on every screen, live ones and the pictures of the rest. stitch2 check also
+     * runs each screen in every value its file does not already have, one mode at a time.
+     */
+    modes?: ModeConfig[];
     /** The live app, for stitch2 compare (see compare.ts): its URL, a sign-in script and a route per screen. */
     app?: {
         url: string;
@@ -91,5 +114,21 @@ export declare const breakpoints: () => Record<string, number>;
  * rule starts (each one is the narrowest window of its layout, where things are most likely to break).
  */
 export declare function checkWidths(device: string): number[];
+export interface Mode {
+    name: string;
+    label: string;
+    attribute: string;
+    values: {
+        value: string;
+        label: string;
+    }[];
+}
+/** The configured modes, checked: a name or attribute that isn't plain, a repeat, or a mode without values is left out. */
+export declare function modes(): Mode[];
+/**
+ * The attributes a request asks for, from its "name:value" pairs; a pair that isn't a configured mode and value is
+ * ignored, so an address can only set what the config offers.
+ */
+export declare function modeAttributes(pairs: string[]): Record<string, string>;
 /** The design folder, with a trailing slash. */
 export declare const ROOT: string;

package/dist/config.js

@@ -51,5 +51,43 @@ export function checkWidths(device) {
     const inside = Object.values(breakpoints()).filter((b) => b > range[0] && b < range[1]);
     return [...new Set([range[0], ...inside, range[1]])].sort((a, b) => a - b);
 }
+const MODE_NAME = /^[a-z][a-z0-9-]*$/;
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** The configured modes, checked: a name or attribute that isn't plain, a repeat, or a mode without values is left out. */
+export function modes() {
+    const out = [];
+    for (const m of Array.isArray(config.modes) ? config.modes : []) {
+        if (typeof m?.name !== 'string' || !MODE_NAME.test(m.name) || out.some((o) => o.name === m.name))
+            continue;
+        const attribute = m.attribute ?? `data-${m.name}`;
+        if (!MODE_NAME.test(attribute))
+            continue;
+        const values = [];
+        for (const v of Array.isArray(m.values) ? m.values : []) {
+            const value = typeof v === 'string' ? v : v?.value;
+            if (typeof value !== 'string' || !value || /[\s"'<>=&:]/.test(value) || values.some((x) => x.value === value))
+                continue;
+            values.push({ value, label: (typeof v === 'object' && v.label) || capitalize(value) });
+        }
+        if (values.length)
+            out.push({ name: m.name, label: m.label ?? capitalize(m.name), attribute, values });
+    }
+    return out;
+}
+/**
+ * The attributes a request asks for, from its "name:value" pairs; a pair that isn't a configured mode and value is
+ * ignored, so an address can only set what the config offers.
+ */
+export function modeAttributes(pairs) {
+    const picked = {};
+    for (const pair of pairs) {
+        const at = pair.indexOf(':');
+        const mode = modes().find((m) => m.name === pair.slice(0, at));
+        const value = pair.slice(at + 1);
+        if (at > 0 && mode?.values.some((v) => v.value === value))
+            picked[mode.attribute] = value;
+    }
+    return picked;
+}
 /** The design folder, with a trailing slash. */
 export const ROOT = join(resolve(BASE, config.designDir), '/');

package/dist/serve.js

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync, watch } from 'node:fs'
 import { createServer } from 'node:http';
 import { dirname, extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { breakpoints, CONFIG_FILE, checkWidths, config, widthRanges } from './config.js';
+import { breakpoints, CONFIG_FILE, checkWidths, config, modeAttributes, modes, widthRanges } from './config.js';
 import { designThemes } from './design-md.js';
 import { allLocales, localeScript, sourceLocale } from './i18n.js';
 import { designPage } from './design-page.js';
@@ -156,7 +156,7 @@ export function startServer(port) {
             return;
         }
         if (url.pathname === '/api/config')
-            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale(), widths: widthRanges(), breakpoints: breakpoints(), checkWidths: Object.fromEntries(Object.keys(widthRanges()).map((d) => [d, checkWidths(d)])) });
+            return json({ ...config, modes: modes(), themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale(), widths: widthRanges(), breakpoints: breakpoints(), checkWidths: Object.fromEntries(Object.keys(widthRanges()).map((d) => [d, checkWidths(d)])) });
         if (url.pathname === '/api/screens')
             return json(listScreens());
         if (url.pathname === '/api/reports')
@@ -169,6 +169,7 @@ export function startServer(port) {
                 width: Math.min(4000, Math.max(200, Number(q.get('width')) || 390)),
                 theme: q.get('theme') || undefined,
                 lang: q.get('lang') || undefined,
+                modes: modeAttributes(q.getAll('mode')),
             });
             if (!job) {
                 res.writeHead(404, { 'content-type': 'text/plain' });

package/dist/shots.d.ts

@@ -3,6 +3,8 @@ export interface ShotRequest {
     width: number;
     theme?: string;
     lang?: string;
+    /** Attributes set on the page's <html> before the picture: the app states picked in the canvas (config modes). */
+    modes?: Record<string, string>;
 }
 /** The server's file watcher calls this: the next picture looks at the shared files again. */
 export declare function sharedChanged(): void;

package/dist/shots.js

@@ -3,7 +3,7 @@
  * components), so a canvas with a hundred of them stalls the browser; the canvas keeps only the screens in view live
  * and draws the rest from these. One headless Chromium renders them, three at a time, and they are kept on disk
  * (os.tmpdir()/stitch2-shots), keyed by everything that changes the picture: the screen file, the files screens
- * share (tokens, components, stylesheets), the theme, the language and its messages, and the width.
+ * share (tokens, components, stylesheets), the theme, the modes, the language and its messages, and the width.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
@@ -53,6 +53,7 @@ function keyOf(r) {
         statSync(file).mtimeMs,
         sharedStamp(),
         r.theme ?? '',
+        JSON.stringify(Object.entries(r.modes ?? {}).sort(([a], [b]) => a.localeCompare(b))),
         r.lang ?? '',
         messages && existsSync(messages) ? statSync(messages).mtimeMs : '',
         r.width,
@@ -98,6 +99,10 @@ export function shot(base, r) {
             await page.goto(`${base}/${r.path}?${query}`, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => { });
             if (r.theme)
                 await page.evaluate((t) => { document.documentElement.dataset.theme = t; }, r.theme);
+            const attributes = Object.entries(r.modes ?? {});
+            if (attributes.length)
+                await page.evaluate((list) => { for (const [name, value] of list)
+                    document.documentElement.setAttribute(name, value); }, attributes);
             await page.evaluate(() => document.fonts.ready);
             // Tailwind's browser build and the components settle after load.
             await page.waitForTimeout(400);

package/dist/typecheck.d.ts

@@ -15,6 +15,8 @@ export interface Issue {
     locale?: string;
     /** Set when the issue shows only at another window width: the edge of its variant's range (config widths). */
     width?: number;
+    /** Set when the issue shows only in another app state (config modes): "name:value", as the canvas sidebar names it. */
+    mode?: string;
 }
 export interface TextItem {
     selector: string;

package/package.json

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

@@ -77,6 +77,8 @@ References, read before the first screen:
    An issue tagged with a width ("at 1024px: …") breaks at an edge of the windows the variant covers: fix it with a
    responsive rule in the screen, or a new variant when the layout's structure has to change (screens.md, Widths).
    Widths include the breakpoints inside the range; `narrow-layout` is a phone column left in a wide window.
+   An issue tagged with an app state ("Signed in: …"; `modes` in the config, screens.md) shows only in that state: fix it in
+   the screen's rules for that state, and look at its render (`--auth-user.png`). Clicking it on the canvas shows the state.
    Overlap checks compare the drawn fragments of wrapped inline controls, not the empty corners of their
    bounding boxes. For fixed bars, the browser's paint order decides coverage: a menu painted in front of a
    header is not hidden by it. Native modal dialogs and ARIA modals limit coverage and control comparisons
@@ -127,7 +129,7 @@ References, read before the first screen:
 |---|---|
 | `setup [--name N --primary #hex] [options]` | Sets a project up in one step; keeps every file that exists |
 | `canvas` | The canvas at http://localhost:4400: screens and versions, DESIGN.md, the consistency report, approval and notes |
-| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme and check language, and at both ends of each variant's widths; `--shots` saves renders |
+| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme, app state and check language, and at both ends of each variant's widths; `--shots` saves renders |
 | `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 |

package/skills/stitch2/references/screens.md

@@ -171,13 +171,33 @@ doesn't cover it is drawn at its nearest edge and faded, because the app shows a
 - A desktop screen is a layout for its range, not a stretched phone: a side navigation instead of the bar,
   list-detail with both panes, extra columns for feeds.
 
+## App states
+
+When the product looks different signed in or out, on another plan or for another role, do not draw a copy of each
+screen per state. Draw it once, let its CSS and scripts answer to an attribute on `<html>`, and list the states as
+`modes` in `stitch2.config.json`:
+
+```json
+"modes": [
+  { "name": "auth", "label": "Account", "values": [{ "value": "guest", "label": "Guest" }, { "value": "user", "label": "Signed in" }] }
+]
+```
+
+The canvas sidebar then has a dropdown for each mode. A value sets the attribute (`data-auth="user"`; `attribute`
+names another) on every screen, live frames and the pictures of the rest, and "As drawn" puts each screen back to what
+its file says. `m` cycles the first mode. A screen is still written for the state it shows (a signed-in account page has
+`data-auth="user"` in its file); modes show the other states of the same screen. `stitch2 check` also runs each screen in every
+value its own file does not have, one mode at a time (modes are not combined), and tags what only shows there with the
+state ("Signed in: …"); clicking such an issue on the canvas shows that state. With `--shots` each state is rendered too
+(`<screen>--auth-user.png`): look at it before hand-over.
+
 ## The canvas
 
 `stitch2 canvas` → http://localhost:4400. The sidebar lists DESIGN.md (drawn as tokens and rules), Components
 (the catalog for the variants the filter shows; a click steps through them), the consistency report and app
 comparison (each with when it last ran, or how many covered screens changed since), Languages, and every screen
-with its versions. Filters: status (active, approved, needs review, all), versions, variants, theme, width and
-language. The reports and Languages follow the filters too: they show only the screens the canvas shows. Selecting a version opens the inspector: status, note, checks, and
+with its versions. Filters: status (active, approved, needs review, all), versions, variants, theme, width,
+language and each app state (`modes`). The reports and Languages follow the filters too: they show only the screens the canvas shows. Selecting a version opens the inspector: status, note, checks, and
 Copy for its reference. Pick mode (`p`) highlights the element under the pointer; a click copies its reference,
 Shift-click collects several (Copy all, Add to note). Keys: `/` search, `j`/`k` next and previous, `a` approve,
-`p` pick, `f` fit, `0` actual size, double-click to use a frame, `Esc` to leave.
+`p` pick, `f` fit, `m` next app state, `0` actual size, double-click to use a frame, `Esc` to leave.