kaloko 0.9.0 → 0.11.0

package/src/cli.mjs

@@ -9,7 +9,7 @@ import { loadConfig, environment, urlFor, baseUrl, CONFIG_FILE, LEGACY_CONFIG_FI
 import { loadScenario, parseScenario, validateScenario, scenarioWarnings } from './lib/scenario.mjs'
 import { createRun, resolveRun, readCaptures, listRuns } from './lib/run.mjs'
 import { gitMeta, projectAndIssue, appVersion } from './lib/git.mjs'
-import { startBrowser, stopBrowser, connectBrowser, currentPage, launchEphemeral, consoleLog, allStates, resetSession, acquireWalkLock } from './lib/browser.mjs'
+import { startBrowser, stopBrowser, connectBrowser, currentPage, launchEphemeral, launchWithRetry, consoleLog, allStates, resetSession, acquireWalkLock } from './lib/browser.mjs'
 import { captureStep, captureCrop, captureOptions, acceptDialogs } from './lib/capture.mjs'
 import { observeConsole } from './lib/console.mjs'
 import { mailClient, waitForMessage, recipient, readMessageFile } from './lib/mail.mjs'
@@ -50,6 +50,7 @@ import { walkDesign, syncDesign, publishVersion, previewNotes, historyCmd, refer
 import { screensCmd } from './lib/screens-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
+import { cleanAssetOrigins } from './lib/design-origins.mjs'
 import { exportDesign } from './lib/design-export.mjs'
 import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
 import { captureApp } from './lib/apps/capture.mjs'
@@ -57,7 +58,7 @@ import { readTree, flatten } from './lib/apps/tree.mjs'
 import { recordSettings, recordingSession, parseRecord, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
 import { nativeSession } from './lib/apps/recording-native.mjs'
 import { videoCmd } from './lib/video-cli.mjs'
-import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, BROWSERS } from './lib/dimensions.mjs'
+import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, stateKeys, nodeStates, BROWSERS } from './lib/dimensions.mjs'
 import { startScope, scopeKeys, dimensionLine, baseViewports, engineKeys, appDeviceGroups } from './lib/walk-dimensions.mjs'
 import { deviceConfig, prepareAndroid, readyAndroid, finishAndroid, prepareSimulator, applyAppAppearance } from './lib/apps/devices.mjs'
 import { attachAndroidWebView } from './lib/apps/webview.mjs'
@@ -113,6 +114,9 @@ Run
                                     More dimensions: every step is captured in each combination (keys like
                                     mobile.webkit.dark); default from the scenario, then walk: in the config
        [--devices pixel-8-api-34,iphone-15-ios-18]   App scenarios: the emulators, simulators or devices to walk on
+       [--states empty,error]       Only these step states (states: on a step; keys like mobile.state-empty)
+       [--token-modes brand-a,brand-b | --token-modes none]
+                                    Design environments: the token modes to render (default every mode of the set)
   browser start|stop|status [--env e] [--headed]   One shared browser per environment (port = browser.port + index)
                                     Shared Chromium with CDP (agents, scripts and people drive it)
   browser install [--with-deps] [--browsers chromium,webkit,firefox]
@@ -121,8 +125,8 @@ Run
   devices [--json]                  Device presets for viewports: (phones, foldables, tablets, laptop, desktop, TV)
   open --step <id> [--locale l]     Navigate the current page to the step URL
   session reset                     New visitor: clear cookies and storage in the shared browser
-  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b]
-                                    Capture the current page for a step in all viewports
+  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b] [--state <name>]
+                                    Capture the current page for a step in all viewports (--state: as that step state)
   capture --step <id> --crop <css> [--title <text>]
                                     Attach an element screenshot to a step
   capture --step <id> --image <shot.png> [--tree <dump.xml|json> | --ocr] [--platform android|ios|desktop]
@@ -307,9 +311,11 @@ Design (environments with kind: design; live HTML steps in a folder)
   sync [--pull|--push] [--branch b] [--mine a,b|--theirs a,b] [--no-lint]
                                     Exchange revisions with the shared draft; only changed steps and missing files travel
                                     Lints the folder first: errors (things that break on the live step) stop the push
-  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--json]
+  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]
                                     Check the folder against the portable HTML rules (relative URLs, no CDNs, no storage,
-                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings
+                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings.
+                                    Fonts, styles and images from origins of the environment are compared with the
+                                    organization's allowed origins (--offline skips that)
   share [--name <text>] [--branch b] [--notes file|-] [--notes-preview]
                                     Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged",
                                     with "what changed" notes per step (screens per viewport, text, tokens); --notes-preview
@@ -321,7 +327,7 @@ Design (environments with kind: design; live HTML steps in a folder)
                                     a folder exported from Figma works without a token. One way: no prototype links
   history [--scenario id] [--step id] [--locale l] [--json]
                                     Versions of the flow; revisions of a step with who (person or agent) and when
-  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]
+  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--state s] [--local] [--json]
                                     What to build for a step as approved: elements with role, name and selector, styles
                                     mapped to DTCG tokens (or the nearest one), :hover/:focus/:active/:disabled, contrast
   drift [step] [--ref design|vN] [--remote <run id|latest>] [--json]
@@ -457,6 +463,21 @@ function stepOf (scenario, id) {
   return node
 }
 
+/**
+ * Font and asset origins for `kaloko design lint` (#46): `wanted` from `origins` of the design environment, and with
+ * `online` the organization's list from the service (GET /me design_origins; null when not signed in or unreachable).
+ */
+async function lintOrigins (config, env, { online = false } = {}) {
+  let wanted = []
+  try { wanted = cleanAssetOrigins(env?.origins || []) } catch (e) { throw new UserError(`Environment ${env.name}, origins: ${e.message}`) }
+  if (!online || !wanted.length) return { wanted, allowed: null }
+  let timer
+  try {
+    const me = await Promise.race([service(config).request('GET', '/me'), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 8000) })])
+    return Array.isArray(me?.design_origins) ? { wanted, allowed: me.design_origins } : { wanted, allowed: null, unchecked: true }
+  } catch { return { wanted, allowed: null, unchecked: true } } finally { clearTimeout(timer) }
+}
+
 /** Scenario of --scenario (id or file) or of the current run. */
 /**
  * kaloko design import figma <file-url|key|folder>: Figma frames (or a folder exported from Figma) become the steps of
@@ -488,7 +509,7 @@ async function designImport (args) {
   if (args.json) say(JSON.stringify(r, null, 2))
   else say(formatImport(r, { dir: relative(process.cwd(), dir) || '.' }))
   if (args['dry-run']) return r
-  const lint = await lintDesign({ dir, scenario })
+  const lint = await lintDesign({ dir, scenario, origins: await lintOrigins(config, env) })
   if (lint.errors) say(`\n${formatLint(lint, { max: 10 })}`)
   if (!args.publish) {
     say(`\nNext: kaloko start --scenario ${relative(process.cwd(), scenarioFile)} --env ${env.name} && kaloko walk && kaloko share (or rerun with --publish).\nAccept the version on the canvas and set it as the design reference (kaloko reference --design --version <n>): implementation runs with packs: [design] are then checked against these frames.`)
@@ -521,6 +542,24 @@ function manualKeys (run, pick) {
   return scopeKeys(scope, keys.length ? keys : engineKeys(scope, 'chromium'), null)
 }
 
+/** Modes of a design environment's token set (tokens.resolver.json or tokens.json); [] without one. */
+async function designTokenModesOf (config, root, env) {
+  try {
+    const { loadTokens } = await import('./lib/drift.mjs')
+    const { modesOf } = await import('./lib/tokens.mjs')
+    const set = await loadTokens({ client: null, config, root, designDir: designDir(env, root) })
+    return set ? modesOf(set) : []
+  } catch { return [] }
+}
+
+/** --state <name> (#46): the keys of that state of the step instead of the default ones. */
+function inState (run, node, keys, state) {
+  if (!state || state === true || state === 'default') return keys
+  const have = nodeStates(run.meta.scope, node)
+  if (!have.includes(state)) throw new UserError(`Step ${node.id} has no state "${state}" in this run (${have.length > 1 ? `its states: ${have.join(', ')}` : 'add states: to the step and start a new run'}).`)
+  return Object.fromEntries(stateKeys(run.meta.scope, Object.keys(keys), state).map((k) => [k, run.meta.scope.viewports[k]]))
+}
+
 /** { key: [w, h] } a capture on a Chromium page takes: every Chromium key of the run, or those of `pick`. */
 function scopeViewports (run, pick) {
   return scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium'), pick)
@@ -772,15 +811,17 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
             if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
             const streakKey = `${group.device || ''}|${locale}`
             if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale}${tag})`); continue }
-            const records = []
+            let records = []
+            // step states (#46): the script (or the deep link) runs once per state; `state` tells the script which
+            let state = 'default'
             try {
               let captured = false
               await rec?.beforeStep(node)
               const capture = async (o = {}) => {
                 captured = true
-                await rec?.beforeCapture(node)
+                if (state === 'default') await rec?.beforeCapture(node)
                 // a named viewport: within this device, or any of the run when it has no devices (as before)
-                const keys = o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys
+                const keys = stateKeys(scope, o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys, state)
                 if (!keys.length) throw new UserError(`Unknown viewport "${o.viewport}" for ${group.device || platform}.`)
                 const out = []
                 for (const key of keys) {
@@ -803,14 +844,25 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
                 records.push(...out)
                 return out.length === 1 ? out[0] : out
               }
-              if (scripted) {
-                const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
-                await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
-              } else await driver.link(link)
-              if (!captured) await capture()
+              const mod = scripted ? await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href) : null
+              const once = async () => {
+                captured = false
+                if (mod) await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(scope, node) } : {}) }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
+                else await driver.link(link)
+                if (!captured) await capture()
+              }
+              await once()
               await rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
               say(`✓ ${node.id} ${locale}${tag}`)
               streak.ok(streakKey)
+              for (const s of nodeStates(scope, node).slice(1)) {
+                state = s; records = []
+                try { await once(); say(`✓ ${node.id} ${locale}${tag} · ${s}`) } catch (error) {
+                  failed.push(`${node.id} (${locale}${tag} · ${s}): ${error.message.split('\n')[0]}`)
+                  say(`✗ ${node.id} ${locale}${tag} · ${s}: ${error.message.split('\n')[0]}`)
+                }
+              }
+              state = 'default'
             } catch (error) {
               await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
               failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
@@ -1026,7 +1078,9 @@ const commands = {
     if (scenario.environments && !scenario.environments.includes(env.name)) throw new UserError(`Scenario ${scenario.id} is not allowed on ${env.name} (allowed: ${scenario.environments.join(', ')}).`)
     if (env.readonly && !scenario.readonly) throw new UserError(`Environment ${env.name} is readonly; the scenario must declare readonly: true.`)
     const locales = list(args.locales) || scenario.locales || ['default']
-    const scope = { ...startScope({ args, scenario, config, env }), ...(args.note ? { note: args.note } : {}) }
+    // design environments render every mode of their token set (#46): the modes come from the folder's set
+    const tokenModes = env.kind === 'design' ? await designTokenModesOf(config, root, env) : []
+    const scope = { ...startScope({ args, scenario, config, env, tokenModes }), ...(args.note ? { note: args.note } : {}) }
     scope.locales = locales
     const vpNames = baseViewports(scope)
     const git = await gitMeta(root)
@@ -1105,7 +1159,8 @@ const commands = {
     }
     if (isApp(scenario.platform)) {
       // the app's current screen, through the environment's driver (no navigation); --viewport may name a device key
-      const key = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const key0 = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const key = Object.keys(inState(run, node, { [key0]: run.meta.scope.viewports[key0] }, args.state))[0] || key0
       const device = run.meta.scope.devices?.[variantOf(run.meta.scope, key).viewport]?.app ? variantOf(run.meta.scope, key).viewport : null
       const cfg = deviceConfig(scenario.platform, env.app?.[scenario.platform] || {}, device)
       const driver = driverFor(scenario.platform, { ...env, app: { ...(env.app || {}), [scenario.platform]: cfg } }, { root, scenarioDir: resolve(root, run.meta.scenario_file, '..'), locale })
@@ -1139,7 +1194,7 @@ const commands = {
         return
       }
       const since = (await readCaptures(run.dir)).filter((c) => c.node === node.id).map((c) => c.at).pop()
-      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: manualKeys(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
+      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: inState(run, node, manualKeys(run, list(args.viewports)), args.state), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
       for (const r of results) {
         const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
         say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.size.width}×${r.size.height}px  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}${r.blocked_requests.length ? `  blocked: ${r.blocked_requests.length}` : ''}`)
@@ -1197,8 +1252,8 @@ const commands = {
       }
     }
     if (env.kind === 'design') {
-      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeViewports(run, list(args.viewports)), say, noCache: !!args['no-cache'] })
-      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium', '*'), list(args.viewports)), say, noCache: !!args['no-cache'] })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario, origins: await lintOrigins(config, env) })
       if (lint.errors || lint.warnings) say(`\nPortable HTML: ${lint.errors} error(s), ${lint.warnings} warning(s); kaloko design lint lists them${lint.errors ? ' (errors stop kaloko sync: they break on the live step)' : ''}.`)
       return
     }
@@ -1341,22 +1396,32 @@ const commands = {
               const scriptFile = resolve(scenarioDir, node.execution.script)
               // one invocation of the step script; the automatic capture runs unless the script captured the step itself:
               // a crop is an attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
-              const rec = await recorderFor(sPage)
-              const runStep = async (mod) => {
+              const rec0 = await recorderFor(sPage)
+              // step states (#46): the script runs once per state with `state`; each run captures that state's keys
+              // (the recording follows the default state)
+              const runStep = async (mod, state = 'default') => {
                 let captured = false
+                const rec = state === 'default' ? rec0 : null
                 rec?.beforeStep(node)
                 const records = []
-                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, pass.keys, opts.viewports || null), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
+                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, stateKeys(run.meta.scope, Object.keys(scopeKeys(run.meta.scope, pass.keys, opts.viewports || null)), state)), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
                 try {
-                  await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
+                  await mod.default({ page: sPage, context: sCtx, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(run.meta.scope, node) } : {}) }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
                   if (!captured) await capture()
                 } catch (error) { await rec?.afterStep(node, { error }); throw error }
                 await rec?.afterStep(node, { records })
               }
               try {
-                await runStep(await import(pathToFileURL(scriptFile).href))
+                const mod = await import(pathToFileURL(scriptFile).href)
+                await runStep(mod)
                 say(`✓ ${node.id} ${locale}${tag}`)
                 streak.ok(streakKey)
+                for (const state of nodeStates(run.meta.scope, node).slice(1)) {
+                  try { await runStep(mod, state); say(`✓ ${node.id} ${locale}${tag} · ${state}`) } catch (error) {
+                    failed.push(`${node.id} (${locale}${tag} · ${state}): ${error.message.split('\n')[0]}`)
+                    say(`✗ ${node.id} ${locale}${tag} · ${state}: ${error.message.split('\n')[0]}`)
+                  }
+                }
               } catch (error) {
                 // a selector the page no longer has: propose one from the page (#13); --heal applies it once the step passes
                 const healed = args['no-heal'] ? null : await healStep({ error, page: sPage, scriptFile, root, output: config.output, run, node, locale, apply: !!args.heal, rerun: runStep }).catch(() => null)
@@ -1598,7 +1663,7 @@ const commands = {
     if (!account.configured) throw new UserError(`Add the account first: environments.${env.name}.accounts.${args.account} in ${CONFIG_FILE} (it may be empty: {}).`)
     if (!process.stdin.isTTY) throw new UserError('kaloko auth save needs a person at the terminal: they sign in in the browser window and press Enter.')
     const { chromium } = await import('playwright')
-    const browser = await chromium.launch({ headless: false, channel: config.browser.channel || undefined })
+    const browser = await launchWithRetry(chromium, { headless: false, channel: config.browser.channel || undefined })
     try {
       const page = await (await newContext(browser, env, { root, config })).newPage()
       await page.goto(typeof args.url === 'string' ? args.url : baseUrl(env), { waitUntil: 'domcontentloaded' })
@@ -1796,7 +1861,7 @@ const commands = {
     const client = service(config)
     if (env.kind === 'design' && !args.pull && !args['no-lint']) {
       // what renders locally may still break on the live step (CSP, sandbox): say so before anything is pushed
-      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario, origins: await lintOrigins(config, env, { online: true }) })
       if (lint.errors || lint.warnings) say(formatLint(lint, { max: 15 }) + '\n')
       if (lint.errors) throw new UserError(`${lint.errors} error(s) above break the design on the live step; fix them, or sync with --no-lint to push anyway.`)
     }
@@ -1805,19 +1870,19 @@ const commands = {
 
   async design (args) {
     if (args._[0] === 'import') return designImport(args)
-    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
+    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
     const { config, root } = await context(args)
     let run = null
     try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
     let dir = typeof args.dir === 'string' ? resolve(args.dir) : null
+    const runEnv = run ? environment(config, run.meta.environment.name) : null
+    const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments || {}).map((n) => environment(config, n)).find((e) => e.kind === 'design')
     if (!dir) {
-      const runEnv = run ? environment(config, run.meta.environment.name) : null
-      const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
       if (!env) throw new UserError('No design environment: pass --dir <folder> or --env <design env>.')
       dir = designDir(env, root)
     }
     const scenario = typeof args.scenario === 'string' && /\.ya?ml$/.test(args.scenario) ? await loadScenario(resolve(args.scenario)) : run ? await loadScenario(resolve(root, run.meta.scenario_file)).catch(() => null) : null
-    const report = await lintDesign({ dir, scenario })
+    const report = await lintDesign({ dir, scenario, origins: env?.kind === 'design' ? await lintOrigins(config, env, { online: !args.offline }) : null })
     say(args.json ? JSON.stringify(report, null, 2) : formatLint(report, { all: !!args.all, max: args.all ? 500 : 60 }))
     if (report.errors || (args.strict && report.warnings)) process.exitCode = 1
   },
@@ -2209,7 +2274,8 @@ const commands = {
       const product = pickProduct(config, root, args.product)
       const printPdf = async (htmlFile, outFile) => {
         const { chromium } = await import('playwright')
-        const browser = await chromium.launch(config.browser?.channel ? { channel: config.browser.channel } : {}).catch(() => chromium.launch())
+        // the configured channel when it is installed, else Playwright's Chromium; a browser that stalls is not retried twice over
+        const browser = await launchWithRetry(chromium, config.browser?.channel ? { channel: config.browser.channel } : {}).catch((e) => e?.name === 'TimeoutError' || !config.browser?.channel ? Promise.reject(e) : launchWithRetry(chromium, {}))
         try {
           const page = await browser.newPage()
           await page.goto(pathToFileURL(htmlFile).href, { waitUntil: 'load', timeout: 60000 })

package/src/lib/assertions.mjs

@@ -200,10 +200,12 @@ export async function jsValues (page, checks, timeout = JS_TIMEOUT) {
       return { type, value }
     })()`
     try {
+      // the page's own timer limits the expression; this one only guards against a page that stopped answering, with
+      // room for a slow round trip on a busy machine (a 1 s margin failed true checks under load)
       let timer
       const result = await Promise.race([
         page.evaluate(wrapped),
-        new Promise((_, no) => { timer = setTimeout(() => no(new Error(`did not finish within ${timeout} ms`)), timeout + 1000) })
+        new Promise((_, no) => { timer = setTimeout(() => no(new Error(`the page did not answer within ${Math.round((timeout + 15000) / 1000)} s`)), timeout + 15000) })
       ]).finally(() => clearTimeout(timer))
       const text = JSON.stringify(result.value)
       out[id] = { expression, result: text && text.length > 2000 ? { type: result.type, value: `${text.slice(0, 2000)}…` } : result }

package/src/lib/browser-daemon.mjs

@@ -5,10 +5,12 @@
 import { chromium } from 'playwright'
 import { writeJson, appendJsonl } from './util.mjs'
 import { prepareContext, clientCertificates } from './access.mjs'
+import { launchPersistentWithRetry } from './browser.mjs'
 
 const opts = JSON.parse(process.argv[2])
 const certs = opts.env ? clientCertificates(opts.env, opts.root) : []
-const context = await chromium.launchPersistentContext(opts.profile, {
+// a time limit and one more try (KALOKO_LAUNCH_TIMEOUT): a start that stalls on a busy machine does not hang here
+const context = await launchPersistentWithRetry(chromium, opts.profile, {
   headless: !opts.headed,
   channel: opts.channel || undefined,
   viewport: { width: 1280, height: 800 },

package/src/lib/browser.mjs

@@ -69,12 +69,16 @@ export async function startBrowser ({ root, config, env, headed }) {
   })
   const child = spawn(process.execPath, [join(here, 'browser-daemon.mjs'), args], { detached: true, stdio: 'ignore' })
   child.unref()
-  for (let i = 0; i < 100; i++) {
+  // the daemon launches with launchLimit() and tries once more after a timeout
+  const wait = 2 * launchLimit() + 10000
+  for (const until = Date.now() + wait; Date.now() < until;) {
     await new Promise((r) => setTimeout(r, 200))
     const state = await readJson(stateFile, null)
     if (state && state.pid === child.pid) return state
+    if (!await alive(child.pid)) throw new UserError('Browser did not start (its process ended). Try "kaloko browser start --headed" to see what happens, or "kaloko doctor".')
   }
-  throw new UserError('Browser did not start within 20 s. Try "kaloko browser start --headed" to see what happens.')
+  try { process.kill(child.pid, 'SIGTERM') } catch {} // Playwright ends the browser it was starting
+  throw new UserError(`Browser did not start within ${Math.round(wait / 1000)} s. Try "kaloko browser start --headed" to see what happens; on a busy machine raise KALOKO_LAUNCH_TIMEOUT (seconds).`)
 }
 
 /** Stops the browser of one environment, or every shared browser of the project. */
@@ -102,7 +106,7 @@ export async function connectBrowser ({ root, config, env }) {
   if (!state) return null
   assertPolicy(state, env)
   const { chromium } = await import('playwright')
-  const browser = await chromium.connectOverCDP(state.cdp)
+  const browser = await connectWithRetry(chromium, state.cdp)
   return { browser, context: browser.contexts()[0], state }
 }
 
@@ -138,17 +142,82 @@ export async function currentPage (context, match) {
   return real[real.length - 1] || pages[pages.length - 1] || context.newPage()
 }
 
+/** The time limit of a browser launch or connection: KALOKO_LAUNCH_TIMEOUT seconds, default 45. */
+export const launchLimit = () => (Number(process.env.KALOKO_LAUNCH_TIMEOUT) || 45) * 1000
+/** The time limit of the first context of a new browser and of every later newContext/newPage: 20 s, or KALOKO_LAUNCH_TIMEOUT when set. */
+export const answerLimit = () => (Number(process.env.KALOKO_LAUNCH_TIMEOUT) > 0 ? launchLimit() : 20000)
+
+const isTimeout = (e) => /Timeout|did not (finish|answer)/i.test(String(e?.name) + ' ' + String(e?.message))
+
+/** `promise`, or a TimeoutError naming `what` when it has not settled within `ms`. */
+export function withTimeout (promise, ms, what) {
+  let timer
+  const limit = new Promise((resolve, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(`${what} did not answer within ${Math.round(ms / 1000)} s (KALOKO_LAUNCH_TIMEOUT)`), { name: 'TimeoutError' })), ms)
+  })
+  return Promise.race([promise, limit]).finally(() => clearTimeout(timer))
+}
+
+/** Runs `attempt` and, when it timed out, once more; any other error reaches the caller. */
+export async function retryOnTimeout (attempt) {
+  try { return await attempt() } catch (e) {
+    if (!isTimeout(e)) throw e
+    return attempt()
+  }
+}
+
+/**
+ * Puts a time limit on newContext and newPage of a browser: a browser that stopped answering (seen on loaded
+ * machines: launched fine, then Target.createBrowserContext never returned) fails the command instead of holding it
+ * forever. A context that arrives after the limit is closed.
+ */
+export function limitBrowser (browser, ms = answerLimit()) {
+  if (!browser || typeof browser.newContext !== 'function' || browser.__kalokoLimited) return browser
+  for (const name of ['newContext', 'newPage']) {
+    const call = browser[name].bind(browser)
+    browser[name] = (...a) => {
+      const pending = call(...a)
+      return withTimeout(pending, ms, `browser.${name}`).catch((e) => {
+        if (isTimeout(e)) pending.then((x) => x?.close?.().catch(() => {}), () => {})
+        throw e
+      })
+    }
+  }
+  browser.__kalokoLimited = true
+  return browser
+}
+
 /**
  * Launches a browser with a time limit and one more try: on a busy machine a browser now and then starts but never
- * answers, and Playwright would wait for it forever. Playwright ends the process of a launch that timed out.
- * KALOKO_LAUNCH_TIMEOUT (seconds, default 45) sets the limit.
+ * answers, and Playwright would wait for it forever. Playwright ends the process of a launch that timed out. A
+ * launched browser must open a context within answerLimit(); one that does not is closed (Playwright kills it when it
+ * does not close within 30 s) and the launch is tried once more. KALOKO_LAUNCH_TIMEOUT (seconds, default 45).
  */
 export async function launchWithRetry (browserType, options = {}) {
-  const timeout = (Number(process.env.KALOKO_LAUNCH_TIMEOUT) || 45) * 1000
-  try { return await browserType.launch({ timeout, ...options }) } catch (e) {
-    if (!/Timeout/i.test(String(e?.name) + String(e?.message))) throw e
-    return browserType.launch({ timeout, ...options })
-  }
+  const timeout = launchLimit()
+  return retryOnTimeout(async () => {
+    const browser = await browserType.launch({ timeout, ...options })
+    if (typeof browser?.newContext !== 'function') return browser
+    try {
+      await withTimeout(browser.newContext().then((c) => c.close()), answerLimit(), 'the new browser')
+    } catch (e) {
+      browser.close().catch(() => {}) // not awaited: the next try starts while Playwright closes or kills this one
+      throw e
+    }
+    return limitBrowser(browser)
+  })
+}
+
+/** chromium.connectOverCDP with a time limit and one more try; the browser's newContext/newPage are limited too. */
+export async function connectWithRetry (browserType, endpoint, options = {}) {
+  const timeout = launchLimit()
+  return limitBrowser(await retryOnTimeout(() => browserType.connectOverCDP(endpoint, { timeout, ...options })))
+}
+
+/** chromium.launchPersistentContext with a time limit and one more try (the shared browser's daemon). */
+export async function launchPersistentWithRetry (browserType, profile, options = {}) {
+  const timeout = launchLimit()
+  return retryOnTimeout(() => browserType.launchPersistentContext(profile, { timeout, ...options }))
 }
 
 export async function launchEphemeral (config) {

package/src/lib/build.mjs

@@ -4,10 +4,9 @@ import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { readJson, writeJson } from './util.mjs'
 import { readCaptures, runPaths, listRuns } from './run.mjs'
-import { latestCaptures, evaluationSource, stepIdOf, appliesOn } from './evaluate.mjs'
-import { fieldsOf, DEFAULT_SEMANTIC_SAMPLE } from './stack.mjs'
+import { latestCaptures, evaluationSource, stepIdOf } from './evaluate.mjs'
 import { layout } from './scenario.mjs'
-import { assembleNode, summarize, statusOf, worst } from './manifest-core.mjs'
+import { assembleNode, assembleStack, summarize } from './manifest-core.mjs'
 import { packageRoot } from './schema.mjs'
 import { variantOf } from './dimensions.mjs'
 
@@ -148,53 +147,17 @@ async function runMedia ({ run, entries }) {
  */
 async function buildStack ({ run, node, base, captures, attachments }) {
   const paths = runPaths(run.dir)
-  const fields = fieldsOf(node).map((f) => ({ id: f.id, label: f.label || f.id }))
-  const environment = run.meta?.environment?.name || null
-  const crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null, ...(appliesOn(c, environment) ? {} : { not_applicable: 'environment' }) }))
-  // criteria limited to other environments do not decide the status of a page
-  const live = new Set(crit.filter((c) => !c.not_applicable).map((c) => c.id))
-  const byItem = new Map()
+  const list = []
   for (const c of captures.filter((x) => x.node === node.id && x.item)) {
     const cap = await readJson(join(run.dir, c.file))
-    const evPath = paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json')
-    const stored = await readJson(evPath, null)
+    const stored = await readJson(paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json'), null)
     const ev = stored?.source === evaluationSource(node, cap) ? stored : null
-    let it = byItem.get(c.item)
-    if (!it) { it = { id: c.item, path: cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size }; byItem.set(c.item, it) }
-    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, url: cap.url, size: cap.size ? [cap.size.width, cap.size.height] : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), eval: ev ? `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` : null }
-    it.results[`${c.locale}|${c.viewport}`] = ev ? Object.fromEntries(ev.criteria.map((r) => [r.id, [r.verdict, r.evidence ? String(r.evidence).slice(0, 200) : null, r.score ?? null]])) : Object.fromEntries(crit.filter((x) => x.type !== 'semantic').map((x) => [x.id, ['not_evaluated', null, null]]))
-    if (!ev) it.stale = true
-  }
-  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, ...it }) => {
-    const per = Object.values(it.results)
-    const verdictOf = (id) => worst(per.map((r) => r[id]?.[0]).filter(Boolean))
-    const verdicts = crit.filter((c) => live.has(c.id)).map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
-    const status = statusOf(verdicts, per.length > 0)
-    const by_locale = Object.fromEntries(Object.keys(it.captures).map((l) => [l, statusOf(Object.entries(it.results).filter(([k]) => k.startsWith(`${l}|`)).flatMap(([, r]) => Object.entries(r).filter(([id]) => live.has(id)).map(([, x]) => x[0])), true)]))
-    return { ...it, status, by_locale, fails: crit.filter((c) => live.has(c.id) && verdictOf(c.id) === 'fail').map((c) => c.id), review: crit.filter((c) => live.has(c.id) && ['needs_review', 'not_evaluated'].includes(verdictOf(c.id))).map((c) => c.id) }
-  })
-  const summary = { pass: 0, partial: 0, fail: 0, skip: 0 }
-  for (const it of items) summary[it.status]++
-  const criteria = crit.map((c) => {
-    const counts = {}
-    for (const it of items) { const v = worst(Object.values(it.results).map((r) => r[c.id]?.[0]).filter(Boolean)); if (v !== 'not_reached') counts[v] = (counts[v] || 0) + 1 }
-    return { ...c, counts, verdict: counts.fail ? 'fail' : counts.needs_review ? 'needs_review' : counts.not_evaluated ? 'not_evaluated' : counts.pass ? 'pass' : 'not_reached', by_locale: {} }
-  })
-  const semanticSample = node.items?.semantic_sample ?? DEFAULT_SEMANTIC_SAMPLE
-  const file = `steps/${node.id}/items.json`
-  await writeJson(join(run.dir, file), { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, items })
-  const thumbOf = (it) => { const c = Object.values(it.captures)[0]; const v = c && Object.values(c)[0]; return v ? v.thumb || v.png : null }
-  const sample = [...items.filter((it) => it.status === 'fail'), ...items.filter((it) => it.status !== 'fail')].slice(0, 4).map((it) => ({ id: it.id, title: it.title, path: it.path, status: it.status, thumb: thumbOf(it) }))
-  const status = !items.length ? 'skip' : summary.fail ? 'fail' : summary.partial || summary.skip ? 'partial' : 'pass'
-  const locales = [...new Set(items.flatMap((it) => Object.keys(it.by_locale)))]
-  const by_locale = Object.fromEntries(locales.map((l) => { const s = items.map((it) => it.by_locale[l]).filter(Boolean); return [l, s.includes('fail') ? 'fail' : s.some((x) => x !== 'pass') ? 'partial' : 'pass'] }))
-  const src = node.items || {}
-  return {
-    ...base, status, by_locale, captures: {}, criteria, semantic: {}, metadata: {}, session: node.session || null,
-    execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : { strategy: 'playwright', instructions: 'Open every page of the stack and capture it.' },
-    attachments: attachments.filter((a) => a.node === node.id && a.kind !== 'focus').map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale })),
-    stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source: ['urls', 'file', 'sitemap', 'crawl', 'script'].find((k) => src[k]) || null, stale: items.filter((it) => it.stale).length }
+    // a variant of a design stack (#61) opens live in the lightbox: its page in the step's revision
+    list.push({ item: c.item, locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, eval: `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` }, ...(cap.live ? { live: cap.live } : {}) })
   }
+  const { node: out, index, file } = assembleStack({ node, base, environment: run.meta?.environment?.name || null, captures: list, attachments })
+  await writeJson(join(run.dir, file), index)
+  return out
 }
 
 /**

package/src/lib/capture.mjs

@@ -165,7 +165,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         }
       }
       // the step spec (Dev mode, `kaloko spec`, drift): elements with roles, names and styles mapped to the tokens
-      if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens, scope?.variants?.[viewport]?.color_scheme || null)
+      if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens, scope?.variants?.[viewport]?.token_mode || scope?.variants?.[viewport]?.color_scheme || null)
       // regions the scenario ignores in pixel comparisons (#20), as page rectangles of this capture
       const ignore = await resolveIgnore(page, node, locale, viewport)
       // what moves while the page sits still (walk --stability N): repeated screenshots, compared here