kaloko 0.9.0 → 0.10.0

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 }
 }
 

package/src/lib/design-origins.mjs

@@ -0,0 +1,86 @@
+// Font and asset origins on live design steps (#46, item 3). An organization admin lists the origins its designs
+// load fonts, stylesheets and images from (Google Fonts, Adobe Fonts, a company CDN); the live origin's CSP adds them
+// to style-src, font-src and img-src, never to script-src, connect-src or anything else. Shared by the service
+// (worker/src/live.js, worker/src/design-origins.js) and the CLI (`kaloko design lint`), so both read an entry alike.
+//
+//   cleanAssetOrigin(s, { reserved })   → 'https://fonts.gstatic.com' or 'https://*.cdn.example.com'; throws on anything else
+//   cleanAssetOrigins(list, opts)       → the cleaned, de-duplicated list (at most MAX_ASSET_ORIGINS); throws on a bad entry
+//   originAllowed(list, url)            → is the URL's origin covered by an entry (wildcards cover subdomains, not the apex)
+//   designCsp(appOrigin, origins)       → the Content-Security-Policy of a live design step
+
+export const MAX_ASSET_ORIGINS = 20
+/** Hosts of Kaloko itself: never a font or asset origin of a design (the app, the files host, the live origin). */
+export const RESERVED_HOSTS = ['kaloko.app', 'kaloko-usercontent.com']
+
+const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?'
+const DOMAIN = new RegExp(`^(?=.{3,253}$)(?:${LABEL}\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9]|xn--[a-z0-9-]{1,59})$`)
+const under = (host, base) => host === base || host.endsWith(`.${base}`)
+
+/** One origin as typed (" HTTPS://Fonts.GoogleAPIs.com/ ") in its stored form; throws an Error that names the entry. */
+export function cleanAssetOrigin (input, { reserved = [] } = {}) {
+  const raw = String(input ?? '').trim()
+  const shown = raw.slice(0, 80)
+  const s = raw.toLowerCase().replace(/\/$/, '')
+  const m = s.match(/^https:\/\/(\*\.)?([^/:?#@\s*]+)(?::(\d{1,5}))?$/)
+  if (!m) {
+    if (/^http:\/\//.test(s)) throw new Error(`Only https origins can be added: ${shown}`)
+    if (s.includes('*')) throw new Error(`A wildcard is allowed only as the first label (https://*.example.com): ${shown}`)
+    throw new Error(`Not an origin (https://host, without a path): ${shown}`)
+  }
+  const [, wild, host, port] = m
+  if (!DOMAIN.test(host)) throw new Error(`Not an origin (https://host, without a path): ${shown}`)
+  // a wildcard needs a registrable base at least: *.example.com, never *.com
+  if (wild && host.split('.').length < 2) throw new Error(`A wildcard needs a domain under it (https://*.example.com): ${shown}`)
+  if (port !== undefined && (Number(port) < 1 || Number(port) > 65535)) throw new Error(`Not an origin (https://host, without a path): ${shown}`)
+  for (const r of [...RESERVED_HOSTS, ...reserved].map((x) => String(x || '').toLowerCase().replace(/:\d+$/, '')).filter(Boolean)) {
+    if (under(host, r) || (wild && under(r, host))) throw new Error(`Kaloko's own hosts cannot be added: ${shown}`)
+  }
+  return `https://${wild || ''}${host}${port && port !== '443' ? `:${port}` : ''}`
+}
+
+/** A list (array, or text with one origin per line, commas or spaces) cleaned; throws on the first bad entry. */
+export function cleanAssetOrigins (list, opts = {}) {
+  const items = (Array.isArray(list) ? list : String(list ?? '').split(/[\s,;]+/)).filter((x) => String(x ?? '').trim())
+  const out = []
+  for (const x of items) { const c = cleanAssetOrigin(x, opts); if (!out.includes(c)) out.push(c) }
+  if (out.length > MAX_ASSET_ORIGINS) throw new Error(`At most ${MAX_ASSET_ORIGINS} font and asset origins.`)
+  return out
+}
+
+/** Does an entry of `list` cover the origin of `url` (a URL or an origin)? Wildcards cover subdomains at any depth. */
+export function originAllowed (list, url) {
+  let u
+  try { u = new URL(String(url).startsWith('//') ? `https:${url}` : String(url)) } catch { return false }
+  if (u.protocol !== 'https:') return false
+  return (list || []).some((entry) => {
+    const m = String(entry).match(/^https:\/\/(\*\.)?([^/:]+)(?::(\d+))?$/)
+    if (!m || (m[3] || '') !== u.port) return false
+    return m[1] ? u.hostname.endsWith(`.${m[2]}`) : u.hostname === m[2]
+  })
+}
+
+/**
+ * The CSP of a live design step. `origins` must already be cleaned (cleanAssetOrigins) and checked against the hosts
+ * of the instance: they are added to style-src, font-src and img-src only. Scripts, connections, frames, workers and
+ * forms stay on the step's own origin whatever the list says.
+ */
+export function designCsp (appOrigin, origins = []) {
+  const extra = origins.length ? ` ${origins.join(' ')}` : ''
+  return [
+    "default-src 'self'",
+    "script-src 'self' 'unsafe-inline'",
+    `style-src 'self' 'unsafe-inline'${extra}`,
+    `img-src 'self' data: blob:${extra}`,
+    `font-src 'self' data:${extra}`,
+    "media-src 'self' blob:",
+    "connect-src 'self'",
+    "frame-src 'none'",
+    "worker-src 'none'",
+    "object-src 'none'",
+    "base-uri 'self'",
+    "form-action 'none'",
+    `frame-ancestors ${appOrigin}`,
+    // opaque origin even when opened directly: no cookies, storage or service workers
+    'sandbox allow-scripts allow-forms'
+  ].join('; ')
+}

package/src/lib/design.mjs

@@ -4,7 +4,7 @@ import { createServer } from 'node:http'
 import { readFile, readdir, stat, mkdir, writeFile, copyFile, rm } from 'node:fs/promises'
 import { join, resolve, dirname, relative, sep } from 'node:path'
 import { UserError } from './util.mjs'
-import { bundleProblems, closure, contentTypeOf, revisionId, sha256Hex, TOKENS_FILE, SHARED_DIR, extOf } from './design-core.mjs'
+import { bundleProblems, closure, contentTypeOf, revisionId, sha256Hex, TOKENS_FILE, SHARED_DIR, extOf, ITEM_ID, MAX_ITEMS, itemProblems } from './design-core.mjs'
 
 export const isDesign = (env) => env?.kind === 'design'
 
@@ -31,12 +31,25 @@ async function listFiles (dir, base = dir) {
   return out
 }
 
+/**
+ * The page of a step state (#46): `<step>/<locale>/<state>.html` or `<step>/<state>.html` next to the entry, or null
+ * (the entry then renders with `?state=<name>`). `files` are the revision's paths (or a list of them).
+ */
+export function statePage (entry, state, files) {
+  if (!state || state === 'default') return entry
+  const has = (p) => (Array.isArray(files) ? files.includes(p) : !!files?.[p])
+  const dir = entry.slice(0, entry.lastIndexOf('/') + 1)
+  const node = entry.split('/')[0]
+  for (const p of [`${dir}${state}.html`, `${node}/${state}.html`]) if (has(p)) return p
+  return null
+}
+
 /**
  * The files of one step in one locale: `<step>/<locale>/…` overrides `<step>/…` (other locales' folders
  * are left out), plus every bundle file those reference. Returns { entry, files: [{ path, bytes, hash }] }
- * or null when the step has no folder.
+ * or null when the step has no folder. `states` (#46): the pages of the step's states travel with it.
  */
-export async function scanStep ({ dir, node, locale, locales }) {
+export async function scanStep ({ dir, node, locale, locales, states = [] }) {
   const stepDir = join(dir, node)
   if (!await exists(stepDir)) return null
   const own = await listFiles(stepDir)
@@ -51,7 +64,9 @@ export async function scanStep ({ dir, node, locale, locales }) {
   const beside = (entryDir === `${node}/` ? common : mine.map((p) => p.slice(locale.length + 1))).filter((p) => !p.includes('/') && extOf(p) !== 'html')
   // a page of its own for the dark colour scheme (<step>/dark/index.html, or per locale): part of the revision
   const dark = own.includes(`${entryDir.slice(node.length + 1)}dark/index.html`) ? [`${entryDir}dark/index.html`] : []
-  const roots = [entry, ...dark, ...beside.map((p) => entryDir + p)]
+  // pages of the step's states (<step>/<state>.html, or per locale): part of the revision like the dark page
+  const stateRoots = (states || []).filter((s) => s !== 'default').map((s) => statePage(entry, s, own.map((p) => `${node}/${p}`))).filter(Boolean)
+  const roots = [entry, ...dark, ...stateRoots, ...beside.map((p) => entryDir + p)]
   const paths = await closure({ roots, read: (p) => readFile(join(dir, p), 'utf8'), exists: (p) => isFile(join(dir, p)) })
   const files = []
   for (const path of paths) {
@@ -63,6 +78,94 @@ export async function scanStep ({ dir, node, locale, locales }) {
   return { entry, files }
 }
 
+/**
+ * Items of a stack step as `items.urls` names them, when they name folders of the step (`refund`, `./refund/`,
+ * `refund/index.html`): a list of folder names. Null when the step lists app URLs (`/credit?reason=x`), uses another
+ * source (sitemap, file, crawl, script) or lists nothing: then the item folders are discovered.
+ */
+export function listedItems (node) {
+  const urls = node?.items?.urls
+  if (!Array.isArray(urls) || !urls.length) return null
+  const ids = urls.map((u) => String(u).trim().replace(/^\.\//, '').replace(/\/index\.html$/, '').replace(/\/+$/, ''))
+  return ids.every((id) => ITEM_ID.test(id) && id !== '.' && id !== '..') ? [...new Set(ids)] : null
+}
+
+/** Folder names inside a step folder that are not items: locale overrides, the dark page and _private folders. */
+const notItem = (name, locales) => locales.includes(name) || name === 'dark' || name.startsWith('_') || name.startsWith('.')
+
+/**
+ * The item folders of a stack step (#61): `<step>/<item>/index.html` (or `<step>/<item>/<locale>/index.html`), in the
+ * order `items.urls` lists them, else every subfolder with a page, sorted by name. Returns [{ id, listed }]; a listed
+ * folder without a page is still returned, so the walk and the lint can name it.
+ */
+export async function stackItems ({ dir, node, locales }) {
+  const stepDir = join(dir, node.id)
+  const listed = listedItems(node)
+  if (listed) return listed.map((id) => ({ id, listed: true }))
+  let entries = []
+  try { entries = await readdir(stepDir, { withFileTypes: true }) } catch { return [] }
+  const out = []
+  for (const e of entries.filter((x) => x.isDirectory() && !notItem(x.name, locales) && ITEM_ID.test(x.name)).sort((a, b) => a.name.localeCompare(b.name))) {
+    const has = await isFile(join(stepDir, e.name, 'index.html')) || (await Promise.all(locales.map((l) => isFile(join(stepDir, e.name, l, 'index.html'))))).some(Boolean)
+    if (has) out.push({ id: e.name, listed: false })
+  }
+  return out
+}
+
+/** Entry of a folder (`<base>/<locale>/index.html` over `<base>/index.html`) and the roots of its revision. */
+async function folderRoots ({ dir, base, locale, locales, states = [] }) {
+  const own = await listFiles(join(dir, base))
+  const localeDirs = new Set(locales)
+  const common = own.filter((p) => !localeDirs.has(p.split('/')[0]))
+  const mine = own.filter((p) => p.split('/')[0] === locale)
+  const entry = mine.includes(`${locale}/index.html`) ? `${base}/${locale}/index.html` : common.includes('index.html') ? `${base}/index.html` : null
+  if (!entry) return null
+  const entryDir = entry.slice(0, entry.lastIndexOf('/') + 1)
+  const beside = (entryDir === `${base}/` ? common : mine.map((p) => p.slice(locale.length + 1))).filter((p) => !p.includes('/') && extOf(p) !== 'html')
+  const dark = own.includes(`${entryDir.slice(base.length + 1)}dark/index.html`) ? [`${entryDir}dark/index.html`] : []
+  // step states (#46) of a variant: <step>/<variant>/<state>.html (or per locale) next to its page
+  const ownPaths = own.map((p) => `${base}/${p}`)
+  const stateRoots = (states || []).filter((s) => s !== 'default').map((s) => [`${entryDir}${s}.html`, `${base}/${s}.html`].find((p) => ownPaths.includes(p))).filter(Boolean)
+  return { entry, roots: [entry, ...dark, ...stateRoots, ...beside.map((p) => entryDir + p)] }
+}
+
+/**
+ * The files of a stack step in one locale (#61): every item's page with what it references, and the optional overview
+ * (`<step>/index.html`). The revision covers the whole step folder; its entry is the overview, else the first item.
+ * Returns { entry, items: [{ id, entry }], files } or null when the step has no folder.
+ */
+export async function scanStack ({ dir, node, locale, locales }) {
+  if (!await exists(join(dir, node.id))) return null
+  const found = await stackItems({ dir, node, locales })
+  if (!found.length) throw new UserError(`Design step ${node.id} is a stack: add a folder per variant with a page, ${node.id}/<variant>/index.html.`)
+  if (found.length > MAX_ITEMS) throw new UserError(`Design step ${node.id} has ${found.length} variants; a stack step holds at most ${MAX_ITEMS}.`)
+  const items = []
+  const roots = []
+  for (const it of found) {
+    const r = await folderRoots({ dir, base: `${node.id}/${it.id}`, locale, locales, states: node.states })
+    if (!r) throw new UserError(`Design step ${node.id}: variant ${it.id} has no page; add ${node.id}/${it.id}/index.html.`)
+    items.push({ id: it.id, entry: r.entry })
+    roots.push(...r.roots)
+  }
+  // the overview: only the step folder's own page and the files beside it, never the item folders (they come above)
+  const own = await listFiles(join(dir, node.id))
+  const overviewEntry = own.includes(`${locale}/index.html`) ? `${node.id}/${locale}/index.html` : own.includes('index.html') ? `${node.id}/index.html` : null
+  if (overviewEntry) {
+    const at = overviewEntry.slice(0, overviewEntry.lastIndexOf('/') + 1)
+    roots.unshift(overviewEntry, ...own.map((p) => `${node.id}/${p}`).filter((p) => p.startsWith(at) && !p.slice(at.length).includes('/') && extOf(p) !== 'html'))
+  }
+  const paths = await closure({ roots, read: (p) => readFile(join(dir, p), 'utf8'), exists: (p) => isFile(join(dir, p)) })
+  const files = []
+  for (const path of paths) {
+    const buf = await readFile(join(dir, path))
+    files.push({ path, bytes: buf.length, hash: await sha256Hex(buf) })
+  }
+  const entry = overviewEntry || items[0].entry
+  const problems = [...bundleProblems(files, entry), ...itemProblems(items, Object.fromEntries(files.map((f) => [f.path, f.hash])), node.id)]
+  if (problems.length) throw new UserError(`Design step ${node.id} (${locale}) breaks the bundle rules:\n  - ${problems.join('\n  - ')}`)
+  return { entry, items, files }
+}
+
 /** Token set reference of the design folder (tokens.json), or null. */
 export async function tokensRef (dir, project) {
   const file = join(dir, TOKENS_FILE)
@@ -73,8 +176,9 @@ export async function tokensRef (dir, project) {
 }
 
 /** A revision of one step and locale, with its id. */
-export async function revisionOf ({ dir, scenario, node, locale, locales, tokens }) {
-  const scan = await scanStep({ dir, node, locale, locales })
+export async function revisionOf ({ dir, scenario, node, locale, locales, tokens, states = [], stack = null }) {
+  // `stack`: the scenario node of a stack step (#61); its revision covers every item folder; `states` (#46): their pages
+  const scan = stack ? await scanStack({ dir, node: stack, locale, locales }) : await scanStep({ dir, node, locale, locales, states })
   if (!scan) return null
   // the token set travels with every revision: the canvas inspector names values from it on the live origin
   if (tokens && !scan.files.some((f) => f.path === TOKENS_FILE)) {
@@ -82,8 +186,8 @@ export async function revisionOf ({ dir, scenario, node, locale, locales, tokens
     scan.files.push({ path: TOKENS_FILE, bytes: buf.length, hash: await sha256Hex(buf) })
   }
   const files = Object.fromEntries(scan.files.map((f) => [f.path, f.hash]))
-  const id = await revisionId({ scenario, node, locale, entry: scan.entry, files, tokens })
-  return { id, scenario, node, locale, state: 'default', kind: 'design', entry: scan.entry, files, sizes: Object.fromEntries(scan.files.map((f) => [f.path, f.bytes])), tokens }
+  const id = await revisionId({ scenario, node, locale, entry: scan.entry, files, tokens, items: scan.items || null })
+  return { id, scenario, node, locale, state: 'default', kind: 'design', entry: scan.entry, ...(scan.items ? { items: scan.items } : {}), files, sizes: Object.fromEntries(scan.files.map((f) => [f.path, f.bytes])), tokens }
 }
 
 /**

package/src/lib/dimensions.mjs

@@ -9,6 +9,7 @@
 import { UserError } from './util.mjs'
 import { devicePreset, emulationOf, presetSummary, presetNames } from './devices.mjs'
 import { launchWithRetry } from './browser.mjs'
+import { STATE_PREFIX, stateOfKey, statesOf } from './manifest-core.mjs'
 
 export const BROWSERS = ['chromium', 'webkit', 'firefox']
 export const COLOR_SCHEMES = ['light', 'dark']
@@ -22,8 +23,15 @@ export const DIMENSIONS = [
   { name: 'color_scheme', list: 'color_schemes', values: COLOR_SCHEMES, default: 'light', suffix: (v) => v },
   { name: 'reduced_motion', list: 'reduced_motion', values: REDUCED_MOTION, default: 'no-preference', suffix: () => 'reduce' },
   { name: 'forced_colors', list: 'forced_colors', values: FORCED_COLORS, default: 'none', suffix: () => 'forced' },
-  { name: 'display_mode', list: 'display_modes', values: DISPLAY_MODES, default: 'browser', suffix: (v) => v }
+  { name: 'display_mode', list: 'display_modes', values: DISPLAY_MODES, default: 'browser', suffix: (v) => v },
+  // token modes of a design's token set (#46): brand-a, high-contrast…; the default mode (the environment's
+  // tokens_mode, else the first) is the first of the list and is left out of keys
+  { name: 'token_mode', list: 'token_modes', values: null, default: null, suffix: (v) => `mode-${v}` },
+  // step states (#46): default, empty, error, loading or any name a step lists in `states:`; always the last part
+  { name: 'step_state', list: 'states', values: null, default: 'default', suffix: (v) => `${STATE_PREFIX}${v}` }
 ]
+/** Names of token modes and states: they are parts of capture keys and file names. */
+export const FREE_VALUE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/
 const ALIASES = { chrome: 'chromium', safari: 'webkit', gecko: 'firefox', 'no-motion': 'reduce', reduced: 'reduce', 'no_preference': 'no-preference', high_contrast: 'active', 'high-contrast': 'active', forced: 'active', pwa: 'standalone', installed: 'standalone' }
 
 const asList = (v) => v == null ? null : Array.isArray(v) ? v.map(String) : String(v).split(',').map((s) => s.trim()).filter(Boolean)
@@ -35,6 +43,11 @@ export function dimensionValues (dim, raw) {
   if (!list?.length) return null
   const out = []
   for (const v0 of list) {
+    if (!d.values) {
+      if (!FREE_VALUE.test(v0)) throw new UserError(`${d.list.replace(/_/g, ' ')}: "${v0}" is not a valid name (letters, digits, - and _; at most 40).`)
+      if (!out.includes(v0)) out.push(v0)
+      continue
+    }
     const v = ALIASES[v0.toLowerCase()] || v0.toLowerCase()
     if (!d.values.includes(v)) throw new UserError(`Unknown ${d.list.replace(/_/g, ' ')} value "${v0}". Use: ${d.values.join(', ')}.`)
     if (!out.includes(v)) out.push(v)
@@ -52,12 +65,28 @@ export function dimensionsFrom ({ args = {}, scenario = {}, config = {} } = {})
   const out = {}
   for (const d of DIMENSIONS) {
     const flag = d.list.replace(/_/g, '-')
+    if (d.name === 'step_state') { out.states = scenarioStates(scenario, args.states); continue }
+    // token modes come from the design's token set (startScope); here only an explicit choice
     const raw = args[flag] ?? args[d.list] ?? scenario?.[d.list] ?? walk[d.list]
-    out[d.list] = dimensionValues(d.name, raw)
+    out[d.list] = raw === false || raw === 'false' || raw === 'none' ? (d.name === 'token_mode' ? false : null) : dimensionValues(d.name, raw)
   }
   return out
 }
 
+/**
+ * The states of a run (#46): `default` and every state a step lists in `states:`, in scenario order; null when no
+ * step has states. `pick` (kaloko start --states) narrows them; default always stays.
+ */
+export function scenarioStates (scenario, pick = null) {
+  const all = []
+  for (const n of scenario?.nodes || []) for (const s of statesOf(n)) if (!all.includes(s)) all.push(s)
+  if (all.length < 2) return null
+  const want = pick ? dimensionValues('step_state', pick) : null
+  if (want) for (const s of want) if (!all.includes(s)) throw new UserError(`No step of this scenario has the state "${s}" (states: ${all.slice(1).join(', ')}).`)
+  const out = want ? all.filter((s) => s === 'default' || want.includes(s)) : all
+  return out.length > 1 ? out : null
+}
+
 /**
  * Viewports of a scenario: { name: [w, h] } as before, or names of device presets — as an array
  * (`[iphone-15, ipad-landscape, desktop]`) or as values (`phone: iphone-15`, `tablet: { device: ipad-portrait }`,
@@ -100,12 +129,14 @@ export function appDevices (ids, platform) {
   return { viewports, devices }
 }
 
-/** The capture key of a viewport and dimension values: defaults are left out. */
-export function variantKey (viewport, dims = {}) {
+/** The capture key of a viewport and dimension values: defaults are left out (`defaults`: the run's own, token mode). */
+export function variantKey (viewport, dims = {}, defaults = {}) {
   const parts = [viewport]
-  for (const d of DIMENSIONS) { const v = dims[d.name]; if (v && v !== d.default) parts.push(d.suffix(v)) }
+  for (const d of DIMENSIONS) { const v = dims[d.name]; if (v && v !== (defaults[d.name] ?? d.default)) parts.push(d.suffix(v)) }
   return parts.join('.')
 }
+/** Defaults a scope sets itself: the token mode left out of keys is the first of its modes. */
+export const scopeDefaults = (scope) => (scope?.dimensions?.token_modes?.length ? { token_mode: scope.dimensions.token_modes[0] } : {})
 
 /**
  * Scope of a run: every combination of viewport and dimension values as a capture key with its size, and the
@@ -119,10 +150,11 @@ export function expandScope ({ locales, viewports, devices = {}, dims = {} }) {
   const out = {}; const variants = {}
   let combos = [{}]
   for (const [d, l] of used) combos = combos.flatMap((c) => l.map((v) => ({ ...c, [d.name]: v })))
+  const defaults = dims.token_modes?.length ? { token_mode: dims.token_modes[0] } : {}
   for (const [name, size] of Object.entries(viewports)) {
     const device = devices[name] || null
     for (const c of combos) {
-      const key = variantKey(name, c)
+      const key = variantKey(name, c, defaults)
       let s = size
       // installed PWA: the whole screen of a preset without the browser's bars (the status bar stays)
       if (c.display_mode === 'standalone' && device?.screen) s = [size[0], Math.max(size[1], device.screen[1] - (device.safe?.top || 0))]
@@ -130,7 +162,7 @@ export function expandScope ({ locales, viewports, devices = {}, dims = {} }) {
       variants[key] = { viewport: name, browser: c.browser || 'chromium', ...c, ...(device ? { device: name } : {}) }
     }
   }
-  if (Object.keys(out).length > 400) throw new UserError(`This scope has ${Object.keys(out).length} combinations of viewport, browser, colour scheme and motion; keep it under 400 (pick fewer viewports or values).`)
+  if (Object.keys(out).length > 400) throw new UserError(`This scope has ${Object.keys(out).length} combinations of viewport, browser, colour scheme, motion, token mode and state; keep it under 400 (pick fewer viewports or values).`)
   const dimensions = Object.fromEntries(used.map(([d, l]) => [d.list, l]))
   return { ...loc, viewports: out, variants, ...(used.length ? { dimensions } : {}), ...(Object.keys(devices).length ? { devices } : {}) }
 }
@@ -147,10 +179,27 @@ export function variantOf (scope, key) {
     else if (part === 'reduce') out.reduced_motion = 'reduce'
     else if (part === 'forced') out.forced_colors = 'active'
     else if (part === 'standalone') out.display_mode = 'standalone'
+    else if (part.startsWith('mode-')) out.token_mode = part.slice(5)
+    else if (part.startsWith(STATE_PREFIX)) out.step_state = part.slice(STATE_PREFIX.length)
   }
   return out
 }
 
+/** The step state of a capture key ('default' when the key has none). */
+export const stateOf = (key) => stateOfKey(key)
+
+/**
+ * Keys of `state` for keys of the default state (a walk pass, a device): `mobile` → `mobile.state-empty`, only those
+ * the scope has. The default state gives the keys back.
+ */
+export function stateKeys (scope, keys, state = 'default') {
+  if (!state || state === 'default') return keys.filter((k) => stateOfKey(k) === 'default')
+  return keys.filter((k) => stateOfKey(k) === 'default').map((k) => `${k}.${STATE_PREFIX}${state}`).filter((k) => scope?.viewports?.[k])
+}
+
+/** The states a walk captures a step in: its `states:` that the run has, default first. */
+export const nodeStates = (scope, node) => statesOf(node).filter((s) => s === 'default' || scope?.dimensions?.states?.includes(s))
+
 /** The fields a capture record and a manifest capture carry for its dimensions (only those that were set). */
 export function variantFields (scope, key) {
   const v = scope?.variants?.[key]
@@ -167,7 +216,8 @@ export function variantFields (scope, key) {
  * `only` limits the engines (walk --browsers).
  */
 export function passesOf (scope, { only = null } = {}) {
-  const keys = Object.keys(scope?.viewports || {})
+  // keys of other step states are captured by the same passes, one step script invocation per state
+  const keys = Object.keys(scope?.viewports || {}).filter((k) => stateOfKey(k) === 'default')
   const passes = new Map()
   for (const key of keys) {
     const v = variantOf(scope, key)
@@ -300,15 +350,19 @@ export function referenceKey (key, available, scope = null) {
   const have = new Set(available || [])
   if (have.has(key)) return key
   const v = variantOf(scope, key)
-  const chromium = variantKey(v.viewport, { ...v, browser: 'chromium' })
+  const defaults = scopeDefaults(scope)
+  const chromium = variantKey(v.viewport, { ...v, browser: 'chromium' }, defaults)
   if (have.has(chromium)) return chromium
   // a reference without a colour scheme dimension (light by default) answers for light captures
-  if (!v.color_scheme || v.color_scheme === 'light') { const plain = variantKey(v.viewport, { ...v, browser: 'chromium', color_scheme: null }); if (have.has(plain)) return plain }
+  if (!v.color_scheme || v.color_scheme === 'light') { const plain = variantKey(v.viewport, { ...v, browser: 'chromium', color_scheme: null }, defaults); if (have.has(plain)) return plain }
   return null
 }
 
-/** Token mode of a capture: its colour scheme when the token set has that mode, else the environment's mode. */
-export const tokenModeOf = (variant, modes = [], fallback = null) => (variant?.color_scheme && modes.includes(variant.color_scheme) ? variant.color_scheme : fallback)
+/**
+ * Token mode of a capture: the token mode it was rendered in (#46), else its colour scheme when the token set has
+ * that mode, else the environment's mode.
+ */
+export const tokenModeOf = (variant, modes = [], fallback = null) => (variant?.token_mode && modes.includes(variant.token_mode) ? variant.token_mode : variant?.color_scheme && modes.includes(variant.color_scheme) ? variant.color_scheme : fallback)
 
 /** Engines a scope needs (for `kaloko browser install` hints and doctor). */
 export const enginesOf = (scope) => [...new Set(Object.keys(scope?.viewports || {}).map((k) => variantOf(scope, k).browser))]

package/src/lib/drift.mjs

@@ -85,7 +85,7 @@ export async function driftForCapture ({ node, entry, capture, runDir, ctx }) {
       const refCaps = !ctx.isDesign ? (await referenceStep(ctx, node.id, entry.locale))?.captures : null
       const refStyles = refCaps ? refCaps[referenceKey(entry.viewport, Object.keys(refCaps))]?.design?.styles : null
       // a dark capture is checked against the dark mode of the token set (DTCG modes light/dark)
-      const off = tokenOffenders(capture.design?.styles, ctx.tokens, tokenModeOf({ color_scheme: capture.color_scheme }, modesOf(ctx.tokens), ctx.mode), refStyles)
+      const off = tokenOffenders(capture.design?.styles, ctx.tokens, tokenModeOf({ color_scheme: capture.color_scheme, token_mode: capture.token_mode }, modesOf(ctx.tokens), ctx.mode), refStyles)
       if (off == null) { results[c.id] = { ok: null, evidence: 'Capture has no style summary; capture this step again.' }; continue }
       results[c.id] = off.length
         ? { ok: false, evidence: `${off.length} value(s) outside the token set: ${off.slice(0, 5).map((o) => `${o.property} ${o.value}${o.suggest ? ` → ${o.suggest}` : ''}`).join('; ')}` }

package/src/lib/evaluate.mjs

@@ -8,6 +8,7 @@ import { KEYBOARD_ASSERTS } from './keyboard.mjs'
 import { needsDrift, driftForCapture, loadTokens, driftCacheDir } from './drift.mjs'
 import { packHelp } from './pack-help.mjs'
 import { tokenCriteria, storedValueChecks, STYLE_ASSERTS } from './assertions.mjs'
+import { appliesToState } from './manifest-core.mjs'
 
 /** Latest capture per node/locale/viewport. */
 export function latestCaptures (entries) {
@@ -19,6 +20,8 @@ export function latestCaptures (entries) {
 export const criteriaHash = (node) => sha256(node.criteria || [])
 /** A criterion with `environments` (e.g. [production]) applies only there; without a known environment it applies. */
 export const appliesOn = (c, environment) => !environment || !Array.isArray(c.environments) || !c.environments.length || c.environments.includes(environment)
+/** Environment and step state (#46): a criterion with `states:` applies only to captures of those states. */
+export const appliesTo = (c, environment, capture) => appliesOn(c, environment) && appliesToState(c, capture?.step_state)
 /** Folder of a capture under steps/: the node, or steps/<node>/items/<item> for a page of a stack step. */
 export const stepIdOf = (e) => (e.item ? `${e.node}/items/${e.item}` : e.node)
 export const evaluationSource = (node, capture) => sha256({ capture, criteria: node.criteria || [], purpose: node.purpose || '' })
@@ -31,6 +34,7 @@ export const evaluationSource = (node, capture) => sha256({ capture, criteria: n
 export function combine ({ node, capture, jev, vision = null, thresholds, environment = null }) {
   return (node.criteria || []).map((c) => {
     if (!appliesOn(c, environment)) return { id: c.id, type: c.check.type, verdict: 'not_evaluated', evidence: `Applies on ${c.environments.join(', ')} only; this walk ran on ${environment}.`, na: true, not_applicable: 'environment' }
+    if (!appliesToState(c, capture?.step_state)) return { id: c.id, type: c.check.type, verdict: 'not_evaluated', evidence: `Applies to the state${c.states.length > 1 ? 's' : ''} ${c.states.join(', ')} only; this capture shows ${capture?.step_state || 'default'}.`, na: true, not_applicable: 'state' }
     if (c.check.type === 'deterministic') {
       const r = capture.checks?.[c.id]
       const verdict = r == null || r.ok == null ? 'not_evaluated' : r.ok ? 'pass' : 'fail'
@@ -106,7 +110,7 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       const current = capture.criteria_hash === criteriaHash(node)
       // console triage needs the evaluator only when the capture has console errors
       const outOfSample = entry.item && !sampled.get(entry.node)?.has(entry.item)
-      const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && appliesOn(c, environment) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
+      const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && appliesTo(c, environment, capture) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
       // quick signals ride along on every captured page state (also steps without semantic criteria)
       const signals = settings.signals !== false && !outOfSample && !!capture.state
       // an imported screen without page text (#11) has nothing to ask about: a person decides on the canvas
@@ -206,7 +210,7 @@ export function semanticPrefetch ({ scenario, config, root, environment = null }
         if (!semantic.length && settings.signals === false) continue
         queue.push(async () => {
           const capture = await readJson(join(runDir, e.file))
-          const crit = semantic.filter((c) => !(c.check.about === 'console' && !(capture.console_errors || []).length))
+          const crit = semantic.filter((c) => appliesToState(c, capture.step_state) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
           const signals = settings.signals !== false && !!capture.state
           if ((!crit.length && !signals) || capture.criteria_hash !== criteriaHash(node)) return
           asked++