kaloko 0.8.0 → 0.10.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

@@ -2,8 +2,10 @@
 // Every check returns { name, ok, detail, hint } so the CLI and tests can read it.
 import { appTools, macPermissions } from './apps/drivers.mjs'
 import { createServer } from 'node:net'
-import { access as exists, stat } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { access as exists, stat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { resolve, join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
 import { environment } from './config.mjs'
 import { gateOf, gateHeaders, accountFor } from './access.mjs'
 import { missing } from './secrets.mjs'
@@ -38,21 +40,38 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {Function} [o.launchEngine] async (engine) => { version } — throws when the engine is not installed
  * @param {object} [o.tools] app tools found (default: looked up on PATH)
  * @param {object[]} [o.scenarios] { file, product, module } of the scenario files (products checks)
+ * @param {boolean} [o.fix] repair what can be repaired here: install missing Playwright browsers, create the run and
+ *   scenario folders, write org: from the token into the config, ask macOS for permissions
+ * @param {Function} [o.installBrowser] async (engine) => void — installs a Playwright engine (--fix)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [] }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [], installBrowser = defaultInstall }) {
   const checks = []
-  const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
+  const add = (name, ok, detail = '', hint = '', fixed = null) => checks.push({ name, ok, detail, hint, ...(fixed ? { fixed } : {}) })
+  // --fix: install an engine, then look again; returns the version or throws what the install said
+  const installed = async (engine, retry) => { await installBrowser(engine); return retry() }
 
   const major = Number(process.versions.node.split('.')[0])
   add('node', major >= 20, `Node ${process.versions.node}`, major >= 20 ? '' : 'Kaloko needs Node 20 or newer.')
 
   add('config', true, `${file || `${root}/kaloko.config.yml`} · org ${config.org || '—'} · ${Object.keys(config.environments || {}).length} environments`)
-  if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the organization slug from kaloko.app).')
+  if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the part after kaloko.app/ when you are signed in), or run kaloko doctor --fix with a token to fill it in.')
+  await folderChecks({ config, root, fix, add })
 
-  try { const c = await launchChrome(config); add('chrome', true, c.version ? `Chrome ${c.version}` : 'Chrome found') } catch (e) { add('chrome', false, e.message.split('\n')[0].slice(0, 160), config.browser?.channel ? 'Install Google Chrome, or remove browser.channel to use bundled Chromium (npx playwright install chromium).' : 'Run: npx playwright install chromium') }
+  try { const c = await launchChrome(config); add('chrome', true, c.version ? `Chrome ${c.version}` : 'Chrome found') } catch (e) {
+    let done = null
+    // the bundled Chromium can be installed from here; a branded Chrome (browser.channel) is the person's to install
+    if (fix && !config.browser?.channel) { try { done = await installed('chromium', () => launchChrome(config)) } catch {} }
+    if (done) add('chrome', true, `Chromium ${done.version || ''}`.trim(), '', 'installed Chromium for Playwright')
+    else add('chrome', false, e.message.split('\n')[0].slice(0, 160), config.browser?.channel ? 'Install Google Chrome, or remove browser.channel to use bundled Chromium (kaloko browser install).' : fix ? 'Installing Chromium did not work; run kaloko browser install and read its output (on Linux add --with-deps).' : 'Run kaloko doctor --fix (or kaloko browser install) to install Chromium for Playwright.')
+  }
   // cross-browser runs (batch E): the Playwright engines the scenarios and walk.browsers name
   for (const engine of [...new Set([...(engines || []), ...(config.walk?.browsers || [])])].filter((e) => e !== 'chromium')) {
-    try { const v = await launchEngine(engine); add(`browser ${engine}`, true, `${engine} ${v.version || ''}`.trim()) } catch { add(`browser ${engine}`, false, `${engine} is not installed for Playwright`, `Run: kaloko browser install --browsers ${engine}${os === 'linux' ? ' --with-deps' : ''}`) }
+    try { const v = await launchEngine(engine); add(`browser ${engine}`, true, `${engine} ${v.version || ''}`.trim()) } catch {
+      let done = null
+      if (fix) { try { done = await installed(engine, () => launchEngine(engine)) } catch {} }
+      if (done) add(`browser ${engine}`, true, `${engine} ${done.version || ''}`.trim(), '', `installed ${engine} for Playwright`)
+      else add(`browser ${engine}`, false, `${engine} is not installed for Playwright`, `Run kaloko doctor --fix, or kaloko browser install --browsers ${engine}${os === 'linux' ? ' --with-deps' : ''}`)
+    }
   }
 
   for (const name of Object.keys(config.environments || {})) {
@@ -132,16 +151,21 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   else {
     try {
       const res = await fetchImpl(`${service}/api/v1/me`, { headers: { Authorization: `Bearer ${token}` } })
-      if (!res.ok) add('token', false, `${service} → HTTP ${res.status}`, res.status === 401 ? `${tokenEnv} is invalid, expired or revoked; create a new one in Settings.` : 'The service did not accept the request.')
+      if (!res.ok) add('token', false, `${service} → HTTP ${res.status}`, res.status === 401 ? `${tokenEnv} is invalid, expired or revoked. Run kaloko login for a new one (it replaces the old token), or create one in Settings → API tokens.` : `The service did not accept the request; try again in a few minutes (${service}/status).`)
       else {
         const me = await res.json()
+        // --fix: a config without org: takes the token's organization
+        if (!config.org && fix && me.org && file) {
+          const wrote = await writeOrg(file, me.org).catch(() => false)
+          if (wrote) { config.org = me.org; const i = checks.findIndex((c) => c.name === 'org'); if (i >= 0) checks[i] = { name: 'org', ok: true, detail: `org ${me.org}`, hint: '', fixed: `wrote org: ${me.org} into ${file}` } }
+        }
         const sameOrg = !config.org || me.org === config.org
         // sharing runs needs the Developer / Tester role (or admin) and, on tokens with scope sets, the upload scope
         const canShare = ['tester', 'admin'].includes(me.role) && (!Array.isArray(me.scopes) || me.scopes.includes('upload'))
         add('token', sameOrg, `${me.email} · ${me.role} · org ${me.org}${canShare ? '' : ' (this token cannot share runs)'}`, sameOrg ? '' : `The token belongs to organization "${me.org}" but the config says "${config.org}".`)
         if (!canShare) add('token role', false, Array.isArray(me.scopes) ? `${me.role} · ${me.scopes.join(', ')}` : me.role, 'kaloko share needs a Developer / Tester token with the upload scope.')
       }
-    } catch (e) { add('token', false, `${service} unreachable: ${e.message}`, 'Check your network; KALOKO_URL overrides the service URL.') }
+    } catch (e) { add('token', false, `${service} unreachable: ${e.cause?.code || e.message}`, 'Check your network or VPN; KALOKO_URL points the CLI to another service.') }
   }
 
   const jev = config.evaluators?.jev
@@ -173,6 +197,44 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   return { ok: checks.every((c) => c.ok), checks }
 }
 
+/** The run folder and the folders the scenario globs start in: reported, and created with --fix. */
+async function folderChecks ({ config, root, fix, add }) {
+  const there = (d) => exists(d).then(() => true, () => false)
+  const out = resolve(root, config.output || 'tmp/kaloko')
+  if (!await there(out)) {
+    if (fix && await mkdir(out, { recursive: true }).then(() => true, () => false)) add('folders', true, `${config.output} created`, '', `created ${config.output}`)
+  }
+  for (const pattern of config.scenarios || []) {
+    const fixed = []
+    for (const p of pattern.split('/')) { if (/[*?{[]/.test(p)) break; fixed.push(p) }
+    if (!fixed.length || fixed.length === pattern.split('/').length) continue
+    const dir = resolve(root, ...fixed)
+    if (await there(dir)) continue
+    if (fix && await mkdir(dir, { recursive: true }).then(() => true, () => false)) add(`scenarios ${fixed.join('/')}`, true, 'folder created; it has no scenarios yet', 'Draft a first one: kaloko draft <url>', `created ${fixed.join('/')}`)
+    else add(`scenarios ${fixed.join('/')}`, false, `${fixed.join('/')} does not exist (scenarios: ${pattern})`, 'Run kaloko doctor --fix to create it, then kaloko draft <url> for a first scenario.')
+  }
+}
+
+/** Writes org: <slug> into the config file, keeping its comments and layout. */
+export async function writeOrg (file, org) {
+  if (!/^[a-z0-9-]+$/.test(org)) return false
+  const text = await readFile(file, 'utf8')
+  let next
+  if (/^org:.*$/m.test(text)) next = text.replace(/^org:.*$/m, `org: ${org}`)
+  else if (/^schema:.*$/m.test(text)) next = text.replace(/^(schema:.*)$/m, `$1\norg: ${org}`)
+  else next = `org: ${org}\n${text}`
+  if (next === text) return false
+  await writeFile(file, next)
+  return true
+}
+
+/** Installs a Playwright engine with the Playwright that kaloko itself uses (same as kaloko browser install). */
+async function defaultInstall (engine) {
+  const cli = join(dirname(fileURLToPath(import.meta.resolve('playwright/package.json'))), 'cli.js')
+  const code = await new Promise((done) => spawn(process.execPath, [cli, 'install', engine], { stdio: 'inherit' }).on('close', done).on('error', () => done(1)))
+  if (code) throw new Error(`playwright install ${engine} exited with ${code}`)
+}
+
 async function defaultEngine (engine) {
   const pw = await import('playwright')
   const browser = await pw[engine].launch({ headless: true })
@@ -189,4 +251,4 @@ async function defaultLaunch (config) {
   return { version }
 }
 
-export const formatDoctor = ({ ok, checks }) => [...checks.map((c) => `${c.ok ? '✓' : '✕'} ${c.name.padEnd(16)} ${c.detail}${!c.ok && c.hint ? `\n    → ${c.hint}` : ''}`), ok ? 'All good.' : 'Fix the ✕ items above.'].join('\n')
+export const formatDoctor = ({ ok, checks }) => [...checks.map((c) => `${c.ok ? '✓' : '✕'} ${c.name.padEnd(16)} ${c.detail}${c.fixed ? ` (fixed: ${c.fixed})` : ''}${(!c.ok || c.fixed) && c.hint ? `\n    → ${c.hint}` : ''}`), ok ? 'All good.' : checks.some((c) => !c.ok && /doctor --fix/.test(c.hint || '')) ? 'Fix the ✕ items above; kaloko doctor --fix repairs the ones that say so.' : 'Fix the ✕ items above.'].join('\n')

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++
@@ -288,7 +292,7 @@ function hostedSender (config, report) {
     try { if (!client) { const { service } = await import('./service.mjs'); client = service(config) } } catch { return { skipped: 'no evaluator key (TYPESAFE_API_KEY) and no service token (KALOKO_TOKEN) for hosted evaluation' } }
     try { return { response: await client.request('POST', `/orgs/${config.org}/semantic`, JSON.parse(body)) } } catch (e) {
       const m = String(e.message || e)
-      if (/HTTP (402|403|503)/.test(m)) { report.hostedStop = m.replace(/^.*HTTP \d+: /, ''); return { skipped: report.hostedStop } }
+      if (/HTTP (402|403|503)/.test(m)) { report.hostedStop = e.serviceMessage ?? m.replace(/^.*HTTP \d+: /, ''); return { skipped: report.hostedStop } }
       return { error: m }
     }
   }

package/src/lib/figma.mjs

@@ -63,7 +63,7 @@ export function figmaClient ({ token, fetch: f = globalThis.fetch, base = figmaA
     variables: (key) => get(`/v1/files/${key}/variables/local`, { optional: true }),
     async download (url) {
       const res = await f(url)
-      if (!res.ok) throw new UserError(`Downloading a frame image failed: HTTP ${res.status}.`)
+      if (!res.ok) throw new UserError(`Downloading a frame image from Figma failed (HTTP ${res.status}). Figma's image links expire after a while; run the import again.`)
       return Buffer.from(await res.arrayBuffer())
     }
   }