kaloko 0.4.11 → 0.5.0

package/src/lib/dimensions.mjs

@@ -0,0 +1,326 @@
+// Run dimensions beyond locale and viewport (batch E): browser engine, colour scheme, reduced motion, forced colours
+// and display mode (installed PWA), plus device presets in `viewports:`.
+//
+// Every combination is one capture key, so the run layout and the service stay as they are
+// (steps/<node>/<locale>/<key>.*): the key is the viewport name followed by the values that differ from the
+// default, joined by dots — `mobile`, `mobile.webkit`, `iphone-15.webkit.dark.reduce`. A run without dimensions has
+// plain viewport keys, and a capture without a browser in its key is Chromium (every run before batch E).
+// `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'
+
+export const BROWSERS = ['chromium', 'webkit', 'firefox']
+export const COLOR_SCHEMES = ['light', 'dark']
+export const REDUCED_MOTION = ['no-preference', 'reduce']
+export const FORCED_COLORS = ['none', 'active']
+export const DISPLAY_MODES = ['browser', 'standalone']
+
+/** The dimensions, their default value (left out of keys) and the key suffix of the other values. */
+export const DIMENSIONS = [
+  { name: 'browser', list: 'browsers', values: BROWSERS, default: 'chromium', suffix: (v) => v },
+  { 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 }
+]
+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)
+
+/** Normalises one dimension's list (CLI string or YAML array); unknown values are a UserError naming the valid ones. */
+export function dimensionValues (dim, raw) {
+  const d = DIMENSIONS.find((x) => x.name === dim || x.list === dim)
+  const list = asList(raw)
+  if (!list?.length) return null
+  const out = []
+  for (const v0 of list) {
+    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)
+  }
+  return out
+}
+
+/**
+ * The run's dimensions from the CLI (--browsers, --color-schemes, --reduced-motion, --forced-colors,
+ * --display-modes), the scenario and the config's `walk:` block, in that order. Lists that are not set stay null:
+ * nothing is emulated for them.
+ */
+export function dimensionsFrom ({ args = {}, scenario = {}, config = {} } = {}) {
+  const walk = config?.walk || {}
+  const out = {}
+  for (const d of DIMENSIONS) {
+    const flag = d.list.replace(/_/g, '-')
+    const raw = args[flag] ?? args[d.list] ?? scenario?.[d.list] ?? walk[d.list]
+    out[d.list] = dimensionValues(d.name, raw)
+  }
+  return out
+}
+
+/**
+ * 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 }`,
+ * `tv: { device: tv-1080p, width: 1280, height: 720 }`). Returns { viewports: { name: [w, h] }, devices: { name: preset } }.
+ * `fullScreen` (Design environments) sizes presets to the whole screen.
+ */
+export function resolveViewports (spec, { fullScreen = false, fallback = { desktop: [1280, 800], mobile: [390, 844] } } = {}) {
+  const viewports = {}; const devices = {}
+  const entries = spec == null ? Object.entries(fallback) : Array.isArray(spec) ? spec.map((s) => (typeof s === 'string' ? [s, s] : Object.entries(s)[0])) : Object.entries(spec)
+  for (const [name, value] of entries) {
+    if (Array.isArray(value)) { viewports[name] = [Number(value[0]), Number(value[1])]; continue }
+    const ref = typeof value === 'string' ? { device: value } : value || {}
+    const preset = devicePreset(ref.device, { fullScreen: ref.full_screen ?? fullScreen })
+    if (!preset) {
+      // a bare name that is no preset, e.g. `viewports: [desktop]`: the default size of that name
+      if (typeof value === 'string' && fallback[value]) { viewports[name] = fallback[value]; continue }
+      throw new UserError(`Viewport "${name}": unknown device "${ref.device}". Presets: ${presetNames().join(', ')} (and <preset>-landscape).`)
+    }
+    viewports[name] = [Number(ref.width) || preset.size[0], Number(ref.height) || preset.size[1]]
+    devices[name] = presetSummary({ ...preset, size: viewports[name] })
+    devices[name].emulation = emulationOf(preset)
+  }
+  return { viewports, devices }
+}
+
+/**
+ * Devices of an app scenario (`devices: [pixel-8-api-34, iphone-15-ios-18]`) as capture keys: the size and frame
+ * come from the longest preset the name starts with (pixel-8, iphone-15), else a common phone of the platform.
+ */
+export function appDevices (ids, platform) {
+  const viewports = {}; const devices = {}
+  for (const id of ids || []) {
+    const parts = String(id).toLowerCase().split('-')
+    let preset = null
+    for (let n = parts.length; n > 0 && !preset; n--) preset = devicePreset(parts.slice(0, n).join('-'), { fullScreen: true })
+    preset ||= devicePreset(platform === 'ios' ? 'iphone-15' : platform === 'android' ? 'pixel-8' : 'laptop', { fullScreen: true })
+    viewports[id] = preset.size
+    devices[id] = { ...presetSummary(preset), name: id, title: preset.name === id ? preset.title : id, app: true }
+  }
+  return { viewports, devices }
+}
+
+/** The capture key of a viewport and dimension values: defaults are left out. */
+export function variantKey (viewport, dims = {}) {
+  const parts = [viewport]
+  for (const d of DIMENSIONS) { const v = dims[d.name]; if (v && v !== d.default) parts.push(d.suffix(v)) }
+  return parts.join('.')
+}
+
+/**
+ * Scope of a run: every combination of viewport and dimension values as a capture key with its size, and the
+ * dimensions of each key. Without dimensions and presets it is the plain { locales, viewports } of before.
+ */
+export function expandScope ({ locales, viewports, devices = {}, dims = {} }) {
+  const lists = DIMENSIONS.map((d) => [d, dims[d.list] || null])
+  const used = lists.filter(([, l]) => l)
+  const loc = locales ? { locales } : {}
+  if (!used.length && !Object.keys(devices).length) return { ...loc, viewports }
+  const out = {}; const variants = {}
+  let combos = [{}]
+  for (const [d, l] of used) combos = combos.flatMap((c) => l.map((v) => ({ ...c, [d.name]: v })))
+  for (const [name, size] of Object.entries(viewports)) {
+    const device = devices[name] || null
+    for (const c of combos) {
+      const key = variantKey(name, c)
+      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))]
+      out[key] = s
+      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).`)
+  const dimensions = Object.fromEntries(used.map(([d, l]) => [d.list, l]))
+  return { ...loc, viewports: out, variants, ...(used.length ? { dimensions } : {}), ...(Object.keys(devices).length ? { devices } : {}) }
+}
+
+/** Dimensions of a capture key: from the scope, or parsed from the key for runs that only have the key. */
+export function variantOf (scope, key) {
+  const v = scope?.variants?.[key]
+  if (v) return { browser: 'chromium', ...v }
+  const [viewport, ...rest] = String(key).split('.')
+  const out = { viewport, browser: 'chromium' }
+  for (const part of rest) {
+    if (BROWSERS.includes(part)) out.browser = part
+    else if (part === 'dark' || part === 'light') out.color_scheme = part
+    else if (part === 'reduce') out.reduced_motion = 'reduce'
+    else if (part === 'forced') out.forced_colors = 'active'
+    else if (part === 'standalone') out.display_mode = 'standalone'
+  }
+  return out
+}
+
+/** 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]
+  if (!v) return {}
+  const out = { browser: v.browser || 'chromium' }
+  for (const d of DIMENSIONS.slice(1)) if (v[d.name]) out[d.name] = v[d.name]
+  if (v.device) out.device_preset = v.device
+  return out
+}
+
+/**
+ * Walk passes of a web run: one browser context per engine and device profile (pixel ratio, mobile, touch, user
+ * agent), each capturing only its own keys. The first pass (Chromium, default profile) is the walk of before.
+ * `only` limits the engines (walk --browsers).
+ */
+export function passesOf (scope, { only = null } = {}) {
+  const keys = Object.keys(scope?.viewports || {})
+  const passes = new Map()
+  for (const key of keys) {
+    const v = variantOf(scope, key)
+    if (only && !only.includes(v.browser)) continue
+    const dev = v.device ? scope.devices?.[v.device] : null
+    const emu = dev?.emulation || null
+    const id = `${v.browser}|${emu ? emu.key : ''}`
+    if (!passes.has(id)) passes.set(id, { engine: v.browser, emulation: emu, keys: [], label: [v.browser !== 'chromium' ? v.browser : null, dev ? dev.title : null].filter(Boolean).join(' · ') })
+    passes.get(id).keys.push(key)
+  }
+  // the plain Chromium pass first: it may use the shared browser and its signed-in context
+  return [...passes.values()].sort((a, b) => (rank(a) - rank(b)))
+}
+const rank = (p) => (p.engine === 'chromium' ? 0 : BROWSERS.indexOf(p.engine) * 10) + (p.emulation ? 1 : 0)
+
+/** Playwright context options of a pass (device profile); Firefox has no mobile viewport mode. */
+export function contextOptionsOf (pass) {
+  const e = pass?.emulation
+  if (!e) return {}
+  return { deviceScaleFactor: e.dpr, hasTouch: e.touch, ...(e.ua ? { userAgent: e.ua } : {}), ...(pass.engine !== 'firefox' ? { isMobile: e.mobile } : {}) }
+}
+
+/**
+ * Keys a script or stack step asks for (`capture({ viewports: ['mobile'] })`) within a pass: a base viewport name
+ * selects its variants of the pass; a full key selects itself.
+ */
+export function pickKeys (scope, passKeys, names) {
+  if (!names) return passKeys
+  return passKeys.filter((k) => names.includes(k) || names.includes(variantOf(scope, k).viewport))
+}
+
+/**
+ * Emulates the key's colour scheme, motion, forced colours and display mode on the page; returns an undo function.
+ * A full-screen device (Design, installed PWA) also gets its safe areas as CSS variables --kaloko-safe-top/right/
+ * bottom/left: browsers on a computer report env(safe-area-inset-*) as 0, so app screens use
+ * max(env(safe-area-inset-top), var(--kaloko-safe-top, 0px)) and look right in Kaloko and on the phone.
+ */
+export async function applyVariant (page, variant, device = null) {
+  if (!variant) return async () => {}
+  const safe = device?.safe && (device.full_screen || variant.display_mode === 'standalone') ? device.safe : null
+  if (safe) await page.evaluate((s) => { for (const k of ['top', 'right', 'bottom', 'left']) document.documentElement.style.setProperty(`--kaloko-safe-${k}`, `${s[k] || 0}px`) }, safe).catch(() => {})
+  const media = {}
+  if (variant.color_scheme) media.colorScheme = variant.color_scheme
+  if (variant.reduced_motion) media.reducedMotion = variant.reduced_motion
+  if (variant.forced_colors) media.forcedColors = variant.forced_colors
+  if (Object.keys(media).length) await page.emulateMedia(media).catch(() => {})
+  let standalone = false
+  if (variant.display_mode === 'standalone') standalone = await page.evaluate(displayMode, 'standalone').catch(() => false)
+  return async () => {
+    if (safe) await page.evaluate(() => { for (const k of ['top', 'right', 'bottom', 'left']) document.documentElement.style.removeProperty(`--kaloko-safe-${k}`) }).catch(() => {})
+    if (Object.keys(media).length) await page.emulateMedia(Object.fromEntries(Object.keys(media).map((k) => [k, null]))).catch(() => {})
+    if (standalone) await page.evaluate(displayMode, null).catch(() => {})
+  }
+}
+
+/**
+ * In the page: makes `(display-mode: standalone)` rules apply and `browser` rules not, and answers matchMedia the
+ * same way (no engine emulates the display mode). Same-origin style sheets only; `null` restores the page.
+ */
+function displayMode (mode) {
+  const w = window
+  if (!mode) {
+    for (const [rule, text] of w.__kalokoDisplayMode || []) { try { rule.media.mediaText = text } catch {} }
+    w.__kalokoDisplayMode = null
+    if (w.__kalokoMatchMedia) { w.matchMedia = w.__kalokoMatchMedia; w.__kalokoMatchMedia = null }
+    return true
+  }
+  const saved = []
+  const visit = (rules) => {
+    for (const r of rules) {
+      if (r.media && /display-mode/.test(r.media.mediaText)) {
+        saved.push([r, r.media.mediaText])
+        // per query of the list: another display mode drops the query, this one becomes an always-true feature
+        const queries = r.media.mediaText.split(',').map((q) => q.trim()).filter((q) => {
+          const m = q.match(/\(\s*display-mode\s*:\s*([a-z-]+)\s*\)/)
+          return !m || m[1] === mode
+        }).map((q) => q.replace(/\(\s*display-mode\s*:\s*[a-z-]+\s*\)/g, '(min-width: 0px)'))
+        try { r.media.mediaText = queries.length ? queries.join(', ') : 'not all' } catch {}
+      }
+      if (r.cssRules) visit(r.cssRules)
+    }
+  }
+  for (const s of document.styleSheets) { try { visit(s.cssRules) } catch {} }
+  w.__kalokoDisplayMode = saved
+  if (!w.__kalokoMatchMedia) {
+    w.__kalokoMatchMedia = w.matchMedia
+    w.matchMedia = (q) => (/display-mode/.test(q) ? { matches: new RegExp(`display-mode\\s*:\\s*${mode}`).test(q), media: q, addListener () {}, removeListener () {}, addEventListener () {}, removeEventListener () {}, onchange: null } : w.__kalokoMatchMedia.call(w, q))
+  }
+  return true
+}
+
+/** Engine name of a Playwright page (Electron and pages over CDP are Chromium). */
+export function engineOf (page) {
+  try { return page.context().browser()?.browserType().name() || 'chromium' } catch { return 'chromium' }
+}
+
+/**
+ * Checks other engines cannot evaluate like Chromium does, with the reason the canvas shows ("not evaluated").
+ * WebKit moves Tab focus between form controls only (Safari's default), so its Tab walk would report false gaps.
+ */
+export const CHROMIUM_ONLY = {
+  a11y_ax_names: 'needs Chromium: the accessibility tree is read over the DevTools protocol',
+  a11y_focus_visible: 'needs Chromium: focus rings are compared on Chromium screenshots',
+  perf_cls: 'needs Chromium: only Chromium reports layout shifts'
+}
+const WEBKIT_TAB = 'not on WebKit: Tab moves between form controls only (Safari\'s default), so the walk would miss links'
+export function engineGap (engine, assert) {
+  if (!engine || engine === 'chromium') return null
+  if (CHROMIUM_ONLY[assert]) return CHROMIUM_ONLY[assert]
+  if (engine === 'webkit' && ['a11y_focus_order', 'a11y_keyboard_trap', 'a11y_skip_link'].includes(assert)) return WEBKIT_TAB
+  return null
+}
+
+/** Marks a capture's checks that the engine cannot evaluate; returns the criteria left for the keyboard walk. */
+export function markEngineGaps (engine, criteria, checks) {
+  const left = []
+  for (const c of criteria || []) {
+    const why = c.check?.type === 'deterministic' ? engineGap(engine, c.check.assert) : null
+    if (why) checks[c.id] = { ok: null, na: true, evidence: `${why} (this capture: ${engine})` }
+    else left.push(c)
+  }
+  return left
+}
+
+/**
+ * The key of a reference capture to compare a capture with (design drift, compare across runs): the same key, else
+ * the same viewport and scheme in Chromium (a WebKit capture is checked against the Chromium design), else null.
+ */
+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' })
+  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 }
+  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)
+
+/** 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))]
+
+/** A Playwright browser type by engine name; a UserError with the install command when it is missing. */
+export async function launchEngine (engine, { channel, headless = true } = {}) {
+  const pw = await import('playwright')
+  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 } : {}) })
+  } 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/doctor.mjs

@@ -33,8 +33,11 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {Function} [o.fetchImpl]
  * @param {Function} [o.launchChrome] async () => { version } — throws when Chrome is missing
  * @param {object} [o.env] process.env
+ * @param {string[]} [o.engines] browser engines the scenarios and config.walk ask for (webkit, firefox)
+ * @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)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, videoToolsImpl = null }) {
+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 }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
 
@@ -45,6 +48,10 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the organization slug from kaloko.app).')
 
   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') }
+  // 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' : ''}`) }
+  }
 
   for (const name of Object.keys(config.environments || {})) {
     let e
@@ -53,13 +60,23 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
     const free = await portFree(port)
     add(`port ${name}`, true, `${port} ${free ? 'free' : 'in use (shared browser running, or another project)'}`)
     const base = typeof e.base_url === 'string' ? e.base_url : Object.values(e.base_url || {})[0]
-    // apps: the tools their driver needs
+    // apps: the tools their driver needs on this operating system, with what to install
     for (const p of Object.keys(e.app || {})) {
-      const t = await appTools()
-      if (p === 'android') add(`app ${name} android`, t.adb, t.adb ? `adb found · ${e.app.android.package || 'no package'}` : 'adb not found', 'Install Android platform-tools and start an emulator or connect a device (adb devices).')
-      if (p === 'ios') add(`app ${name} ios`, t.simctl, t.simctl ? `simctl · ${t.idb ? 'idb for the UI tree and taps' : 'no idb: screen text by OCR, deep links only'}` : 'Xcode simctl not found', 'Install Xcode with an iOS Simulator runtime; optional idb (brew install facebook/fb/idb-companion, pip install fb-idb) for the UI tree and taps.')
+      const t = tools || await appTools()
+      if (p === 'android') {
+        const a = e.app.android
+        const needEmu = !!(a.avd || Object.values(a.devices || {}).some((d) => d.avd))
+        add(`app ${name} android`, t.adb && (!needEmu || t.emulator), [t.adb ? 'adb found' : 'adb not found', needEmu ? (t.emulator ? 'emulator found' : 'emulator not found') : null, a.connect ? `Wi-Fi device ${a.connect}` : null, a.package || 'no package', a.webview ? 'WebView pages over CDP' : null].filter(Boolean).join(' · '), !t.adb ? `Install Android platform-tools (${os === 'darwin' ? 'brew install --cask android-platform-tools' : os === 'win32' ? 'winget install Google.PlatformTools' : 'apt install android-tools-adb, or the SDK'}) and start an emulator or connect a device (adb devices).` : needEmu && !t.emulator ? 'Install the Android emulator (Android Studio → SDK Manager) or set app.android.emulator / ANDROID_HOME.' : '')
+      }
+      if (p === 'ios') {
+        const i = e.app.ios
+        if (os !== 'darwin') { add(`app ${name} ios`, false, 'the iOS Simulator and devicectl need macOS', 'Walk iOS on a Mac (or a macos CI runner); elsewhere import screens with kaloko capture --image.'); continue }
+        if (i.real || Object.values(i.devices || {}).some((d) => d.real)) add(`app ${name} ios device`, t.devicectl && (t.idevicescreenshot || t.pymobiledevice3), `${t.devicectl ? 'devicectl' : 'no devicectl'} · ${t.idevicescreenshot ? 'idevicescreenshot' : t.pymobiledevice3 ? 'pymobiledevice3' : 'no screenshot tool'} · no taps or UI tree (OCR)`, t.devicectl ? 'Install libimobiledevice (brew install libimobiledevice) or pymobiledevice3 (pipx install pymobiledevice3; iOS 17+: sudo pymobiledevice3 remote tunneld).' : 'Install Xcode 15 or newer (xcrun devicectl).')
+        if (!i.real) add(`app ${name} ios`, t.simctl, t.simctl ? `simctl · ${t.idb ? 'idb for the UI tree and taps' : 'no idb: screen text by OCR, deep links only'}` : 'Xcode simctl not found', 'Install Xcode with an iOS Simulator runtime; optional idb (brew install facebook/fb/idb-companion, pip install fb-idb) for the UI tree and taps.')
+      }
+      if (p === 'windows') add(`app ${name} windows`, os === 'win32' ? t.powershell : !!e.app.windows.powershell, os === 'win32' ? (t.powershell ? 'PowerShell · UI Automation tree, clicks and typing' : 'PowerShell not found') : 'Windows apps are walked on Windows', os === 'win32' ? (t.powershell ? '' : 'Windows PowerShell is part of Windows; set app.windows.powershell to pwsh if it was removed.') : 'Walk on a Windows machine or a windows-latest CI runner, or capture with kaloko capture --image --platform windows.')
       if (p === 'desktop') {
-        if (process.platform !== 'darwin') { add(`app ${name} desktop`, false, 'built-in desktop capture needs macOS', 'On Windows or Linux capture with kaloko capture --image --tree.'); continue }
+        if (os !== 'darwin') { add(`app ${name} desktop`, false, 'built-in desktop capture needs macOS', os === 'win32' ? 'For a Windows app use platform: windows with app.windows (UI Automation).' : 'On Linux capture with kaloko capture --image --tree.'); continue }
         const perm = await macPermissions(false).catch(() => null)
         add(`app ${name} desktop`, !!perm?.screen, perm ? `Screen Recording ${perm.screen ? 'allowed' : 'not allowed'} · Accessibility ${perm.accessibility ? 'allowed (UI tree)' : 'not allowed (text by OCR)'}` : 'the macOS helper could not run', perm?.screen ? '' : 'Run kaloko doctor --fix to ask macOS, then turn this terminal on in System Settings → Privacy & Security → Screen Recording (and Accessibility for the UI tree) and restart it.')
         if (fix && perm && (!perm.screen || !perm.accessibility)) await macPermissions(true).catch(() => {})
@@ -151,6 +168,14 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   return { ok: checks.every((c) => c.ok), checks }
 }
 
+async function defaultEngine (engine) {
+  const pw = await import('playwright')
+  const browser = await pw[engine].launch({ headless: true })
+  const version = browser.version()
+  await browser.close()
+  return { version }
+}
+
 async function defaultLaunch (config) {
   const { chromium } = await import('playwright')
   const browser = await chromium.launch({ headless: true, channel: config.browser?.channel || undefined })

package/src/lib/drift.mjs

@@ -4,7 +4,8 @@
 // in-page checks, so combine() turns them into verdicts the usual way.
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import { flattenTokens, tokenIndex, checkDeclaration } from './tokens.mjs'
+import { flattenTokens, tokenIndex, checkDeclaration, modesOf } from './tokens.mjs'
+import { referenceKey, tokenModeOf } from './dimensions.mjs'
 import { sha256 } from './util.mjs'
 
 export const DRIFT_ASSERTS = new Set(['design_pixels', 'design_structure', 'uses_tokens'])
@@ -81,8 +82,10 @@ export async function driftForCapture ({ node, entry, capture, runDir, ctx }) {
     const a = c.check.assert
     if (a === 'uses_tokens') {
       if (!ctx.tokens) { results[c.id] = { ok: null, evidence: 'No token set: push one with kaloko tokens push, or keep tokens.json in the design folder.' }; continue }
-      const refStyles = !ctx.isDesign ? (await referenceStep(ctx, node.id, entry.locale))?.captures?.[entry.viewport]?.design?.styles : null
-      const off = tokenOffenders(capture.design?.styles, ctx.tokens, ctx.mode, refStyles)
+      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)
       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('; ')}` }
@@ -91,7 +94,8 @@ export async function driftForCapture ({ node, entry, capture, runDir, ctx }) {
     }
     if (ctx.isDesign) { results[c.id] = { ok: null, evidence: 'This is the design itself; the check applies to implementation runs.' }; continue }
     if (!ref) { results[c.id] = { ok: null, evidence: ctx.referenceError || 'No design reference for this scenario yet: accept a version and set it as the design reference.' }; continue }
-    const rc = ref.captures?.[entry.viewport]
+    // the same key, else the Chromium capture of that viewport and scheme: a WebKit page is checked against the design
+    const rc = ref.captures?.[referenceKey(entry.viewport, Object.keys(ref.captures || {}))]
     if (!rc) { results[c.id] = { ok: null, evidence: `The design reference has no ${entry.viewport} capture for ${entry.locale}.` }; continue }
     if (a === 'design_structure') {
       const diff = structureDiff(capture.design?.structure, rc.design?.structure)

package/src/lib/evaluate.mjs

@@ -7,6 +7,7 @@ import { prepareImages, visionPlan, askVision, hostedVisionSender } from './visi
 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'
 
 /** Latest capture per node/locale/viewport. */
 export function latestCaptures (entries) {
@@ -31,7 +32,7 @@ export function combine ({ node, capture, jev, vision = null, thresholds }) {
       const r = capture.checks?.[c.id]
       const verdict = r == null || r.ok == null ? 'not_evaluated' : r.ok ? 'pass' : 'fail'
       const live = c.check.assert === 'no_console_errors' || c.check.assert === 'no_overflow' || c.check.assert === 'http_status' || c.check.assert === 'links_ok' || c.check.assert === 'hreflang_pairs' || /^perf_/.test(c.check.assert || '') || KEYBOARD_ASSERTS.has(c.check.assert)
-      return { id: c.id, type: 'deterministic', verdict, evidence: r?.evidence ?? null, ...(capture.rechecked_at && !live ? { rechecked: true } : {}) }
+      return { id: c.id, type: 'deterministic', verdict, evidence: r?.evidence ?? null, ...(r?.na ? { na: true } : {}), ...(capture.rechecked_at && !live ? { rechecked: true } : {}) }
     }
     if (c.check.type === 'semantic' && c.check.about === 'console' && !(capture.console_errors || []).length && capture.checks) {
       return { id: c.id, type: 'semantic', verdict: 'pass', evidence: 'no console errors', score: null, provider: null, note: null, reason: 'No console errors on this page, so there is nothing to triage.', reason_source: 'rule' }
@@ -72,6 +73,8 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
   const vision = vset ? visionContext({ config, root, settings: vset, report, fetchImpl }) : null
   // checks against the design reference and the token set (pack design, #42) need the service and a browser
   const drift = scenario.nodes.some(needsDrift) ? await driftContext({ run, scenario, config, root }) : null
+  // style checks against a token (style_equals token: color.brand.primary) use the project's token set
+  const styleTokens = scenario.nodes.some((n) => tokenCriteria(n).length) ? (drift ? { tokens: drift.tokens, mode: drift.mode } : await runTokens({ config, root })) : null
   try {
   const latest = latestCaptures(await readCaptures(run.dir))
   // stack steps: semantic criteria only on the first N pages (items.semantic_sample, default 20); cost stays bounded
@@ -122,6 +125,7 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
     for (const { entry, node, capture, current, outOfSample, request, jev, vision: seen } of work) {
       const source = evaluationSource(node, capture)
       if (drift && current && needsDrift(node)) { capture.checks = { ...capture.checks, ...await driftForCapture({ node, entry, capture, runDir: run.dir, ctx: drift }) }; report.drift++ }
+      if (styleTokens?.tokens && current && tokenCriteria(node).length) capture.checks = { ...capture.checks, ...storedValueChecks(node, capture, { ...styleTokens, recorded: !!capture.rechecked_at, only: (c) => !!c.check.token && STYLE_ASSERTS.has(c.check.assert) }) }
       let criteria = combine({ node, capture: current ? capture : {}, jev, vision: seen, thresholds: settings.thresholds })
       // pages outside the semantic sample carry only the deterministic results
       if (outOfSample) criteria = criteria.filter((c) => c.type !== 'semantic' || c.evidence === 'no console errors')
@@ -285,17 +289,31 @@ function hostedSender (config, report) {
   }
 }
 
+/** The design environment's folder and token mode, when the config has one. */
+async function designEnv ({ config, root }) {
+  try {
+    const { environment } = await import('./config.mjs')
+    const d = Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
+    if (d) return { designDir: resolve(root, d.serve), mode: d.tokens_mode || null }
+  } catch {}
+  return { designDir: null, mode: null }
+}
+
+/** The token set of the run without the design checks: the project's on the service, else the design folder's. */
+async function runTokens ({ config, root }) {
+  let client = null
+  try { const { service } = await import('./service.mjs'); client = service(config) } catch {}
+  const { designDir, mode } = await designEnv({ config, root })
+  return { tokens: await loadTokens({ client, config, root, designDir }), mode }
+}
+
 /** Context of the design checks: service client, token set, reference cache and a browser for pixel diffs. */
 async function driftContext ({ run, scenario, config, root }) {
   const isDesign = run.meta.environment.kind === 'design'
   const ctx = { org: config.org, scenarioId: scenario.id, isDesign, git: run.meta.git?.branch || null, references: new Map(), cacheDir: driftCacheDir(root, config.output), mode: null, tokens: null, client: null, page: null, browser: null }
   try { const { service } = await import('./service.mjs'); ctx.client = service(config) } catch (e) { ctx.referenceError = `Design checks need the service: ${e.message}` }
-  let designDir = null
-  try {
-    const { environment } = await import('./config.mjs')
-    const d = Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
-    if (d) { designDir = resolve(root, d.serve); ctx.mode = d.tokens_mode || null }
-  } catch {}
+  const { designDir, mode } = await designEnv({ config, root })
+  ctx.mode = mode
   ctx.tokens = await loadTokens({ client: ctx.client, config, root, designDir })
   if (!isDesign && scenario.nodes.some((n) => (n.criteria || []).some((c) => c.check.assert === 'design_pixels'))) {
     const { launchEphemeral } = await import('./browser.mjs')

package/src/lib/import.mjs

@@ -272,7 +272,8 @@ export function stepFor (item, nodes, map = {}) {
 /** The run viewport closest to the image's width (screens taken at 2× or 3× count by their CSS width). */
 export function viewportFor (size, viewports, wanted = null) {
   if (wanted && viewports[wanted]) return wanted
-  const names = Object.keys(viewports)
+  // plain keys first: an imported screenshot is Chromium, light, unless --viewport names a key like mobile.dark
+  const names = Object.keys(viewports).sort((a, b) => a.includes('.') - b.includes('.'))
   if (!size || names.length === 1) return names[0]
   let best = names[0]; let bestD = Infinity
   for (const n of names) for (const k of [1, 2, 3]) { const d = Math.abs(size[0] / k - viewports[n][0]); if (d < bestD) { bestD = d; best = n } }

package/src/lib/jev.mjs

@@ -42,7 +42,9 @@ export function buildRequest ({ node, capture, criteria, model, signals = false
     screen_purpose: purposeOf(node, capture),
     url: capture.url,
     locale: capture.locale,
-    viewport: capture.viewport,
+    // the viewport name without browser and scheme (mobile.webkit.dark → mobile): the same page text in another
+    // engine or scheme is the same question, answered once from the cache
+    viewport: capture.viewport == null ? capture.viewport : String(capture.viewport).split('.')[0],
     page: capture.state,
     ...(Object.keys(scopes).length ? { scopes } : {}),
     ...(criteria.some((c) => c.check.about === 'console') ? { console_errors: (capture.console_errors || []).slice(0, 30) } : {})

package/src/lib/manifest-core.mjs

@@ -21,6 +21,12 @@ export function targetOf (c) {
   return null
 }
 
+/**
+ * Verdicts that count for a criterion: a check another browser engine cannot run (`na`, e.g. the accessibility tree
+ * outside Chromium) does not make a step partial when the engines that can run it gave a verdict.
+ */
+export const counted = (entries) => { const own = entries.filter((e) => !e?.na); return (own.length ? own : entries).map((e) => e?.verdict ?? 'not_reached') }
+
 /** Node status from criterion verdicts. */
 export function statusOf (verdicts, captured) {
   if (!captured) return 'skip'
@@ -39,6 +45,7 @@ export function slimCapture (cap) {
     ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.platform ? { platform: cap.platform, device: cap.device || null } : {}),
     ...(cap.design ? { design: cap.design } : {}), ...(cap.capture ? { capture: cap.capture } : {}),
     ...(cap.criteria_hash ? { criteria_hash: cap.criteria_hash } : {}),
+    ...Object.fromEntries(['browser', 'color_scheme', 'reduced_motion', 'forced_colors', 'display_mode', 'device_preset'].filter((k) => cap[k]).map((k) => [k, cap[k]])),
     ...(cap.ignore?.length ? { ignore: cap.ignore } : {}), ...(cap.unstable ? { unstable: cap.unstable } : {}), ...(cap.keyboard ? { keyboard: cap.keyboard } : {})
   }
 }
@@ -65,6 +72,8 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
     ;(capturesOut[c.locale] ||= {})[c.viewport] = {
       png: c.files.png, thumb: c.files.thumb || null, html: c.files.html || null, url: cap.url ?? null,
       ...(cap.platform ? { platform: cap.platform, device: cap.device || null, tree: c.files.tree || null } : {}),
+      // run dimensions (batch E): engine, colour scheme, motion, forced colours, display mode, device preset
+      ...Object.fromEntries(['browser', 'color_scheme', 'reduced_motion', 'forced_colors', 'display_mode', 'device_preset'].filter((k) => cap[k]).map((k) => [k, cap[k]])),
       ...(cap.http_status ? { http_status: cap.http_status } : {}),
       ...(cap.capture && (cap.capture.scale !== 1 || cap.capture.format === 'png' || cap.capture.masked || cap.capture.annotations?.length) ? { quality: cap.capture } : {}), size: [cap.size.width, cap.size.height],
       boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 20), blocked_list: (cap.blocked_requests || []).slice(0, 20),
@@ -90,20 +99,20 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
       // semantic answers carry the thresholds they were judged by and where they were evaluated (own key or Kaloko)
       // semantic answers carry their one-sentence reason (#17) and whether the evaluator saw the screenshot
       const seen = r.provider && /-vision$/.test(r.provider)
-      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && (seen ? ev.vision?.via : ev.semantic?.via) ? { via: seen ? ev.vision.via : ev.semantic.via } : {}), ...(r.reason ? { reason: r.reason, ...(r.reason_source === 'model' ? { reason_by: 'model' } : {}) } : {}), ...(seen ? { vision: true, ...(r.text_score != null ? { text_score: r.text_score } : {}) } : {}) }
+      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(r.na ? { na: true } : {}), ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && (seen ? ev.vision?.via : ev.semantic?.via) ? { via: seen ? ev.vision.via : ev.semantic.via } : {}), ...(r.reason ? { reason: r.reason, ...(r.reason_source === 'model' ? { reason_by: 'model' } : {}) } : {}), ...(seen ? { vision: true, ...(r.text_score != null ? { text_score: r.text_score } : {}) } : {}) }
       if (r.evidence && (!agg.evidence || r.verdict !== 'pass')) agg.evidence = r.evidence
       if (r.reason && (!agg.reason || (r.verdict !== 'pass' && agg.reason_verdict === 'pass'))) { agg.reason = r.reason; agg.reason_verdict = r.verdict }
     }
   }
   const criteria = [...perCriterion.values()].map(({ reason_verdict: _rv, ...agg }) => {
     for (const l of applicable) for (const vp of viewportNames) ((agg.by_locale[l] ||= {})[vp] ||= { verdict: 'not_reached' })
-    const verdicts = applicable.flatMap((l) => viewportNames.map((vp) => agg.by_locale[l][vp].verdict))
+    const verdicts = counted(applicable.flatMap((l) => viewportNames.map((vp) => agg.by_locale[l][vp])))
     return { ...agg, verdict: aggregate(verdicts) }
   })
   const byLocale = {}
   for (const l of locales) {
     const captured = !!capturesOut[l]
-    const vs = criteria.map((c) => aggregate(Object.values(c.by_locale[l] || {}).map((v) => v.verdict)))
+    const vs = criteria.map((c) => aggregate(counted(Object.values(c.by_locale[l] || {}))))
     if (applicable.includes(l) && viewportNames.some((vp) => !capturesOut[l]?.[vp])) vs.push('not_reached')
     byLocale[l] = statusOf(vs, captured)
   }