kaloko 0.7.1 → 0.9.0

package/README.md

@@ -182,7 +182,9 @@ npx kaloko import walkthrough/ --adhoc      # a Cursor or Antigravity walkthroug
 lays screenshots, Playwright reports and traces out as a run: matched to the
 scenario's steps (by step id in `steps.json`, URL or title), or as an ad-hoc
 flow when there is no scenario. Build and share it like any run. When something does not work (Chrome,
-token, environment URL, evaluator key), `npx kaloko doctor` says what to fix.
+token, environment URL, evaluator key), `npx kaloko doctor` says what to fix, and
+`npx kaloko doctor --fix` installs a missing browser, creates missing folders and fills in `org:` from your token.
+Every error the CLI prints says what to do next; if you are still stuck, write to support@sinfin.cz.
 
 ## Review only what changed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test --test-timeout=900000 test/*.test.mjs worker/test/*.test.mjs"
+    "test": "node scripts/test.mjs"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/schemas/scenario.v1.json

@@ -84,6 +84,10 @@
       "default": "web",
       "description": "What the flow runs on. web: pages in a browser (an installed PWA too: display_modes). android/ios/electron/desktop/windows: an app, driven by the environment's app block (adb, iOS Simulator or device, Playwright Electron, macOS window, Windows UI Automation) or captured with kaloko capture --image. Node paths are deep links for apps."
     },
+    "page": {
+      "enum": ["landing", "work", "list", "settings", "form", "doc"],
+      "description": "Default page type of every step (a step may set its own). landing: a public or marketing page; work: an app screen where people work (overview, canvas, inbox); list: a list or table of items; settings: settings or billing; form: a form to fill in; doc: documentation or long text. The usability pack picks its questions by type. Not set: landing for steps with the seo pack or scenarios allowed on production, work otherwise."
+    },
     "tags": {
       "type": "array",
       "items": {
@@ -307,6 +311,10 @@
           ],
           "description": "For `kaloko walk --affected`: globs of repository files (relative to the config) that shape this step, next to the routes and imports Kaloko finds itself; `always` walks the step on every affected walk (sign-in, consent)."
         },
+        "page": {
+          "enum": ["landing", "work", "list", "settings", "form", "doc"],
+          "description": "What kind of page this step is (see the scenario's page); the usability pack asks per type, e.g. one primary call to action only on landing pages."
+        },
         "packs": {
           "type": "array",
           "items": {
@@ -321,7 +329,7 @@
               "design"
             ]
           },
-          "description": "Check packs whose criteria are added to this node (ids AC1xx seo, AC2xx usability, AC3xx a11y, AC4xx perf, AC5xx console, AC6xx design: checks against the design reference)."
+          "description": "Check packs whose criteria are added to this node (ids AC1xx seo, AC2xx usability, AC3xx a11y, AC4xx perf, AC5xx console, AC6xx errors, AC7xx app, AC8xx design: checks against the design reference)."
         },
         "capture": {
           "$ref": "#/$defs/capture"
@@ -528,6 +536,12 @@
         "pack": {
           "type": "string",
           "description": "Set by the CLI on criteria that came from a pack."
+        },
+        "environments": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" },
+          "description": "Environments where this criterion applies, e.g. [production] for hreflang to the live domain, the live demo or the sitemap. On any other environment the walk reports it as not applicable (not_evaluated with na: environment) and it does not make the step partial."
         }
       }
     },

package/skills/kaloko/reference/acceptance.md

@@ -42,12 +42,42 @@ sharpen each purpose and add the criteria the page must really meet.
 criteria (ids `AC1xx` for `seo`, `AC2xx` for `usability`) at load time:
 `seo` checks one H1, title and description length, canonical, hreflang for
 every locale, Open Graph, indexing, viewport, `html lang`, overflow and
-console; `usability` asks the evaluator about purpose, one primary action
-and link texts and checks unlabeled inputs. A node's own criterion with the
+console; `usability` checks unlabeled inputs and link texts and asks the
+evaluator questions that fit the step's page type. A node's own criterion with the
 same id wins. Pack criteria are marked `pack` on the canvas and do not count
 as drift in `--coverage`; the plan may still mention them by id. Use packs
 for public pages and landings; task flows keep their own criteria.
 
+Set `page` on every step (or once on the scenario) so the usability pack
+asks the right questions:
+
+| `page` | for | asks |
+| --- | --- | --- |
+| `landing` | public and marketing pages | purpose in the first screen (`AC201`), exactly one primary call to action (`AC202`) |
+| `work` | app screens where people work: overview, canvas, detail, inbox item | the heading says what the screen is for (`AC205`) |
+| `list` | lists and tables: runs, projects, inbox | `AC205`, each item says what it is and how to open it (`AC207`) |
+| `settings` | settings, billing, tokens | `AC205`, each setting says what it changes and how it is saved (`AC208`) |
+| `form` | sign-up, sign-in, a form to fill in | `AC205`, how to send it and what happens next (`AC206`) |
+| `doc` | documentation, guides, terms | `AC201`, headings and short paragraphs (`AC209`) |
+
+Every type also gets `AC203` and `AC204`. Without `page` a step with the
+`seo` pack, or any step of a scenario allowed on production, is `landing`;
+everything else is `work`. Do not put `landing` on signed-in screens: "one
+primary call to action" is a marketing rule, and a work screen rightly offers
+several actions.
+
+A criterion that only makes sense on production (hreflang pairs pointing at
+the live domain, an embedded live demo, the production sitemap) carries
+`environments: [production]`. Walked anywhere else it is reported as not
+applicable to that environment (`not_evaluated` with `not_applicable:
+environment`) and does not make the step partial.
+
+When a scenario walks several locales, a text check (`text_matches`,
+`title_matches`, …) must match every language: write
+`pattern: "(Your data|Vaše data)"`. `kaloko validate` warns when a pattern
+reads in one language only (it looks for diacritics and common Czech or
+English words; one plain word such as a brand name is left alone).
+
 - `a11y` (`AC3xx`): images with alt, links and buttons with a name, labelled
   fields, heading levels not skipped, WCAG AA text contrast, a `main`
   landmark, unique ids (`AC301`–`AC307`, read from the page). After the

package/src/cli.mjs

@@ -6,7 +6,7 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 import { availableParallelism } from 'node:os'
 import yaml from 'js-yaml'
 import { loadConfig, environment, urlFor, baseUrl, CONFIG_FILE, LEGACY_CONFIG_FILE } from './lib/config.mjs'
-import { loadScenario, validateScenario } from './lib/scenario.mjs'
+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'
@@ -20,7 +20,7 @@ import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
 import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
 import { signoffCmd } from './lib/signoff.mjs'
-import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote } from './lib/util.mjs'
+import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote, SUPPORT_LINE, SUPPORT_EMAIL, NO_ORG } from './lib/util.mjs'
 import { packageRoot } from './lib/schema.mjs'
 import { compareRuns, formatComparison } from './lib/compare.mjs'
 import { doctor, formatDoctor } from './lib/doctor.mjs'
@@ -29,7 +29,7 @@ import { calibrate, formatCalibration, casesFromGolden, casesFromRun } from './l
 import { pageFacts, draftScenario, scenarioYaml } from './lib/draft.mjs'
 import { detectProject, initScenario, formatDetection } from './lib/init-detect.mjs'
 import { recheckCaptures } from './lib/recheck.mjs'
-import { resolveItems, fieldsOf, DEFAULT_LIMIT } from './lib/stack.mjs'
+import { resolveItems, fieldsOf, DEFAULT_LIMIT, timeLeft } from './lib/stack.mjs'
 import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
 import { expandPacks } from './lib/packs.mjs'
 import { upsertPrComment } from './lib/pr.mjs'
@@ -94,7 +94,9 @@ Project
                                     the organization and what the token may do; the token (at most 30 days) goes to
                                     ~/.config/kaloko/.env, or is printed with --print
   doctor [--json] [--fix]           Check Node, Chrome, config, environments, browser ports, token, evaluator key
-                                    and app tools; --fix asks macOS for the desktop capture permissions
+                                    and app tools; --fix installs missing Playwright browsers, creates the run and
+                                    scenario folders, writes org: from the token and asks macOS for the desktop
+                                    capture permissions
   validate <scenario.yml>... [--coverage [--source ACCEPTANCE.md]]
                                     Validate scenarios (schema + references); --coverage compares criteria with the plan
                                     With a token it also warns about scenarios the service still lists whose file is gone (--offline skips it)
@@ -233,7 +235,7 @@ Results
   signoff --verify <file.json|file.pdf> [--key file|url] [--json]
                                     Check a record someone handed over (no token needed); exit 1 when it does not verify
   stability --pull [--scenario id] [--json]
-                                    Regions people drew on screenshots on kaloko.app (step detail → Page → Draw a
+                                    Regions people drew on screenshots on kaloko.app (step detail → Mark a changing
                                     region) go into the scenario's ignore: of their steps; walk them again after
   screens [words] [--project p] [--product p] [--module m] [--scenario id] [--locale l] [--viewport v] [--device d]
           [--status pass|partial|fail|skip] [--environment e] [--designs] [--all] [--json] [--cursor c]
@@ -449,7 +451,7 @@ async function runContext (args) {
 }
 
 function stepOf (scenario, id) {
-  if (!id) throw new UserError('--step <id> is required.')
+  if (!id) throw new UserError(`Which step? Pass --step <id>; this scenario has: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}.`)
   const node = scenario.nodes.find((n) => n.id === id)
   if (!node) throw new UserError(`Unknown step "${id}". Steps: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}`)
   return node
@@ -655,6 +657,7 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
   page.on('response', onResponse)
   const streak = failureStreak(5)
   const failed = []; let ok = 0
+  const started = Date.now(); let told = started
   try {
     for (const [i, item] of chosen.entries()) {
       if (streak.stopped('stack')) { failed.push(`${item.id}: not walked after repeated failures`); continue }
@@ -671,7 +674,8 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
         failed.push(`${item.id} (${item.path}): ${error.message.split('\n')[0]}`)
         if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}${tag}): the last 5 pages failed with the same error`)
       }
-      if ((i + 1) % 25 === 0 && i + 1 < chosen.length) say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}`)
+      // long stacks: progress every 25 pages (or 30 s) with the time left, estimated from the pages so far
+      if (i + 1 < chosen.length && ((i + 1) % 25 === 0 || Date.now() - told > 30000)) { told = Date.now(); const left = timeLeft(i + 1, chosen.length, told - started); say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}${left ? ` · ${left}` : ''}`) }
     }
   } finally { page.off('response', onResponse) }
   say(`${failed.length ? '✗' : '✓'} ${node.id} ${locale}${tag}: ${ok}/${chosen.length} page(s) captured`)
@@ -987,10 +991,12 @@ const commands = {
     if (!args._.length) throw new UserError('Usage: kaloko validate <scenario.yml>...')
     let failed = 0
     for (const file of args._) {
-      const scenario = yaml.load(await readFile(file, 'utf8'))
+      let scenario
+      try { scenario = parseScenario(await readFile(file, 'utf8'), file) } catch (e) { if (!(e instanceof UserError)) throw e; failed++; say(`✕ ${e.message}`); continue }
       const problems = validateScenario(scenario)
       if (!problems.length) expandPacks(scenario)
       if (problems.length) { failed++; say(`✕ ${file}\n  - ${problems.join('\n  - ')}`) } else say(`✓ ${file}`)
+      if (!problems.length) for (const w of scenarioWarnings(scenario)) say(`  ! ${w}`)
       if (args.coverage) {
         // the plan is scenario.source (relative to the working directory or to the scenario file), or --source
         const candidates = typeof args.source === 'string' ? [resolve(args.source)] : scenario.source ? [resolve(scenario.source), resolve(file, '..', scenario.source), resolve(file, '..', '..', scenario.source)] : []
@@ -1223,7 +1229,7 @@ const commands = {
     const parallel = concurrency > 1 && locales.length > 1
     const scenarioDir = resolve(root, run.meta.scenario_file, '..')
     // semantic questions of every new capture start right away; the walk ends with the verdicts (--no-evaluate: skip)
-    const prefetch = args['no-evaluate'] ? null : semanticPrefetch({ scenario, config, root })
+    const prefetch = args['no-evaluate'] ? null : semanticPrefetch({ scenario, config, root, environment: env?.name || null })
     const walked = await readCaptures(run.dir)
     // recordings and traces (batch D, #12): opt-in recordings, traces unless turned off; encoded in an own headless Chrome
     const recSettings = recordSettings({ args, config, scenario })
@@ -2104,9 +2110,9 @@ const commands = {
     }
     let runId = args.run
     if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
-    if (!runId) throw new UserError('--run <id> is required when there is no current run.')
+    if (!runId) throw new UserError('No current run here. Pass --run <id>, or walk the scenario first (kaloko start, then kaloko walk).')
     const run = await load(runId)
-    if (!run) throw new UserError(`Run ${runId} not found locally or on the service.`)
+    if (!run) throw new UserError(`Run ${runId} is neither in ${config.output} nor on the service. Check the id (kaloko runs lists the local ones; the run's address on Kaloko shows a shared one).`)
     let baseId = typeof args.baseline === 'string' ? args.baseline : null
     // --design: against the design reference of the scenario (#42)
     if (args.design && run.scenario?.id) { client ||= service(config); baseId = (await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(run.scenario.id)}/references`)).design; if (!baseId) throw new UserError('This scenario has no design reference yet (kaloko reference --design --version <n>).') }
@@ -2118,7 +2124,7 @@ const commands = {
     }
     if (!baseId) throw new UserError('No baseline or earlier run of this scenario to compare with; pass --baseline <id>.')
     const base = await load(baseId)
-    if (!base) throw new UserError(`Run ${baseId} not found locally or on the service.`)
+    if (!base) throw new UserError(`Baseline run ${baseId} is neither in ${config.output} nor on the service. Check the id, or pass another --baseline <id>.`)
     const d = compareRuns(run, base)
     if (args.json) { say(JSON.stringify(d, null, 2)); return }
     say(formatComparison(d))
@@ -2197,7 +2203,7 @@ const commands = {
     if (typeof args.scenario === 'string') return exportScenario({ args, config, root, client })
     if (typeof args.format === 'string') {
       // living docs and the changelog as files (docs/DOCS-CHANGELOG.md → Exports)
-      if (!config.org) throw new UserError('Set org: in the config first.')
+      if (!config.org) throw new UserError(NO_ORG)
       const { pickProduct } = await import('./lib/changelog.mjs')
       const { exportDocs } = await import('./lib/docs.mjs')
       const product = pickProduct(config, root, args.product)
@@ -2218,7 +2224,7 @@ const commands = {
     }
     let runId = args.run
     if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
-    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('--run <id> is required (a shared run id).')
+    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('Which run? Pass --run <id> with the id of a shared run (kaloko share prints it), or run this where kaloko start made a current run.')
     const out = typeof args.out === 'string' ? resolve(args.out) : resolve(root, config.output, `${runId}.zip`)
     const { createWriteStream } = await import('node:fs')
     const { Readable } = await import('node:stream')
@@ -2234,7 +2240,7 @@ const commands = {
     const client = service(config)
     let runId = args.run
     if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
-    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('--run <id> is required (a shared run id).')
+    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('Which run? Pass --run <id> with the id of a shared run (kaloko share prints it), or run this where kaloko start made a current run.')
     const r = await client.request('POST', `/orgs/${config.org}/runs/${runId}/public`, { public: !args.off })
     say(r.public ? `Public: ${r.url} (readable without sign-in; only one public run per scenario)` : `Private again: ${runId}`)
   },
@@ -2282,7 +2288,7 @@ const commands = {
     const product = pickProduct(config, root, args.product)
     const version = typeof args.version === 'string' ? args.version : 'latest'
     if (sub === 'publish') {
-      if (!config.org && !args['dry-run']) throw new UserError('Set org: in the config first.')
+      if (!config.org && !args['dry-run']) throw new UserError(NO_ORG)
       const r = await docs.publishDocs({ root, config, product, client: args['dry-run'] ? null : service(config), version, reviewed: !!args.reviewed, dryRun: !!args['dry-run'] })
       if (args.json) { say(JSON.stringify(r, null, 2)); return }
       if (r.dry_run) { say(`${product.slug}: ${r.pages} page(s) from ${r.dir} would go to Kaloko as ${r.version} (${r.languages.join(', ')}); dry run, nothing sent.${r.broken.length ? `\n  ! broken step references: ${r.broken.join('; ')}` : ''}`); return }
@@ -2310,12 +2316,12 @@ const commands = {
     const { config, root } = await context(args)
     const lib = await import('./lib/changelog.mjs')
     if (sub === 'list') {
-      if (!config.org) throw new UserError('Set org: in the config first.')
+      if (!config.org) throw new UserError(NO_ORG)
       const r = await lib.listProducts({ root, config, client: service(config) })
       say(args.json ? JSON.stringify(r, null, 2) : lib.formatList(r))
       return
     }
-    if (!config.org && !args['dry-run']) throw new UserError('Set org: in the config first.')
+    if (!config.org && !args['dry-run']) throw new UserError(NO_ORG)
     const r = await lib.syncProducts({ root, config, client: args['dry-run'] ? null : service(config), only: typeof args.product === 'string' ? args.product : null, dryRun: !!args['dry-run'] })
     say(args.json ? JSON.stringify(r, null, 2) : lib.formatSync(r))
     if (r.products.some((p) => p.ok === false)) process.exitCode = 1
@@ -2324,7 +2330,7 @@ const commands = {
   /** `kaloko release <version>`: the version's changelog entry and its reference runs on the service. */
   async release (args) {
     const { config, root } = await context(args)
-    if (!config.org) throw new UserError('Set org: in the config first.')
+    if (!config.org) throw new UserError(NO_ORG)
     const { pickProduct, releaseProduct } = await import('./lib/changelog.mjs')
     const product = pickProduct(config, root, args.product)
     const client = args['dry-run'] ? null : service(config)
@@ -2358,10 +2364,13 @@ export async function main (argv) {
   const args = parse(argv)
   const name = args._.shift() || 'help'
   const cmd = commands[name] || (args.help ? commands.help : null)
-  if (!cmd) { console.error(`Unknown command "${name}".\n`); say(HELP); process.exitCode = 2; return }
+  if (!cmd) { console.error(`There is no command "${name}". The commands are below; kaloko help <command> explains one.\n`); say(HELP); process.exitCode = 2; return }
   try {
     await cmd(args)
   } catch (error) {
-    if (error instanceof UserError) { console.error(error.message); process.exitCode = 1 } else throw error
+    if (error instanceof UserError) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = 1 } else {
+      console.error(`Kaloko stopped on an unexpected error (a bug on our side). Send the output below to ${SUPPORT_EMAIL} with the command you ran.`)
+      throw error
+    }
   }
 }

package/src/lib/access.mjs

@@ -167,7 +167,7 @@ export function totp (base32, { step = 30, digits = 6, now = Date.now() } = {})
   let bits = ''
   for (const ch of base32.replace(/[\s=]/g, '').toUpperCase()) {
     const v = alphabet.indexOf(ch)
-    if (v < 0) throw new UserError('The TOTP secret is not base32.')
+    if (v < 0) throw new UserError('The TOTP secret is not base32 (letters A–Z and digits 2–7). Copy the secret again from the setup screen of the account, not the six-digit code.')
     bits += v.toString(2).padStart(5, '0')
   }
   const key = Buffer.from((bits.match(/.{8}/g) || []).map((b) => parseInt(b, 2)))

package/src/lib/apps/drivers.mjs

@@ -78,7 +78,7 @@ function android (cfg, ctx) {
     platform: 'android',
     async open ({ locale, reset, attach = false } = {}) {
       const { stdout } = await adb(['get-state']).catch((e) => { throw new UserError(`No Android device: ${e.message}. Start an emulator or connect a device (adb devices).`) })
-      if (!/device/.test(stdout)) throw new UserError('The Android device is not ready (adb get-state).')
+      if (!/device/.test(stdout)) throw new UserError('The Android device is connected but not ready (adb get-state). Unlock it and allow USB debugging, or wait until the emulator has booted, then run the command again.')
       const dens = (await shell('wm', 'density')).stdout.match(/(\d+)\s*$/m)
       density = dens ? Number(dens[1]) / 160 : 1
       if (!cfg.device) device = (await shell('getprop', 'ro.product.model')).stdout.trim() || 'android'

package/src/lib/apps/webview.mjs

@@ -27,7 +27,7 @@ export function webviewSockets (procNetUnix) {
  * local port and connects Playwright over CDP. Returns { browser, page, pages, close }.
  */
 export async function attachAndroidWebView (cfg, { timeout = 15000 } = {}) {
-  const adb = (args) => run(cfg.adb || 'adb', [...(cfg.serial ? ['-s', cfg.serial] : []), ...args], { timeout: 30000 }).then((r) => r.stdout).catch((e) => { if (e.code === 'ENOENT') throw new UserError('adb is not installed or not on PATH.'); throw e })
+  const adb = (args) => run(cfg.adb || 'adb', [...(cfg.serial ? ['-s', cfg.serial] : []), ...args], { timeout: 30000 }).then((r) => r.stdout).catch((e) => { if (e.code === 'ENOENT') throw new UserError('adb is not installed or not on PATH. Install Android platform-tools (kaloko doctor names the command for this system) and open a new terminal.'); throw e })
   const end = Date.now() + timeout
   let socket = null
   while (!socket && Date.now() < end) {
@@ -43,12 +43,12 @@ export async function attachAndroidWebView (cfg, { timeout = 15000 } = {}) {
   let browser
   try { browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`, { timeout }) } catch (e) {
     await adb(['forward', '--remove', `tcp:${port}`]).catch(() => {})
-    throw new UserError(`Could not connect to the WebView (${socket.socket}): ${e.message.split('\n')[0]}`)
+    throw new UserError(`Could not connect to the WebView (${socket.socket}): ${e.message.split('\n')[0]}. Bring the app to the front and run the command again.`)
   }
   const pages = browser.contexts().flatMap((c) => c.pages())
   // the visible page first: a WebView app often keeps hidden ones around
   let page = pages[0] || null
   for (const p of pages) { if (await p.evaluate(() => document.visibilityState === 'visible').catch(() => false)) { page = p; break } }
-  if (!page) { await browser.close().catch(() => {}); throw new UserError('The WebView has no page open.') }
+  if (!page) { await browser.close().catch(() => {}); throw new UserError('The WebView has no page open. Open the screen with the WebView in the app, then run the command again.') }
   return { browser, page, pages, socket: socket.socket, close: async () => { await browser.close().catch(() => {}); await adb(['forward', '--remove', `tcp:${port}`]).catch(() => {}) } }
 }

package/src/lib/browser.mjs

@@ -138,10 +138,22 @@ export async function currentPage (context, match) {
   return real[real.length - 1] || pages[pages.length - 1] || context.newPage()
 }
 
+/**
+ * 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.
+ */
+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 })
+  }
+}
+
 export async function launchEphemeral (config) {
   const { chromium } = await import('playwright')
-  const browser = await chromium.launch({ headless: true, channel: config.browser.channel || undefined })
-  return browser
+  return launchWithRetry(chromium, { headless: true, channel: config.browser.channel || undefined })
 }
 
 /**

package/src/lib/build.mjs

@@ -4,7 +4,7 @@ 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 } from './evaluate.mjs'
+import { latestCaptures, evaluationSource, stepIdOf, appliesOn } from './evaluate.mjs'
 import { fieldsOf, DEFAULT_SEMANTIC_SAMPLE } from './stack.mjs'
 import { layout } from './scenario.mjs'
 import { assembleNode, summarize, statusOf, worst } from './manifest-core.mjs'
@@ -149,7 +149,10 @@ 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 crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null }))
+  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()
   for (const c of captures.filter((x) => x.node === node.id && x.item)) {
     const cap = await readJson(join(run.dir, c.file))
@@ -165,10 +168,10 @@ async function buildStack ({ run, node, base, captures, attachments }) {
   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.map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
+    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.values(r).map((x) => x[0])), true)]))
-    return { ...it, status, by_locale, fails: crit.filter((c) => verdictOf(c.id) === 'fail').map((c) => c.id), review: crit.filter((c) => ['needs_review', 'not_evaluated'].includes(verdictOf(c.id))).map((c) => c.id) }
+    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]++

package/src/lib/changelog.mjs

@@ -8,7 +8,7 @@ import { promisify } from 'node:util'
 import { join, resolve, relative, dirname, basename } from 'node:path'
 import { UserError, sha256 } from './util.mjs'
 import { repoSlug } from './git.mjs'
-import { cleanVersion, compareVersions, tagFor, versionOfTag, latestVersionIn, sectionOf, applyDraft, finalizeRelease, draftEntry, groupsMarkdown, parseEntry, findStepRefs, CHANGELOG_SKELETON } from './changelog-core.mjs'
+import { cleanVersion, compareVersions, tagFor, versionOfTag, latestVersionIn, sectionOf, applyDraft, finalizeRelease, draftEntry, parseEntry, findStepRefs, CHANGELOG_SKELETON } from './changelog-core.mjs'
 
 const run = promisify(execFile)
 async function out (cmd, args, cwd, timeout = 20000) {
@@ -236,7 +236,7 @@ export async function releaseProduct ({ root, config, product, version = null, d
   const src = await detectVersionSource(root, product)
   const v = cleanVersion(version || src.version || '')
   if (!v) throw new UserError(`Which version? Pass it (kaloko release 2.4.0); ${src.source === 'git-tag' ? `no tag matches ${src.pattern}` : `${src.path || src.source} names none`}.`)
-  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/.test(v)) throw new UserError(`Not a version: ${v}`)
+  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/.test(v)) throw new UserError(`${v} is not a version Kaloko can use: letters, digits, dots, + and -, at most 80 characters (e.g. 2.4.0).`)
   const notes = []
   if (src.version && src.version !== v && src.source !== 'git-tag' && src.source !== 'semantic-release') notes.push(`${src.tool || src.source} (${src.path}) says ${src.version}; recording ${v} as you asked.`)
   const file = changelogFile(root, product)
@@ -361,14 +361,35 @@ export function docsConfigBlock ({ products = null, full = false } = {}) {
   return `${lines.join('\n')}\n`
 }
 
-/** Apps of a monorepo that look like products (apps/* with a package.json), for kaloko init. */
+/**
+ * Apps of a monorepo that look like products, for kaloko init: the folders of the workspaces (package.json
+ * `workspaces`, pnpm-workspace.yaml `packages`), apps/* and packages/*. A folder needs a package.json; outside apps/*
+ * it must also run as an app (a dev, start or serve script), so shared libraries and configs are left out. Only
+ * offered when there are at least two.
+ */
 export async function detectProducts (root) {
-  const out = []
-  for (const base of ['apps']) {
-    const names = await readdir(join(root, base)).catch(() => [])
-    for (const n of names.sort()) {
-      const pkg = await readJson(join(root, base, n, 'package.json'))
-      if (pkg) out.push({ slug: slugOf(n), name: pkg.name ? String(pkg.name).replace(/^@[^/]+\//, '') : n, dir: `${base}/${n}`, path: `${base}/${n}/package.json` })
+  const globs = new Set(['apps/*', 'packages/*'])
+  const rootPkg = await readJson(join(root, 'package.json'))
+  const ws = Array.isArray(rootPkg?.workspaces) ? rootPkg.workspaces : Array.isArray(rootPkg?.workspaces?.packages) ? rootPkg.workspaces.packages : []
+  for (const g of ws) globs.add(String(g))
+  const pnpm = await readFile(join(root, 'pnpm-workspace.yaml'), 'utf8').catch(() => '')
+  for (const m of pnpm.matchAll(/^\s*-\s*['"]?([^'"\n#]+?)['"]?\s*$/gm)) globs.add(m[1].trim())
+  const out = []; const seen = new Set()
+  for (const g of [...globs].sort()) {
+    if (g.startsWith('!')) continue
+    // "dir/*" (one level) or a plain folder; deeper patterns are left to the person
+    const m = g.replace(/\/+$/, '').match(/^([^*]+?)(\/\*)?$/)
+    if (!m) continue
+    const dirs = m[2] ? (await readdir(join(root, m[1])).catch(() => [])).sort().map((n) => `${m[1]}/${n}`) : [m[1]]
+    for (const dir of dirs) {
+      if (seen.has(dir)) continue
+      const pkg = await readJson(join(root, dir, 'package.json'))
+      if (!pkg) continue
+      const runs = ['dev', 'start', 'serve'].some((k) => pkg.scripts?.[k])
+      if (!dir.startsWith('apps/') && !runs) continue
+      seen.add(dir)
+      const n = basename(dir)
+      out.push({ slug: slugOf(n), name: pkg.name ? String(pkg.name).replace(/^@[^/]+\//, '') : n, dir, path: `${dir}/package.json` })
     }
   }
   return out.length > 1 ? out : []

package/src/lib/design-export.mjs

@@ -89,7 +89,7 @@ async function runIdOf ({ client, org, scenarioId, ref, branch }) {
   }
   if (/^v\d+$/.test(ref)) {
     const v = (await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/versions`)).find((x) => String(x.version) === ref.slice(1))
-    if (!v) throw new UserError(`${scenarioId} has no version ${ref}.`)
+    if (!v) throw new UserError(`${scenarioId} has no version ${ref}. kaloko history lists its versions.`)
     return v.id
   }
   return ref
@@ -111,7 +111,7 @@ export async function exportDesign ({ config, scenarioId, client, ref = 'design'
   const sink = exportSink(out)
   const fileOf = async (path) => {
     const res = draft ? await fetch(manifest.files_base + path) : await client.fetch(`/orgs/${org}/runs/${runId}/files/${path.split('/').map(enc).join('/')}`)
-    if (!res.ok) throw new UserError(`${path}: HTTP ${res.status}`)
+    if (!res.ok) throw new UserError(`Downloading ${path} failed (HTTP ${res.status}). Run the export again; if it keeps failing, the file may have expired with its run.`)
     return Buffer.from(await res.arrayBuffer())
   }
   // the live files keep the design folder layout: links between steps work from disk exactly as in the folder

package/src/lib/dimensions.mjs

@@ -8,6 +8,7 @@
 // `scope.variants` names the dimensions of each key; `scope.dimensions` lists the values for the canvas switchers.
 import { UserError } from './util.mjs'
 import { devicePreset, emulationOf, presetSummary, presetNames } from './devices.mjs'
+import { launchWithRetry } from './browser.mjs'
 
 export const BROWSERS = ['chromium', 'webkit', 'firefox']
 export const COLOR_SCHEMES = ['light', 'dark']
@@ -318,7 +319,7 @@ export async function launchEngine (engine, { channel, headless = true } = {}) {
   const type = pw[engine]
   if (!type) throw new UserError(`Unknown browser engine ${engine}. Use: ${BROWSERS.join(', ')}.`)
   try {
-    return await type.launch({ headless, ...(engine === 'chromium' && channel ? { channel } : {}) })
+    return await launchWithRetry(type, { headless, ...(engine === 'chromium' && channel ? { channel } : {}) })
   } catch (error) {
     if (/Executable doesn't exist|install/i.test(error.message)) throw new UserError(`${engine} is not installed for Playwright. Run: kaloko browser install --browsers ${engine}`)
     throw error

package/src/lib/docs-core.mjs

@@ -288,11 +288,12 @@ export const escapeHtml = esc
 
 /** Inline Markdown: code, bold, italics, links (safe schemes; `link(href)` may rewrite or drop them). Images are removed. */
 export function inlineHtml (s, { link = null } = {}) {
-  let out = esc(String(s).replace(/!\[[^\]]*\]\([^)]*\)/g, ''))
+  let out = esc(String(s).replace(/!\[[^[\]]*\]\([^()]*\)/g, ''))
   const codes = []
   out = out.replace(/`([^`]+)`/g, (_, c) => { codes.push(`<code>${c}</code>`); return `\u0000${codes.length - 1}\u0000` })
   out = out.replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>').replace(/__([^_]+)__/g, '<b>$1</b>').replace(/(^|[\s(])_([^_]+)_(?=$|[\s).,;:!?])/g, '$1<i>$2</i>').replace(/(^|[\s(])\*([^*\s][^*]*)\*(?=$|[\s).,;:!?])/g, '$1<i>$2</i>')
-  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_, t, href) => {
+  // no [ inside the brackets, at most one pair of ( ) in the target: a long run of [ stays linear
+  out = out.replace(/\[([^[\]]+)\]\(([^()[\]\s]+(?:\([^()\s]*\)[^()[\]\s]*)?)(?:\s+&quot;[^&]*&quot;)?\)/g, (_, t, href) => {
     const raw = href.replace(/&amp;/g, '&')
     const target = link ? link(raw) : raw
     if (target == null) return t
@@ -302,7 +303,7 @@ export function inlineHtml (s, { link = null } = {}) {
 }
 
 const LIST = /^(\s{0,3})([-*+]|\d{1,9}[.)])\s+(.*)$/
-const IMG = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g
+const IMG = /!\[([^[\]]*)\]\(([^()[\]\s]+)(?:\s+"[^"]*")?\)/g
 
 /**
  * Markdown to HTML for docs: headings (with ids), paragraphs, lists (nested by indentation), fenced code,
@@ -361,16 +362,18 @@ function blocks (lines, o) {
       continue
     }
     if (/^\s{0,3}([-*_])(\s*\1){2,}\s*$/.test(l)) { flush(); out.push('<hr>'); i++; continue }
-    if (/^\s{0,3}>/.test(l)) {
+    // quotes nest at most 16 deep; deeper > are text (100 000 levels would overflow the stack)
+    if (/^\s{0,3}>/.test(l) && (o.quoteDepth || 0) < 16) {
       flush()
       const buf = []
       while (i < lines.length && /^\s{0,3}>/.test(lines[i])) buf.push(lines[i++].replace(/^\s{0,3}>\s?/, ''))
-      out.push(`<blockquote>${blocks(buf, { ...o, notice: null })}</blockquote>`)
+      out.push(`<blockquote>${blocks(buf, { ...o, notice: null, quoteDepth: (o.quoteDepth || 0) + 1 })}</blockquote>`)
       continue
     }
     if (/^\s*\|.*\|\s*$/.test(l) && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(lines[i + 1])) {
       flush()
-      const row = (x) => x.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim())
+      // GFM: `\|` is a pipe inside a cell (also inside code), not a column break
+      const row = (x) => x.trim().replace(/^\||(?<!\\)\|$/g, '').split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, '|'))
       const head = row(l); i += 2
       const rows = []
       while (i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])) rows.push(row(lines[i++]))

package/src/lib/docs.mjs

@@ -5,7 +5,7 @@
 import { readFile, readdir, writeFile, mkdir, mkdtemp, rm } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
-import { join, resolve, relative, dirname } from 'node:path'
+import { join, resolve, relative, dirname, sep, isAbsolute } from 'node:path'
 import { tmpdir } from 'node:os'
 import { UserError, sha256 } from './util.mjs'
 import { findStepRefs, cleanVersion } from './changelog-core.mjs'
@@ -210,7 +210,9 @@ export async function unpack (buf, dir) {
   for (const [name, read] of entries) {
     if (name.endsWith('/')) continue
     const target = resolve(dir, name)
-    if (!target.startsWith(resolve(dir) + '/')) throw new UserError(`The export holds a path outside its folder: ${name}`)
+    // relative() rather than a '/' prefix test, so the check also holds with Windows separators (a\..\..\x)
+    const rel = relative(resolve(dir), target)
+    if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) || name.includes('\0')) throw new UserError(`The export holds a path outside its folder: ${name}`)
     await mkdir(dirname(target), { recursive: true })
     await writeFile(target, read())
     n++