kaloko 0.8.0 → 0.10.0

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>
@@ -89,7 +94,7 @@ async function runIdOf ({ client, org, scenarioId, ref, branch }) {
   }
   if (/^v\d+$/.test(ref)) {
     const v = (await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/versions`)).find((x) => String(x.version) === ref.slice(1))
-    if (!v) throw new UserError(`${scenarioId} has no version ${ref}.`)
+    if (!v) throw new UserError(`${scenarioId} has no version ${ref}. kaloko history lists its versions.`)
     return v.id
   }
   return ref
@@ -111,14 +116,17 @@ export async function exportDesign ({ config, scenarioId, client, ref = 'design'
   const sink = exportSink(out)
   const fileOf = async (path) => {
     const res = draft ? await fetch(manifest.files_base + path) : await client.fetch(`/orgs/${org}/runs/${runId}/files/${path.split('/').map(enc).join('/')}`)
-    if (!res.ok) throw new UserError(`${path}: HTTP ${res.status}`)
+    if (!res.ok) throw new UserError(`Downloading ${path} failed (HTTP ${res.status}). Run the export again; if it keeps failing, the file may have expired with its run.`)
     return Buffer.from(await res.arrayBuffer())
   }
   // 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()

package/src/lib/design-lint.mjs

@@ -5,6 +5,8 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
 import { BUNDLE_LIMITS, SHARED_DIR, TOKENS_FILE, TEXT_TYPES, contentTypeOf, extOf, resolveRef } from './design-core.mjs'
+import { listedItems } from './design.mjs'
+import { originAllowed } from './design-origins.mjs'
 
 /** Rule id → level and a short reason (the fix is in each finding). */
 export const LINT_RULES = {
@@ -19,7 +21,9 @@ export const LINT_RULES = {
   'websocket': ['error', 'network connections are blocked (connect-src self)'],
   'too-large': ['error', 'over the bundle limits'],
   'tokens-json': ['error', 'tokens.json is not valid JSON'],
+  'variant-page': ['error', 'a variant folder of a stack step without its index.html'],
   'storage': ['warn', 'storage and cookies throw in the sandboxed frame and are not shared between viewers'],
+  'origin-not-allowed': ['warn', 'a font or asset origin the organization has not allowed yet; it does not load on the live step'],
   'nondeterministic': ['warn', 'random values and the current time change every capture'],
   'directory-link': ['warn', 'a link to a folder does not open its index.html from disk or a zip'],
   'broken-link': ['warn', 'a link to a page that is not in the folder'],
@@ -39,7 +43,8 @@ export const LINT_RULES = {
   'missing-step': ['warn', 'a scenario step without a design'],
   'external-link': ['info', 'a link that leaves the prototype'],
   'stray-folder': ['info', 'a folder that is not a step of the scenario'],
-  'no-tokens': ['info', 'no token set: the inspector cannot name values']
+  'no-tokens': ['info', 'no token set: the inspector cannot name values'],
+  'origins-unchecked': ['info', 'the organization\'s list of font and asset origins could not be read']
 }
 export const BUDGET = { file_bytes: 1024 * 1024, step_bytes: 5 * 1024 * 1024 }
 
@@ -50,21 +55,37 @@ const kb = (b) => `${Math.round(b / 1024)} kB`
 
 /**
  * Lints the files of a design folder. `files`: Map path → { bytes, text? } (text for text types), `steps`: step ids of
- * the scenario (null = every top-level folder but _shared). Returns findings { rule, level, file, line, message, fix }.
+ * the scenario (null = every top-level folder but _shared), `stacks`: stack step id → the variant folders its
+ * `items.urls` lists (null: discovered from subfolders), `locales` of the scenario. `origins`: { wanted, allowed,
+ * unchecked } font and asset origins (#46): `wanted` the design environment declares (`origins` in
+ * kaloko.config.yml), `allowed` the organization's list on the service (null when unknown; `unchecked` says it could
+ * not be read). A stylesheet, font or image from a wanted or allowed origin is no error; one the organization has not
+ * allowed yet is a warning. Scripts, fetches and media never load from other sites. Returns findings
+ * { rule, level, file, line, message, fix }.
  */
-export function lintFiles (files, { steps = null } = {}) {
+export function lintFiles (files, { steps = null, stacks = {}, locales = [], origins = null } = {}) {
+  const wanted = origins?.wanted || [], allowed = Array.isArray(origins?.allowed) ? origins.allowed : null
   const out = []
   const add = (rule, file, line, message, fix = '') => out.push({ rule, level: LINT_RULES[rule][0], file, line: line || null, message, fix })
   const has = (p) => files.has(p)
   const isDir = (p) => [...files.keys()].some((f) => f.startsWith(p.replace(/\/?$/, '/')))
   let anyMotion = null, reducedMotion = false, usesVars = false
-  const resource = (file, text, i, raw, { script = false, data = false } = {}) => {
+  const resource = (file, text, i, raw, { script = false, data = false, media = false } = {}) => {
     const u = raw.trim()
     if (!u || u.startsWith('#') || /^(about:blank|blob:)/i.test(u)) return
     const line = lineAt(text, i)
     if (/^data:/i.test(u)) { if (script) add('external-url', file, line, 'a script from a data: URL is blocked (script-src self)', 'Put the script into a .js file of the bundle.'); return }
     if (/^javascript:/i.test(u)) return
-    if (/^(https?:)?\/\//i.test(u) || SCHEME.test(u)) return add('external-url', file, line, `loads ${u.slice(0, 120)} from another site; it will not load on the live step (CSP default-src 'self')`, data ? 'Live steps have no network: put the data into a JSON fixture of the bundle and fetch(\'./fixtures/….json\').' : 'Download the file into _shared/ (fonts as woff2) and reference it with a relative path.')
+    if (/^(https?:)?\/\//i.test(u) || SCHEME.test(u)) {
+      // fonts, stylesheets and images may come from an origin the organization allows (style-src, font-src, img-src)
+      const asset = /^(https:)?\/\//i.test(u) && !script && !data && !media
+      if (asset && (originAllowed(wanted, u) || (allowed && originAllowed(allowed, u)))) {
+        if (allowed && !originAllowed(allowed, u)) add('origin-not-allowed', file, line, `${new URL(u.startsWith('//') ? `https:${u}` : u).origin} is in origins of the design environment, but the organization does not allow it yet; it will not load on the live step`, 'Ask an organization admin to add it in Settings → Security → Fonts and assets of designs, or download the file into _shared/.')
+        return
+      }
+      const why = script ? 'scripts load only from the bundle, also from origins the organization allows' : data ? 'live steps have no network (connect-src self)' : media ? 'video and audio load only from the bundle' : 'it will not load on the live step unless the organization allows that origin'
+      return add('external-url', file, line, `loads ${u.slice(0, 120)} from another site; ${why}`, data ? 'Live steps have no network: put the data into a JSON fixture of the bundle and fetch(\'./fixtures/….json\').' : asset ? 'Download the file into _shared/ (fonts as woff2) and reference it with a relative path, or add its origin to origins of the design environment and ask an organization admin to allow it (Settings → Security).' : 'Download the file into _shared/ and reference it with a relative path.')
+    }
     if (u.startsWith('/')) return add('root-relative', file, line, `${u.slice(0, 120)} starts with /, which is the origin root on the live step and the disk root from file://`, `Use a path relative to ${file} (for example ../${SHARED_DIR}/…).`)
     const p = resolveRef(file, stripQ(u))
     if (!p) return add('outside-folder', file, line, `${u.slice(0, 120)} points outside the design folder`, 'Keep every file the page needs inside the design folder.')
@@ -99,7 +120,7 @@ export function lintFiles (files, { steps = null } = {}) {
     at(/\bnew\s+(?:XMLHttpRequest|EventSource|WebSocket)\b/g, (m, l) => add('websocket', file, l, `${m[0].replace(/^new\s+/, '')} needs a network the live step does not have (connect-src self)`, 'Read fixtures from JSON files in the bundle with fetch(\'./fixtures/…json\').'))
     at(/(?:^|[^.\w$])(?:eval\s*\(|new\s+Function\s*\(|set(?:Timeout|Interval)\s*\(\s*['"`])/g, (m, l) => add('eval', file, l, 'code from a string is blocked on the live step (no \'unsafe-eval\')', 'Pass a function instead of a string; do not use eval or new Function.'))
     at(/navigator\.serviceWorker/g, (m, l) => add('service-worker', file, l, 'service workers are refused on live steps and outlive the page', 'Remove the registration; prototypes need no offline cache.'))
-    at(/\b(localStorage|sessionStorage|indexedDB|document\.cookie)\b/g, (m, l) => add('storage', file, l, `${m[1]} throws in the sandboxed live step (opaque origin) and is empty for every other viewer`, 'Keep prototype state in the URL (location.hash or ?query) or in memory; wrap any storage access in try/catch.'))
+    at(/\b(localStorage|sessionStorage|indexedDB|document\.cookie)\b/g, (m, l) => add('storage', file, l, `${m[1]} throws in the sandboxed live step (opaque origin) and is empty for every other viewer`, 'Keep state between steps in window.kaloko.state (the prototype state of the canvas) or in the URL (?query, #hash); wrap any storage access in try/catch.'))
     at(/\b(Date\.now\(\)|new Date\(\s*\)|Math\.random\(\)|crypto\.(?:randomUUID|getRandomValues)\()/g, (m, l) => add('nondeterministic', file, l, `${m[1].replace(/\($/, '()')} makes every capture different, so unchanged steps look changed`, 'Use fixed dates (new Date(\'2026-01-15T10:00\')) and a seeded generator for fake data.'))
     at(/(?:^|[^.\w$]|window\.)(alert|confirm|prompt)\s*\(/g, (m, l) => add('modal', file, l, `${m[1]}() is blocked in the sandbox (no allow-modals)`, 'Show an in-page <dialog> instead.'))
     at(/(?:^|[^.\w$])window\.open\s*\(/g, (m, l) => add('new-window', file, l, 'window.open is blocked in the sandbox (no allow-popups)', 'Navigate in the same frame (location.href = \'../next/index.html\').'))
@@ -113,8 +134,8 @@ export function lintFiles (files, { steps = null } = {}) {
     if (ext === 'css') css(file, t)
     else if (ext === 'js' || ext === 'mjs') js(file, t)
     else if (ext === 'html' || ext === 'svg') {
-      for (const m of t.matchAll(/\s(src|poster|data-src)\s*=\s*(['"])([^'"]*)\2/gi)) resource(file, t, m.index, m[3], { script: /<script\b[^>]*$/i.test(t.slice(Math.max(0, m.index - 200), m.index)) })
-      for (const m of t.matchAll(/<link\b([^>]*)>/gi)) { const h = m[1].match(/\shref\s*=\s*(['"])([^'"]*)\1/i); const rel = (m[1].match(/\srel\s*=\s*(['"]?)([^'"\s>]+)\1/i)?.[2] || '').toLowerCase(); if (h && !/^(canonical|alternate|author|help|license|next|prev|search|dns-prefetch|preconnect)$/.test(rel)) resource(file, t, m.index, h[2]) }
+      for (const m of t.matchAll(/\s(src|poster|data-src)\s*=\s*(['"])([^'"]*)\2/gi)) { const before = t.slice(Math.max(0, m.index - 200), m.index); resource(file, t, m.index, m[3], { script: /<script\b[^>]*$/i.test(before), media: m[1].toLowerCase() === 'src' && /<(video|audio|source|track)\b[^>]*$/i.test(before) }) }
+      for (const m of t.matchAll(/<link\b([^>]*)>/gi)) { const h = m[1].match(/\shref\s*=\s*(['"])([^'"]*)\1/i); const rel = (m[1].match(/\srel\s*=\s*(['"]?)([^'"\s>]+)\1/i)?.[2] || '').toLowerCase(); if (h && !/^(canonical|alternate|author|help|license|next|prev|search|dns-prefetch|preconnect)$/.test(rel)) resource(file, t, m.index, h[2], { script: rel === 'modulepreload' || /\sas\s*=\s*["']?script/i.test(m[1]) }) }
       for (const m of t.matchAll(/<(?:use|image|feImage)\b[^>]*\s(?:xlink:)?href\s*=\s*(['"])([^'"]*)\1/gi)) resource(file, t, m.index, m[2])
       for (const m of t.matchAll(/\ssrcset\s*=\s*(['"])([^'"]*)\1/gi)) for (const part of m[2].split(',')) resource(file, t, m.index, part.trim().split(/\s+/)[0])
       for (const m of t.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) css(file, m[1], m.index + m[0].indexOf(m[1]), t)
@@ -137,6 +158,7 @@ export function lintFiles (files, { steps = null } = {}) {
     try { JSON.parse(files.get(TOKENS_FILE).text) } catch (e) { add('tokens-json', TOKENS_FILE, null, e.message, 'Fix the JSON (kaloko tokens validate).') }
     if (!usesVars) add('tokens-unused', TOKENS_FILE, null, 'no var(--…) in any stylesheet', 'Write token values as CSS custom properties (--color-accent) and use var(--color-accent), so the inspector and kaloko tokens check see them.')
   } else add('no-tokens', '.', null, 'no tokens.json in the folder', 'Add a W3C DTCG token set (kaloko tokens pull, or write tokens.json).')
+  if (wanted.length && !allowed && origins?.unchecked) add('origins-unchecked', '.', null, `origins of the design environment (${wanted.join(', ')}) were not compared with the organization's list`, 'Sign in (kaloko login) so kaloko design lint can read which origins the organization allows.')
   // per step: everything under its folder plus the shared files (an upper bound of what a revision carries)
   const tops = [...new Set([...files.keys()].filter((p) => p.includes('/')).map((p) => p.split('/')[0]))].filter((d) => d !== SHARED_DIR)
   const shared = [...files].filter(([p]) => p.startsWith(`${SHARED_DIR}/`)).reduce((s, [, f]) => s + f.bytes, 0)
@@ -146,6 +168,17 @@ export function lintFiles (files, { steps = null } = {}) {
     else if (own + shared > BUDGET.step_bytes) add('large-file', `${d}/`, null, `${kb(own + shared)} with the shared files: over the ${kb(BUDGET.step_bytes)} budget of a step`, 'Compress images and fonts; drop unused files from _shared/.')
     if (steps && !steps.includes(d)) add('stray-folder', `${d}/`, null, `${d}/ is not a step of the scenario`, 'Rename it to a step id, or move shared files into _shared/.')
   }
+  // stack steps (#61): every variant is a folder with its own page, <step>/<variant>/index.html
+  for (const [step, listed] of Object.entries(stacks || {})) {
+    const under = [...files.keys()].filter((p) => p.startsWith(`${step}/`) && p.split('/').length > 2)
+    const subs = [...new Set(under.map((p) => p.split('/')[1]))].filter((n) => !locales.includes(n) && n !== 'dark' && !n.startsWith('_'))
+    for (const id of listed || subs) {
+      if (has(`${step}/${id}/index.html`) || locales.some((l) => has(`${step}/${id}/${l}/index.html`))) continue
+      // a discovered folder without any page holds assets, not a variant
+      if (!listed && !under.some((p) => p.startsWith(`${step}/${id}/`) && extOf(p) === 'html')) continue
+      add('variant-page', `${step}/${id}/`, null, `variant ${id} of the stack step ${step} has no ${step}/${id}/index.html`, `Add ${step}/${id}/index.html${listed ? `, or drop ${id} from items.urls` : ''}.`)
+    }
+  }
   if (steps) for (const s of steps) if (!has(`${s}/index.html`) && ![...files.keys()].some((p) => p.startsWith(`${s}/`) && p.endsWith('/index.html'))) add('missing-step', `${s}/`, null, `step ${s} has no ${s}/index.html`, `Add ${s}/index.html.`)
   const order = { error: 0, warn: 1, info: 2 }
   return out.sort((a, b) => order[a.level] - order[b.level] || a.file.localeCompare(b.file) || (a.line || 0) - (b.line || 0))
@@ -170,11 +203,12 @@ export async function readDesignFolder (dir) {
   return files
 }
 
-/** Lints a design folder; `scenario` (optional) names the steps. */
-export async function lintDesign ({ dir, scenario = null }) {
+/** Lints a design folder; `scenario` (optional) names the steps, `origins` ({ wanted, allowed, unchecked }) see lintFiles. */
+export async function lintDesign ({ dir, scenario = null, origins = null }) {
   const files = await readDesignFolder(dir)
   const steps = scenario ? scenario.nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'external').map((n) => n.id) : null
-  const findings = lintFiles(files, { steps })
+  const stacks = scenario ? Object.fromEntries(scenario.nodes.filter((n) => n.kind === 'stack').map((n) => [n.id, listedItems(n)])) : {}
+  const findings = lintFiles(files, { steps, stacks, locales: scenario?.locales || [], origins })
   return { dir, files: files.size, findings, errors: findings.filter((f) => f.level === 'error').length, warnings: findings.filter((f) => f.level === 'warn').length }
 }