kaloko 0.4.10 → 0.5.0

package/src/lib/capture.mjs

@@ -22,13 +22,14 @@ export async function encodeImage (page, png, { format = 'webp', quality = 0.82,
       g.beginPath(); g.arc(x, y, r, 0, Math.PI * 2); g.fillStyle = '#ffe452'; g.fill(); g.lineWidth = 2 * scale; g.strokeStyle = '#151514'; g.stroke()
       g.fillStyle = '#151514'; g.font = `700 ${14 * scale}px system-ui, sans-serif`; g.textAlign = 'center'; g.textBaseline = 'middle'; g.fillText(String(m.n), x, y + scale)
     }
-    const blob = (c, type, q) => new Promise((res, rej) => c.toBlob((b) => (b ? b.arrayBuffer().then((buf) => res(Array.from(new Uint8Array(buf)))) : rej(new Error('encode failed'))), type, q))
+    // the blob's own type: WebKit cannot write WebP and silently returns PNG
+    const blob = (c, type, q) => new Promise((res, rej) => c.toBlob((b) => (b ? b.arrayBuffer().then((buf) => res({ bytes: Array.from(new Uint8Array(buf)), type: b.type })) : rej(new Error('encode failed'))), type, q))
     const k = Math.min(1, thumbWidth / img.width)
     const t = document.createElement('canvas'); t.width = Math.round(img.width * k); t.height = Math.round(img.height * k)
     t.getContext('2d').drawImage(full, 0, 0, t.width, t.height)
     return { image: await blob(full, format === 'png' ? 'image/png' : 'image/webp', quality), thumb: await blob(t, 'image/webp', thumbQuality) }
   }, { dataUrl: `data:image/png;base64,${png.toString('base64')}`, format, quality, thumbWidth, thumbQuality, marks, scale, masks })
-  return { image: Buffer.from(result.image), thumb: Buffer.from(result.thumb) }
+  return { image: Buffer.from(result.image.bytes), thumb: Buffer.from(result.thumb.bytes), imageType: result.image.type, thumbType: result.thumb.type }
 }
 
 /** WebP encoding for the canvas (kept for callers of the old name). */
@@ -39,9 +40,9 @@ export const toWebp = (page, png, opts = {}) => encodeImage(page, png, { ...opts
  * { format: png, scale: 2, mask: [selectors], annotate: true }; daily acceptance keeps the WebP default.
  */
 /** The page spec (src/lib/devspec.mjs), kept under ~250 kB so it fits a design revision's capture record. */
-export async function stepSpec (page, tokens = null) {
+export async function stepSpec (page, tokens = null, mode = null) {
   try {
-    const spec = await page.evaluate(pageSpecScript(tokens))
+    const spec = await page.evaluate(pageSpecScript(tokens, 300, mode))
     while (spec.elements.length > 20 && JSON.stringify(spec).length > 250000) spec.elements = spec.elements.slice(0, Math.floor(spec.elements.length * 0.8))
     return spec
   } catch { return null }
@@ -68,6 +69,8 @@ import { readFields } from './stack.mjs'
 import { checkLinks, checkHreflang, requester, walkCache, NETWORK_ASSERTS, isolatedRequest, cacheScope } from './linkcheck.mjs'
 import { keyboardChecks, needsKeyboard, KEYBOARD_ASSERTS } from './keyboard.mjs'
 import { repeatRegions, resolveIgnore } from './stability.mjs'
+import { applyVariant, engineOf, markEngineGaps, variantFields } from './dimensions.mjs'
+import { liveValueChecks } from './assertions.mjs'
 
 /** Probe arguments derived from the node's criteria. */
 export function probeArgs (node, maxChars, design = false) {
@@ -118,127 +121,151 @@ export async function captureStep ({ page, node, locale, viewports, run, console
   const original = page.viewportSize()
   const results = []
   let netResults = null
+  // batch E: the engine of this page, and per key its colour scheme, motion and display mode (run scope variants)
+  const engine = engineOf(page)
+  const scope = run.meta?.scope
   for (const [viewport, [width, height]] of Object.entries(viewports)) {
     const now = page.viewportSize()
     if (!now || now.width !== width || now.height !== height) await page.setViewportSize({ width, height })
-    await settle(page)
-    const html = paths.step(stepId, locale, viewport, 'html')
-    await rm(paths.step(stepId, locale, viewport, 'eval.json'), { force: true })
-    await mkdir(dirname(html), { recursive: true })
-    // PII selectors are covered by a solid box; at 2× Chrome renders the full page at double scale (CDP), and
-    // the boxes are drawn while encoding because Playwright's own mask only works at the page's pixel ratio
-    const maskRects = opts.mask.length ? await page.evaluate((sels) => sels.flatMap((sel) => { try { return [...document.querySelectorAll(sel)] } catch { return [] } }).map((el) => { const r = el.getBoundingClientRect(); return { x: r.left + scrollX, y: r.top + scrollY, w: r.width, h: r.height } }).filter((r) => r.w > 0 && r.h > 0), opts.mask) : []
-    let shot
-    if (opts.scale === 2) {
-      const cdp = await page.context().newCDPSession(page)
-      try {
-        const doc = await page.evaluate(() => ({ w: Math.ceil(document.documentElement.scrollWidth), h: Math.ceil(document.documentElement.scrollHeight) }))
-        const r = await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: opts.fullPage, clip: { x: 0, y: 0, width: opts.fullPage ? doc.w : width, height: opts.fullPage ? doc.h : height, scale: 2 } })
-        shot = Buffer.from(r.data, 'base64')
-      } finally { await cdp.detach().catch(() => {}) }
-    } else shot = await page.screenshot({ fullPage: opts.fullPage, ...(opts.mask.length ? { mask: opts.mask.map((sel) => page.locator(sel)), maskColor: '#1f1f1d' } : {}) })
-    // secrets the CLI used (gate, accounts) never land in a capture, even if the page echoes them
-    await writeFile(html, redact(await page.content()))
-    let result
-    for (let attempt = 0; ; attempt++) {
-      try { result = await page.evaluate(probe, probeArgs(node, maxChars, designSummary)); break } catch (error) {
-        // the page navigated under us (redirect, Turbo); wait once and probe the new document
-        if (attempt < 2 && /Execution context was destroyed|navigation/i.test(error.message)) { await page.waitForLoadState('domcontentloaded').catch(() => {}); await page.waitForTimeout(500); continue }
-        throw error
-      }
-    }
-    // the step spec (Dev mode, `kaloko spec`, drift): elements with roles, names and styles mapped to the tokens
-    if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens)
-    // regions the scenario ignores in pixel comparisons (#20), as page rectangles of this capture
-    const ignore = await resolveIgnore(page, node, locale, viewport)
-    // what moves while the page sits still (walk --stability N): repeated screenshots, compared here
-    const unstable = stability > 1 ? await repeatRegions(page, { n: Math.min(6, stability), fullPage: opts.fullPage }).catch((error) => ({ error: String(error.message).slice(0, 200) })) : null
-    // numbered marks on the highlighted elements, in criteria order (first box of each)
-    const annotations = opts.annotate ? Object.entries(result.boxes || {}).filter(([, list]) => list?.length).map(([criterion, list], i) => ({ n: i + 1, criterion, x: list[0].x, y: list[0].y })) : []
-    let image = paths.step(stepId, locale, viewport, opts.format)
-    const thumb = paths.step(stepId, locale, viewport, 'thumb.webp')
-    let thumbWritten = true
+    const undoVariant = await applyVariant(page, scope?.variants?.[viewport], scope?.devices?.[scope?.variants?.[viewport]?.device] || null)
     try {
-      const enc = await encodeImage(page, shot, { format: opts.format, quality: opts.quality, marks: annotations, scale: opts.scale, masks: opts.scale === 2 ? maskRects : [] })
-      await writeFile(image, enc.image)
-      await writeFile(thumb, enc.thumb)
-    } catch (error) {
-      // never store an unmasked image when masks were asked for
-      if (opts.scale === 2 && maskRects.length) throw new Error(`capture: could not draw the masks on ${node.id} (${error.message}); the image was not stored`)
-      image = paths.step(stepId, locale, viewport, 'png'); thumbWritten = false
-      await writeFile(image, shot)
-    }
-    const url = page.url()
-    const collected = consoleFile ? await readJsonl(consoleFile) : consoleEntriesFor(page)
-    const consoleEntries = (collected || []).filter((e) => !since || e.ts >= since)
-    // requests blocked by the readonly policy surface as ERR_BLOCKED_BY_CLIENT; they are reported separately
-    // an error page's own status ("Failed to load resource: … 404" for the document itself) is not a console error
-    const ownStatus = (e) => result.http_status >= 400 && /^Failed to load resource: the server responded with a status of \d+/.test(e.text) && e.src && sameDocument(e.src, url)
-    const errors = consoleEntries.filter((e) => e.type !== 'blocked' && sameDocument(e.url, url) && !e.text.includes('ERR_BLOCKED_BY_CLIENT') && !ownStatus(e)).map((e) => e.text)
-    const blocked = consoleEntries.filter((e) => e.type === 'blocked').map((e) => `${e.text}`)
-    // network checks (internal links, hreflang pairs) run once per page, outside the page, with a walk-wide cache
-    const net = (node.criteria || []).filter((c) => c.check.type === 'deterministic' && NETWORK_ASSERTS.has(c.check.assert))
-    if (net.length) {
-      netResults ||= await networkChecks(page, net, url, { run, locale })
-      Object.assign(result.checks, netResults)
-    }
-    for (const c of node.criteria || []) {
-      if (c.check.type === 'deterministic' && c.check.assert === 'no_console_errors') {
-        result.checks[c.id] = collected === null
-          ? { ok: null, evidence: 'Console was not observed.' }
-          : { ok: errors.length === 0, evidence: errors.length ? errors.slice(0, 3).join(' | ') : 'no console errors' }
+      await settle(page)
+      const html = paths.step(stepId, locale, viewport, 'html')
+      await rm(paths.step(stepId, locale, viewport, 'eval.json'), { force: true })
+      await mkdir(dirname(html), { recursive: true })
+      // PII selectors are covered by a solid box; at 2× Chrome renders the full page at double scale (CDP), and
+      // the boxes are drawn while encoding because Playwright's own mask only works at the page's pixel ratio
+      const maskRects = opts.mask.length ? await page.evaluate((sels) => sels.flatMap((sel) => { try { return [...document.querySelectorAll(sel)] } catch { return [] } }).map((el) => { const r = el.getBoundingClientRect(); return { x: r.left + scrollX, y: r.top + scrollY, w: r.width, h: r.height } }).filter((r) => r.w > 0 && r.h > 0), opts.mask) : []
+      let shot
+      // a device preset's pixel ratio (3 on an iPhone) shapes the layout, not the image: captures stay in CSS pixels
+      // (or 2× for documentation), so the canvas, boxes and diffs work the same for every device
+      const dpr = await page.evaluate(() => devicePixelRatio).catch(() => 1)
+      let shotScale = opts.scale
+      if (opts.scale === 2 && engine === 'chromium') {
+        const cdp = await page.context().newCDPSession(page)
+        try {
+          const doc = await page.evaluate(() => ({ w: Math.ceil(document.documentElement.scrollWidth), h: Math.ceil(document.documentElement.scrollHeight) }))
+          const r = await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: opts.fullPage, clip: { x: 0, y: 0, width: opts.fullPage ? doc.w : width, height: opts.fullPage ? doc.h : height, scale: 2 / (dpr || 1) } })
+          shot = Buffer.from(r.data, 'base64')
+        } finally { await cdp.detach().catch(() => {}) }
+      } else {
+        // WebKit and Firefox have no 2× capture of their own: 2× when the context renders at 2× or more, else 1×
+        // (exactly 2×: a 3× or 2.625× device would give an image the masks and marks are not drawn for)
+        if (opts.scale === 2 && dpr !== 2) shotScale = 1
+        shot = await page.screenshot({ fullPage: opts.fullPage, scale: shotScale === 2 ? 'device' : 'css', ...(opts.mask.length && shotScale === 1 ? { mask: opts.mask.map((sel) => page.locator(sel)), maskColor: '#1f1f1d' } : {}) })
       }
-    }
-    // keyboard and screen-reader checks (#19): a Tab walk and the accessibility tree, after the screenshot and after
-    // the console was read (focus handlers of the page must not count as its errors)
-    let keyboard = null
-    // stack steps walk the keyboard on their first few pages only (one template, hundreds of pages)
-    const kbKey = `${run.dir}|${node.id}|${viewport}`
-    const kbSampled = !item || (STACK_KEYBOARD.set(kbKey, (STACK_KEYBOARD.get(kbKey) || 0) + 1).get(kbKey) <= STACK_KEYBOARD_PAGES)
-    if (needsKeyboard(node) && !kbSampled) {
-      for (const c of node.criteria) if (KEYBOARD_ASSERTS.has(c.check.assert)) result.checks[c.id] = { ok: null, evidence: `keyboard walk runs on the first ${STACK_KEYBOARD_PAGES} pages of a stack step` }
-    }
-    if (needsKeyboard(node) && kbSampled) {
-      const kb = await keyboardChecks(page, node.criteria, {
-        saveShot: async (n, png) => { const f = paths.step(stepId, locale, viewport, `focus-${n}.png`); await writeFile(f, png); return relative(run.dir, f) }
-      })
-      Object.assign(result.checks, kb.checks)
-      result.boxes = { ...result.boxes, ...kb.boxes }
-      keyboard = kb.keyboard
-      for (const s of keyboard?.shots || []) await addCapture(run.dir, { type: 'attachment', kind: 'focus', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, title: `Focus ${s.n}: ${s.name}`, file: s.file, at: new Date().toISOString() })
-    }
-    // experimental HTML view (#42): a scrubbed, script-free static copy with rehosted assets
-    let view = null
-    if (htmlView) {
+      // secrets the CLI used (gate, accounts) never land in a capture, even if the page echoes them
+      await writeFile(html, redact(await page.content()))
+      let result
+      for (let attempt = 0; ; attempt++) {
+        try { result = await page.evaluate(probe, probeArgs(node, maxChars, designSummary)); break } catch (error) {
+          // the page navigated under us (redirect, Turbo); wait once and probe the new document
+          if (attempt < 2 && /Execution context was destroyed|navigation/i.test(error.message)) { await page.waitForLoadState('domcontentloaded').catch(() => {}); await page.waitForTimeout(500); continue }
+          throw error
+        }
+      }
+      // the step spec (Dev mode, `kaloko spec`, drift): elements with roles, names and styles mapped to the tokens
+      if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens, scope?.variants?.[viewport]?.color_scheme || null)
+      // regions the scenario ignores in pixel comparisons (#20), as page rectangles of this capture
+      const ignore = await resolveIgnore(page, node, locale, viewport)
+      // what moves while the page sits still (walk --stability N): repeated screenshots, compared here
+      const unstable = stability > 1 ? await repeatRegions(page, { n: Math.min(6, stability), fullPage: opts.fullPage }).catch((error) => ({ error: String(error.message).slice(0, 200) })) : null
+      // numbered marks on the highlighted elements, in criteria order (first box of each)
+      const annotations = opts.annotate ? Object.entries(result.boxes || {}).filter(([, list]) => list?.length).map(([criterion, list], i) => ({ n: i + 1, criterion, x: list[0].x, y: list[0].y })) : []
+      let image = paths.step(stepId, locale, viewport, opts.format)
+      let thumb = paths.step(stepId, locale, viewport, 'thumb.webp')
+      let thumbWritten = true
       try {
-        // the same PII masks as the screenshot (#27), applied to the text of the copy
-        const rev = await buildHtmlView({ page, run, scenarioId: htmlView.scenarioId, node: node.id, locale, viewport, mask: [...(opts.mask || []), ...(htmlView.mask || [])] })
-        await writeJson(join(run.dir, 'views', `${rev.id}.json`), rev)
-        view = { revision: rev.id, entry: rev.entry }
-      } catch (error) { view = { error: String(error.message).slice(0, 200) } }
-    }
-    const record = {
-      schema: 'qawalk.capture.v1',
-      ...(view ? { view } : {}),
-      node: node.id, locale, viewport, url,
-      captured_at: new Date().toISOString(),
-      criteria_hash: criteriaHash(node),
-      console_errors: errors, blocked_requests: blocked,
-      ...result,
-      ...extra,
-      http_status: extra.http_status ?? result.http_status ?? null,
-      capture: { format: String(image).split('.').pop(), scale: opts.scale, masked: opts.mask.length, annotations, ...(opts.fullPage ? {} : { full_page: false }) },
-      ...(ignore.length ? { ignore } : {}),
-      ...(unstable ? { unstable } : {}),
-      ...(keyboard ? { keyboard } : {}),
-      ...(item ? { item: { id: item.id, path: item.path, ...(item.title ? { title: item.title } : {}), ...(item.purpose ? { purpose: item.purpose } : {}) } } : {}),
-      ...(fields ? { fields: { ...(await page.evaluate(readFields, fields).catch(() => ({}))), ...(fields.some((f) => (f.from || f.id) === 'http') ? Object.fromEntries(fields.filter((f) => (f.from || f.id) === 'http').map((f) => [f.id, extra.http_status ?? result.http_status ?? null])) : {}) } } : {}),
-      files: { png: relative(run.dir, image), image: relative(run.dir, image), thumb: thumbWritten ? relative(run.dir, thumb) : null, html: relative(run.dir, html) }
-    }
-    const file = paths.step(stepId, locale, viewport, 'capture.json')
-    await writeJson(file, redactDeep(record))
-    await addCapture(run.dir, { type: 'capture', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, file: relative(run.dir, file), at: record.captured_at })
-    results.push(record)
+        const enc = await encodeImage(page, shot, { format: opts.format, quality: opts.quality, marks: annotations, scale: shotScale, masks: shotScale === 2 ? maskRects : [] })
+        // the extension follows the bytes (WebKit encodes PNG), so the service accepts the file
+        if (enc.imageType === 'image/png') image = paths.step(stepId, locale, viewport, 'png')
+        if (enc.thumbType === 'image/png') thumb = paths.step(stepId, locale, viewport, 'thumb.png')
+        await writeFile(image, enc.image)
+        await writeFile(thumb, enc.thumb)
+      } catch (error) {
+        // never store an unmasked image when masks were asked for
+        if (shotScale === 2 && maskRects.length) throw new Error(`capture: could not draw the masks on ${node.id} (${error.message}); the image was not stored`)
+        image = paths.step(stepId, locale, viewport, 'png'); thumbWritten = false
+        await writeFile(image, shot)
+      }
+      const url = page.url()
+      // URL, computed styles and read-only expressions (src/lib/assertions.mjs), before the keyboard walk moves focus
+      await liveValueChecks({ page, node, result, url, tokens })
+      const collected = consoleFile ? await readJsonl(consoleFile) : consoleEntriesFor(page)
+      const consoleEntries = (collected || []).filter((e) => !since || e.ts >= since)
+      // requests blocked by the readonly policy surface as ERR_BLOCKED_BY_CLIENT; they are reported separately
+      // an error page's own status ("Failed to load resource: … 404" for the document itself) is not a console error
+      const ownStatus = (e) => result.http_status >= 400 && /^Failed to load resource: the server responded with a status of \d+/.test(e.text) && e.src && sameDocument(e.src, url)
+      const errors = consoleEntries.filter((e) => e.type !== 'blocked' && sameDocument(e.url, url) && !e.text.includes('ERR_BLOCKED_BY_CLIENT') && !ownStatus(e)).map((e) => e.text)
+      const blocked = consoleEntries.filter((e) => e.type === 'blocked').map((e) => `${e.text}`)
+      // network checks (internal links, hreflang pairs) run once per page, outside the page, with a walk-wide cache
+      const net = (node.criteria || []).filter((c) => c.check.type === 'deterministic' && NETWORK_ASSERTS.has(c.check.assert))
+      if (net.length) {
+        netResults ||= await networkChecks(page, net, url, { run, locale })
+        Object.assign(result.checks, netResults)
+      }
+      for (const c of node.criteria || []) {
+        if (c.check.type === 'deterministic' && c.check.assert === 'no_console_errors') {
+          result.checks[c.id] = collected === null
+            ? { ok: null, evidence: 'Console was not observed.' }
+            : { ok: errors.length === 0, evidence: errors.length ? errors.slice(0, 3).join(' | ') : 'no console errors' }
+        }
+      }
+      // keyboard and screen-reader checks (#19): a Tab walk and the accessibility tree, after the screenshot and after
+      // the console was read (focus handlers of the page must not count as its errors)
+      let keyboard = null
+      // checks another engine cannot evaluate like Chromium (accessibility tree over CDP, layout shifts, WebKit's Tab)
+      // are "not evaluated" with the reason; the keyboard walk takes the rest
+      const kbNode = engine === 'chromium' ? node : { ...node, criteria: markEngineGaps(engine, node.criteria, result.checks) }
+      // stack steps walk the keyboard on their first few pages only (one template, hundreds of pages)
+      const kbKey = `${run.dir}|${node.id}|${viewport}`
+      const kbSampled = !item || (STACK_KEYBOARD.set(kbKey, (STACK_KEYBOARD.get(kbKey) || 0) + 1).get(kbKey) <= STACK_KEYBOARD_PAGES)
+      if (needsKeyboard(kbNode) && !kbSampled) {
+        for (const c of kbNode.criteria) if (KEYBOARD_ASSERTS.has(c.check.assert)) result.checks[c.id] = { ok: null, evidence: `keyboard walk runs on the first ${STACK_KEYBOARD_PAGES} pages of a stack step` }
+      }
+      if (needsKeyboard(kbNode) && kbSampled) {
+        const kb = await keyboardChecks(page, kbNode.criteria, {
+          saveShot: async (n, png) => { const f = paths.step(stepId, locale, viewport, `focus-${n}.png`); await writeFile(f, png); return relative(run.dir, f) }
+        })
+        Object.assign(result.checks, kb.checks)
+        result.boxes = { ...result.boxes, ...kb.boxes }
+        keyboard = kb.keyboard
+        for (const s of keyboard?.shots || []) await addCapture(run.dir, { type: 'attachment', kind: 'focus', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, title: `Focus ${s.n}: ${s.name}`, file: s.file, at: new Date().toISOString() })
+      }
+      // experimental HTML view (#42): a scrubbed, script-free static copy with rehosted assets
+      let view = null
+      if (htmlView) {
+        try {
+          // the same PII masks as the screenshot (#27), applied to the text of the copy
+          const rev = await buildHtmlView({ page, run, scenarioId: htmlView.scenarioId, node: node.id, locale, viewport, mask: [...(opts.mask || []), ...(htmlView.mask || [])] })
+          await writeJson(join(run.dir, 'views', `${rev.id}.json`), rev)
+          view = { revision: rev.id, entry: rev.entry }
+        } catch (error) { view = { error: String(error.message).slice(0, 200) } }
+      }
+      const record = {
+        schema: 'qawalk.capture.v1',
+        ...(view ? { view } : {}),
+        node: node.id, locale, viewport, url,
+        ...variantFields(scope, viewport),
+        captured_at: new Date().toISOString(),
+        criteria_hash: criteriaHash(node),
+        console_errors: errors, blocked_requests: blocked,
+        ...result,
+        ...extra,
+        http_status: extra.http_status ?? result.http_status ?? null,
+        capture: { format: String(image).split('.').pop(), scale: shotScale, ...(dpr !== 1 ? { dpr } : {}), masked: opts.mask.length, annotations, ...(opts.fullPage ? {} : { full_page: false }) },
+        ...(ignore.length ? { ignore } : {}),
+        ...(unstable ? { unstable } : {}),
+        ...(keyboard ? { keyboard } : {}),
+        ...(item ? { item: { id: item.id, path: item.path, ...(item.title ? { title: item.title } : {}), ...(item.purpose ? { purpose: item.purpose } : {}) } } : {}),
+        ...(fields ? { fields: { ...(await page.evaluate(readFields, fields).catch(() => ({}))), ...(fields.some((f) => (f.from || f.id) === 'http') ? Object.fromEntries(fields.filter((f) => (f.from || f.id) === 'http').map((f) => [f.id, extra.http_status ?? result.http_status ?? null])) : {}) } } : {}),
+        files: { png: relative(run.dir, image), image: relative(run.dir, image), thumb: thumbWritten ? relative(run.dir, thumb) : null, html: relative(run.dir, html) }
+      }
+      const file = paths.step(stepId, locale, viewport, 'capture.json')
+      await writeJson(file, redactDeep(record))
+      await addCapture(run.dir, { type: 'capture', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, file: relative(run.dir, file), at: record.captured_at })
+      results.push(record)
+    } finally { await undoVariant() }
   }
   const last = page.viewportSize()
   if (original && (!last || last.width !== original.width || last.height !== original.height)) await page.setViewportSize(original)

package/src/lib/ci.mjs

@@ -113,7 +113,7 @@ function walkScript ({ scenarios, env, affected, k }) {
 }
 
 /** .github/workflows/kaloko.yml */
-export function githubWorkflow ({ scenarios, env = 'preview', trigger = 'deployment', affected = true, pm = 'npm', dependency = true, version = 'latest', node = 22 }) {
+export function githubWorkflow ({ scenarios, env = 'preview', trigger = 'deployment', affected = true, pm = 'npm', dependency = true, version = 'latest', node = 22, browsers = ['chromium'] }) {
   const { install, kaloko: k } = runner({ pm, dependency, version })
   const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
   const on = trigger === 'deployment'
@@ -153,7 +153,7 @@ ${guard}    runs-on: ubuntu-latest
       - uses: actions/setup-node@v4
         with:
           node-version: ${node}
-${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}      - run: ${k} browser install --with-deps   # the Chromium of kaloko's own Playwright
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}      - run: ${k} browser install --with-deps${engineFlag(browsers)}   # the ${engineWords(browsers)} of kaloko's own Playwright
       - name: Preview deployment
         # the deployment's URL, the pull request and its base; waits for the preview when it is still building
         run: ${k} ci preview-url --wait 600 --github-env
@@ -163,8 +163,12 @@ ${indent(walkScript({ scenarios, env, affected, k }), 10)}
 `
 }
 
+/** `--browsers webkit,…` when a scenario walks more than Chromium (cross-browser runs install their engines). */
+const engineFlag = (browsers = ['chromium']) => (browsers.some((b) => b !== 'chromium') ? ` --browsers ${browsers.join(',')}` : '')
+const engineWords = (browsers = ['chromium']) => (browsers.some((b) => b !== 'chromium') ? 'browser engines' : 'Chromium')
+
 /** kaloko.gitlab-ci.yml, included from .gitlab-ci.yml */
-export function gitlabJob ({ scenarios, env = 'preview', affected = true, pm = 'npm', dependency = true, version = 'latest', playwright = '1.55.0' }) {
+export function gitlabJob ({ scenarios, env = 'preview', affected = true, pm = 'npm', dependency = true, version = 'latest', playwright = '1.55.0', browsers = ['chromium'] }) {
   const { install, kaloko: k } = runner({ pm, dependency, version })
   const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
   return `# Kaloko: walk the scenarios a merge request affects on its review app and comment on the MR.
@@ -182,7 +186,7 @@ kaloko:
     KALOKO_AGENT: gitlab-ci
     # KALOKO_PREVIEW_URL: https://$CI_COMMIT_REF_SLUG.review.example.com   # when the review app URL is known
   script:
-${install ? `${['pnpm', 'yarn'].includes(pm) ? '    - corepack enable\n' : ''}    - ${install}\n` : ''}    - ${k} browser install
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '    - corepack enable\n' : ''}    - ${install}\n` : ''}    - ${k} browser install${engineFlag(browsers)}
     - export KALOKO_PREVIEW_URL="$(${k} ci preview-url --wait 600)"
     - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
     - |

package/src/lib/design-cli.mjs

@@ -11,6 +11,7 @@ import { loadTokens } from './drift.mjs'
 import { layout } from './scenario.mjs'
 import { launchEphemeral } from './browser.mjs'
 import { observeConsole } from './console.mjs'
+import { contextOptionsOf } from './dimensions.mjs'
 import { slimCapture } from './manifest-core.mjs'
 import { captureKey, sha256Hex, extOf, TEXT_TYPES, RENDERER } from './design-core.mjs'
 import { designDir, revisionOf, serveDesign, copyLive, fromCache, toCache, restoreCached, readBase, writeBase, headKey, tokensRef } from './design.mjs'
@@ -50,8 +51,16 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
   const tokens = await loadTokens({ client: null, config, root, designDir: dir })
   let rendered = 0, reused = 0
   try {
-    const page = await (await browser.newContext()).newPage()
-    observeConsole(page)
+    // one page per device profile (batch E): a phone preset renders with touch, its pixel ratio and user agent, so
+    // (pointer: coarse) and (hover: none) apply to the design as on the phone
+    const pages = new Map()
+    const scope = run.meta.scope
+    const pageFor = async (vp) => {
+      const emulation = scope?.devices?.[scope?.variants?.[vp]?.device]?.emulation || null
+      const k = emulation?.key || ''
+      if (!pages.has(k)) { const p = await (await browser.newContext(contextOptionsOf({ engine: 'chromium', emulation }))).newPage(); observeConsole(p); pages.set(k, p) }
+      return pages.get(k)
+    }
     for (const [key, rev] of Object.entries(fresh)) {
       const node = scenario.nodes.find((n) => n.id === rev.node)
       revisions[key] = rev
@@ -70,10 +79,21 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
           reused++
         } else todo[vp] = size
       }
-      if (Object.keys(todo).length) {
+      // dark captures render <step>/dark/index.html when the step has one; otherwise the page itself in the dark
+      // scheme (prefers-color-scheme emulated): one page load per entry
+      const darkEntry = rev.entry.replace(/index\.html$/, 'dark/index.html')
+      const groups = new Map()
+      for (const [vp, size] of Object.entries(todo)) {
+        const entry = run.meta.scope?.variants?.[vp]?.color_scheme === 'dark' && rev.files[darkEntry] ? darkEntry : rev.entry
+        const page = await pageFor(vp)
+        const g = `${entry}|${[...pages.values()].indexOf(page)}`
+        if (!groups.has(g)) groups.set(g, { entry, page, vps: {} })
+        groups.get(g).vps[vp] = size
+      }
+      for (const { entry, page, vps } of groups.values()) {
         const since = new Date().toISOString()
-        await page.goto(`${server.url}/${rev.entry}`, { waitUntil: 'load' })
-        const results = await captureStep({ page, node, locale: rev.locale, viewports: todo, run, maxChars: config.evaluators?.jev?.max_state_chars, since, extra: { live }, designSummary: true, tokens })
+        await page.goto(`${server.url}/${entry}`, { waitUntil: 'load' })
+        const results = await captureStep({ page, node, locale: rev.locale, viewports: vps, run, maxChars: config.evaluators?.jev?.max_state_chars, since, extra: { live: entry === rev.entry ? live : { ...live, entry } }, designSummary: true, tokens })
         for (const r of results) { await toCache({ root, output: config.output, key: captureKey(rev.id, r.viewport, mode), runDir: run.dir, record: r }); rendered++ }
       }
       say(`✓ ${node.id} ${rev.locale}  revision ${rev.id.slice(0, 8)}${Object.keys(todo).length ? '' : '  (unchanged, reused)'}`)
@@ -88,6 +108,15 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
   return { rendered, reused, revisions }
 }
 
+/**
+ * The scope the draft keeps: locales and capture keys, and (batch E) what the keys mean and the device presets, so
+ * versions on the service get the scheme switcher and device frames. User agents stay local.
+ */
+export function syncScope (scope, locales) {
+  const devices = scope.devices ? Object.fromEntries(Object.entries(scope.devices).map(([k, { emulation: _e, ...d }]) => [k, d])) : null
+  return { locales, viewports: scope.viewports, ...(scope.variants ? { variants: scope.variants } : {}), ...(scope.dimensions ? { dimensions: scope.dimensions } : {}), ...(devices ? { devices } : {}) }
+}
+
 /** Scenario snapshot the service keeps with the draft (so it can compose versions without the CLI). */
 export function snapshotOf (scenario, run) {
   const pos = Object.fromEntries(layout(scenario).map((p) => [p.id, { col: p.col, lane: p.lane }]))
@@ -246,7 +275,7 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
     await uploadBlobs({ client, org, files, say })
     const heads = toPush.map((key) => ({ node: local[key].node, locale: local[key].locale, state: local[key].state, revision: local[key].id, base: remoteHeads[key] || null }))
     try {
-      result = await client.request('POST', `/orgs/${org}/scenarios/${sid}/draft`, { branch, snapshot, scope: { locales, viewports: run.meta.scope.viewports }, environment: env.name, git_branch: run.meta.git?.branch || null, revisions, heads })
+      result = await client.request('POST', `/orgs/${org}/scenarios/${sid}/draft`, { branch, snapshot, scope: syncScope(run.meta.scope, locales), environment: env.name, git_branch: run.meta.git?.branch || null, revisions, heads })
     } catch (e) {
       if (/HTTP 409/.test(e.message)) { say(`${e.message}\nSomeone changed these steps a moment ago; sync again to see them.`); process.exitCode = 1; return { conflicts: true } }
       throw e

package/src/lib/design.mjs

@@ -49,7 +49,9 @@ export async function scanStep ({ dir, node, locale, locales }) {
   // the default page or another locale's); everything else comes in through references
   const entryDir = entry.slice(0, entry.lastIndexOf('/') + 1)
   const beside = (entryDir === `${node}/` ? common : mine.map((p) => p.slice(locale.length + 1))).filter((p) => !p.includes('/') && extOf(p) !== 'html')
-  const roots = [entry, ...beside.map((p) => entryDir + p)]
+  // 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)]
   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) {

package/src/lib/devices.mjs

@@ -0,0 +1,85 @@
+// Device presets (batch E): named devices a scenario's `viewports:` may use instead of a bare size, with the pixel
+// ratio, user agent, touch, safe areas and the frame the canvas and Kaloko Design draw around the capture.
+//   screen  the whole display in CSS pixels, portrait for phones and tablets
+//   ui      [top, bottom] browser UI and status bar a web page does not get (Safari's address bar, Chrome's toolbar);
+//           web walks use screen minus ui, Design and installed PWAs (display mode standalone) use the whole screen
+//   safe    safe-area insets of the screen (notch, Dynamic Island, home indicator, punch-hole camera)
+// Values are the common ones of each device class, not a lab measurement: good enough to catch layout bugs, not a
+// replacement for a real device. `<preset>-landscape` turns any phone, foldable or tablet preset sideways.
+
+const IOS_UA = (os = '18_0', v = '18.0', kind = 'iPhone') => `Mozilla/5.0 (${kind}; CPU ${kind === 'iPad' ? 'OS' : 'iPhone OS'} ${os} like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/${v} Mobile/15E148 Safari/604.1`
+const ANDROID_UA = (model, mobile = true) => `Mozilla/5.0 (Linux; Android 14; ${model}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 ${mobile ? 'Mobile ' : ''}Safari/537.36`
+
+export const DEVICES = {
+  'iphone-se': { title: 'iPhone SE', kind: 'phone', os: 'ios', screen: [375, 667], ui: [20, 94], dpr: 2, mobile: true, touch: true, ua: IOS_UA(), safe: { top: 20, bottom: 0 }, frame: 'home-button' },
+  'iphone-15': { title: 'iPhone 15', kind: 'phone', os: 'ios', screen: [393, 852], ui: [59, 134], dpr: 3, mobile: true, touch: true, ua: IOS_UA(), safe: { top: 59, bottom: 34 }, frame: 'island' },
+  'iphone-16': { title: 'iPhone 16', kind: 'phone', os: 'ios', screen: [393, 852], ui: [59, 134], dpr: 3, mobile: true, touch: true, ua: IOS_UA(), safe: { top: 59, bottom: 34 }, frame: 'island' },
+  'iphone-16-pro-max': { title: 'iPhone 16 Pro Max', kind: 'phone', os: 'ios', screen: [440, 956], ui: [62, 134], dpr: 3, mobile: true, touch: true, ua: IOS_UA(), safe: { top: 62, bottom: 34 }, frame: 'island' },
+  'pixel-8': { title: 'Pixel 8', kind: 'phone', os: 'android', screen: [412, 915], ui: [52, 24], dpr: 2.625, mobile: true, touch: true, ua: ANDROID_UA('Pixel 8'), safe: { top: 24, bottom: 24 }, frame: 'punch-hole' },
+  'pixel-8-pro': { title: 'Pixel 8 Pro', kind: 'phone', os: 'android', screen: [448, 998], ui: [52, 24], dpr: 3, mobile: true, touch: true, ua: ANDROID_UA('Pixel 8 Pro'), safe: { top: 24, bottom: 24 }, frame: 'punch-hole' },
+  'galaxy-s24': { title: 'Galaxy S24', kind: 'phone', os: 'android', screen: [360, 780], ui: [52, 24], dpr: 3, mobile: true, touch: true, ua: ANDROID_UA('SM-S921B'), safe: { top: 24, bottom: 24 }, frame: 'punch-hole' },
+  'fold-folded': { title: 'Galaxy Z Fold (folded)', kind: 'foldable', os: 'android', screen: [344, 882], ui: [52, 24], dpr: 2.625, mobile: true, touch: true, ua: ANDROID_UA('SM-F946B'), safe: { top: 24, bottom: 24 }, frame: 'punch-hole' },
+  'fold-open': { title: 'Galaxy Z Fold (open)', kind: 'foldable', os: 'android', screen: [690, 829], ui: [52, 24], dpr: 2.625, mobile: true, touch: true, ua: ANDROID_UA('SM-F946B'), safe: { top: 24, bottom: 24 }, frame: 'fold' },
+  'ipad-portrait': { title: 'iPad', kind: 'tablet', os: 'ios', screen: [820, 1180], ui: [74, 0], dpr: 2, mobile: true, touch: true, ua: IOS_UA('18_0', '18.0', 'iPad'), safe: { top: 24, bottom: 20 }, frame: 'tablet' },
+  'ipad-landscape': { title: 'iPad (landscape)', kind: 'tablet', os: 'ios', screen: [1180, 820], ui: [74, 0], dpr: 2, mobile: true, touch: true, ua: IOS_UA('18_0', '18.0', 'iPad'), safe: { top: 24, bottom: 20 }, frame: 'tablet' },
+  'ipad-pro-portrait': { title: 'iPad Pro 12.9″', kind: 'tablet', os: 'ios', screen: [1024, 1366], ui: [74, 0], dpr: 2, mobile: true, touch: true, ua: IOS_UA('18_0', '18.0', 'iPad'), safe: { top: 24, bottom: 20 }, frame: 'tablet' },
+  'ipad-pro-landscape': { title: 'iPad Pro 12.9″ (landscape)', kind: 'tablet', os: 'ios', screen: [1366, 1024], ui: [74, 0], dpr: 2, mobile: true, touch: true, ua: IOS_UA('18_0', '18.0', 'iPad'), safe: { top: 24, bottom: 20 }, frame: 'tablet' },
+  'android-tablet-portrait': { title: 'Android tablet', kind: 'tablet', os: 'android', screen: [800, 1280], ui: [80, 48], dpr: 2, mobile: true, touch: true, ua: ANDROID_UA('SM-X710', false), safe: { top: 24, bottom: 48 }, frame: 'tablet' },
+  'android-tablet-landscape': { title: 'Android tablet (landscape)', kind: 'tablet', os: 'android', screen: [1280, 800], ui: [80, 48], dpr: 2, mobile: true, touch: true, ua: ANDROID_UA('SM-X710', false), safe: { top: 24, bottom: 48 }, frame: 'tablet' },
+  laptop: { title: 'Laptop 1440', kind: 'laptop', os: null, screen: [1440, 900], ui: [0, 0], dpr: 2, mobile: false, touch: false, ua: null, safe: null, frame: 'laptop' },
+  'desktop-hd': { title: 'Desktop 1920', kind: 'desktop', os: null, screen: [1920, 1080], ui: [0, 0], dpr: 1, mobile: false, touch: false, ua: null, safe: null, frame: 'monitor' },
+  'desktop-wide': { title: 'Wide 2560', kind: 'desktop', os: null, screen: [2560, 1440], ui: [0, 0], dpr: 1, mobile: false, touch: false, ua: null, safe: null, frame: 'monitor' },
+  'tv-1080p': { title: 'TV 1080p', kind: 'tv', os: null, screen: [1920, 1080], ui: [0, 0], dpr: 1, mobile: false, touch: false, ua: 'Mozilla/5.0 (SMART-TV; LINUX; Tizen 7.0) AppleWebKit/537.36 (KHTML, like Gecko) 94.0.4606.31/7.0 TV Safari/537.36', safe: { top: 27, bottom: 27, left: 48, right: 48 }, frame: 'tv' }
+}
+
+/** Other names people use for the same preset. */
+export const ALIASES = {
+  'small-phone': 'iphone-se', 'large-phone': 'iphone-16-pro-max', 'android-phone': 'pixel-8', 'ipad': 'ipad-portrait',
+  'tablet-portrait': 'ipad-portrait', 'tablet-landscape': 'ipad-landscape', 'fold-closed': 'fold-folded', 'foldable': 'fold-open',
+  'laptop-1440': 'laptop', 'desktop-1920': 'desktop-hd', 'wide': 'desktop-wide', 'wide-2560': 'desktop-wide', 'tv': 'tv-1080p'
+}
+
+const ROTATES = new Set(['phone', 'foldable', 'tablet'])
+
+/**
+ * A preset by name (aliases and `-landscape` included), with `name` and `size`: the CSS viewport a walk uses.
+ * `fullScreen` (Design, installed PWA, app mockups) uses the whole screen instead of screen minus browser UI.
+ * Returns null for an unknown name.
+ */
+export function devicePreset (name, { fullScreen = false } = {}) {
+  const key = String(name || '').trim().toLowerCase()
+  let id = ALIASES[key] || key
+  let base = DEVICES[id]
+  let landscape = false
+  if (!base && id.endsWith('-landscape')) {
+    const portrait = ALIASES[id.slice(0, -10)] || id.slice(0, -10)
+    if (DEVICES[portrait] && ROTATES.has(DEVICES[portrait].kind) && DEVICES[portrait].screen[0] < DEVICES[portrait].screen[1]) { base = DEVICES[portrait]; landscape = true; id = `${portrait}-landscape` }
+  }
+  if (!base) return null
+  const d = JSON.parse(JSON.stringify(base))
+  if (landscape) {
+    d.title = `${d.title} (landscape)`
+    d.screen = [d.screen[1], d.screen[0]]
+    // the notch and the home indicator move to the sides; the browser keeps a top bar
+    if (d.safe) d.safe = { top: 0, bottom: d.safe.bottom ? 21 : 0, left: d.safe.top > 24 ? d.safe.top : 0, right: d.safe.top > 24 ? d.safe.top : 0 }
+    d.ui = [Math.min(d.ui[0], 50), 0]
+  }
+  const ui = fullScreen ? [0, 0] : d.ui
+  return { name: id, ...d, size: [d.screen[0], Math.max(200, d.screen[1] - ui[0] - ui[1])], full_screen: !!fullScreen }
+}
+
+/** Every preset name (for help texts, validation messages and the skill). */
+export const presetNames = () => Object.keys(DEVICES)
+
+/**
+ * What a capture needs to emulate the preset in a browser context: pixel ratio, mobile viewport, touch and user
+ * agent. Desktop presets emulate only the pixel ratio. The profile key groups variants that can share one context.
+ */
+export function emulationOf (preset) {
+  if (!preset) return null
+  const profile = { dpr: preset.dpr || 1, mobile: !!preset.mobile, touch: !!preset.touch, ua: preset.ua || null }
+  return { ...profile, key: `${profile.dpr}|${profile.mobile ? 'm' : 'd'}|${profile.touch ? 't' : ''}|${profile.ua || ''}` }
+}
+
+/** What the canvas and the manifest keep of a preset (no user agent: it is long and only the walk needs it). */
+export const presetSummary = (p) => p && ({ name: p.name, title: p.title, kind: p.kind, os: p.os, screen: p.screen, size: p.size, dpr: p.dpr, touch: p.touch, safe: p.safe, frame: p.frame, ui: p.full_screen ? [0, 0] : p.ui, ...(p.full_screen ? { full_screen: true } : {}) })

package/src/lib/devspec.mjs

@@ -206,7 +206,8 @@ export function kalokoDev (opts) {
     if (/width$/.test(prop)) return { kind: 'dim', fit: (e) => e.type === 'borderWidth' || /border|stroke/i.test(e.name) }
     return null
   }
-  const pref = (list) => list.find((e) => !e.mode) || list[0]
+  // the capture's colour scheme picks the token mode (light, dark) when the set has it (batch E)
+  const pref = (list) => (o.mode && list.find((e) => e.mode === o.mode)) || list.find((e) => !e.mode) || list[0]
   const tokOut = (m, e, extra) => Object.assign({ m, name: e.name, value: e.css }, e.mode ? { mode: e.mode } : {}, extra || {})
   /**
    * The token of one computed value: { m: 'exact', name, value, mode? } or { m: 'nearest', name, value } for a
@@ -818,4 +819,4 @@ export function driftText (findings, { title = '' } = {}) {
 }
 
 /** Expression for page.evaluate that returns the page spec (async: linked stylesheets may need a fetch). */
-export const pageSpecScript = (tokens, maxElements = 300) => `(${kalokoDev.toString()})(${JSON.stringify({ tokens: tokens || null, maxElements })}).pageSpec()`
+export const pageSpecScript = (tokens, maxElements = 300, mode = null) => `(${kalokoDev.toString()})(${JSON.stringify({ tokens: tokens || null, maxElements, ...(mode ? { mode } : {}) })}).pageSpec()`