kaloko 0.5.2 → 0.6.0

package/src/lib/figma.mjs

@@ -0,0 +1,584 @@
+// Figma import (batch G, docs/BACKLOG-IDEAS.md idea 1): frames of a Figma file become the steps of a design folder,
+// so a design version made from them is the design reference implementation runs are checked against (pixels with
+// design_pixels, styles and tokens with kaloko drift). One way: Figma → Kaloko; prototype links, components and
+// auto layout are not carried over. Each step page shows the frame's PNG (1× and 2×) and, under it, the frame's text
+// layers as real text with Figma's typography and colors (var(--token) where the layer uses a variable or style),
+// so the step spec has text, roles and tokens to compare. Variables (or, without them, the color and text styles the
+// frames use) become tokens.json (W3C DTCG). Teams without an API token import a folder exported from Figma (PNG/SVG).
+import { readFile, writeFile, mkdir, readdir, rm, stat } from 'node:fs/promises'
+import { join, relative, extname, basename } from 'node:path'
+import yaml from 'js-yaml'
+import { UserError } from './util.mjs'
+import { validateTokens, flattenTokens } from './tokens.mjs'
+import { TOKENS_FILE } from './design-core.mjs'
+
+export const GENERATOR = 'kaloko figma import'
+export const figmaApi = () => (process.env.KALOKO_FIGMA_API || 'https://api.figma.com').replace(/\/+$/, '')
+const FRAME_TYPES = new Set(['FRAME', 'COMPONENT', 'COMPONENT_SET', 'INSTANCE', 'GROUP'])
+const IMAGE_RE = /^figma(-[A-Za-z0-9_-]+)?(\.[23]x)?\.(png|svg|jpg|jpeg|webp)$/
+
+// ---------------------------------------------------------------- references and names
+
+/** A Figma file reference: { key, nodeIds } from a file URL (design/file/proto, ?node-id=1-2) or a bare key. */
+export function parseFigmaRef (input) {
+  const s = String(input || '').trim()
+  let m = s.match(/^https?:\/\/(?:www\.)?figma\.com\/(?:file|design|proto|board)\/([A-Za-z0-9]{10,})(?:\/[^?#]*)?(?:\?([^#]*))?/)
+  if (m) {
+    const params = new URLSearchParams(m[2] || '')
+    const node = params.get('node-id')
+    return { key: m[1], nodeIds: node ? node.split(',').map((n) => n.replace(/-/g, ':')) : [] }
+  }
+  m = s.match(/^[A-Za-z0-9]{10,}$/)
+  return m ? { key: s, nodeIds: [] } : null
+}
+
+/** A name as a slug: lower case, diacritics folded, words joined by dashes. */
+export const slug = (s) => String(s || '').normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+/** A token path segment: as in the name, without the characters DTCG names may not have. */
+const tokenSeg = (s) => String(s).trim().toLowerCase().replace(/[{}.$]/g, '').replace(/\s+/g, '-') || '_'
+const segmentsOf = (name) => String(name || '').split(/\s*[/|@·—–]\s*|\s+-\s+|\s*[[\]()]\s*/).map(slug).filter(Boolean)
+
+// ---------------------------------------------------------------- the REST API
+
+/** A small client of the Figma REST API (X-Figma-Token); `fetch` can be replaced in tests. */
+export function figmaClient ({ token, fetch: f = globalThis.fetch, base = figmaApi(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  if (!token) throw new UserError('Figma needs a personal access token: create one in Figma (Settings → Security → Personal access tokens, scope file content read-only) and put it in FIGMA_TOKEN, or name the variable with --token-env. Without a token, export the frames as PNG and import the folder.')
+  const get = async (path, { optional = false } = {}) => {
+    for (let attempt = 0; ; attempt++) {
+      const res = await f(`${base}${path}`, { headers: { 'X-Figma-Token': token } })
+      if (res.status === 429 && attempt < 3) { await sleep(Math.min(30, Number(res.headers.get('retry-after')) || 2 ** attempt) * 1000); continue }
+      if (res.ok) return res.json()
+      if (optional && (res.status === 403 || res.status === 404)) return null
+      const body = await res.text().catch(() => '')
+      if (res.status === 403) throw new UserError(`Figma refused the token (403)${/scope|permission/i.test(body) ? `: ${body.slice(0, 160)}` : ''}. Check that it may read this file.`)
+      if (res.status === 404) throw new UserError('Figma file not found (404): check the link or key and that the token\'s account can open it.')
+      throw new UserError(`Figma API ${path.split('?')[0]}: HTTP ${res.status} ${body.slice(0, 160)}`)
+    }
+  }
+  const ids = (list) => list.map(encodeURIComponent).join(',')
+  return {
+    file: (key, depth = 3) => get(`/v1/files/${key}?depth=${depth}`),
+    nodes: (key, list) => get(`/v1/files/${key}/nodes?ids=${ids(list)}`),
+    images: (key, list, scale = 1, format = 'png') => get(`/v1/images/${key}?ids=${ids(list)}&scale=${scale}&format=${format}`),
+    variables: (key) => get(`/v1/files/${key}/variables/local`, { optional: true }),
+    async download (url) {
+      const res = await f(url)
+      if (!res.ok) throw new UserError(`Downloading a frame image failed: HTTP ${res.status}.`)
+      return Buffer.from(await res.arrayBuffer())
+    }
+  }
+}
+
+// ---------------------------------------------------------------- frames and steps
+
+/** Top-level frames of the file's pages (frames inside sections too): { id, name, page, width, height }. */
+export function framesOf (document, { page = null } = {}) {
+  const out = []
+  const box = (n) => n.absoluteBoundingBox || n.absoluteRenderBounds || { width: n.size?.x, height: n.size?.y }
+  const add = (n, pageName) => {
+    if (n.visible === false) return
+    if (n.type === 'SECTION') { for (const c of n.children || []) add(c, pageName); return }
+    if (!FRAME_TYPES.has(n.type) || n.type === 'GROUP') return
+    const b = box(n)
+    out.push({ id: n.id, name: n.name, page: pageName, width: Math.round(b?.width || 0), height: Math.round(b?.height || 0) })
+  }
+  for (const p of document?.children || []) {
+    if (p.type !== 'CANVAS') { add(p, null); continue }
+    if (page && slug(p.name) !== slug(page) && p.id !== page) continue
+    for (const n of p.children || []) add(n, p.name)
+  }
+  return out
+}
+
+/**
+ * Which frame is which step: an explicit map (frame name or id → step, or { step, viewport, locale }) first, then the
+ * name: a segment of it ("Checkout / Payment — mobile", "payment@mobile", "Payment [cs]") that is a step id or title,
+ * a viewport name and a locale. A step with several frames and no viewport in their names takes them by width.
+ * Returns { assigned: [{ frame, step, viewport, locale }], unmatched: [frame], missing: [step id], duplicates: [frame] }.
+ */
+export function mapFrames (frames, { steps, viewports = {}, locales = [], map = null }) {
+  const bySlug = new Map()
+  for (const s of steps) { bySlug.set(slug(s.id), s.id); const t = typeof s.title === 'string' ? s.title : s.title && typeof s.title === 'object' ? Object.values(s.title) : []; for (const x of [].concat(t)) if (x && !bySlug.has(slug(x))) bySlug.set(slug(x), s.id) }
+  const vpNames = Object.keys(viewports)
+  const assigned = [], unmatched = [], duplicates = []
+  const explicit = (f) => { const e = map?.[f.id] ?? map?.[f.name]; return e == null ? null : typeof e === 'string' ? { step: e } : e }
+  for (const f of frames) {
+    const e = explicit(f)
+    let step = null, viewport = null, locale = null
+    if (e) {
+      if (e.skip || e.step === null || e.step === false) continue
+      step = steps.some((s) => s.id === e.step) ? e.step : null
+      viewport = e.viewport || null
+      locale = e.locale || null
+      if (!step) { unmatched.push({ ...f, reason: `map names step ${e.step}, which the scenario does not have` }); continue }
+    } else {
+      const segs = segmentsOf(f.name)
+      const words = slug(f.name).split('-')
+      step = bySlug.get(slug(f.name)) || segs.map((s) => bySlug.get(s)).find(Boolean) || null
+      if (!step) { const hit = [...bySlug.keys()].filter((k) => slug(f.name).startsWith(`${k}-`) || slug(f.name).endsWith(`-${k}`)).sort((a, b) => b.length - a.length)[0]; step = hit ? bySlug.get(hit) : null }
+      viewport = vpNames.find((v) => segs.includes(slug(v)) || words.includes(slug(v))) || null
+      locale = locales.find((l) => l !== 'default' && (segs.includes(slug(l)) || words.includes(slug(l)))) || null
+      if (!step) { unmatched.push(f); continue }
+    }
+    if (viewport && !viewports[viewport]) viewport = null
+    if (locale && !locales.includes(locale)) locale = null
+    assigned.push({ frame: f, step, viewport, locale })
+  }
+  // several frames of one step without a viewport in their names: each takes the free viewport of its width
+  const groups = new Map()
+  for (const a of assigned) { const k = `${a.step}|${a.locale || ''}`; groups.set(k, [...(groups.get(k) || []), a]) }
+  for (const list of groups.values()) {
+    if (list.length < 2) continue
+    for (const a of list.filter((x) => !x.viewport)) {
+      const taken = new Set(list.map((x) => x.viewport).filter(Boolean))
+      const fit = vpNames.filter((v) => !taken.has(v)).sort((x, y) => Math.abs(viewports[x][0] - a.frame.width) - Math.abs(viewports[y][0] - a.frame.width))[0]
+      if (fit && Math.abs(viewports[fit][0] - a.frame.width) <= Math.max(8, viewports[fit][0] * 0.05)) a.viewport = fit
+    }
+  }
+  // one frame per step, locale and viewport: later ones are left out
+  const seen = new Set()
+  const out = []
+  for (const a of assigned) { const k = `${a.step}|${a.locale || ''}|${a.viewport || ''}`; if (seen.has(k)) { duplicates.push(a.frame); continue } seen.add(k); out.push(a) }
+  const missing = steps.map((s) => s.id).filter((id) => !out.some((a) => a.step === id))
+  return { assigned: out, unmatched, missing, duplicates }
+}
+
+// ---------------------------------------------------------------- colors, texts, tokens
+
+const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n * 255))).toString(16).padStart(2, '0')
+/** A Figma color ({ r, g, b, a } in 0..1, times the paint's opacity) as #rrggbb or #rrggbbaa. */
+export function colorHex (c, opacity = 1) {
+  if (!c) return null
+  const a = (c.a ?? 1) * (opacity ?? 1)
+  return `#${hex2(c.r)}${hex2(c.g)}${hex2(c.b)}${a < 0.999 ? hex2(a) : ''}`
+}
+const solid = (paints) => (paints || []).find((p) => p.type === 'SOLID' && p.visible !== false)
+export const fillOf = (node) => { const p = solid(node?.fills); return p ? colorHex(p.color, p.opacity) : null }
+
+const WEIGHT_NAMES = { thin: 100, hairline: 100, extralight: 200, ultralight: 200, light: 300, regular: 400, normal: 400, book: 400, medium: 500, semibold: 600, demibold: 600, bold: 700, extrabold: 800, ultrabold: 800, black: 900, heavy: 900 }
+const weightOf = (st) => st?.fontWeight || WEIGHT_NAMES[String(st?.fontPostScriptName || st?.fontStyle || '').toLowerCase().replace(/[^a-z]/g, '').replace(/italic$/, '')] || 400
+const px = (n) => `${Math.round(n * 100) / 100}px`
+
+/** A text style as DTCG typography: family, size, weight, line height (a ratio) and letter spacing. */
+function typographyOf (st) {
+  if (!st?.fontFamily) return null
+  const size = st.fontSize || 16
+  const lh = st.lineHeightPx ? Math.round((st.lineHeightPx / size) * 1000) / 1000 : st.lineHeightPercentFontSize ? Math.round(st.lineHeightPercentFontSize * 10) / 1000 : null
+  return { fontFamily: st.fontFamily, fontSize: px(size), fontWeight: weightOf(st), ...(lh ? { lineHeight: lh } : {}), letterSpacing: px(st.letterSpacing || 0) }
+}
+
+/** Where a token lives in tokens.json: the variable or style name split on "/", a kind group for styles. */
+function tokenPath (name, kind = null) {
+  const segs = String(name).split('/').map(tokenSeg).filter(Boolean)
+  if (kind && segs.length && !(kind === 'color' ? ['color', 'colors', 'colour'] : ['typography', 'text', 'type', 'font', 'fonts']).includes(segs[0])) segs.unshift(kind)
+  else if (kind && segs.length) segs[0] = kind
+  return segs
+}
+const setAt = (doc, path, token) => { let o = doc; for (const k of path.slice(0, -1)) { if (!o[k] || typeof o[k] !== 'object' || '$value' in o[k]) o[k] = {}; o = o[k] } o[path[path.length - 1]] = token }
+
+/**
+ * DTCG tokens from the file's local variables: colors, numbers as px dimensions (sizes, radii, spacing, font sizes)
+ * or plain numbers, font families and weights; aliases as {references}. A collection with several modes adds a group
+ * per extra mode (dark, …) named in $extensions.qawalk.modes. Returns { doc, names: Map variable id → token name }.
+ */
+export function tokensFromVariables (meta) {
+  const vars = meta?.meta?.variables || meta?.variables || {}
+  const cols = meta?.meta?.variableCollections || meta?.variableCollections || {}
+  const doc = {}
+  const names = new Map()
+  const extra = new Map() // mode name → overrides
+  for (const v of Object.values(vars)) names.set(v.id, tokenPath(v.name).join('.'))
+  const valueOf = (v, raw) => {
+    if (raw && typeof raw === 'object' && raw.type === 'VARIABLE_ALIAS') return names.has(raw.id) ? `{${names.get(raw.id)}}` : null
+    const scopes = v.scopes || []
+    if (v.resolvedType === 'COLOR') return { $type: 'color', $value: colorHex(raw) }
+    if (v.resolvedType === 'FLOAT') {
+      if (scopes.includes('FONT_WEIGHT')) return { $type: 'fontWeight', $value: raw }
+      if (scopes.some((s) => /RADIUS|GAP|WIDTH_HEIGHT|FONT_SIZE|LINE_HEIGHT|LETTER_SPACING|STROKE|EFFECT_FLOAT|PARAGRAPH/.test(s)) || scopes.includes('ALL_SCOPES') || /space|spacing|size|radius|gap|width|height|padding|margin/i.test(v.name)) return { $type: 'dimension', $value: px(raw) }
+      return { $type: 'number', $value: raw }
+    }
+    if (v.resolvedType === 'STRING' && (scopes.includes('FONT_FAMILY') || /font|family/i.test(v.name))) return { $type: 'fontFamily', $value: raw }
+    return null
+  }
+  for (const v of Object.values(vars)) {
+    const col = cols[v.variableCollectionId]
+    const modes = col?.modes || []
+    const def = col?.defaultModeId || modes[0]?.modeId || Object.keys(v.valuesByMode || {})[0]
+    const path = names.get(v.id).split('.')
+    const base = v.valuesByMode?.[def]
+    const t = valueOf(v, base)
+    if (!t) continue
+    const tok = typeof t === 'string' ? { $type: { COLOR: 'color', FLOAT: 'dimension', STRING: 'fontFamily' }[v.resolvedType] || undefined, $value: t } : t
+    if (v.description) tok.$description = v.description
+    setAt(doc, path, tok)
+    for (const m of modes) {
+      if (m.modeId === def || !(m.modeId in (v.valuesByMode || {}))) continue
+      const mt = valueOf(v, v.valuesByMode[m.modeId])
+      if (!mt) continue
+      const mname = tokenSeg(m.name)
+      const group = extra.get(mname) || extra.set(mname, {}).get(mname)
+      setAt(group, path, typeof mt === 'string' ? { $value: mt } : mt)
+    }
+  }
+  if (!Object.keys(doc).length) return null
+  const modeNames = [...extra.keys()].filter((m) => !(m in doc))
+  if (modeNames.length) {
+    const defName = tokenSeg(Object.values(cols).find((c) => (c.modes || []).length > 1)?.modes?.find((m) => m.modeId === Object.values(cols).find((c) => (c.modes || []).length > 1)?.defaultModeId)?.name || 'default')
+    for (const m of modeNames) doc[m] = extra.get(m)
+    if (!doc[defName] && !modeNames.includes(defName)) doc[defName] = {}
+    doc.$extensions = { 'qawalk.modes': [defName, ...modeNames].filter((m) => doc[m]) }
+  }
+  return { doc, names }
+}
+
+/**
+ * Tokens from the color and text styles the imported frames use (files without variables, or plans without the
+ * variables API): a style's value is read from a node that uses it. Returns { doc, names: Map style id → token name }.
+ */
+export function tokensFromStyles (styles, roots) {
+  const doc = {}
+  const names = new Map()
+  const seen = new Set()
+  const visit = (n) => {
+    for (const [kind, id] of Object.entries(n.styles || {})) {
+      const st = styles?.[id]
+      if (!st || seen.has(id)) continue
+      if ((kind === 'fill' || kind === 'fills') && st.styleType === 'FILL') { const c = fillOf(n); if (c) { const p = tokenPath(st.name, 'color'); setAt(doc, p, { $type: 'color', $value: c, ...(st.description ? { $description: st.description } : {}) }); names.set(id, p.join('.')); seen.add(id) } }
+      if (kind === 'text' && st.styleType === 'TEXT') { const t = typographyOf(n.style); if (t) { const p = tokenPath(st.name, 'typography'); setAt(doc, p, { $type: 'typography', $value: t, ...(st.description ? { $description: st.description } : {}) }); names.set(id, p.join('.')); seen.add(id) } }
+    }
+    for (const c of n.children || []) visit(c)
+  }
+  for (const r of roots) visit(r)
+  return Object.keys(doc).length ? { doc, names } : null
+}
+
+const HEADING = /^h([1-6])\b|heading|headline|title/i
+/**
+ * The visible text layers of a frame, relative to it: text, box, typography, color, and the role to give them
+ * (heading, button, link or paragraph) from the layer and its parents' names and the sizes on the frame.
+ */
+export function textsOfFrame (frame, { tokenNames = new Map() } = {}) {
+  const origin = frame.absoluteBoundingBox || { x: 0, y: 0 }
+  const out = []
+  const walk = (n, trail) => {
+    if (n.visible === false || n.opacity === 0) return
+    const names = [...trail, n.name || '']
+    if (n.type === 'TEXT' && String(n.characters || '').trim()) {
+      const b = n.absoluteBoundingBox || { x: origin.x, y: origin.y, width: 0, height: 0 }
+      const st = n.style || {}
+      const fillPaint = solid(n.fills)
+      const varId = n.boundVariables?.fills?.[0]?.id
+      const colorToken = (varId && tokenNames.get(varId)) || (n.styles?.fill && tokenNames.get(n.styles.fill)) || null
+      const typeToken = (n.styles?.text && tokenNames.get(n.styles.text)) || null
+      const sizeVar = n.boundVariables?.fontSize?.[0]?.id || n.boundVariables?.fontSize?.id
+      const context = names.slice(-3).join(' ')
+      const role = /\b(button|btn|cta)\b/i.test(context) ? 'button' : /\blink\b/i.test(context) ? 'link' : (n.name || '').match(/^h([1-6])\b/i) ? `h${(n.name.match(/^h([1-6])\b/i))[1]}` : null
+      out.push({
+        text: String(n.characters).slice(0, 2000), x: Math.round(b.x - origin.x), y: Math.round(b.y - origin.y), w: Math.round(b.width), h: Math.round(b.height),
+        style: { family: st.fontFamily || null, size: st.fontSize || null, weight: weightOf(st), lineHeight: st.lineHeightPx || null, letterSpacing: st.letterSpacing || 0, italic: !!st.italic, align: (st.textAlignHorizontal || 'LEFT').toLowerCase(), transform: st.textCase === 'UPPER' ? 'uppercase' : st.textCase === 'LOWER' ? 'lowercase' : null },
+        color: fillPaint ? colorHex(fillPaint.color, fillPaint.opacity) : null, colorToken, typeToken, sizeToken: sizeVar ? tokenNames.get(sizeVar) || null : null, role, layer: n.name || ''
+      })
+    }
+    for (const c of n.children || []) walk(c, names)
+  }
+  for (const c of frame.children || []) walk(c, [frame.name || ''])
+  // headings: layers named like one, else the largest text on the frame when it stands out (24 px and up)
+  const sizes = out.map((t) => t.style.size || 0)
+  const top = Math.max(0, ...sizes)
+  for (const t of out) {
+    if (t.role) continue
+    if (HEADING.test(t.layer) && !/subtitle/i.test(t.layer)) t.role = 'h2'
+    if (t.style.size === top && top >= 24 && sizes.filter((s) => s === top).length <= 2) t.role = 'h1'
+  }
+  return out
+}
+
+// ---------------------------------------------------------------- the step page
+
+const escHtml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+const cssVar = (name) => `--${name.replace(/\./g, '-')}`
+const cssFont = (f) => (/^[A-Za-z0-9 -]+$/.test(f) ? `"${f}"` : `"${String(f).replace(/["\\]/g, '')}"`)
+
+/**
+ * The HTML of one step: each frame (default, or for one viewport) as a block of its size, its image on top and its
+ * text layers underneath. `frames`: [{ viewport | null, width, height, src, src2x, background, texts }].
+ * `vars`: Map token name → CSS value for the custom properties the texts use.
+ */
+export function stepHtml ({ title, lang = 'en', frames, viewports = {}, vars = new Map(), source = '' }) {
+  const css = [
+    'html,body{margin:0;padding:0}body{background:#fff}',
+    '.kf{position:relative;margin:0 auto;display:none;overflow:hidden}',
+    '.kf>img{position:absolute;left:0;top:0;width:100%;height:100%;display:block;z-index:1}',
+    '.kf>.t{position:absolute;margin:0;padding:0;white-space:pre-wrap;overflow:hidden;z-index:0}',
+    '.kf--default{display:block}'
+  ]
+  if (vars.size) css.unshift(`:root{${[...vars].map(([n, v]) => `${cssVar(n)}:${v}`).join(';')}}`)
+  for (const f of frames.filter((x) => x.viewport && viewports[x.viewport])) css.push(`@media (width: ${viewports[f.viewport][0]}px){.kf--default{display:none}.kf--vp-${f.viewport.replace(/[^A-Za-z0-9_-]/g, '_')}{display:block}}`)
+  const block = (f) => {
+    const cls = f.viewport ? `kf${f.alsoDefault ? ' kf--default' : ''} kf--vp-${f.viewport.replace(/[^A-Za-z0-9_-]/g, '_')}` : 'kf kf--default'
+    const texts = (f.texts || []).map((t) => {
+      const tag = /^h[1-6]$/.test(t.role || '') ? t.role : 'p'
+      const role = t.role === 'button' ? ' role="button"' : t.role === 'link' ? ' role="link"' : ''
+      const st = t.style || {}
+      const color = t.colorToken && t.color ? `var(${cssVar(t.colorToken)}, ${t.color})` : t.color
+      const style = [`left:${t.x}px`, `top:${t.y}px`, `width:${Math.max(1, t.w)}px`, `min-height:${Math.max(1, t.h)}px`,
+        st.family && `font-family:${cssFont(st.family)}, sans-serif`, st.size && `font-size:${t.sizeToken ? `var(${cssVar(t.sizeToken)}, ${px(st.size)})` : px(st.size)}`, `font-weight:${st.weight || 400}`,
+        st.lineHeight && `line-height:${px(st.lineHeight)}`, st.letterSpacing && `letter-spacing:${px(st.letterSpacing)}`, st.italic && 'font-style:italic', st.align && st.align !== 'left' && `text-align:${st.align === 'justified' ? 'justify' : st.align}`,
+        st.transform && `text-transform:${st.transform}`, color && `color:${color}`].filter(Boolean).join(';')
+      return `<${tag} class="t"${role} style="${escHtml(style)}">${escHtml(t.text)}</${tag}>`
+    }).join('\n    ')
+    const srcset = f.src2x && f.src !== f.src2x ? ` srcset="${escHtml(f.src)} 1x, ${escHtml(f.src2x)} 2x"` : ''
+    return `  <div class="${cls}" data-kaloko="figma-frame" style="width:${f.width}px;height:${f.height}px${f.background ? `;background:${f.background}` : ''}">
+    <img src="${escHtml(f.src)}"${srcset} alt="" width="${f.width}" height="${f.height}">
+    ${texts}
+  </div>`
+  }
+  // without a frame for every viewport, the widest one with a viewport also stands for the viewports without one
+  const fallback = frames.some((f) => !f.viewport) ? null : [...frames].sort((a, b) => b.width - a.width)[0]
+  const ordered = [...frames.filter((f) => !f.viewport), ...frames.filter((f) => f.viewport)].map((f) => (f === fallback ? { ...f, alsoDefault: true } : f))
+  return `<!doctype html>
+<html lang="${escHtml(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="${GENERATOR}">
+<title>${escHtml(title)}</title>
+<style>
+${css.join('\n')}
+</style>
+</head>
+<body>
+<!-- ${escHtml(source)}: the frame image on top, its text layers underneath (for the step spec and drift). Re-import to update; edits here are overwritten. -->
+${ordered.map(block).join('\n')}
+</body>
+</html>
+`
+}
+
+// ---------------------------------------------------------------- local export (no API token)
+
+/** Width and height of a PNG, JPEG or SVG file (pixels; an SVG's width/height or viewBox). */
+export function imageSize (buf, ext) {
+  if (ext === 'png' && buf.length > 24 && buf.readUInt32BE(12) === 0x49484452) return [buf.readUInt32BE(16), buf.readUInt32BE(20)]
+  if (ext === 'jpg' || ext === 'jpeg') {
+    for (let i = 2; i < buf.length - 9;) {
+      if (buf[i] !== 0xff) { i++; continue }
+      const marker = buf[i + 1]; const len = buf.readUInt16BE(i + 2)
+      if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) return [buf.readUInt16BE(i + 7), buf.readUInt16BE(i + 5)]
+      i += 2 + len
+    }
+    return null
+  }
+  if (ext === 'svg') {
+    const head = buf.toString('utf8', 0, 4000)
+    const tag = head.match(/<svg\b[^>]*>/i)?.[0] || ''
+    const num = (a) => { const m = tag.match(new RegExp(`\\s${a}\\s*=\\s*["']\\s*([\\d.]+)(px)?\\s*["']`, 'i')); return m ? Number(m[1]) : null }
+    const vb = tag.match(/viewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)/i)
+    const w = num('width') ?? (vb ? Number(vb[1]) : null), h = num('height') ?? (vb ? Number(vb[2]) : null)
+    return w && h ? [Math.round(w), Math.round(h)] : null
+  }
+  return null
+}
+
+/**
+ * Frames of a folder exported from Figma (File → Export, or the export panel): PNG, JPEG or SVG files named after
+ * their frames, @2x/@3x suffixes for scales. Returns { frames: [{ id, name, width, height, files: { 1?, 2? } }], tokens }.
+ */
+export async function readExportFolder (dir) {
+  const list = []
+  const walk = async (d) => { for (const e of await readdir(d, { withFileTypes: true })) { if (e.name.startsWith('.')) continue; const p = join(d, e.name); if (e.isDirectory()) await walk(p); else list.push(p) } }
+  await walk(dir)
+  const byName = new Map()
+  let tokens = null
+  for (const p of list.sort()) {
+    const ext = extname(p).slice(1).toLowerCase()
+    if (ext === 'json' && /(^|[.-])tokens\.json$/i.test(basename(p))) {
+      try { const doc = JSON.parse(await readFile(p, 'utf8')); if (!validateTokens(doc).length) tokens = doc } catch {}
+      continue
+    }
+    if (!['png', 'svg', 'jpg', 'jpeg'].includes(ext)) continue
+    const rel = relative(dir, p).slice(0, -(ext.length + 1))
+    const m = rel.match(/^(.*?)(?:@([23])x)?$/)
+    const name = m[1].split(/[\\/]/).join(' / ')
+    const scale = Number(m[2] || 1)
+    const buf = await readFile(p)
+    const size = imageSize(buf, ext)
+    if (!size) continue
+    const f = byName.get(name) || byName.set(name, { id: `file:${name}`, name, width: 0, height: 0, files: {} }).get(name)
+    if (!f.files[scale] || ext === 'png') f.files[scale] = { path: p, ext, buf }
+    if (!f.width || scale === 1) { f.width = Math.round(size[0] / (ext === 'svg' ? 1 : scale)); f.height = Math.round(size[1] / (ext === 'svg' ? 1 : scale)) }
+  }
+  return { frames: [...byName.values()], tokens }
+}
+
+// ---------------------------------------------------------------- the import
+
+const exists = async (p) => { try { await stat(p); return true } catch { return false } }
+const RECORD = (dir) => join(dir, '.qawalk', 'figma.json')
+
+/** Reads a frame map file (JSON or YAML): { "<frame name or id>": "step" | { step, viewport, locale } | { skip: true } }. */
+export async function readMap (file) {
+  const text = await readFile(file, 'utf8').catch(() => { throw new UserError(`--map: cannot read ${file}.`) })
+  const doc = /\.ya?ml$/i.test(file) ? yaml.load(text) : JSON.parse(text)
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) throw new UserError('--map: an object of frame name or id → step id (or { step, viewport, locale }).')
+  return doc
+}
+
+/**
+ * Imports Figma frames into a design folder. `source`: a Figma URL, a file key or a local export folder. Writes per
+ * step `<step>/index.html` (or `<step>/<locale>/index.html` for locale frames), the frame images and figma.json, and
+ * tokens.json when the file has variables or styles (unless the folder has its own set: --tokens write overwrites,
+ * --tokens skip never writes). Returns a summary.
+ */
+export async function importFigma ({ source, scenario, viewports, locales, dir, token = null, fetch = globalThis.fetch, map = null, only = null, page = null, tokensMode = 'auto', force = false, dryRun = false, say = () => {} }) {
+  const steps = scenario.nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'external')
+  const local = !parseFigmaRef(source) && await exists(source) && (await stat(source)).isDirectory()
+  const ref = local ? null : parseFigmaRef(source)
+  if (!local && !ref) throw new UserError(`Not a Figma file link, key or export folder: ${source}`)
+  const prev = JSON.parse(await readFile(RECORD(dir), 'utf8').catch(() => 'null'))
+  let frames, meta = {}, tokens = null
+  const nodes = new Map(), images = new Map()
+  const client = local ? null : figmaClient({ token, fetch })
+  const pick = (list) => (only?.length ? list.filter((f) => only.includes(f.id) || only.includes(f.name) || only.some((o) => slug(o) === slug(f.name))) : list)
+  if (local) {
+    const exp = await readExportFolder(source)
+    frames = pick(exp.frames)
+    if (exp.tokens) tokens = { doc: exp.tokens, names: new Map(), from: 'folder' }
+    meta = { source: 'folder', folder: source }
+  } else {
+    const file = await client.file(ref.key)
+    meta = { source: 'figma', key: ref.key, name: file.name, version: file.version || null, last_modified: file.lastModified || null }
+    let all = framesOf(file.document, { page })
+    if (ref.nodeIds.length) {
+      const picked = await client.nodes(ref.key, ref.nodeIds)
+      all = []
+      // a link to a page, a section or one frame: the frames it names
+      for (const [id, n] of Object.entries(picked.nodes || {})) {
+        const doc = n?.document
+        if (!doc) continue
+        if (doc.type === 'CANVAS') all.push(...framesOf({ children: [doc] }))
+        else if (doc.type === 'SECTION') all.push(...framesOf({ children: [{ type: 'CANVAS', name: '', children: [doc] }] }))
+        else if (FRAME_TYPES.has(doc.type)) { const b = doc.absoluteBoundingBox || {}; all.push({ id, name: doc.name, page: null, width: Math.round(b.width || 0), height: Math.round(b.height || 0) }) }
+      }
+    }
+    frames = pick(all)
+    meta.styles = file.styles || {}
+  }
+  const mapping = mapFrames(frames, { steps, viewports, locales, map })
+  if (!mapping.assigned.length) throw new UserError(`No frame matches a step of ${scenario.id}. Frames: ${frames.slice(0, 12).map((f) => `"${f.name}"`).join(', ')}${frames.length > 12 ? ', …' : ''}. Name frames after step ids or titles (with a viewport like "payment / mobile"), or pass --map frames.json.`)
+  // hand-written steps are not overwritten without --force
+  const touched = [...new Set(mapping.assigned.map((a) => a.step))]
+  const mine = []
+  for (const s of touched) {
+    const file = join(dir, s, 'index.html')
+    if (await exists(file) && !(await readFile(file, 'utf8')).includes(`content="${GENERATOR}"`)) mine.push(s)
+  }
+  if (mine.length && !force) throw new UserError(`These steps already have a design that was not imported from Figma: ${mine.join(', ')}. Pass --force to replace them, or --frames to import others.`)
+  if (!local) {
+    const ids = mapping.assigned.map((a) => a.frame.id)
+    for (let i = 0; i < ids.length; i += 50) {
+      const chunk = ids.slice(i, i + 50)
+      const full = await client.nodes(ref.key, chunk)
+      for (const [id, n] of Object.entries(full.nodes || {})) if (n?.document) { nodes.set(id, n.document); Object.assign(meta.styles, n.styles || {}) }
+      for (const scale of [1, 2]) {
+        const r = await client.images(ref.key, chunk, scale)
+        if (r.err) throw new UserError(`Figma could not render the frames: ${r.err}`)
+        for (const [id, url] of Object.entries(r.images || {})) if (url) images.set(`${id}@${scale}`, url)
+      }
+    }
+    const vars = tokensMode === 'skip' ? null : await client.variables(ref.key)
+    tokens = vars ? tokensFromVariables(vars) : null
+    if (tokens) tokens.from = 'variables'
+    else if (tokensMode !== 'skip') { const st = tokensFromStyles(meta.styles, [...nodes.values()]); if (st) tokens = { ...st, from: 'styles' } }
+  }
+  // the token set: written when the folder has none or the last one came from Figma
+  const tokFile = join(dir, TOKENS_FILE)
+  const ownSet = await exists(tokFile) && !prev?.tokens_written
+  const writeTokens = tokens?.doc && tokensMode !== 'skip' && (tokensMode === 'write' || !ownSet)
+  if (tokens?.doc) { const problems = validateTokens(tokens.doc); if (problems.length) { say(`! The token set from Figma has problems and is not written: ${problems.slice(0, 3).join('; ')}`); tokens = null } }
+  const tokenValues = new Map()
+  const known = tokens?.doc ? new Map(flattenTokens(tokens.doc).map((t) => [t.name, t.value])) : (await exists(tokFile) ? new Map(flattenTokens(JSON.parse(await readFile(tokFile, 'utf8'))).map((t) => [t.name, t.value])) : new Map())
+  // pages per step and locale (null = the step's default page)
+  const written = []
+  const warnings = []
+  const byStep = new Map()
+  for (const a of mapping.assigned) { const k = `${a.step}|${a.locale || ''}`; byStep.set(k, [...(byStep.get(k) || []), a]) }
+  // a step drawn only per locale: its first locale's frames are the page of the other locales too
+  for (const s of touched) if (!byStep.has(`${s}|`)) { const first = locales.map((l) => byStep.get(`${s}|${l}`)).find(Boolean); if (first) byStep.set(`${s}|`, first.map((a) => ({ ...a, locale: null }))) }
+  const lang = (l) => (l && l !== 'default' ? l : scenario.locales?.[0] && scenario.locales[0] !== 'default' ? scenario.locales[0] : 'en')
+  if (!dryRun) await mkdir(dir, { recursive: true })
+  for (const s of touched) {
+    if (dryRun) continue
+    const sdir = join(dir, s)
+    await mkdir(sdir, { recursive: true })
+    // images from an earlier import go first: a frame removed from Figma leaves nothing behind
+    for (const d of [sdir, ...locales.map((l) => join(sdir, l))]) for (const f of await readdir(d).catch(() => [])) if (IMAGE_RE.test(f) || f === 'figma.json') await rm(join(d, f), { force: true })
+  }
+  for (const [k, list] of byStep) {
+    const [s, loc] = k.split('|')
+    const node = steps.find((n) => n.id === s)
+    const pageDir = loc ? join(dir, s, loc) : join(dir, s)
+    const frameOut = []
+    const metaOut = []
+    for (const a of list) {
+      const f = a.frame
+      const name = a.viewport ? `figma-${a.viewport.replace(/[^A-Za-z0-9_-]/g, '_')}` : 'figma'
+      if (!dryRun) await mkdir(pageDir, { recursive: true })
+      const outs = {}
+      if (local) {
+        for (const [scale, file] of Object.entries(f.files)) {
+          const out = `${name}${scale === '1' ? '' : `.${scale}x`}.${file.ext}`
+          if (!dryRun) await writeFile(join(pageDir, out), file.buf)
+          outs[scale] = out
+        }
+      } else {
+        for (const scale of [1, 2]) {
+          const url = images.get(`${f.id}@${scale}`)
+          if (!url) continue
+          const out = `${name}${scale === 1 ? '' : '.2x'}.png`
+          if (!dryRun) await writeFile(join(pageDir, out), await client.download(url))
+          outs[scale] = out
+        }
+      }
+      const src = outs[1] || outs[2] || outs[3] || null
+      const src2x = outs[1] ? outs[2] || null : null
+      if (!src) { warnings.push(`${f.name}: no image (an empty or hidden frame?)`); continue }
+      const tree = nodes.get(f.id)
+      const texts = tree ? textsOfFrame(tree, { tokenNames: tokens?.names || new Map() }) : []
+      const vpSize = a.viewport ? viewports[a.viewport] : null
+      if (vpSize && Math.abs(vpSize[0] - f.width) > 2) warnings.push(`${f.name}: ${f.width} px wide, viewport ${a.viewport} is ${vpSize[0]} px; the pixel comparison will differ at the edges`)
+      if (!a.viewport && list.length === 1) { const off = Object.entries(viewports).filter(([, [w]]) => Math.abs(w - f.width) > 2).map(([v]) => v); if (off.length && off.length === Object.keys(viewports).length) warnings.push(`${f.name}: ${f.width} px wide matches no viewport (${Object.entries(viewports).map(([v, [w]]) => `${v} ${w}`).join(', ')}); add a frame per viewport ("${s} / ${Object.keys(viewports)[0]}") for a pixel comparison`) }
+      frameOut.push({ viewport: a.viewport, width: f.width, height: f.height, src, src2x, background: tree ? fillOf(tree) : null, texts })
+      metaOut.push({ id: f.id, name: f.name, page: f.page ?? null, viewport: a.viewport, locale: a.locale, width: f.width, height: f.height, texts: texts.length, ...(ref ? { url: `https://www.figma.com/design/${ref.key}?node-id=${encodeURIComponent(f.id.replace(/:/g, '-'))}` } : {}) })
+    }
+    if (!frameOut.length) continue
+    // the custom properties the texts use, with their values from the token set
+    const vars = new Map()
+    for (const fr of frameOut) for (const t of fr.texts) for (const n of [t.colorToken, t.sizeToken]) if (n && known.has(n) && typeof known.get(n) !== 'object') vars.set(n, known.get(n))
+    const title = (node && (typeof node.title === 'string' ? node.title : node.title?.[lang(loc)] || node.title?.en)) || s
+    const html = stepHtml({ title, lang: lang(loc), frames: frameOut, viewports, vars, source: local ? `Imported from the folder ${basename(source)}` : `Imported from Figma: ${meta.name || ref.key}` })
+    if (!dryRun) {
+      await mkdir(pageDir, { recursive: true })
+      await writeFile(join(pageDir, 'index.html'), html)
+      await writeFile(join(pageDir, 'figma.json'), JSON.stringify({ source: local ? 'folder' : 'figma', ...(ref ? { file: ref.key, name: meta.name || null } : {}), frames: metaOut }, null, 2) + '\n')
+    }
+    written.push({ step: s, locale: loc || null, frames: metaOut.length, viewports: metaOut.map((m) => m.viewport || 'all'), texts: frameOut.reduce((n, f) => n + f.texts.length, 0) })
+  }
+  if (writeTokens && !dryRun) await writeFile(tokFile, JSON.stringify(tokens.doc, null, 2) + '\n')
+  if (tokens?.doc && !writeTokens && tokensMode !== 'skip') warnings.push(`${TOKENS_FILE} is your own set, so the tokens from Figma were not written (--tokens write replaces it)`)
+  const record = { ...(ref ? { key: ref.key, name: meta.name, version: meta.version, last_modified: meta.last_modified } : { folder: source }), imported_at: new Date().toISOString(), tokens_written: writeTokens ? true : (prev?.tokens_written && !ownSet) || false, steps: written.map((w) => w.step) }
+  if (!dryRun) { await mkdir(join(dir, '.qawalk'), { recursive: true }); await writeFile(RECORD(dir), JSON.stringify(record, null, 2) + '\n'); await writeFile(join(dir, '.qawalk', '.gitignore'), '*\n').catch(() => {}) }
+  return { source: meta.source, file: ref ? { key: ref.key, name: meta.name, version: meta.version } : { folder: source }, written, unmatched: mapping.unmatched, duplicates: mapping.duplicates, missing: mapping.missing, tokens: tokens?.doc ? { from: tokens.from, count: flattenTokens(tokens.doc).length, written: !!writeTokens } : null, warnings }
+}
+
+/** The import summary for the terminal. */
+export function formatImport (r, { dir }) {
+  const lines = [`Imported ${r.written.reduce((n, w) => n + w.frames, 0)} frame(s) from ${r.file.name ? `Figma "${r.file.name}"` : r.file.key ? `Figma ${r.file.key}` : r.file.folder} into ${dir}:`]
+  for (const w of r.written) lines.push(`  ✓ ${w.step}${w.locale ? ` (${w.locale})` : ''}  ${w.viewports.join(', ')}${w.texts ? `  ${w.texts} text layer(s)` : ''}`)
+  if (r.tokens) lines.push(`  tokens: ${r.tokens.count} from ${r.tokens.from}${r.tokens.written ? ` → ${TOKENS_FILE}` : ' (not written)'}`)
+  if (r.missing.length) lines.push(`Steps without a frame: ${r.missing.join(', ')}`)
+  if (r.unmatched.length) lines.push(`Frames that match no step (name them after a step, or map them with --map): ${r.unmatched.slice(0, 15).map((f) => `"${f.name}"${f.reason ? ` (${f.reason})` : ''}`).join(', ')}${r.unmatched.length > 15 ? ', …' : ''}`)
+  if (r.duplicates.length) lines.push(`Left out (a frame of the same step, locale and viewport came first): ${r.duplicates.map((f) => `"${f.name}"`).join(', ')}`)
+  for (const w of r.warnings) lines.push(`! ${w}`)
+  return lines.join('\n')
+}

package/src/lib/git.mjs

@@ -24,7 +24,24 @@ export async function repoSlug (cwd) {
  * Project = config.project, else the repository name. Issue = scenario.issue,
  * else a number found in the scenario id (TASK-1273) or the branch (feat/1273-…).
  */
-export async function projectAndIssue ({ cwd, config, scenario, branch }) {
+/**
+ * A Jira or Linear issue key (WEB-12, eng-42 in Linear's branch names) in the scenario's issue:, the branch or the
+ * pull request title; upper-cased, or null. Branch words that only look like keys (fix-12, release-3) are skipped.
+ */
+export function issueKeyOf ({ scenario = {}, branch = null, title = null } = {}) {
+  const given = scenario.issue?.key
+  if (typeof given === 'string' && /^[A-Z][A-Z0-9_]{0,19}-[1-9][0-9]{0,8}$/.test(given)) return given
+  const NOT = new Set(['FEAT', 'FEATURE', 'FIX', 'BUGFIX', 'HOTFIX', 'CHORE', 'DOCS', 'TEST', 'TESTS', 'REFACTOR', 'RELEASE', 'RELEASES', 'V', 'VERSION', 'ISSUE', 'ISSUES', 'PR', 'MR', 'PULL', 'BUG', 'TASK', 'STORY', 'WIP', 'UPDATE', 'DEPS', 'BUMP', 'BUILD', 'CI', 'PERF', 'STYLE', 'REVERT', 'MAIN', 'DEV', 'STAGING', 'PROD', 'SPRINT', 'WEEK', 'PHASE', 'STEP', 'PART', 'ROUND', 'BATCH', 'DEPENDABOT', 'RENOVATE'])
+  for (const text of [title, branch]) {
+    for (const m of String(text || '').matchAll(/(?:^|[^A-Za-z0-9])([A-Za-z][A-Za-z0-9_]{0,19})-([1-9][0-9]{0,8})(?=$|[^0-9])/g)) {
+      const key = m[1].toUpperCase()
+      if (!NOT.has(key) && /^[A-Z]/.test(key)) return `${key}-${m[2]}`
+    }
+  }
+  return null
+}
+
+export async function projectAndIssue ({ cwd, config, scenario, branch, title = null }) {
   const repo = await repoSlug(cwd)
   // the scenario may sort itself into a project; otherwise the config, then the repository name
   const project = scenario.project
@@ -40,6 +57,9 @@ export async function projectAndIssue ({ cwd, config, scenario, branch }) {
     const url = given?.url || (slug && repo?.host === 'github' ? `https://github.com/${slug}/issues/${num}` : slug && repo?.host === 'gitlab' ? `https://gitlab.com/${slug}/-/issues/${num}` : null)
     issue = { repo: slug, number: num, url, title: given?.title || null }
   }
+  // a Jira or Linear key travels beside a GitHub number: the service links the run to that issue (trackers)
+  const key = issueKeyOf({ scenario, branch, title })
+  if (key) issue = { ...(issue || { repo: null, url: given?.url || null, title: given?.title || null }), key }
   return { project, issue }
 }
 
@@ -63,11 +83,11 @@ export async function gitMeta (cwd) {
   // CI checks out a detached commit: the branch and pull request come from the environment
   const ciBranch = vars.KALOKO_BRANCH || vars.GITHUB_HEAD_REF || vars.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || vars.CI_COMMIT_REF_NAME || null
   if (vars.GITLAB_CI && vars.CI_MERGE_REQUEST_IID) pr = { number: Number(vars.CI_MERGE_REQUEST_IID), url: `${vars.CI_MERGE_REQUEST_PROJECT_URL || vars.CI_PROJECT_URL}/-/merge_requests/${vars.CI_MERGE_REQUEST_IID}`, state: 'open' }
-  const json = pr ? null : await out('gh', ['pr', 'view', ...(vars.KALOKO_PR ? [String(vars.KALOKO_PR)] : []), '--json', 'number,url,state'], cwd)
+  const json = pr ? null : await out('gh', ['pr', 'view', ...(vars.KALOKO_PR ? [String(vars.KALOKO_PR)] : []), '--json', 'number,url,state,title'], cwd)
   if (json) {
     try {
       const p = JSON.parse(json)
-      pr = { number: p.number, url: p.url, state: String(p.state).toLowerCase() }
+      pr = { number: p.number, url: p.url, state: String(p.state).toLowerCase(), ...(p.title ? { title: String(p.title).slice(0, 300) } : {}) }
     } catch {}
   }
   return { branch: branch === 'HEAD' && ciBranch ? ciBranch : branch, commit, sha, message, author, pr }