kaloko 0.9.0 → 0.10.0

package/src/lib/build.mjs

@@ -4,10 +4,9 @@ import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { readJson, writeJson } from './util.mjs'
 import { readCaptures, runPaths, listRuns } from './run.mjs'
-import { latestCaptures, evaluationSource, stepIdOf, appliesOn } from './evaluate.mjs'
-import { fieldsOf, DEFAULT_SEMANTIC_SAMPLE } from './stack.mjs'
+import { latestCaptures, evaluationSource, stepIdOf } from './evaluate.mjs'
 import { layout } from './scenario.mjs'
-import { assembleNode, summarize, statusOf, worst } from './manifest-core.mjs'
+import { assembleNode, assembleStack, summarize } from './manifest-core.mjs'
 import { packageRoot } from './schema.mjs'
 import { variantOf } from './dimensions.mjs'
 
@@ -148,53 +147,17 @@ async function runMedia ({ run, entries }) {
  */
 async function buildStack ({ run, node, base, captures, attachments }) {
   const paths = runPaths(run.dir)
-  const fields = fieldsOf(node).map((f) => ({ id: f.id, label: f.label || f.id }))
-  const environment = run.meta?.environment?.name || null
-  const crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null, ...(appliesOn(c, environment) ? {} : { not_applicable: 'environment' }) }))
-  // criteria limited to other environments do not decide the status of a page
-  const live = new Set(crit.filter((c) => !c.not_applicable).map((c) => c.id))
-  const byItem = new Map()
+  const list = []
   for (const c of captures.filter((x) => x.node === node.id && x.item)) {
     const cap = await readJson(join(run.dir, c.file))
-    const evPath = paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json')
-    const stored = await readJson(evPath, null)
+    const stored = await readJson(paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json'), null)
     const ev = stored?.source === evaluationSource(node, cap) ? stored : null
-    let it = byItem.get(c.item)
-    if (!it) { it = { id: c.item, path: cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size }; byItem.set(c.item, it) }
-    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, url: cap.url, size: cap.size ? [cap.size.width, cap.size.height] : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), eval: ev ? `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` : null }
-    it.results[`${c.locale}|${c.viewport}`] = ev ? Object.fromEntries(ev.criteria.map((r) => [r.id, [r.verdict, r.evidence ? String(r.evidence).slice(0, 200) : null, r.score ?? null]])) : Object.fromEntries(crit.filter((x) => x.type !== 'semantic').map((x) => [x.id, ['not_evaluated', null, null]]))
-    if (!ev) it.stale = true
-  }
-  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, ...it }) => {
-    const per = Object.values(it.results)
-    const verdictOf = (id) => worst(per.map((r) => r[id]?.[0]).filter(Boolean))
-    const verdicts = crit.filter((c) => live.has(c.id)).map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
-    const status = statusOf(verdicts, per.length > 0)
-    const by_locale = Object.fromEntries(Object.keys(it.captures).map((l) => [l, statusOf(Object.entries(it.results).filter(([k]) => k.startsWith(`${l}|`)).flatMap(([, r]) => Object.entries(r).filter(([id]) => live.has(id)).map(([, x]) => x[0])), true)]))
-    return { ...it, status, by_locale, fails: crit.filter((c) => live.has(c.id) && verdictOf(c.id) === 'fail').map((c) => c.id), review: crit.filter((c) => live.has(c.id) && ['needs_review', 'not_evaluated'].includes(verdictOf(c.id))).map((c) => c.id) }
-  })
-  const summary = { pass: 0, partial: 0, fail: 0, skip: 0 }
-  for (const it of items) summary[it.status]++
-  const criteria = crit.map((c) => {
-    const counts = {}
-    for (const it of items) { const v = worst(Object.values(it.results).map((r) => r[c.id]?.[0]).filter(Boolean)); if (v !== 'not_reached') counts[v] = (counts[v] || 0) + 1 }
-    return { ...c, counts, verdict: counts.fail ? 'fail' : counts.needs_review ? 'needs_review' : counts.not_evaluated ? 'not_evaluated' : counts.pass ? 'pass' : 'not_reached', by_locale: {} }
-  })
-  const semanticSample = node.items?.semantic_sample ?? DEFAULT_SEMANTIC_SAMPLE
-  const file = `steps/${node.id}/items.json`
-  await writeJson(join(run.dir, file), { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, items })
-  const thumbOf = (it) => { const c = Object.values(it.captures)[0]; const v = c && Object.values(c)[0]; return v ? v.thumb || v.png : null }
-  const sample = [...items.filter((it) => it.status === 'fail'), ...items.filter((it) => it.status !== 'fail')].slice(0, 4).map((it) => ({ id: it.id, title: it.title, path: it.path, status: it.status, thumb: thumbOf(it) }))
-  const status = !items.length ? 'skip' : summary.fail ? 'fail' : summary.partial || summary.skip ? 'partial' : 'pass'
-  const locales = [...new Set(items.flatMap((it) => Object.keys(it.by_locale)))]
-  const by_locale = Object.fromEntries(locales.map((l) => { const s = items.map((it) => it.by_locale[l]).filter(Boolean); return [l, s.includes('fail') ? 'fail' : s.some((x) => x !== 'pass') ? 'partial' : 'pass'] }))
-  const src = node.items || {}
-  return {
-    ...base, status, by_locale, captures: {}, criteria, semantic: {}, metadata: {}, session: node.session || null,
-    execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : { strategy: 'playwright', instructions: 'Open every page of the stack and capture it.' },
-    attachments: attachments.filter((a) => a.node === node.id && a.kind !== 'focus').map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale })),
-    stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source: ['urls', 'file', 'sitemap', 'crawl', 'script'].find((k) => src[k]) || null, stale: items.filter((it) => it.stale).length }
+    // a variant of a design stack (#61) opens live in the lightbox: its page in the step's revision
+    list.push({ item: c.item, locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, eval: `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` }, ...(cap.live ? { live: cap.live } : {}) })
   }
+  const { node: out, index, file } = assembleStack({ node, base, environment: run.meta?.environment?.name || null, captures: list, attachments })
+  await writeJson(join(run.dir, file), index)
+  return out
 }
 
 /**

package/src/lib/capture.mjs

@@ -165,7 +165,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         }
       }
       // 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)
+      if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens, scope?.variants?.[viewport]?.token_mode || 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

package/src/lib/design-cli.mjs

@@ -11,10 +11,12 @@ 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 { contextOptionsOf, stateOf } from './dimensions.mjs'
+import { slimCapture, keyAppliesTo } from './manifest-core.mjs'
+import { modeCss } from './tokens.mjs'
+import { fieldsOf } from './stack.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'
+import { designDir, revisionOf, serveDesign, copyLive, fromCache, toCache, restoreCached, readBase, writeBase, headKey, tokensRef, statePage } from './design.mjs'
 
 const enc = encodeURIComponent
 const screensOf = (scenario) => scenario.nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'external')
@@ -26,29 +28,50 @@ export async function localRevisions ({ dir, scenario, locales, allLocales, proj
   for (const locale of locales) {
     for (const node of screensOf(scenario)) {
       if (pick && !pick.includes(node.id)) continue
-      const rev = await revisionOf({ dir, scenario: scenario.id, node: node.id, locale, locales: allLocales, tokens })
+      const rev = await revisionOf({ dir, scenario: scenario.id, node: node.id, locale, locales: allLocales, tokens, states: node.states, stack: node.kind === 'stack' ? node : null })
       if (rev) out[headKey(node.id, locale)] = rev
     }
   }
   return out
 }
 
+/**
+ * In the page: a token mode's custom properties after the page's own styles, and data-kaloko-mode on <html> for
+ * pages that switch themes themselves (#46). `null` removes both.
+ */
+function setTokenMode (arg) {
+  const old = document.getElementById('kaloko-token-mode')
+  if (old) old.remove()
+  if (!arg) { document.documentElement.removeAttribute('data-kaloko-mode'); return }
+  const style = document.createElement('style')
+  style.id = 'kaloko-token-mode'
+  style.textContent = arg.css
+  ;(document.head || document.documentElement).appendChild(style)
+  document.documentElement.setAttribute('data-kaloko-mode', arg.mode)
+}
+
 /**
  * Walk of a design environment: serves the folder, renders each step and locale in every viewport, and reuses
  * captures of revisions that were already rendered (content cache). Writes revisions.json into the run.
+ * Steps with states (#46) render each state's page (statePage, else the entry with ?state=<name>); runs with token
+ * modes render each mode with its tokens as custom properties.
  */
 export async function walkDesign ({ config, root, run, scenario, env, pick, locales, viewports, say, noCache = false }) {
   const dir = designDir(env, root)
   const revisions = await readJson(join(run.dir, 'revisions.json'), {})
   const fresh = await localRevisions({ dir, scenario, locales, allLocales: run.meta.scope.locales, project: run.meta.project?.slug, pick })
   const missing = []
-  for (const locale of locales) for (const node of screensOf(scenario)) if ((!pick || pick.includes(node.id)) && !fresh[headKey(node.id, locale)]) missing.push(`${node.id} (${locale}): add ${node.id}/index.html to ${relative(process.cwd(), dir)}/`)
+  for (const locale of locales) for (const node of screensOf(scenario)) if ((!pick || pick.includes(node.id)) && !fresh[headKey(node.id, locale)]) missing.push(`${node.id} (${locale}): add ${node.kind === 'stack' ? `a folder per variant, ${node.id}/<variant>/index.html,` : `${node.id}/index.html`} to ${relative(process.cwd(), dir)}/`)
   const server = await serveDesign(dir)
   const browser = await launchEphemeral(config)
   const paths = runPaths(run.dir)
   const mode = env.tokens_mode || ''
   // the design folder's own set names the values in the step spec (the one its live pages reference)
   const tokens = await loadTokens({ client: null, config, root, designDir: dir })
+  const scope0 = run.meta.scope
+  // token modes (#46): the set's values of each mode as CSS, set on the page before it is captured
+  const modeSheets = new Map((scope0?.dimensions?.token_modes || []).map((m) => [m, tokens ? modeCss(tokens, m) : '']))
+  const stateNotes = new Set()
   let rendered = 0, reused = 0
   try {
     // one page per device profile (batch E): a phone preset renders with touch, its pixel ratio and user agent, so
@@ -61,42 +84,69 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
       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
-      await copyLive(run.dir, dir, rev)
-      const live = { revision: rev.id, entry: rev.entry }
+    // renders one page (a step, or one item of a stack step) in the viewports whose captures are not cached
+    const renderPage = async ({ node, rev, entry: base, vpsIn, item = null }) => {
+      const stepId = item ? `${node.id}/items/${item.id}` : node.id
+      const live = { revision: rev.id, entry: base }
       const todo = {}
-      for (const [vp, size] of Object.entries(viewports)) {
-        const ck = captureKey(rev.id, vp, mode)
+      for (const [vp, size] of Object.entries(vpsIn)) {
+        if (!keyAppliesTo(vp, node)) continue // a state this step does not have
+        const ck = captureKey(rev.id, vp, mode, item?.id)
         const cached = noCache ? null : await fromCache({ root, output: config.output, key: ck })
-        // a capture from before the step spec existed renders again, so Dev mode and `kaloko spec` have it
-        if (cached && cached.record.criteria_hash === criteriaHash(node) && cached.record.spec) {
-          const record = await restoreCached({ cached, runDir: run.dir, paths, node: node.id, locale: rev.locale, viewport: vp })
-          const file = paths.step(node.id, rev.locale, vp, 'capture.json')
+        // a capture from before the step spec existed renders again, so Dev mode and `kaloko spec` have it (items have none)
+        if (cached && cached.record.criteria_hash === criteriaHash(node) && (item || cached.record.spec)) {
+          const record = await restoreCached({ cached, runDir: run.dir, paths, node: stepId, locale: rev.locale, viewport: vp })
+          const file = paths.step(stepId, rev.locale, vp, 'capture.json')
           await writeJson(file, record)
-          await addCapture(run.dir, { type: 'capture', node: node.id, locale: rev.locale, viewport: vp, file: relative(run.dir, file), at: new Date().toISOString() })
+          await addCapture(run.dir, { type: 'capture', node: node.id, ...(item ? { item: item.id } : {}), locale: rev.locale, viewport: vp, file: relative(run.dir, file), at: new Date().toISOString() })
           reused++
         } else todo[vp] = size
       }
-      // dark captures render <step>/dark/index.html when the step has one; otherwise the page itself in the dark
+      // dark captures render <page folder>/dark/index.html when there is 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 darkEntry = base.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 variant = run.meta.scope?.variants?.[vp] || {}
+        const state = stateOf(vp)
+        // a state renders its own page (<page folder>/<state>.html), else the page with ?state=<name>
+        let entry = state === 'default' ? base : statePage(base, state, rev.files)
+        let query = ''
+        if (!entry) {
+          entry = base; query = `?state=${encodeURIComponent(state)}`
+          const note = `${node.id}${item ? `/${item.id}` : ''} ${state}: no ${base.replace(/index\.html$/, `${state}.html`)}; rendered ${base}${query}`
+          if (!stateNotes.has(note)) { stateNotes.add(note); say(`  ${note}`) }
+        }
+        if (state === 'default' && variant.color_scheme === 'dark' && rev.files[darkEntry]) entry = darkEntry
+        const tokenMode = modeSheets.size ? (variant.token_mode || scope0.dimensions.token_modes[0]) : null
         const page = await pageFor(vp)
-        const g = `${entry}|${[...pages.values()].indexOf(page)}`
-        if (!groups.has(g)) groups.set(g, { entry, page, vps: {} })
+        const g = `${entry}${query}|${tokenMode || ''}|${[...pages.values()].indexOf(page)}`
+        if (!groups.has(g)) groups.set(g, { entry, query, tokenMode, page, vps: {} })
         groups.get(g).vps[vp] = size
       }
-      for (const { entry, page, vps } of groups.values()) {
+      for (const { entry, query, tokenMode, page, vps } of groups.values()) {
         const since = new Date().toISOString()
-        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++ }
+        await page.goto(`${server.url}/${entry}${query}`, { waitUntil: 'load' })
+        if (tokenMode) await page.evaluate(setTokenMode, { mode: tokenMode, css: modeSheets.get(tokenMode) || '' })
+        const results = await captureStep({ page, node, locale: rev.locale, viewports: vps, run, maxChars: config.evaluators?.jev?.max_state_chars, since, extra: { live: entry !== base ? { ...live, entry } : query ? { ...live, query: query.slice(1) } : live }, designSummary: true, tokens, ...(item ? { item, fields: fieldsOf(node) } : {}) })
+        for (const r of results) { await toCache({ root, output: config.output, key: captureKey(rev.id, r.viewport, mode, item?.id), runDir: run.dir, record: r }); rendered++ }
+      }
+      return Object.keys(todo).length
+    }
+    for (const [key, rev] of Object.entries(fresh)) {
+      const node = scenario.nodes.find((n) => n.id === rev.node)
+      revisions[key] = rev
+      await copyLive(run.dir, dir, rev)
+      if (rev.items) {
+        // a stack step (#61): every variant is a page of its own, captured like a page of a stack in an app run
+        const vps = stackViewports(node, viewports)
+        let todo = 0
+        for (const it of rev.items) todo += await renderPage({ node, rev, entry: it.entry, vpsIn: vps, item: { id: it.id, path: it.entry.replace(/index\.html$/, '') } })
+        say(`✓ ${node.id} ${rev.locale}  revision ${rev.id.slice(0, 8)}  ${rev.items.length} variant(s)${todo ? '' : '  (unchanged, reused)'}`)
+        continue
       }
-      say(`✓ ${node.id} ${rev.locale}  revision ${rev.id.slice(0, 8)}${Object.keys(todo).length ? '' : '  (unchanged, reused)'}`)
+      const todo = await renderPage({ node, rev, entry: rev.entry, vpsIn: viewports })
+      say(`✓ ${node.id} ${rev.locale}  revision ${rev.id.slice(0, 8)}${todo ? '' : '  (unchanged, reused)'}`)
     }
   } finally {
     await browser.close()
@@ -108,6 +158,17 @@ export async function walkDesign ({ config, root, run, scenario, env, pick, loca
   return { rendered, reused, revisions }
 }
 
+/**
+ * Viewports a stack step's variants are captured in on a design environment (#61): `items.viewports` when the step
+ * names some, else every viewport of the walk (a design has a few variants, not hundreds of pages).
+ */
+export function stackViewports (node, viewports) {
+  const want = node.items?.viewports
+  if (!Array.isArray(want) || !want.length) return viewports
+  const out = Object.fromEntries(Object.entries(viewports).filter(([k]) => want.includes(k) || want.includes(k.split('.')[0])))
+  return Object.keys(out).length ? out : viewports
+}
+
 /**
  * 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.
@@ -163,6 +224,8 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
   const remote = await client.request('GET', `/orgs/${org}/scenarios/${sid}/draft?branch=${enc(branch)}`)
   const remoteHeads = Object.fromEntries((remote.heads || []).map((h) => [headKey(h.node, h.locale, h.state), h.revision]))
   const remoteCaps = Object.fromEntries((remote.heads || []).map((h) => [headKey(h.node, h.locale, h.state), h.captures || {}]))
+  // a stack step's captures are per variant (#61): item → viewport → { renderer, criteria_hash }
+  const remoteItemCaps = Object.fromEntries((remote.heads || []).map((h) => [headKey(h.node, h.locale, h.state), h.item_captures || {}]))
   const snapshot = snapshotOf(scenario, run)
   const snapshotChanged = !remote.exists || remote.snapshot_hash !== await sha256Hex(JSON.stringify(snapshot))
   let local = await localRevisions({ dir, scenario, locales, allLocales: locales, project: run.meta.project?.slug })
@@ -214,32 +277,38 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
   }
   let result = null
   // same revision, but its draft captures were rendered by another renderer or for other criteria: send them again
-  const vpsAll = Object.keys(run.meta.scope.viewports)
-  const toRefresh = push ? Object.keys(local).filter((key) => local[key].id === remoteHeads[key] && !toPush.includes(key) && vpsAll.some((vp) => { const rc = remoteCaps[key]?.[vp]; const node = scenario.nodes.find((n) => n.id === local[key].node); return !rc || rc.renderer !== RENDERER || rc.criteria_hash !== criteriaHash(node) })) : []
+  const nodeOf = (key) => scenario.nodes.find((n) => n.id === local[key].node)
+  // what a step's draft captures are: [item, viewport] pairs (item '' for a plain step; every variant of a stack step),
+  // without the keys of states (#46) the step does not have
+  const slots = (key) => {
+    const rev = local[key]
+    const vps = Object.keys(rev.items ? stackViewports(nodeOf(key), run.meta.scope.viewports) : run.meta.scope.viewports).filter((k) => keyAppliesTo(k, nodeOf(key)))
+    return rev.items ? rev.items.flatMap((it) => vps.map((vp) => [it.id, vp])) : vps.map((vp) => ['', vp])
+  }
+  const toRefresh = push ? Object.keys(local).filter((key) => local[key].id === remoteHeads[key] && !toPush.includes(key) && slots(key).some(([item, vp]) => { const rc = item ? remoteItemCaps[key]?.[item]?.[vp] : remoteCaps[key]?.[vp]; return !rc || rc.renderer !== RENDERER || rc.criteria_hash !== criteriaHash(nodeOf(key)) })) : []
   if (push && (toPush.length || toRefresh.length || snapshotChanged)) {
-    // steps to push need captures of their current revision in every viewport of the run
-    const vps = Object.keys(run.meta.scope.viewports)
-    const capturesByKey = async () => new Map(latestCaptures(await readCaptures(run.dir)).map((c) => [`${c.node}|${c.locale}|${c.viewport}`, c]))
+    // steps to push need captures of their current revision in every viewport of the run (and state of the step)
+    const capturesByKey = async () => new Map(latestCaptures(await readCaptures(run.dir)).map((c) => [`${c.node}|${c.item || ''}|${c.locale}|${c.viewport}`, c]))
     let byKey = await capturesByKey()
     const stale = []
     const sending = [...toPush, ...toRefresh]
     for (const key of sending) {
       const [node, locale] = key.split('|')
       const want = criteriaHash(scenario.nodes.find((n) => n.id === node))
-      for (const vp of vps) {
-        const c = byKey.get(`${node}|${locale}|${vp}`)
+      for (const [item, vp] of slots(key)) {
+        const c = byKey.get(`${node}|${item}|${locale}|${vp}`)
         const rec = c ? await readJson(join(run.dir, c.file), null) : null
-        if (!rec || rec.live?.revision !== local[key].id || rec.criteria_hash !== want || !rec.design) stale.push(node)
+        if (!rec || rec.live?.revision !== local[key].id || rec.criteria_hash !== want || (!item && !rec.design)) stale.push(node)
       }
     }
     if (stale.length) { await render([...new Set(stale)]); byKey = await capturesByKey() }
     // every pushed capture carries a valid evaluation of the scenario's criteria (deterministic checks are free)
     let unevaluated = false
-    for (const key of sending) for (const vp of vps) {
+    for (const key of sending) for (const [item, vp] of slots(key)) {
       const [node, locale] = key.split('|')
-      const c = byKey.get(`${node}|${locale}|${vp}`)
+      const c = byKey.get(`${node}|${item}|${locale}|${vp}`)
       const rec = c && await readJson(join(run.dir, c.file), null)
-      const ev = await readJson(runPaths(run.dir).step(node, locale, vp, 'eval.json'), null)
+      const ev = await readJson(runPaths(run.dir).step(item ? `${node}/items/${item}` : node, locale, vp, 'eval.json'), null)
       if (rec && ev?.source !== evaluationSource(scenario.nodes.find((n) => n.id === node), rec)) unevaluated = true
     }
     if (unevaluated) { const { evaluateRun } = await import('./evaluate.mjs'); await evaluateRun({ run, scenario, config, root }); say('Evaluated the new captures against the scenario criteria.') }
@@ -250,11 +319,13 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
       const node = scenario.nodes.find((n) => n.id === rev.node)
       for (const [p, h] of Object.entries(rev.files)) files.set(h, { abs: join(dir, p), ext: extOf(p) })
       const captures = {}
-      for (const vp of vps) {
-        const c = byKey.get(`${rev.node}|${rev.locale}|${vp}`)
-        if (!c) throw new UserError(`${rev.node} ${rev.locale} ${vp}: no capture; run kaloko walk first.`)
+      const itemCaptures = {}
+      for (const [item, vp] of slots(key)) {
+        const what = `${rev.node}${item ? `/${item}` : ''} ${rev.locale} ${vp}`
+        const c = byKey.get(`${rev.node}|${item}|${rev.locale}|${vp}`)
+        if (!c) throw new UserError(`${what}: no capture; run kaloko walk first.`)
         const rec = await readJson(join(run.dir, c.file))
-        if (rec.live?.revision !== rev.id) throw new UserError(`${rev.node} ${rev.locale} ${vp}: capture does not match the folder; run kaloko walk again.`)
+        if (rec.live?.revision !== rev.id) throw new UserError(`${what}: capture does not match the folder; run kaloko walk again.`)
         const out = {}
         for (const [k, rel] of [['image', rec.files.image], ['thumb', rec.files.thumb], ['html', rec.files.html]]) {
           if (!rel) continue
@@ -263,14 +334,17 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
           files.set(h, { abs, ext: extOf(rel) })
           out[k] = h
         }
-        const stored = await readJson(runPaths(run.dir).step(rev.node, rev.locale, vp, 'eval.json'), null)
-        out.record = { ...slimCapture(rec), ...(rec.spec ? { spec: rec.spec } : {}) }
+        const stored = await readJson(runPaths(run.dir).step(item ? `${rev.node}/items/${item}` : rev.node, rev.locale, vp, 'eval.json'), null)
+        // a variant keeps what the stack index shows: its id, page and index fields; a step the page the capture
+        // rendered (a state's or the dark page, #46), so the canvas opens that page live
+        out.record = { ...slimCapture(rec), ...(rec.spec ? { spec: rec.spec } : {}), ...(item ? { item: rec.item, fields: rec.fields || {}, live: rec.live } : rec.live?.entry && rec.live.entry !== rev.entry ? { live: { entry: rec.live.entry } } : rec.live?.query ? { live: { query: rec.live.query } } : {}) }
         out.evaluation = stored?.source === evaluationSource(node, rec) ? stored : null
-        out.mode = env.tokens_mode || ''
+        out.mode = rec.token_mode || env.tokens_mode || ''
         out.renderer = RENDERER
-        captures[vp] = out
+        if (item) (itemCaptures[item] ||= {})[vp] = out
+        else captures[vp] = out
       }
-      revisions.push({ id: rev.id, node: rev.node, locale: rev.locale, state: rev.state, entry: rev.entry, files: rev.files, tokens: rev.tokens, based_on: base[key] || remoteHeads[key] || null, captures })
+      revisions.push({ id: rev.id, node: rev.node, locale: rev.locale, state: rev.state, entry: rev.entry, ...(rev.items ? { items: rev.items, item_captures: itemCaptures } : {}), files: rev.files, tokens: rev.tokens, based_on: base[key] || remoteHeads[key] || null, captures })
     }
     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 }))

package/src/lib/design-core.mjs

@@ -87,13 +87,35 @@ export const REVISION_ID = /^[0-9a-f]{32}$/
  * Identity of a revision: same content, same id, on every machine. `files` maps bundle paths to
  * blob hashes; `tokens` is the token set reference ({ project, version, hash }) or null.
  */
-export async function revisionId ({ scenario, node, locale, state = 'default', kind = 'design', entry, files, tokens = null }) {
-  const canonical = JSON.stringify({ v: 1, scenario, node, locale, state, kind, entry, files: Object.keys(files).sort().map((k) => [k, files[k]]), tokens: tokens ? tokens.hash || null : null })
+export async function revisionId ({ scenario, node, locale, state = 'default', kind = 'design', entry, files, tokens = null, items = null }) {
+  // a stack step's revision covers its whole folder and names its items (variants) with their pages: [{ id, entry }];
+  // steps without items keep the identity they always had
+  const canonical = JSON.stringify({ v: 1, scenario, node, locale, state, kind, entry, files: Object.keys(files).sort().map((k) => [k, files[k]]), tokens: tokens ? tokens.hash || null : null, ...(Array.isArray(items) ? { items: items.map((i) => [i.id, i.entry]) } : {}) })
   return (await sha256Hex(canonical)).slice(0, 32)
 }
 
-/** Key of a rendered capture: a revision rendered in one viewport and token mode by one renderer. */
-export const captureKey = (revision, viewport, mode = '') => `${revision}|${viewport}|${mode}|${RENDERER}`
+/** Key of a rendered capture: a revision (or one item of a stack revision) rendered in one viewport and token mode by one renderer. */
+export const captureKey = (revision, viewport, mode = '', item = '') => `${revision}${item ? `+${item}` : ''}|${viewport}|${mode}|${RENDERER}`
+
+/** Item ids of a stack step: folder names (a path segment of the bundle), at most this many per step. */
+export const ITEM_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/
+export const MAX_ITEMS = 200
+
+/** Problems with the items of a stack revision ([{ id, entry }]) against its file list (empty when valid). */
+export function itemProblems (items, files, node) {
+  if (!Array.isArray(items) || !items.length) return ['a stack revision needs at least one item']
+  const problems = []
+  if (items.length > MAX_ITEMS) problems.push(`more than ${MAX_ITEMS} items`)
+  const seen = new Set()
+  for (const it of items) {
+    if (!it || !ITEM_ID.test(it.id || '')) { problems.push(`item ${String(it?.id).slice(0, 40)}: invalid id`); continue }
+    if (seen.has(it.id)) problems.push(`item ${it.id}: listed twice`)
+    seen.add(it.id)
+    if (typeof it.entry !== 'string' || !it.entry.startsWith(`${node}/${it.id}/`) || extOf(it.entry) !== 'html') problems.push(`item ${it.id}: entry must be an .html page in ${node}/${it.id}/`)
+    else if (!(it.entry in files)) problems.push(`item ${it.id}: entry ${it.entry} is not among the files`)
+  }
+  return problems
+}
 
 // ---- reference scanner: which bundle files an entry needs ----
 

package/src/lib/design-export.mjs

@@ -19,10 +19,12 @@ const titleOf = (t, locale) => (t && typeof t === 'object' ? t[locale] ?? t.defa
 const flowOrder = (nodes) => nodes.filter((n) => n.kind !== 'decision').slice().sort((a, b) => (a.col ?? 0) - (b.col ?? 0) || (a.lane ?? 0) - (b.lane ?? 0))
 
 /** A qawalk.scenario.v1 document from a run manifest: a design version carries the whole flow (steps, criteria, edges). */
-export function scenarioFromManifest (m) {
+export function scenarioFromManifest (m, { variants = {} } = {}) {
   const lanes = m.lanes || []
   const nodes = m.nodes.map((n) => {
     const own = (n.criteria || []).filter((c) => !c.pack)
+    // a stack step lists its variant folders (#61), so the exported scenario validates and walks the exported folder
+    const items = n.kind === 'stack' ? { items: { urls: variants[n.id]?.length ? variants[n.id] : (n.stack?.sample || []).map((x) => x.id) } } : {}
     const packs = [...new Set((n.criteria || []).filter((c) => c.pack).map((c) => c.pack))]
     return {
       id: n.id, kind: n.kind, title: n.title,
@@ -30,7 +32,7 @@ export function scenarioFromManifest (m) {
       ...(lanes.length && Number.isInteger(n.lane) ? { lane: n.lane } : {}), ...(n.session ? { session: n.session } : {}),
       // run manifests do not carry how a step is reached; the scenario needs it, so the export names the manual way
       ...(['decision', 'stack'].includes(n.kind) ? {} : { execution: n.execution?.strategy && n.execution?.instructions ? { strategy: n.execution.strategy, instructions: n.execution.instructions } : { strategy: 'manual', instructions: `Open ${typeof n.path === 'string' ? n.path : `the ${n.id} step`}.` } }),
-      ...(own.length ? { criteria: own.map((c) => ({ id: c.id, text: c.text, check: c.check })) } : {}), ...(packs.length ? { packs } : {})
+      ...items, ...(own.length ? { criteria: own.map((c) => ({ id: c.id, text: c.text, check: c.check })) } : {}), ...(packs.length ? { packs } : {})
     }
   })
   return {
@@ -44,7 +46,10 @@ export function scenarioFromManifest (m) {
 /** Start page of an exported design: the steps in flow order with each locale's page and screenshot; plain HTML, no script. */
 export function exportIndexHtml ({ index }) {
   const loc0 = index.locales[0]
-  const rows = index.steps.map((s) => `<li><h2>${esc(titleOf(s.title, loc0))} <small>${esc(s.id)}</small></h2>${s.purpose ? `<p>${esc(s.purpose)}</p>` : ''}<p>${index.locales.filter((l) => s.pages[l]).map((l) => `<a href="${esc(s.pages[l].split('/').map(enc).join('/'))}">${esc(l)}: ${esc(titleOf(s.title, l))}</a>`).join(' · ') || '<em>no page</em>'}</p>${s.screenshots.length ? `<p class="shots">${s.screenshots.map((x) => `<a href="${esc(x.file)}"><img src="${esc(x.file)}" alt="${esc(`${s.id} ${x.locale} ${x.viewport}`)}" loading="lazy" width="160"></a>`).join('')}</p>` : ''}</li>`).join('\n')
+  const href = (p) => esc(p.split('/').map(enc).join('/'))
+  // a stack step lists its variants: each one's page per locale (#61)
+  const variants = (s) => s.variants?.length ? `<ul>${s.variants.map((v) => `<li>${esc(v.id)}: ${index.locales.filter((l) => v.pages[l]).map((l) => `<a href="${href(v.pages[l])}">${esc(l)}</a>`).join(' · ')}</li>`).join('')}</ul>` : ''
+  const rows = index.steps.map((s) => `<li><h2>${esc(titleOf(s.title, loc0))} <small>${esc(s.id)}</small></h2>${s.purpose ? `<p>${esc(s.purpose)}</p>` : ''}<p>${index.locales.filter((l) => s.pages[l]).map((l) => `<a href="${href(s.pages[l])}">${esc(l)}: ${esc(titleOf(s.title, l))}</a>`).join(' · ') || '<em>no page</em>'}</p>${variants(s)}${s.screenshots.length ? `<p class="shots">${s.screenshots.map((x) => `<a href="${esc(x.file)}"><img src="${esc(x.file)}" alt="${esc(`${s.id} ${x.locale} ${x.viewport}`)}" loading="lazy" width="160"></a>`).join('')}</p>` : ''}</li>`).join('\n')
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(index.scenario.title)} · ${esc(index.ref)}</title>
 <style>:root{color-scheme:light dark;--ink:#151514;--paper:#fff;--line:#ddd}@media (prefers-color-scheme:dark){:root{--ink:#eee;--paper:#151514;--line:#333}}body{margin:0;font:16px/1.5 system-ui,sans-serif;color:var(--ink);background:var(--paper)}main{max-width:960px;margin:0 auto;padding:32px 16px}ol{padding-left:20px}li{border-top:1px solid var(--line);padding:12px 0}h2{font-size:18px;margin:0}small{font-weight:400;opacity:.6}.shots img{border:1px solid var(--line);border-radius:4px;margin:0 8px 8px 0;height:auto}code{font-size:14px}</style></head>
@@ -117,8 +122,11 @@ export async function exportDesign ({ config, scenarioId, client, ref = 'design'
   // the live files keep the design folder layout: links between steps work from disk exactly as in the folder
   const paths = new Map(), clashes = []
   const pages = {}
+  const variantPages = {}
   for (const s of revs.steps.filter((x) => x.state === 'default')) {
     ;(pages[s.node] ||= {})[s.locale] = s.entry
+    // the variants of a stack step (#61) are folders of the step: <step>/<variant>/index.html
+    for (const it of s.items || []) { safeExportPath(it.entry); ((variantPages[s.node] ||= {})[it.id] ||= {})[s.locale] = it.entry }
     for (const [p, hash] of Object.entries(s.files)) {
       safeExportPath(p) // checked before anything is written
       if (paths.has(p)) { if (paths.get(p).hash !== hash) clashes.push(p); continue }
@@ -143,16 +151,28 @@ export async function exportDesign ({ config, scenarioId, client, ref = 'design'
       screenshots.push({ locale, viewport, file, size: c.size || null })
       shots++
     }
-    steps.push({ id: n.id, title: n.title, purpose: n.purpose || '', kind: n.kind, pages: pages[n.id] || {}, screenshots })
+    // a stack step's screenshots are its variants': screenshots/<step>/<variant>/<locale>/<viewport>.webp
+    if (n.stack?.items) {
+      const idx = JSON.parse((await fileOf(n.stack.items)).toString('utf8'))
+      for (const it of idx.items || []) for (const [locale, vps] of Object.entries(it.captures || {})) for (const [viewport, c] of Object.entries(vps || {})) {
+        if (!c?.png) continue
+        const file = `screenshots/${n.id}/${safeExportPath(it.id)}/${locale}/${viewport}.${c.png.split('.').pop()}`
+        await sink.put(file, await fileOf(c.png))
+        screenshots.push({ item: it.id, locale, viewport, file, size: c.size || null })
+        shots++
+      }
+    }
+    const variants = Object.entries(variantPages[n.id] || {}).map(([id, byLocale]) => ({ id, pages: byLocale }))
+    steps.push({ id: n.id, title: n.title, purpose: n.purpose || '', kind: n.kind, pages: pages[n.id] || {}, ...(variants.length ? { variants } : {}), screenshots })
   }
   const index = {
     schema: DESIGN_EXPORT_SCHEMA, scenario: { id: scenarioId, title: manifest.scenario?.title || scenarioId }, ref, run_id: runId,
     version: manifest.version ?? null, version_name: manifest.version_name ?? null, branch, exported_at: new Date().toISOString(),
     locales: manifest.scope.locales, viewports: manifest.scope.viewports, tokens: paths.has(TOKENS_FILE) ? TOKENS_FILE : null,
-    formats: { pages: 'HTML, CSS, JS and assets in the design folder layout (<step>/index.html, <step>/<locale>/index.html, _shared/)', tokens: 'W3C Design Tokens (DTCG) JSON', scenario: 'qawalk.scenario.v1 YAML', screenshots: 'WebP or PNG per step, locale and viewport' },
+    formats: { pages: 'HTML, CSS, JS and assets in the design folder layout (<step>/index.html, <step>/<locale>/index.html, <stack step>/<variant>/index.html, _shared/)', tokens: 'W3C Design Tokens (DTCG) JSON', scenario: 'qawalk.scenario.v1 YAML', screenshots: 'WebP or PNG per step, locale and viewport' },
     steps
   }
-  await sink.put('scenario.yml', `# Exported from Kaloko (${ref}); validate with: kaloko validate scenario.yml\n` + yaml.dump(scenarioFromManifest(manifest), { lineWidth: 140, noRefs: true }))
+  await sink.put('scenario.yml', `# Exported from Kaloko (${ref}); validate with: kaloko validate scenario.yml\n` + yaml.dump(scenarioFromManifest(manifest, { variants: Object.fromEntries(Object.entries(variantPages).map(([k, v]) => [k, Object.keys(v)])) }), { lineWidth: 140, noRefs: true }))
   await sink.put('kaloko.json', JSON.stringify(index, null, 2) + '\n')
   await sink.put('index.html', exportIndexHtml({ index }))
   await sink.close()