kaloko 0.3.0

package/src/lib/schema.mjs

@@ -0,0 +1,25 @@
+import Ajv2020 from 'ajv/dist/2020.js'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname } from 'node:path'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const ajv = new Ajv2020({ allErrors: true, strict: false, useDefaults: true })
+const cache = new Map()
+
+export function validator (name) {
+  if (!cache.has(name)) {
+    const schema = JSON.parse(readFileSync(join(root, 'schemas', `${name}.json`), 'utf8'))
+    cache.set(name, ajv.compile(schema))
+  }
+  return cache.get(name)
+}
+
+/** Returns a list of human-readable problems; empty when valid. */
+export function schemaErrors (name, data) {
+  const validate = validator(name)
+  if (validate(data)) return []
+  return validate.errors.map((e) => `${e.instancePath || '/'} ${e.message}${e.params?.allowedValues ? ` (${e.params.allowedValues.join(', ')})` : ''}`)
+}
+
+export const packageRoot = root

package/src/lib/secrets.mjs

@@ -0,0 +1,59 @@
+// Secrets are named in the config (`*_env`, `{ env: NAME }`) and read from the process
+// environment only when needed. Every value read here is remembered, so captures, HTML and
+// logs can be scrubbed before they are written or shared.
+import { UserError } from './util.mjs'
+
+const known = new Set()
+
+/** Value of a secret variable; throws with the variable name (never the value) when it is missing. */
+export function secret (name, what, env = process.env) {
+  const value = env[name]
+  if (value == null || value === '') throw new UserError(`Set ${name}${what ? ` (${what})` : ''} in the environment, the project .env or ~/.config/kaloko/.env.`)
+  remember(value)
+  return value
+}
+
+/** Names of the variables a config fragment refers to that are not set. */
+export function missing (names, env = process.env) {
+  return names.filter((n) => n && (env[n] == null || env[n] === ''))
+}
+
+export function remember (value) {
+  // very short values (a PIN, "x") would scrub ordinary words from the evidence
+  if (typeof value === 'string' && value.length >= 4) known.add(value)
+}
+
+/** Replaces every remembered secret (and its base64 / URL-encoded forms) with a marker. */
+export function redact (text) {
+  if (typeof text !== 'string' || !known.size) return text
+  // longest first: one secret's form may be part of another's (a password inside a Basic pair)
+  const forms = [...new Set([...known].flatMap((v) => [v, encodeURIComponent(v), Buffer.from(v).toString('base64')]))].sort((a, b) => b.length - a.length)
+  let out = text
+  for (const form of forms) if (out.includes(form)) out = out.split(form).join('[redacted]')
+  return out
+}
+
+/** Deep copy with every string redacted (capture records, console entries). */
+export function redactDeep (value) {
+  if (typeof value === 'string') return redact(value)
+  if (Array.isArray(value)) return value.map(redactDeep)
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v)]))
+  return value
+}
+
+export const _forget = () => known.clear() // tests
+
+/**
+ * Remembers every secret an environment refers to that is set (`*_env` except user names,
+ * `{ env: NAME }` header values), so captures are scrubbed even when a person or an agent
+ * typed the password and the CLI never read it itself.
+ */
+export function rememberEnvironment (envConfig, env = process.env) {
+  const visit = (node, key) => {
+    if (!node || typeof node !== 'object') return
+    for (const [k, v] of Object.entries(node)) {
+      if (typeof v === 'string' && ((k.endsWith('_env') && k !== 'user_env') || (k === 'env' && key !== 'base_url'))) { if (env[v]) remember(env[v]) } else visit(v, k)
+    }
+  }
+  visit({ access: envConfig.access, http_auth: envConfig.http_auth, accounts: envConfig.accounts, mail: envConfig.mail })
+}

package/src/lib/service.mjs

@@ -0,0 +1,52 @@
+// Client of the Kaloko service API (kaloko.app or KALOKO_URL) with the organization token.
+import { UserError } from './util.mjs'
+
+/** Base URL of the service; configs written before the rename name app.qawalk.com, which now means kaloko.app. */
+export function serviceUrl (config, vars = process.env) {
+  const url = (vars.KALOKO_URL || config.share?.url || 'https://kaloko.app').replace(/\/$/, '')
+  return url.replace(/^https:\/\/app\.qawalk\.com$/, 'https://kaloko.app')
+}
+
+export function service (config) {
+  const base = serviceUrl(config) + '/api/v1'
+  const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
+  const token = process.env[tokenEnv]
+  if (!token) throw new UserError(`Set ${tokenEnv} (create a token in Kaloko → Settings).`)
+  // an agent names itself (KALOKO_AGENT, e.g. "claude-code"); the service shows it in presence, history and audit (#42)
+  const headers = { Authorization: `Bearer ${token}`, ...(process.env.KALOKO_AGENT ? { 'X-QAwalk-Agent': process.env.KALOKO_AGENT.slice(0, 60) } : {}) }
+  const check = async (res, what) => {
+    if (res.ok) return res.json()
+    const body = await res.json().catch(() => ({}))
+    throw new UserError(`${what} → HTTP ${res.status}: ${body.error || res.statusText}`)
+  }
+  // the service limits requests per token (HTTP 429, nothing was processed): wait as told and try again
+  // read-your-writes across requests: the service answers with a database bookmark the next request sends back
+  let bookmark = null
+  const limited = async (send) => {
+    for (let attempt = 0; ; attempt++) {
+      const res = await send()
+      const bm = res.headers?.get?.('X-D1-Bookmark'); if (bm) { bookmark = bm; headers['X-D1-Bookmark'] = bm }
+      if (res.status !== 429 || attempt >= 6) return res
+      const wait = Math.min(60, Number(res.headers.get('Retry-After')) || 2 ** attempt)
+      await new Promise((r) => setTimeout(r, wait * 1000))
+    }
+  }
+  return {
+    async request (method, path, body) {
+      const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
+      return check(res, `${method} ${path}`)
+    },
+    async fetch (path) {
+      const res = await fetch(base + path, { headers })
+      if (!res.ok) { const body = await res.json().catch(() => ({})); throw new UserError(`GET ${path} → HTTP ${res.status}: ${body.error || res.statusText}`) }
+      return res
+    },
+    async upload (path, data, name, extra = {}) {
+      for (let attempt = 0; ; attempt++) {
+        const res = await limited(() => fetch(base + path, { method: 'PUT', headers: { ...headers, ...extra }, body: data }))
+        if (res.ok || attempt >= 2 || res.status < 500) return check(res, `upload ${name}`)
+        await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
+      }
+    }
+  }
+}

package/src/lib/stack.mjs

@@ -0,0 +1,130 @@
+// Stack steps: one step that stands for many pages of the same template (magazine articles, product pages, an SEO
+// landing catalogue). The pages come from urls, a file, a sitemap, a crawl of a listing or a script; every page is
+// captured with the step's criteria and a few index fields, and the canvas shows them as a stack with an index.
+import { readFile } from 'node:fs/promises'
+import { resolve, extname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createHash } from 'node:crypto'
+import { UserError } from './util.mjs'
+
+export const DEFAULT_LIMIT = 500
+export const DEFAULT_SEMANTIC_SAMPLE = 20
+export const DEFAULT_FIELDS = [
+  { id: 'title', label: 'Title', from: 'title' },
+  { id: 'h1', label: 'H1', from: 'h1' },
+  { id: 'words', label: 'Words', from: 'words' },
+  { id: 'http', label: 'HTTP', from: 'http' }
+]
+export const fieldsOf = (node) => (node.fields?.length ? node.fields.map((f) => ({ label: f.label || f.id, from: f.from || f.id, ...f })) : DEFAULT_FIELDS)
+
+const slug = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+/** Stable, readable id of a page: the path as a slug (≤ 60 chars) plus a short hash when needed. */
+export function itemId (path, taken) {
+  let base = slug(path).slice(0, 60) || 'root'
+  if (taken.has(base)) base = `${base.slice(0, 52)}-${createHash('sha1').update(path).digest('hex').slice(0, 7)}`
+  taken.add(base)
+  return base
+}
+
+const pathOf = (u, origin) => { try { const x = new URL(u, origin); return x.origin === origin ? x.pathname + x.search : x.href } catch { return String(u) } }
+
+/** Parses <loc> entries of a sitemap or sitemap index. */
+export function sitemapLocs (xml) {
+  const locs = [...String(xml).matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/gi)].map((m) => m[1].replace(/&amp;/g, '&'))
+  return { index: /<sitemapindex[\s>]/i.test(xml), locs }
+}
+
+/** Reads a list file: text (one per line), CSV (first column) or JSON ([path] or [{path|url, title, key}]). */
+export async function listFile (file) {
+  const text = await readFile(file, 'utf8').catch(() => { throw new UserError(`items.file ${file} cannot be read.`) })
+  if (extname(file) === '.json') {
+    const data = JSON.parse(text)
+    return (Array.isArray(data) ? data : data.items || []).map((x) => (typeof x === 'string' ? { path: x } : { path: x.path || x.url, title: x.title, key: x.key }))
+  }
+  return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#')).map((l) => ({ path: extname(file) === '.csv' ? l.split(/[,;]/)[0].replace(/^"|"$/g, '') : l })).filter((x) => x.path && !/^(path|url)$/i.test(x.path))
+}
+
+/**
+ * The pages of a stack step, deduplicated, filtered (match/exclude), limited: [{ id, path, url, title? }].
+ * `base` is the environment's URL for the locale; `page` is used for crawl and script sources. `match` and
+ * `exclude` are regexes on the path with its query; `{locale}` in any source string is the walked locale.
+ */
+export async function resolveItems ({ node, base, page, scenarioDir, env, locale, limit, fetchImpl = fetch }) {
+  // `{locale}` in any string of the source (sitemap, match, crawl.from, file…) becomes the walked locale
+  const sub = (v) => (typeof v === 'string' ? v.replaceAll('{locale}', locale || '') : Array.isArray(v) ? v.map(sub) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, sub(x)])) : v)
+  const src = sub(node.items || {})
+  const origin = new URL(base).origin
+  const abs = (p) => new URL(p, base.endsWith('/') ? base : base + '/').href.replace(/^(https?:\/\/[^/]+)\/\//, '$1/')
+  const toUrl = (p) => (/^https?:\/\//.test(p) ? p : new URL(p, origin).href)
+  let raw = []
+  if (src.urls) raw = src.urls.map((p) => ({ path: p }))
+  else if (src.file) raw = await listFile(resolve(scenarioDir, src.file))
+  else if (src.sitemap) {
+    const get = async (u) => { const r = await fetchImpl(u, { headers: { 'User-Agent': 'Kaloko' } }); if (!r.ok) throw new UserError(`items.sitemap ${u}: HTTP ${r.status}`); return r.text() }
+    const first = sitemapLocs(await get(toUrl(src.sitemap)))
+    let locs = first.locs
+    if (first.index) { locs = []; for (const u of first.locs.slice(0, 50)) locs.push(...sitemapLocs(await get(u)).locs) }
+    raw = locs.map((u) => ({ path: u }))
+  } else if (src.crawl) {
+    if (!page) throw new UserError('items.crawl needs a browser page.')
+    let url = toUrl(src.crawl.from)
+    for (let i = 0; i < (src.crawl.pages || 1) && url; i++) {
+      await page.goto(url, { waitUntil: 'domcontentloaded' })
+      const found = await page.$$eval(src.crawl.links, (as) => as.map((a) => ({ href: a.href, title: (a.innerText || a.title || '').trim().slice(0, 200) })))
+      raw.push(...found.map((f) => ({ path: f.href, title: f.title || undefined })))
+      url = src.crawl.next ? await page.$eval(src.crawl.next, (a) => a.href).catch(() => null) : null
+    }
+  } else if (src.script) {
+    const mod = await import(pathToFileURL(resolve(scenarioDir, src.script)).href)
+    const fn = mod.default || mod.items
+    if (typeof fn !== 'function') throw new UserError(`items.script ${src.script} must export a default function.`)
+    raw = (await fn({ page, env, locale, url: abs })) || []
+    raw = raw.map((x) => (typeof x === 'string' ? { path: x } : { path: x.path || x.url, title: x.title, key: x.key }))
+  }
+  const match = src.match ? new RegExp(src.match) : null
+  const exclude = src.exclude ? new RegExp(src.exclude) : null
+  const seen = new Set(); const taken = new Set(); const out = []
+  const max = limit || src.limit || DEFAULT_LIMIT
+  for (const r of raw) {
+    if (!r.path) continue
+    const path = pathOf(r.path, origin)
+    const test = path.startsWith('http') ? (({ pathname, search }) => pathname + search)(new URL(path)) : path // path with its query
+    if (match && !match.test(test)) continue
+    if (exclude && exclude.test(test)) continue
+    if (seen.has(path)) continue
+    seen.add(path)
+    out.push({ id: r.key ? itemId(String(r.key), taken) : itemId(path, taken), path, url: path.startsWith('http') ? path : toUrl(path), ...(r.title ? { title: r.title } : {}) })
+    if (out.length >= max) break
+  }
+  return { items: out, total: seen.size, truncated: out.length >= max && raw.length > out.length }
+}
+
+/** In-page extraction of the index fields (self-contained; runs through page.evaluate). */
+export function readFields (specs) {
+  const text = (el) => (el ? (el.innerText || el.textContent || '').replace(/\s+/g, ' ').trim() : null)
+  const meta = (sel) => document.querySelector(sel)?.getAttribute('content') || null
+  const out = {}
+  for (const f of specs) {
+    const from = f.from || f.id
+    try {
+      if (from === 'title') out[f.id] = document.title || null
+      else if (from === 'h1') out[f.id] = text(document.querySelector('h1'))
+      else if (from === 'description') out[f.id] = meta("meta[name='description']")
+      else if (from === 'canonical') out[f.id] = document.querySelector("link[rel='canonical']")?.href || null
+      else if (from === 'lang') out[f.id] = document.documentElement.lang || null
+      else if (from === 'url') out[f.id] = location.href
+      else if (from === 'path') out[f.id] = location.pathname + location.search
+      else if (from === 'words') { const root = document.querySelector('main, article, [role=main]') || document.body; out[f.id] = (text(root) || '').split(/\s+/).filter(Boolean).length }
+      else if (from === 'http') out[f.id] = null // filled from the navigation response
+      else if (from.startsWith('count:')) out[f.id] = document.querySelectorAll(from.slice(6)).length
+      else {
+        const at = from.lastIndexOf('@')
+        const sel = at > 0 ? from.slice(0, at) : from
+        const el = document.querySelector(sel)
+        out[f.id] = at > 0 ? el?.getAttribute(from.slice(at + 1)) ?? null : text(el)
+      }
+      if (typeof out[f.id] === 'string') out[f.id] = out[f.id].slice(0, 300)
+    } catch { out[f.id] = null }
+  }
+  return out
+}

package/src/lib/tokens.mjs

@@ -0,0 +1,352 @@
+// Design tokens (#42): W3C DTCG token sets, resolved to name → value, and the checks that keep live
+// files and captured pages on the set. Pure except checkTokens, which reads a design folder.
+import { readFile, readdir } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+
+// Both the older string values ("#2E6BFF", "16px") and the DTCG 2025.10 shapes are read: colors as
+// { colorSpace, components, alpha, hex }, dimensions and durations as { value, unit }, composite types
+// (typography, shadow, border, transition, gradient), aliases as {group.token} or { "$ref": "#/json/pointer" },
+// groups with $extends, $root and $deprecated. Modes come from a resolver document (sets, modifiers,
+// resolutionOrder) or, as before, from top-level groups named like a mode.
+
+const isToken = (v) => v && typeof v === 'object' && !Array.isArray(v) && '$value' in v
+const isGroup = (v) => v && typeof v === 'object' && !Array.isArray(v) && !('$value' in v)
+const clone = (v) => (v == null ? v : JSON.parse(JSON.stringify(v)))
+/** Deep merge for $extends and resolver sets: later wins, groups merge, tokens replace. */
+function merge (base, over) {
+  const out = clone(base) || {}
+  for (const [k, v] of Object.entries(over || {})) out[k] = isGroup(v) && isGroup(out[k]) ? merge(out[k], v) : clone(v)
+  return out
+}
+/** RFC 6901 JSON Pointer in a document ("#/a/b/0"). */
+export function pointer (doc, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#')) return undefined
+  let cur = doc
+  for (const raw of ref.slice(1).split('/').slice(1)) {
+    const k = raw.replace(/~1/g, '/').replace(/~0/g, '~')
+    if (cur == null || typeof cur !== 'object' || !(k in cur)) return undefined
+    cur = cur[k]
+  }
+  return cur
+}
+/** A group or token by dotted path ("color.brand"). */
+function byPath (doc, path) {
+  let cur = doc
+  for (const k of path.split('.')) { if (cur == null || typeof cur !== 'object' || !(k in cur)) return undefined; cur = cur[k] }
+  return cur
+}
+
+/** Applies $extends (a group inherits another group, local keys override). */
+function applyExtends (doc, node = doc, depth = 0) {
+  if (!isGroup(node) || depth > 20) return node
+  let out = {}
+  for (const [k, v] of Object.entries(node)) out[k] = isGroup(v) ? applyExtends(doc, v, depth + 1) : v
+  const ext = node.$extends
+  if (typeof ext === 'string') {
+    const target = ext.startsWith('#') ? pointer(doc, ext) : byPath(doc, ext.replace(/^\{|\}$/g, ''))
+    if (isGroup(target)) { const { $extends, ...local } = out; out = merge(applyExtends(doc, target, depth + 1), local) }
+  }
+  return out
+}
+
+/** Is this a DTCG resolver document (sets, modifiers, resolutionOrder)? */
+export const isResolver = (doc) => !!doc && typeof doc === 'object' && Array.isArray(doc.resolutionOrder)
+
+/** Modifier contexts of a resolver (light, dark, …), or the legacy mode groups of a set. */
+export function modesOf (set) {
+  if (isResolver(set)) return [...new Set(Object.values(set.modifiers || {}).flatMap((m) => Object.keys(m.contexts || {})))]
+  const declared = set?.$extensions?.['qawalk.modes']
+  if (Array.isArray(declared)) return declared.filter((m) => set[m])
+  return ['light', 'dark', 'high-contrast'].filter((m) => set?.[m] && typeof set[m] === 'object' && !('$value' in set[m]))
+}
+
+/**
+ * One token set out of a resolver: the resolution order merged, each modifier at the context the input picks
+ * (a string mode picks that context in every modifier that has it; otherwise the modifier's default or first).
+ * Sources are inline token objects or { $ref } into the resolver itself; files are inlined by inlineResolver.
+ */
+export function resolveResolver (doc, input = null) {
+  const want = typeof input === 'string' ? input : null
+  const pick = (name, mod) => {
+    const ctx = mod.contexts || {}
+    const chosen = (input && typeof input === 'object' && input[name]) || (want && ctx[want] ? want : null) || mod.default || Object.keys(ctx)[0]
+    return ctx[chosen] || []
+  }
+  const sourcesOf = (list) => (list || []).map((src) => (src && src.$ref ? pointer(doc, src.$ref) : src)).filter(isGroup)
+  let out = {}
+  for (const item of doc.resolutionOrder || []) {
+    const ref = item?.$ref || ''
+    const target = ref ? pointer(doc, ref) : item
+    if (!target) continue
+    if (ref.startsWith('#/modifiers/') || (!ref && target.contexts)) { for (const s of sourcesOf(pick(ref.split('/')[2] || target.name || '', target))) out = merge(out, s) }
+    else if (Array.isArray(target.sources)) { for (const s of sourcesOf(target.sources)) out = merge(out, s) }
+    else if (isGroup(target)) out = merge(out, target)
+  }
+  return out
+}
+
+/** Replaces file sources ({ "$ref": "light.json" }) of a resolver by their content, so it can be stored alone. */
+export async function inlineResolver (doc, readFileRef) {
+  const out = clone(doc)
+  const inline = async (list) => Promise.all((list || []).map(async (src) => (src?.$ref && !src.$ref.startsWith('#') ? JSON.parse(await readFileRef(src.$ref)) : src)))
+  for (const set of Object.values(out.sets || {})) set.sources = await inline(set.sources)
+  for (const mod of Object.values(out.modifiers || {})) for (const k of Object.keys(mod.contexts || {})) mod.contexts[k] = await inline(mod.contexts[k])
+  out.resolutionOrder = await Promise.all(out.resolutionOrder.map(async (item) => (item?.$ref && !item.$ref.startsWith('#') ? JSON.parse(await readFileRef(item.$ref)) : item)))
+  return out
+}
+
+/**
+ * Tokens of a set as [{ name, type, value, raw, deprecated, description }]: aliases and JSON Pointer references
+ * resolved, $extends applied, `$root` tokens named after their group, `value` CSS-ready (composite types: an
+ * object of CSS-ready parts). A mode picks a resolver context or a legacy mode group.
+ */
+export function flattenTokens (set, mode = null) {
+  let doc
+  if (isResolver(set)) doc = resolveResolver(set, mode)
+  else {
+    const modes = modesOf(set)
+    const base = Object.fromEntries(Object.entries(set || {}).filter(([k]) => !modes.includes(k)))
+    doc = mode && set?.[mode] ? merge(base, set[mode]) : base
+  }
+  doc = applyExtends(doc)
+  const out = new Map()
+  const walk = (obj, path, inherited, deprecated) => {
+    for (const [k, v] of Object.entries(obj || {})) {
+      if (k.startsWith('$') && k !== '$root') continue
+      const dep = v && typeof v === 'object' && '$deprecated' in v ? v.$deprecated : deprecated
+      if (isToken(v)) out.set((k === '$root' ? path : [...path, k]).join('.'), { type: v.$type || inherited || null, raw: v.$value, deprecated: dep || false, description: v.$description || null })
+      else if (isGroup(v)) walk(v, [...path, k], v.$type || inherited, dep)
+    }
+  }
+  walk(doc, [], null, false)
+  const resolve = (value, depth = 0) => {
+    if (depth > 10) return value
+    if (typeof value === 'string') {
+      const m = value.match(/^\{([^}]+)\}$/)
+      if (!m) return value
+      const t = out.get(m[1].replace(/\.\$root$/, ''))
+      return t ? resolve(t.raw, depth + 1) : value
+    }
+    if (value && typeof value === 'object' && typeof value.$ref === 'string') { const at = pointer(doc, value.$ref); return resolve(isToken(at) ? at.$value : at, depth + 1) } // a pointer at a token means its value
+    if (Array.isArray(value)) return value.map((x) => resolve(x, depth + 1))
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, x]) => [k, resolve(x, depth + 1)]))
+    return value
+  }
+  return [...out].map(([name, t]) => {
+    const raw = resolve(t.raw)
+    return { name, type: t.type, value: cssValue(t.type, raw), raw, deprecated: t.deprecated, description: t.description }
+  })
+}
+
+const WEIGHTS = { thin: 100, hairline: 100, 'extra-light': 200, 'ultra-light': 200, light: 300, normal: 400, regular: 400, book: 400, medium: 500, 'semi-bold': 600, 'demi-bold': 600, bold: 700, 'extra-bold': 800, 'ultra-bold': 800, black: 900, heavy: 900, 'extra-black': 950, 'ultra-black': 950 }
+const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0')
+/** A DTCG color object as #rrggbb[aa]: srgb, srgb-linear and hsl are converted, other spaces use their hex. */
+export function colorObject (c) {
+  if (!c || typeof c !== 'object') return null
+  const a = c.alpha == null ? 1 : Number(c.alpha)
+  const withAlpha = (hex) => (hex ? (a < 1 ? hex.slice(0, 7) + hex2(a * 255) : hex.slice(0, 7)) : null)
+  const [x, y, z] = (c.components || []).map((v) => (v === 'none' ? 0 : Number(v)))
+  const space = String(c.colorSpace || '').toLowerCase()
+  const ok = [x, y, z].every(Number.isFinite)
+  if (space === 'srgb' && ok) return withAlpha('#' + [x, y, z].map((v) => hex2(v * 255)).join(''))
+  if (space === 'srgb-linear' && ok) { const g = (v) => (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055); return withAlpha('#' + [x, y, z].map((v) => hex2(g(v) * 255)).join('')) }
+  if (space === 'hsl' && ok) {
+    const s = y / 100, l = z / 100, k = (n) => (n + x / 30) % 12, f = (n) => l - s * Math.min(l, 1 - l) * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1))
+    return withAlpha('#' + [f(0), f(8), f(4)].map((v) => hex2(v * 255)).join(''))
+  }
+  return c.hex ? withAlpha(normColor(c.hex)) : null
+}
+const unitValue = (v) => (v && typeof v === 'object' && 'value' in v ? `${v.value}${v.unit || ''}` : v)
+/** A resolved DTCG value as CSS: strings and numbers stay, objects of known types become CSS values or parts. */
+export function cssValue (type, v) {
+  if (v == null) return v
+  if (type === 'color' || (typeof v === 'object' && 'colorSpace' in v)) return typeof v === 'string' ? v : colorObject(v)
+  if (type === 'dimension' || type === 'duration' || (typeof v === 'object' && 'unit' in v && 'value' in v)) return unitValue(v)
+  if (type === 'fontFamily') return Array.isArray(v) ? v.join(', ') : v
+  if (type === 'fontWeight') return typeof v === 'string' ? (WEIGHTS[v.toLowerCase()] ?? v) : v
+  if (type === 'cubicBezier' && Array.isArray(v)) return `cubic-bezier(${v.join(', ')})`
+  if (type === 'typography' && typeof v === 'object') return { fontFamily: cssValue('fontFamily', v.fontFamily), fontSize: cssValue('dimension', v.fontSize), fontWeight: cssValue('fontWeight', v.fontWeight), lineHeight: v.lineHeight, letterSpacing: cssValue('dimension', v.letterSpacing) }
+  if (type === 'border' && typeof v === 'object') return { color: cssValue('color', v.color), width: cssValue('dimension', v.width), style: typeof v.style === 'string' ? v.style : null }
+  if (type === 'shadow') return [].concat(v).map((s) => ({ color: cssValue('color', s.color), offsetX: cssValue('dimension', s.offsetX), offsetY: cssValue('dimension', s.offsetY), blur: cssValue('dimension', s.blur), spread: cssValue('dimension', s.spread) }))
+  if (type === 'gradient' && Array.isArray(v)) return v.map((s) => ({ color: cssValue('color', s.color), position: s.position }))
+  if (type === 'transition' && typeof v === 'object') return { duration: unitValue(v.duration), delay: unitValue(v.delay), timingFunction: cssValue('cubicBezier', v.timingFunction) }
+  return v
+}
+
+/** Structural problems of a set or resolver: names, references that point nowhere, unreadable values. */
+export function validateTokens (set) {
+  if (!set || typeof set !== 'object' || Array.isArray(set)) return ['A token set is a JSON object.']
+  const problems = []
+  const modes = modesOf(set)
+  const docs = isResolver(set) ? (modes.length ? modes.map((m) => resolveResolver(set, m)) : [resolveResolver(set)]) : [set]
+  const names = (obj, path = []) => {
+    for (const [k, v] of Object.entries(obj || {})) {
+      if (k.startsWith('$')) continue
+      if (/[{}.]/.test(k)) problems.push(`${[...path, k].join('.')}: a name must not contain { } or .`)
+      if (isGroup(v)) names(v, [...path, k])
+    }
+  }
+  for (const doc of docs) {
+    names(doc)
+    for (const t of flattenTokens(doc)) {
+      for (const r of JSON.stringify(t.raw ?? null).match(/"\{[^}"]+\}"/g) || []) problems.push(`${t.name}: ${r.slice(1, -1)} points at no token`)
+      if (t.type === 'color' && !normColor(t.value)) problems.push(`${t.name}: the color value cannot be read`)
+      if ((t.type === 'dimension' || t.type === 'duration') && typeof t.value !== 'string' && typeof t.value !== 'number') problems.push(`${t.name}: a ${t.type} needs { value, unit }`)
+    }
+  }
+  return [...new Set(problems)]
+}
+
+// ---- value normalisation ----
+
+const NAMED = { white: '#ffffff', black: '#000000' }
+export function normColor (v) {
+  if (v && typeof v === 'object') return colorObject(v)
+  if (typeof v !== 'string') return null
+  const s = v.trim().toLowerCase()
+  if (NAMED[s]) return NAMED[s]
+  let m = s.match(/^#([0-9a-f]{3,8})$/)
+  if (m) {
+    let h = m[1]
+    if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('')
+    return '#' + h.slice(0, 6) + (h.length === 8 && h.slice(6) !== 'ff' ? h.slice(6) : '')
+  }
+  m = s.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/)
+  if (m) {
+    const hex = (n) => Math.max(0, Math.min(255, Math.round(Number(n)))).toString(16).padStart(2, '0')
+    const a = m[4] == null ? 1 : m[4].endsWith('%') ? Number(m[4].slice(0, -1)) / 100 : Number(m[4])
+    return '#' + hex(m[1]) + hex(m[2]) + hex(m[3]) + (a < 1 ? hex(a * 255) : '')
+  }
+  return null
+}
+export function normDimension (v, rootPx = 16) {
+  if (typeof v === 'number') return v
+  if (typeof v !== 'string') return null
+  const m = v.trim().match(/^(-?[\d.]+)(px|rem|em)?$/)
+  if (!m) return null
+  const n = Number(m[1])
+  return m[2] === 'rem' || m[2] === 'em' ? n * rootPx : n
+}
+const normFont = (v) => String(Array.isArray(v) ? v[0] : v || '').split(',')[0].trim().replace(/^["']|["']$/g, '').toLowerCase()
+
+/** Lookup tables of a flattened set by kind. */
+export function tokenIndex (flatIn) {
+  const colors = new Map(), dims = new Map(), fonts = new Map(), deprecated = new Map()
+  // composite tokens contribute their parts (typography.fontSize, border.color, shadow colors and offsets);
+  // deprecated tokens are no suggestion, and a value only they have is reported as deprecated
+  const flat = []
+  for (const t of flatIn) {
+    if (t.deprecated) { const c = normColor(t.value); if (c) deprecated.set(c, { name: t.name, note: typeof t.deprecated === 'string' ? t.deprecated : null }); continue }
+    if (t.value && typeof t.value === 'object') {
+      for (const part of [].concat(t.value)) for (const [k, v] of Object.entries(part || {})) {
+        if (v == null) continue
+        const type = k === 'color' ? 'color' : k === 'fontFamily' ? 'fontFamily' : /size|width|offset|blur|spread|spacing/i.test(k) ? 'dimension' : null
+        if (type) flat.push({ name: `${t.name}.${k}`, type, value: v })
+      }
+    } else flat.push(t)
+  }
+  for (const t of flat) {
+    const c = (t.type === 'color' || !t.type) ? normColor(t.value) : null
+    if (c) { if (!colors.has(c)) colors.set(c, t.name); continue }
+    if (t.type === 'fontFamily' || /font.?family/i.test(t.name)) { const f = normFont(t.value); if (f && !fonts.has(f)) fonts.set(f, t.name); continue }
+    const d = normDimension(t.value?.value != null ? `${t.value.value}${t.value.unit || ''}` : t.value)
+    // several tokens may share a value (8px spacing, 8px radius): keep all names, pick by property later
+    if (d != null && (t.type === 'dimension' || t.type === 'fontSize' || t.type === 'spacing' || t.type === 'borderRadius' || !t.type)) dims.set(d, [...(dims.get(d) || []), t.name])
+  }
+  return { colors, dims, fonts, deprecated }
+}
+
+const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16))
+function nearestColor (c, colors) {
+  let best = null, dist = Infinity
+  const [r, g, b] = rgb(c)
+  for (const [hex, name] of colors) { const [x, y, z] = rgb(hex); const d = (r - x) ** 2 + (g - y) ** 2 + (b - z) ** 2; if (d < dist) { dist = d; best = name } }
+  return best
+}
+/** Token names that suit a CSS property (font sizes for font-size, radii for border-radius, …). */
+export const kindFor = (prop) => /radius/.test(prop) ? /radius|round|corner/i : /font-size|line-height|letter/.test(prop) ? /font|text|size|type|leading|line/i : /padding|margin|gap|inset/.test(prop) ? /space|spacing|gap|gutter|inset|size/i : null
+function nearestDim (n, dims, want = null) {
+  let best = null, dist = Infinity
+  for (const [v, names] of dims) {
+    const name = want ? names.find((x) => want.test(x)) : names[0]
+    if (!name) continue
+    const d = Math.abs(v - n); if (d < dist) { dist = d; best = name }
+  }
+  return best
+}
+
+const COLOR_PROPS = /^(color|background|background-color|border(-top|-right|-bottom|-left)?(-color)?|outline(-color)?|fill|stroke|box-shadow|text-decoration-color|caret-color|accent-color)$/
+const DIM_PROPS = /^(font-size|margin(-top|-right|-bottom|-left|-inline|-block)?|padding(-top|-right|-bottom|-left|-inline|-block)?|gap|row-gap|column-gap|border-radius|border(-top|-right|-bottom|-left)?-(left-|right-)?radius)$/
+const IGNORE = new Set(['0', '0px', 'auto', 'inherit', 'initial', 'unset', 'none', 'transparent', 'currentcolor', '100%', '50%', 'revert'])
+
+/**
+ * Checks one declaration value against the token index; returns offenders [{ value, suggest }].
+ * var(--…) and calc() with vars are fine: the value then comes from the set by construction.
+ */
+export function checkDeclaration (property, value, index) {
+  const prop = property.trim().toLowerCase()
+  const v = value.trim().replace(/\s*!important$/, '')
+  if (!v || v.includes('var(')) return []
+  const out = []
+  if (COLOR_PROPS.test(prop)) {
+    for (const m of v.matchAll(/#[0-9a-f]{3,8}\b|rgba?\([^)]*\)|\b(white|black)\b/gi)) {
+      const c = normColor(m[0])
+      if (c && !index.colors.has(c)) out.push({ value: m[0], suggest: nearestColor(c, index.colors), ...(index.deprecated?.has(c) ? { deprecated: index.deprecated.get(c).name, note: index.deprecated.get(c).note } : {}) })
+    }
+  } else if (DIM_PROPS.test(prop)) {
+    for (const part of v.split(/\s+/)) {
+      if (IGNORE.has(part.toLowerCase())) continue
+      const d = normDimension(part)
+      if (d != null && d !== 0 && !index.dims.has(Math.abs(d))) out.push({ value: part, suggest: nearestDim(Math.abs(d), index.dims, kindFor(prop)) })
+    }
+  } else if (prop === 'font-family') {
+    const f = normFont(v)
+    if (f && !['inherit', 'system-ui', 'sans-serif', 'serif', 'monospace'].includes(f) && index.fonts.size && !index.fonts.has(f)) out.push({ value: v, suggest: [...index.fonts.values()][0] })
+  }
+  return out
+}
+
+/** Declarations of a CSS text with line numbers (comments removed; good enough for design files). */
+export function declarations (css) {
+  const out = []
+  const text = css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+  const re = /([a-z-]+)\s*:\s*([^;{}]+)(?=;|})/gi
+  let m
+  while ((m = re.exec(text))) {
+    if (m[1].startsWith('--')) continue
+    out.push({ property: m[1], value: m[2], line: text.slice(0, m.index).split('\n').length })
+  }
+  return out
+}
+
+async function files (dir, base = dir) {
+  const out = []
+  for (const e of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+    if (e.name.startsWith('.')) continue
+    const full = join(dir, e.name)
+    if (e.isDirectory()) out.push(...await files(full, base))
+    else if (/\.(css|html)$/i.test(e.name)) out.push(relative(base, full).split(sep).join('/'))
+  }
+  return out
+}
+
+/** Raw values outside the token set across the CSS and HTML (style blocks and attributes) of a design folder. */
+export async function checkTokens ({ dir, tokens, mode = null }) {
+  const index = tokenIndex(flattenTokens(tokens, mode))
+  const offenders = []
+  let checked = 0
+  for (const file of await files(dir)) {
+    const text = await readFile(join(dir, file), 'utf8')
+    const chunks = file.endsWith('.css') ? [{ css: text, offset: 0 }] : [
+      ...[...text.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => ({ css: m[1], offset: text.slice(0, m.index).split('\n').length - 1 })),
+      ...[...text.matchAll(/\sstyle\s*=\s*"([^"]*)"/gi)].map((m) => ({ css: `x{${m[1]}}`, offset: text.slice(0, m.index).split('\n').length - 1 }))
+    ]
+    for (const { css, offset } of chunks) {
+      for (const d of declarations(css)) {
+        checked++
+        for (const o of checkDeclaration(d.property, d.value, index)) offenders.push({ file, line: d.line + offset, property: d.property, ...o })
+      }
+    }
+  }
+  return { checked, offenders, tokens: { colors: index.colors.size, dimensions: index.dims.size, fonts: index.fonts.size } }
+}