stitch2 0.22.12 → 0.23.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.

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.",
+      "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.
@@ -1176,6 +1214,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 +1253,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/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,11 @@ 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.
+     */
+    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 +113,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/package.json

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

@@ -171,13 +171,31 @@ 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` runs on the screens as
+drawn, not in each state, so open the other states on the canvas and look at them 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.