kaloko 0.9.0 → 0.11.0

package/src/lib/design-origins.mjs

@@ -0,0 +1,86 @@
+// Font and asset origins on live design steps (#46, item 3). An organization admin lists the origins its designs
+// load fonts, stylesheets and images from (Google Fonts, Adobe Fonts, a company CDN); the live origin's CSP adds them
+// to style-src, font-src and img-src, never to script-src, connect-src or anything else. Shared by the service
+// (worker/src/live.js, worker/src/design-origins.js) and the CLI (`kaloko design lint`), so both read an entry alike.
+//
+//   cleanAssetOrigin(s, { reserved })   → 'https://fonts.gstatic.com' or 'https://*.cdn.example.com'; throws on anything else
+//   cleanAssetOrigins(list, opts)       → the cleaned, de-duplicated list (at most MAX_ASSET_ORIGINS); throws on a bad entry
+//   originAllowed(list, url)            → is the URL's origin covered by an entry (wildcards cover subdomains, not the apex)
+//   designCsp(appOrigin, origins)       → the Content-Security-Policy of a live design step
+
+export const MAX_ASSET_ORIGINS = 20
+/** Hosts of Kaloko itself: never a font or asset origin of a design (the app, the files host, the live origin). */
+export const RESERVED_HOSTS = ['kaloko.app', 'kaloko-usercontent.com']
+
+const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?'
+const DOMAIN = new RegExp(`^(?=.{3,253}$)(?:${LABEL}\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9]|xn--[a-z0-9-]{1,59})$`)
+const under = (host, base) => host === base || host.endsWith(`.${base}`)
+
+/** One origin as typed (" HTTPS://Fonts.GoogleAPIs.com/ ") in its stored form; throws an Error that names the entry. */
+export function cleanAssetOrigin (input, { reserved = [] } = {}) {
+  const raw = String(input ?? '').trim()
+  const shown = raw.slice(0, 80)
+  const s = raw.toLowerCase().replace(/\/$/, '')
+  const m = s.match(/^https:\/\/(\*\.)?([^/:?#@\s*]+)(?::(\d{1,5}))?$/)
+  if (!m) {
+    if (/^http:\/\//.test(s)) throw new Error(`Only https origins can be added: ${shown}`)
+    if (s.includes('*')) throw new Error(`A wildcard is allowed only as the first label (https://*.example.com): ${shown}`)
+    throw new Error(`Not an origin (https://host, without a path): ${shown}`)
+  }
+  const [, wild, host, port] = m
+  if (!DOMAIN.test(host)) throw new Error(`Not an origin (https://host, without a path): ${shown}`)
+  // a wildcard needs a registrable base at least: *.example.com, never *.com
+  if (wild && host.split('.').length < 2) throw new Error(`A wildcard needs a domain under it (https://*.example.com): ${shown}`)
+  if (port !== undefined && (Number(port) < 1 || Number(port) > 65535)) throw new Error(`Not an origin (https://host, without a path): ${shown}`)
+  for (const r of [...RESERVED_HOSTS, ...reserved].map((x) => String(x || '').toLowerCase().replace(/:\d+$/, '')).filter(Boolean)) {
+    if (under(host, r) || (wild && under(r, host))) throw new Error(`Kaloko's own hosts cannot be added: ${shown}`)
+  }
+  return `https://${wild || ''}${host}${port && port !== '443' ? `:${port}` : ''}`
+}
+
+/** A list (array, or text with one origin per line, commas or spaces) cleaned; throws on the first bad entry. */
+export function cleanAssetOrigins (list, opts = {}) {
+  const items = (Array.isArray(list) ? list : String(list ?? '').split(/[\s,;]+/)).filter((x) => String(x ?? '').trim())
+  const out = []
+  for (const x of items) { const c = cleanAssetOrigin(x, opts); if (!out.includes(c)) out.push(c) }
+  if (out.length > MAX_ASSET_ORIGINS) throw new Error(`At most ${MAX_ASSET_ORIGINS} font and asset origins.`)
+  return out
+}
+
+/** Does an entry of `list` cover the origin of `url` (a URL or an origin)? Wildcards cover subdomains at any depth. */
+export function originAllowed (list, url) {
+  let u
+  try { u = new URL(String(url).startsWith('//') ? `https:${url}` : String(url)) } catch { return false }
+  if (u.protocol !== 'https:') return false
+  return (list || []).some((entry) => {
+    const m = String(entry).match(/^https:\/\/(\*\.)?([^/:]+)(?::(\d+))?$/)
+    if (!m || (m[3] || '') !== u.port) return false
+    return m[1] ? u.hostname.endsWith(`.${m[2]}`) : u.hostname === m[2]
+  })
+}
+
+/**
+ * The CSP of a live design step. `origins` must already be cleaned (cleanAssetOrigins) and checked against the hosts
+ * of the instance: they are added to style-src, font-src and img-src only. Scripts, connections, frames, workers and
+ * forms stay on the step's own origin whatever the list says.
+ */
+export function designCsp (appOrigin, origins = []) {
+  const extra = origins.length ? ` ${origins.join(' ')}` : ''
+  return [
+    "default-src 'self'",
+    "script-src 'self' 'unsafe-inline'",
+    `style-src 'self' 'unsafe-inline'${extra}`,
+    `img-src 'self' data: blob:${extra}`,
+    `font-src 'self' data:${extra}`,
+    "media-src 'self' blob:",
+    "connect-src 'self'",
+    "frame-src 'none'",
+    "worker-src 'none'",
+    "object-src 'none'",
+    "base-uri 'self'",
+    "form-action 'none'",
+    `frame-ancestors ${appOrigin}`,
+    // opaque origin even when opened directly: no cookies, storage or service workers
+    'sandbox allow-scripts allow-forms'
+  ].join('; ')
+}

package/src/lib/design.mjs

@@ -4,7 +4,7 @@ import { createServer } from 'node:http'
 import { readFile, readdir, stat, mkdir, writeFile, copyFile, rm } from 'node:fs/promises'
 import { join, resolve, dirname, relative, sep } from 'node:path'
 import { UserError } from './util.mjs'
-import { bundleProblems, closure, contentTypeOf, revisionId, sha256Hex, TOKENS_FILE, SHARED_DIR, extOf } from './design-core.mjs'
+import { bundleProblems, closure, contentTypeOf, revisionId, sha256Hex, TOKENS_FILE, SHARED_DIR, extOf, ITEM_ID, MAX_ITEMS, itemProblems } from './design-core.mjs'
 
 export const isDesign = (env) => env?.kind === 'design'
 
@@ -31,12 +31,25 @@ async function listFiles (dir, base = dir) {
   return out
 }
 
+/**
+ * The page of a step state (#46): `<step>/<locale>/<state>.html` or `<step>/<state>.html` next to the entry, or null
+ * (the entry then renders with `?state=<name>`). `files` are the revision's paths (or a list of them).
+ */
+export function statePage (entry, state, files) {
+  if (!state || state === 'default') return entry
+  const has = (p) => (Array.isArray(files) ? files.includes(p) : !!files?.[p])
+  const dir = entry.slice(0, entry.lastIndexOf('/') + 1)
+  const node = entry.split('/')[0]
+  for (const p of [`${dir}${state}.html`, `${node}/${state}.html`]) if (has(p)) return p
+  return null
+}
+
 /**
  * The files of one step in one locale: `<step>/<locale>/…` overrides `<step>/…` (other locales' folders
  * are left out), plus every bundle file those reference. Returns { entry, files: [{ path, bytes, hash }] }
- * or null when the step has no folder.
+ * or null when the step has no folder. `states` (#46): the pages of the step's states travel with it.
  */
-export async function scanStep ({ dir, node, locale, locales }) {
+export async function scanStep ({ dir, node, locale, locales, states = [] }) {
   const stepDir = join(dir, node)
   if (!await exists(stepDir)) return null
   const own = await listFiles(stepDir)
@@ -51,7 +64,9 @@ export async function scanStep ({ dir, node, locale, locales }) {
   const beside = (entryDir === `${node}/` ? common : mine.map((p) => p.slice(locale.length + 1))).filter((p) => !p.includes('/') && extOf(p) !== 'html')
   // a page of its own for the dark colour scheme (<step>/dark/index.html, or per locale): part of the revision
   const dark = own.includes(`${entryDir.slice(node.length + 1)}dark/index.html`) ? [`${entryDir}dark/index.html`] : []
-  const roots = [entry, ...dark, ...beside.map((p) => entryDir + p)]
+  // pages of the step's states (<step>/<state>.html, or per locale): part of the revision like the dark page
+  const stateRoots = (states || []).filter((s) => s !== 'default').map((s) => statePage(entry, s, own.map((p) => `${node}/${p}`))).filter(Boolean)
+  const roots = [entry, ...dark, ...stateRoots, ...beside.map((p) => entryDir + p)]
   const paths = await closure({ roots, read: (p) => readFile(join(dir, p), 'utf8'), exists: (p) => isFile(join(dir, p)) })
   const files = []
   for (const path of paths) {
@@ -63,6 +78,94 @@ export async function scanStep ({ dir, node, locale, locales }) {
   return { entry, files }
 }
 
+/**
+ * Items of a stack step as `items.urls` names them, when they name folders of the step (`refund`, `./refund/`,
+ * `refund/index.html`): a list of folder names. Null when the step lists app URLs (`/credit?reason=x`), uses another
+ * source (sitemap, file, crawl, script) or lists nothing: then the item folders are discovered.
+ */
+export function listedItems (node) {
+  const urls = node?.items?.urls
+  if (!Array.isArray(urls) || !urls.length) return null
+  const ids = urls.map((u) => String(u).trim().replace(/^\.\//, '').replace(/\/index\.html$/, '').replace(/\/+$/, ''))
+  return ids.every((id) => ITEM_ID.test(id) && id !== '.' && id !== '..') ? [...new Set(ids)] : null
+}
+
+/** Folder names inside a step folder that are not items: locale overrides, the dark page and _private folders. */
+const notItem = (name, locales) => locales.includes(name) || name === 'dark' || name.startsWith('_') || name.startsWith('.')
+
+/**
+ * The item folders of a stack step (#61): `<step>/<item>/index.html` (or `<step>/<item>/<locale>/index.html`), in the
+ * order `items.urls` lists them, else every subfolder with a page, sorted by name. Returns [{ id, listed }]; a listed
+ * folder without a page is still returned, so the walk and the lint can name it.
+ */
+export async function stackItems ({ dir, node, locales }) {
+  const stepDir = join(dir, node.id)
+  const listed = listedItems(node)
+  if (listed) return listed.map((id) => ({ id, listed: true }))
+  let entries = []
+  try { entries = await readdir(stepDir, { withFileTypes: true }) } catch { return [] }
+  const out = []
+  for (const e of entries.filter((x) => x.isDirectory() && !notItem(x.name, locales) && ITEM_ID.test(x.name)).sort((a, b) => a.name.localeCompare(b.name))) {
+    const has = await isFile(join(stepDir, e.name, 'index.html')) || (await Promise.all(locales.map((l) => isFile(join(stepDir, e.name, l, 'index.html'))))).some(Boolean)
+    if (has) out.push({ id: e.name, listed: false })
+  }
+  return out
+}
+
+/** Entry of a folder (`<base>/<locale>/index.html` over `<base>/index.html`) and the roots of its revision. */
+async function folderRoots ({ dir, base, locale, locales, states = [] }) {
+  const own = await listFiles(join(dir, base))
+  const localeDirs = new Set(locales)
+  const common = own.filter((p) => !localeDirs.has(p.split('/')[0]))
+  const mine = own.filter((p) => p.split('/')[0] === locale)
+  const entry = mine.includes(`${locale}/index.html`) ? `${base}/${locale}/index.html` : common.includes('index.html') ? `${base}/index.html` : null
+  if (!entry) return null
+  const entryDir = entry.slice(0, entry.lastIndexOf('/') + 1)
+  const beside = (entryDir === `${base}/` ? common : mine.map((p) => p.slice(locale.length + 1))).filter((p) => !p.includes('/') && extOf(p) !== 'html')
+  const dark = own.includes(`${entryDir.slice(base.length + 1)}dark/index.html`) ? [`${entryDir}dark/index.html`] : []
+  // step states (#46) of a variant: <step>/<variant>/<state>.html (or per locale) next to its page
+  const ownPaths = own.map((p) => `${base}/${p}`)
+  const stateRoots = (states || []).filter((s) => s !== 'default').map((s) => [`${entryDir}${s}.html`, `${base}/${s}.html`].find((p) => ownPaths.includes(p))).filter(Boolean)
+  return { entry, roots: [entry, ...dark, ...stateRoots, ...beside.map((p) => entryDir + p)] }
+}
+
+/**
+ * The files of a stack step in one locale (#61): every item's page with what it references, and the optional overview
+ * (`<step>/index.html`). The revision covers the whole step folder; its entry is the overview, else the first item.
+ * Returns { entry, items: [{ id, entry }], files } or null when the step has no folder.
+ */
+export async function scanStack ({ dir, node, locale, locales }) {
+  if (!await exists(join(dir, node.id))) return null
+  const found = await stackItems({ dir, node, locales })
+  if (!found.length) throw new UserError(`Design step ${node.id} is a stack: add a folder per variant with a page, ${node.id}/<variant>/index.html.`)
+  if (found.length > MAX_ITEMS) throw new UserError(`Design step ${node.id} has ${found.length} variants; a stack step holds at most ${MAX_ITEMS}.`)
+  const items = []
+  const roots = []
+  for (const it of found) {
+    const r = await folderRoots({ dir, base: `${node.id}/${it.id}`, locale, locales, states: node.states })
+    if (!r) throw new UserError(`Design step ${node.id}: variant ${it.id} has no page; add ${node.id}/${it.id}/index.html.`)
+    items.push({ id: it.id, entry: r.entry })
+    roots.push(...r.roots)
+  }
+  // the overview: only the step folder's own page and the files beside it, never the item folders (they come above)
+  const own = await listFiles(join(dir, node.id))
+  const overviewEntry = own.includes(`${locale}/index.html`) ? `${node.id}/${locale}/index.html` : own.includes('index.html') ? `${node.id}/index.html` : null
+  if (overviewEntry) {
+    const at = overviewEntry.slice(0, overviewEntry.lastIndexOf('/') + 1)
+    roots.unshift(overviewEntry, ...own.map((p) => `${node.id}/${p}`).filter((p) => p.startsWith(at) && !p.slice(at.length).includes('/') && extOf(p) !== 'html'))
+  }
+  const paths = await closure({ roots, read: (p) => readFile(join(dir, p), 'utf8'), exists: (p) => isFile(join(dir, p)) })
+  const files = []
+  for (const path of paths) {
+    const buf = await readFile(join(dir, path))
+    files.push({ path, bytes: buf.length, hash: await sha256Hex(buf) })
+  }
+  const entry = overviewEntry || items[0].entry
+  const problems = [...bundleProblems(files, entry), ...itemProblems(items, Object.fromEntries(files.map((f) => [f.path, f.hash])), node.id)]
+  if (problems.length) throw new UserError(`Design step ${node.id} (${locale}) breaks the bundle rules:\n  - ${problems.join('\n  - ')}`)
+  return { entry, items, files }
+}
+
 /** Token set reference of the design folder (tokens.json), or null. */
 export async function tokensRef (dir, project) {
   const file = join(dir, TOKENS_FILE)
@@ -73,8 +176,9 @@ export async function tokensRef (dir, project) {
 }
 
 /** A revision of one step and locale, with its id. */
-export async function revisionOf ({ dir, scenario, node, locale, locales, tokens }) {
-  const scan = await scanStep({ dir, node, locale, locales })
+export async function revisionOf ({ dir, scenario, node, locale, locales, tokens, states = [], stack = null }) {
+  // `stack`: the scenario node of a stack step (#61); its revision covers every item folder; `states` (#46): their pages
+  const scan = stack ? await scanStack({ dir, node: stack, locale, locales }) : await scanStep({ dir, node, locale, locales, states })
   if (!scan) return null
   // the token set travels with every revision: the canvas inspector names values from it on the live origin
   if (tokens && !scan.files.some((f) => f.path === TOKENS_FILE)) {
@@ -82,8 +186,8 @@ export async function revisionOf ({ dir, scenario, node, locale, locales, tokens
     scan.files.push({ path: TOKENS_FILE, bytes: buf.length, hash: await sha256Hex(buf) })
   }
   const files = Object.fromEntries(scan.files.map((f) => [f.path, f.hash]))
-  const id = await revisionId({ scenario, node, locale, entry: scan.entry, files, tokens })
-  return { id, scenario, node, locale, state: 'default', kind: 'design', entry: scan.entry, files, sizes: Object.fromEntries(scan.files.map((f) => [f.path, f.bytes])), tokens }
+  const id = await revisionId({ scenario, node, locale, entry: scan.entry, files, tokens, items: scan.items || null })
+  return { id, scenario, node, locale, state: 'default', kind: 'design', entry: scan.entry, ...(scan.items ? { items: scan.items } : {}), files, sizes: Object.fromEntries(scan.files.map((f) => [f.path, f.bytes])), tokens }
 }
 
 /**

package/src/lib/dimensions.mjs

@@ -9,6 +9,7 @@
 import { UserError } from './util.mjs'
 import { devicePreset, emulationOf, presetSummary, presetNames } from './devices.mjs'
 import { launchWithRetry } from './browser.mjs'
+import { STATE_PREFIX, stateOfKey, statesOf } from './manifest-core.mjs'
 
 export const BROWSERS = ['chromium', 'webkit', 'firefox']
 export const COLOR_SCHEMES = ['light', 'dark']
@@ -22,8 +23,15 @@ export const DIMENSIONS = [
   { name: 'color_scheme', list: 'color_schemes', values: COLOR_SCHEMES, default: 'light', suffix: (v) => v },
   { name: 'reduced_motion', list: 'reduced_motion', values: REDUCED_MOTION, default: 'no-preference', suffix: () => 'reduce' },
   { name: 'forced_colors', list: 'forced_colors', values: FORCED_COLORS, default: 'none', suffix: () => 'forced' },
-  { name: 'display_mode', list: 'display_modes', values: DISPLAY_MODES, default: 'browser', suffix: (v) => v }
+  { name: 'display_mode', list: 'display_modes', values: DISPLAY_MODES, default: 'browser', suffix: (v) => v },
+  // token modes of a design's token set (#46): brand-a, high-contrast…; the default mode (the environment's
+  // tokens_mode, else the first) is the first of the list and is left out of keys
+  { name: 'token_mode', list: 'token_modes', values: null, default: null, suffix: (v) => `mode-${v}` },
+  // step states (#46): default, empty, error, loading or any name a step lists in `states:`; always the last part
+  { name: 'step_state', list: 'states', values: null, default: 'default', suffix: (v) => `${STATE_PREFIX}${v}` }
 ]
+/** Names of token modes and states: they are parts of capture keys and file names. */
+export const FREE_VALUE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/
 const ALIASES = { chrome: 'chromium', safari: 'webkit', gecko: 'firefox', 'no-motion': 'reduce', reduced: 'reduce', 'no_preference': 'no-preference', high_contrast: 'active', 'high-contrast': 'active', forced: 'active', pwa: 'standalone', installed: 'standalone' }
 
 const asList = (v) => v == null ? null : Array.isArray(v) ? v.map(String) : String(v).split(',').map((s) => s.trim()).filter(Boolean)
@@ -35,6 +43,11 @@ export function dimensionValues (dim, raw) {
   if (!list?.length) return null
   const out = []
   for (const v0 of list) {
+    if (!d.values) {
+      if (!FREE_VALUE.test(v0)) throw new UserError(`${d.list.replace(/_/g, ' ')}: "${v0}" is not a valid name (letters, digits, - and _; at most 40).`)
+      if (!out.includes(v0)) out.push(v0)
+      continue
+    }
     const v = ALIASES[v0.toLowerCase()] || v0.toLowerCase()
     if (!d.values.includes(v)) throw new UserError(`Unknown ${d.list.replace(/_/g, ' ')} value "${v0}". Use: ${d.values.join(', ')}.`)
     if (!out.includes(v)) out.push(v)
@@ -52,12 +65,28 @@ export function dimensionsFrom ({ args = {}, scenario = {}, config = {} } = {})
   const out = {}
   for (const d of DIMENSIONS) {
     const flag = d.list.replace(/_/g, '-')
+    if (d.name === 'step_state') { out.states = scenarioStates(scenario, args.states); continue }
+    // token modes come from the design's token set (startScope); here only an explicit choice
     const raw = args[flag] ?? args[d.list] ?? scenario?.[d.list] ?? walk[d.list]
-    out[d.list] = dimensionValues(d.name, raw)
+    out[d.list] = raw === false || raw === 'false' || raw === 'none' ? (d.name === 'token_mode' ? false : null) : dimensionValues(d.name, raw)
   }
   return out
 }
 
+/**
+ * The states of a run (#46): `default` and every state a step lists in `states:`, in scenario order; null when no
+ * step has states. `pick` (kaloko start --states) narrows them; default always stays.
+ */
+export function scenarioStates (scenario, pick = null) {
+  const all = []
+  for (const n of scenario?.nodes || []) for (const s of statesOf(n)) if (!all.includes(s)) all.push(s)
+  if (all.length < 2) return null
+  const want = pick ? dimensionValues('step_state', pick) : null
+  if (want) for (const s of want) if (!all.includes(s)) throw new UserError(`No step of this scenario has the state "${s}" (states: ${all.slice(1).join(', ')}).`)
+  const out = want ? all.filter((s) => s === 'default' || want.includes(s)) : all
+  return out.length > 1 ? out : null
+}
+
 /**
  * Viewports of a scenario: { name: [w, h] } as before, or names of device presets — as an array
  * (`[iphone-15, ipad-landscape, desktop]`) or as values (`phone: iphone-15`, `tablet: { device: ipad-portrait }`,
@@ -100,12 +129,14 @@ export function appDevices (ids, platform) {
   return { viewports, devices }
 }
 
-/** The capture key of a viewport and dimension values: defaults are left out. */
-export function variantKey (viewport, dims = {}) {
+/** The capture key of a viewport and dimension values: defaults are left out (`defaults`: the run's own, token mode). */
+export function variantKey (viewport, dims = {}, defaults = {}) {
   const parts = [viewport]
-  for (const d of DIMENSIONS) { const v = dims[d.name]; if (v && v !== d.default) parts.push(d.suffix(v)) }
+  for (const d of DIMENSIONS) { const v = dims[d.name]; if (v && v !== (defaults[d.name] ?? d.default)) parts.push(d.suffix(v)) }
   return parts.join('.')
 }
+/** Defaults a scope sets itself: the token mode left out of keys is the first of its modes. */
+export const scopeDefaults = (scope) => (scope?.dimensions?.token_modes?.length ? { token_mode: scope.dimensions.token_modes[0] } : {})
 
 /**
  * Scope of a run: every combination of viewport and dimension values as a capture key with its size, and the
@@ -119,10 +150,11 @@ export function expandScope ({ locales, viewports, devices = {}, dims = {} }) {
   const out = {}; const variants = {}
   let combos = [{}]
   for (const [d, l] of used) combos = combos.flatMap((c) => l.map((v) => ({ ...c, [d.name]: v })))
+  const defaults = dims.token_modes?.length ? { token_mode: dims.token_modes[0] } : {}
   for (const [name, size] of Object.entries(viewports)) {
     const device = devices[name] || null
     for (const c of combos) {
-      const key = variantKey(name, c)
+      const key = variantKey(name, c, defaults)
       let s = size
       // installed PWA: the whole screen of a preset without the browser's bars (the status bar stays)
       if (c.display_mode === 'standalone' && device?.screen) s = [size[0], Math.max(size[1], device.screen[1] - (device.safe?.top || 0))]
@@ -130,7 +162,7 @@ export function expandScope ({ locales, viewports, devices = {}, dims = {} }) {
       variants[key] = { viewport: name, browser: c.browser || 'chromium', ...c, ...(device ? { device: name } : {}) }
     }
   }
-  if (Object.keys(out).length > 400) throw new UserError(`This scope has ${Object.keys(out).length} combinations of viewport, browser, colour scheme and motion; keep it under 400 (pick fewer viewports or values).`)
+  if (Object.keys(out).length > 400) throw new UserError(`This scope has ${Object.keys(out).length} combinations of viewport, browser, colour scheme, motion, token mode and state; keep it under 400 (pick fewer viewports or values).`)
   const dimensions = Object.fromEntries(used.map(([d, l]) => [d.list, l]))
   return { ...loc, viewports: out, variants, ...(used.length ? { dimensions } : {}), ...(Object.keys(devices).length ? { devices } : {}) }
 }
@@ -147,10 +179,27 @@ export function variantOf (scope, key) {
     else if (part === 'reduce') out.reduced_motion = 'reduce'
     else if (part === 'forced') out.forced_colors = 'active'
     else if (part === 'standalone') out.display_mode = 'standalone'
+    else if (part.startsWith('mode-')) out.token_mode = part.slice(5)
+    else if (part.startsWith(STATE_PREFIX)) out.step_state = part.slice(STATE_PREFIX.length)
   }
   return out
 }
 
+/** The step state of a capture key ('default' when the key has none). */
+export const stateOf = (key) => stateOfKey(key)
+
+/**
+ * Keys of `state` for keys of the default state (a walk pass, a device): `mobile` → `mobile.state-empty`, only those
+ * the scope has. The default state gives the keys back.
+ */
+export function stateKeys (scope, keys, state = 'default') {
+  if (!state || state === 'default') return keys.filter((k) => stateOfKey(k) === 'default')
+  return keys.filter((k) => stateOfKey(k) === 'default').map((k) => `${k}.${STATE_PREFIX}${state}`).filter((k) => scope?.viewports?.[k])
+}
+
+/** The states a walk captures a step in: its `states:` that the run has, default first. */
+export const nodeStates = (scope, node) => statesOf(node).filter((s) => s === 'default' || scope?.dimensions?.states?.includes(s))
+
 /** The fields a capture record and a manifest capture carry for its dimensions (only those that were set). */
 export function variantFields (scope, key) {
   const v = scope?.variants?.[key]
@@ -167,7 +216,8 @@ export function variantFields (scope, key) {
  * `only` limits the engines (walk --browsers).
  */
 export function passesOf (scope, { only = null } = {}) {
-  const keys = Object.keys(scope?.viewports || {})
+  // keys of other step states are captured by the same passes, one step script invocation per state
+  const keys = Object.keys(scope?.viewports || {}).filter((k) => stateOfKey(k) === 'default')
   const passes = new Map()
   for (const key of keys) {
     const v = variantOf(scope, key)
@@ -300,15 +350,19 @@ export function referenceKey (key, available, scope = null) {
   const have = new Set(available || [])
   if (have.has(key)) return key
   const v = variantOf(scope, key)
-  const chromium = variantKey(v.viewport, { ...v, browser: 'chromium' })
+  const defaults = scopeDefaults(scope)
+  const chromium = variantKey(v.viewport, { ...v, browser: 'chromium' }, defaults)
   if (have.has(chromium)) return chromium
   // a reference without a colour scheme dimension (light by default) answers for light captures
-  if (!v.color_scheme || v.color_scheme === 'light') { const plain = variantKey(v.viewport, { ...v, browser: 'chromium', color_scheme: null }); if (have.has(plain)) return plain }
+  if (!v.color_scheme || v.color_scheme === 'light') { const plain = variantKey(v.viewport, { ...v, browser: 'chromium', color_scheme: null }, defaults); if (have.has(plain)) return plain }
   return null
 }
 
-/** Token mode of a capture: its colour scheme when the token set has that mode, else the environment's mode. */
-export const tokenModeOf = (variant, modes = [], fallback = null) => (variant?.color_scheme && modes.includes(variant.color_scheme) ? variant.color_scheme : fallback)
+/**
+ * Token mode of a capture: the token mode it was rendered in (#46), else its colour scheme when the token set has
+ * that mode, else the environment's mode.
+ */
+export const tokenModeOf = (variant, modes = [], fallback = null) => (variant?.token_mode && modes.includes(variant.token_mode) ? variant.token_mode : variant?.color_scheme && modes.includes(variant.color_scheme) ? variant.color_scheme : fallback)
 
 /** Engines a scope needs (for `kaloko browser install` hints and doctor). */
 export const enginesOf = (scope) => [...new Set(Object.keys(scope?.viewports || {}).map((k) => variantOf(scope, k).browser))]

package/src/lib/doctor.mjs

@@ -237,7 +237,8 @@ async function defaultInstall (engine) {
 
 async function defaultEngine (engine) {
   const pw = await import('playwright')
-  const browser = await pw[engine].launch({ headless: true })
+  const { launchWithRetry } = await import('./browser.mjs')
+  const browser = await launchWithRetry(pw[engine], { headless: true })
   const version = browser.version()
   await browser.close()
   return { version }
@@ -245,7 +246,8 @@ async function defaultEngine (engine) {
 
 async function defaultLaunch (config) {
   const { chromium } = await import('playwright')
-  const browser = await chromium.launch({ headless: true, channel: config.browser?.channel || undefined })
+  const { launchWithRetry } = await import('./browser.mjs')
+  const browser = await launchWithRetry(chromium, { headless: true, channel: config.browser?.channel || undefined })
   const version = browser.version()
   await browser.close()
   return { version }

package/src/lib/drift.mjs

@@ -85,7 +85,7 @@ export async function driftForCapture ({ node, entry, capture, runDir, ctx }) {
       const refCaps = !ctx.isDesign ? (await referenceStep(ctx, node.id, entry.locale))?.captures : null
       const refStyles = refCaps ? refCaps[referenceKey(entry.viewport, Object.keys(refCaps))]?.design?.styles : null
       // a dark capture is checked against the dark mode of the token set (DTCG modes light/dark)
-      const off = tokenOffenders(capture.design?.styles, ctx.tokens, tokenModeOf({ color_scheme: capture.color_scheme }, modesOf(ctx.tokens), ctx.mode), refStyles)
+      const off = tokenOffenders(capture.design?.styles, ctx.tokens, tokenModeOf({ color_scheme: capture.color_scheme, token_mode: capture.token_mode }, modesOf(ctx.tokens), ctx.mode), refStyles)
       if (off == null) { results[c.id] = { ok: null, evidence: 'Capture has no style summary; capture this step again.' }; continue }
       results[c.id] = off.length
         ? { ok: false, evidence: `${off.length} value(s) outside the token set: ${off.slice(0, 5).map((o) => `${o.property} ${o.value}${o.suggest ? ` → ${o.suggest}` : ''}`).join('; ')}` }

package/src/lib/evaluate.mjs

@@ -8,6 +8,7 @@ import { KEYBOARD_ASSERTS } from './keyboard.mjs'
 import { needsDrift, driftForCapture, loadTokens, driftCacheDir } from './drift.mjs'
 import { packHelp } from './pack-help.mjs'
 import { tokenCriteria, storedValueChecks, STYLE_ASSERTS } from './assertions.mjs'
+import { appliesToState } from './manifest-core.mjs'
 
 /** Latest capture per node/locale/viewport. */
 export function latestCaptures (entries) {
@@ -19,6 +20,8 @@ export function latestCaptures (entries) {
 export const criteriaHash = (node) => sha256(node.criteria || [])
 /** A criterion with `environments` (e.g. [production]) applies only there; without a known environment it applies. */
 export const appliesOn = (c, environment) => !environment || !Array.isArray(c.environments) || !c.environments.length || c.environments.includes(environment)
+/** Environment and step state (#46): a criterion with `states:` applies only to captures of those states. */
+export const appliesTo = (c, environment, capture) => appliesOn(c, environment) && appliesToState(c, capture?.step_state)
 /** Folder of a capture under steps/: the node, or steps/<node>/items/<item> for a page of a stack step. */
 export const stepIdOf = (e) => (e.item ? `${e.node}/items/${e.item}` : e.node)
 export const evaluationSource = (node, capture) => sha256({ capture, criteria: node.criteria || [], purpose: node.purpose || '' })
@@ -31,6 +34,7 @@ export const evaluationSource = (node, capture) => sha256({ capture, criteria: n
 export function combine ({ node, capture, jev, vision = null, thresholds, environment = null }) {
   return (node.criteria || []).map((c) => {
     if (!appliesOn(c, environment)) return { id: c.id, type: c.check.type, verdict: 'not_evaluated', evidence: `Applies on ${c.environments.join(', ')} only; this walk ran on ${environment}.`, na: true, not_applicable: 'environment' }
+    if (!appliesToState(c, capture?.step_state)) return { id: c.id, type: c.check.type, verdict: 'not_evaluated', evidence: `Applies to the state${c.states.length > 1 ? 's' : ''} ${c.states.join(', ')} only; this capture shows ${capture?.step_state || 'default'}.`, na: true, not_applicable: 'state' }
     if (c.check.type === 'deterministic') {
       const r = capture.checks?.[c.id]
       const verdict = r == null || r.ok == null ? 'not_evaluated' : r.ok ? 'pass' : 'fail'
@@ -106,7 +110,7 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       const current = capture.criteria_hash === criteriaHash(node)
       // console triage needs the evaluator only when the capture has console errors
       const outOfSample = entry.item && !sampled.get(entry.node)?.has(entry.item)
-      const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && appliesOn(c, environment) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
+      const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && appliesTo(c, environment, capture) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
       // quick signals ride along on every captured page state (also steps without semantic criteria)
       const signals = settings.signals !== false && !outOfSample && !!capture.state
       // an imported screen without page text (#11) has nothing to ask about: a person decides on the canvas
@@ -206,7 +210,7 @@ export function semanticPrefetch ({ scenario, config, root, environment = null }
         if (!semantic.length && settings.signals === false) continue
         queue.push(async () => {
           const capture = await readJson(join(runDir, e.file))
-          const crit = semantic.filter((c) => !(c.check.about === 'console' && !(capture.console_errors || []).length))
+          const crit = semantic.filter((c) => appliesToState(c, capture.step_state) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
           const signals = settings.signals !== false && !!capture.state
           if ((!crit.length && !signals) || capture.criteria_hash !== criteriaHash(node)) return
           asked++