kaloko 0.19.0 → 0.20.0

package/src/lib/health-findings.mjs

@@ -0,0 +1,116 @@
+// Findings (#156): thousands of open health results folded into a handful a team can act on. A finding is one check
+// on one site in one locale on one step (a stack step is a template): fingerprint check|origin|locale|step. Its
+// severity is the worst of its results, its count the pages it affects; first seen is the earliest first seen of its
+// results. What a person decided (acknowledged, ignored with a reason) and the issue a tracker holds for it are kept
+// per fingerprint by the service (worker/src/health-findings.js); everything else is derived from what the flow keeps
+// open (health_open), so a finding is fixed once none of its results is open any more.
+//
+// Pure: no Node APIs. The shapes are documented in help/reference/health-api.md.
+import { parseHealthKey } from './health-index.mjs'
+import { severityRank, SEVERITIES } from './health-core.mjs'
+
+export const HEALTH_FINDINGS_SCHEMA = 'kaloko.health-findings.v1'
+/** What a person may set; fixed is never set, it is derived. */
+export const FINDING_STATUSES = ['open', 'acknowledged', 'ignored']
+export const FINDING_FILTERS = ['open', 'acknowledged', 'ignored', 'fixed']
+/** Sample pages a finding shows. */
+export const SAMPLE_MAX = 10
+
+/** The site of a result: the origin of its URL ('' when it has none or it is not a URL). */
+export function siteOf (url) {
+  if (!url) return ''
+  try { const u = new URL(String(url)); return /^https?:$/.test(u.protocol) ? u.origin : '' } catch { return '' }
+}
+
+/** check|origin|locale|step: stable while the check, the site, the locale and the step keep their ids. */
+export const findingFingerprint = ({ check, url = null, site = null, locale = '', step }) => [check, site ?? siteOf(url), locale || '', step].join('|')
+
+/** check|origin|locale|step → { check, site, locale, step }; the origin holds no "|". */
+export function parseFingerprint (fp) {
+  const [check, site, locale, ...rest] = String(fp).split('|')
+  return { check, site, locale, step: rest.join('|') }
+}
+
+/**
+ * A short id of a fingerprint for URLs (16 hex digits, FNV-1a 64-bit). The same everywhere: the API, the page, MCP
+ * and an issue's title.
+ */
+export function findingId (fp) {
+  let h = 0xcbf29ce484222325n
+  const prime = 0x100000001b3n
+  for (const b of new TextEncoder().encode(String(fp))) { h ^= BigInt(b); h = (h * prime) & 0xffffffffffffffffn }
+  return h.toString(16).padStart(16, '0')
+}
+
+/**
+ * Findings of a flow from its open results. rows: health_open rows ({ key, severity, url, first_run, first_at, misses
+ * }); checks: { HC…: { text, pack } } of the newest run's index; edit: "step|page" → edit_url; seen: { run, at } of
+ * the newest run (last seen of what it checked). Returns findings, worst first: { id, fingerprint, check, text, pack,
+ * site, locale, step, severity, count, unchecked, samples: [{ page, url, edit_url }], first_seen, last_seen }.
+ */
+export function groupFindings (rows, { checks = {}, edit = {}, seen = null } = {}) {
+  const out = new Map()
+  for (const r of rows || []) {
+    const k = parseHealthKey(r.key)
+    const fp = findingFingerprint({ check: k.check, url: r.url, locale: k.locale, step: k.step })
+    let f = out.get(fp)
+    if (!f) {
+      const c = Object.hasOwn(checks || {}, k.check) ? checks[k.check] : null
+      f = { id: findingId(fp), fingerprint: fp, check: k.check, text: c?.text || null, pack: c?.pack || null, site: siteOf(r.url) || null, locale: k.locale || null, step: k.step, severity: null, count: 0, unchecked: 0, samples: [], first_seen: null, last_seen: null }
+      out.set(fp, f)
+    }
+    f.count++
+    if (severityRank(r.severity) > severityRank(f.severity)) f.severity = r.severity
+    if (r.misses > 0) f.unchecked++
+    else if (seen) f.last_seen = seen
+    if (r.first_at && (!f.first_seen || r.first_at < f.first_seen.at)) f.first_seen = { run: r.first_run, at: r.first_at }
+    if (f.samples.length < SAMPLE_MAX) {
+      const ek = `${k.step}|${k.page}`
+      f.samples.push({ page: k.page || null, url: r.url || null, edit_url: (edit && Object.hasOwn(edit, ek) ? edit[ek] : null) || null })
+    }
+  }
+  return [...out.values()].sort(worstFirst)
+}
+
+export const FINDINGS_SUMMARY_SCHEMA = 'kaloko.health-findings-summary.v1'
+
+/**
+ * The findings of a flow after a recorded run, made once and kept with the run's health files: groupFindings of what
+ * the flow keeps open, plus the findings whose every page the run fixed (`fixed`: the diff's fixed results as rows;
+ * count 0, last seen `previous`). An open finding counts the pages the run fixed in `fixed` too.
+ */
+export function summarizeFindings (rows, { checks = {}, edit = {}, seen = null, fixed = [], previous = null } = {}) {
+  const list = groupFindings(rows, { checks, edit, seen })
+  const at = new Map(list.map((f) => [f.id, f]))
+  for (const g of groupFindings(fixed, { checks, edit })) {
+    const f = at.get(g.id)
+    if (f) { f.fixed = g.count; continue }
+    list.push({ ...g, count: 0, fixed: g.count, unchecked: 0, last_seen: previous })
+  }
+  for (const f of list) f.fixed ||= 0
+  return { schema: FINDINGS_SUMMARY_SCHEMA, run: seen?.run || null, started_at: seen?.at || null, findings: list }
+}
+
+/** An http(s) URL as given, or null: what may become a link in a page or an issue. */
+export function httpUrl (u) {
+  if (!u) return null
+  try { const x = new URL(String(u)); return /^https?:$/.test(x.protocol) ? x.href : null } catch { return null }
+}
+
+/** Errors before warnings before unsure, then the most pages, then by fingerprint (stable). */
+export const worstFirst = (a, b) => severityRank(b.severity) - severityRank(a.severity) || b.count - a.count || (a.fingerprint < b.fingerprint ? -1 : 1)
+
+/**
+ * The status of a finding: fixed when none of its results is open (count 0), else what a person set (acknowledged,
+ * ignored), else open.
+ */
+export const statusOf = (count, stored) => count > 0 ? (FINDING_STATUSES.includes(stored) ? stored : 'open') : 'fixed'
+
+/** At least this severity: error ≥ warning ≥ info. */
+export const atLeastSeverity = (severity, min) => SEVERITIES.includes(min) && severityRank(severity) >= severityRank(min)
+
+/**
+ * A change of the number of affected pages worth telling the tracker about: by at least 3 pages and a quarter of what
+ * the issue last said.
+ */
+export const countChanged = (before, now) => before != null && Math.abs(now - before) >= Math.max(3, Math.ceil(before * 0.25))

package/src/lib/health-index.mjs

@@ -20,6 +20,8 @@ export const VERDICTS = ['pass', 'fail', 'needs_review', 'not_evaluated']
 export const TOP_KEEP = 20
 /** Open results a run keeps (worst first); a site with more is cut and says so (`truncated`). */
 export const OPEN_MAX = 50000
+/** Edit links an index keeps (pages of the open list, worst first): a bounded index for any catalogue. */
+export const EDIT_MAX = 5000
 
 const blank = () => ({ pass: 0, fail: 0, needs_review: 0, not_evaluated: 0 })
 const cut = (s, n = 200) => s == null ? null : String(s).slice(0, n)
@@ -38,13 +40,16 @@ const firstUrl = (vps) => { for (const c of Object.values(vps || {})) if (c?.url
  * The index of a run manifest. `stacks` maps a stack step's id to its items index (steps/<node>/items.json); a stack
  * step without one counts as one page. Returns { schema, checks: { HC…: { text, pack, level } }, totals, groups:
  * [{ locale, step, check, counts, top: [{ page, path, url, verdict, evidence }] }], open: [[key, severity, url]],
- * open_total, truncated, passed }. passed says which checks passed on which page: { "step|locale": { sigs: ["HC103,HC112",
- * …], pages: { <page>: <index into sigs> } } }; only a result that passed counts as fixed later (passedIn).
+ * open_total, truncated, passed, edit }. passed says which checks passed on which page: { "step|locale": { sigs:
+ * ["HC103,HC112", …], pages: { <page>: <index into sigs> } } }; only a result that passed counts as fixed later
+ * (passedIn). edit maps "step|page" to the edit_url of a stack page with open results (findings link it).
  */
 export function buildHealthIndex (manifest, stacks = {}) {
   const checks = Object.create(null); const groups = new Map(); const open = []; const pages = new Set(); const ok = new Map()
+  // where a page with open results is edited (a stack item's edit_url): "step|page" → URL, kept below for the open list only
+  const edits = new Map()
   const totals = { results: 0, ...blank() }
-  const add = (step, locale, page, path, url, check, verdict, evidence) => {
+  const add = (step, locale, page, path, url, check, verdict, evidence, editUrl = null) => {
     if (!VERDICTS.includes(verdict)) return
     pages.add(`${step}|${page}`)
     const gk = `${locale}\u0000${step}\u0000${check}`
@@ -57,6 +62,7 @@ export function buildHealthIndex (manifest, stacks = {}) {
     const list = verdict === 'fail' ? g.fails : g.unsure
     if (list.length < TOP_KEEP) list.push({ page, ...(path ? { path } : {}), url: url || null, verdict, ...(evidence ? { evidence: cut(evidence) } : {}) })
     open.push([healthKey(step, locale, check, page), severity, url || null])
+    if (editUrl && typeof editUrl === 'string' && /^https?:\/\//i.test(editUrl)) edits.set(`${step}|${page}`, cut(editUrl, 500))
   }
   for (const n of manifest?.nodes || []) {
     if (n.kind === 'decision') continue
@@ -79,7 +85,7 @@ export function buildHealthIndex (manifest, stacks = {}) {
             if (!was || worst([was.v, x[0]]) !== was.v) per.set(k, { locale, id, v: x[0], e: x[1] })
           }
         }
-        for (const { locale, id, v, e } of per.values()) add(n.id, locale, String(it.id), it.path || null, it.url || firstUrl(it.captures?.[locale]), id, v, e)
+        for (const { locale, id, v, e } of per.values()) add(n.id, locale, String(it.id), it.path || null, it.url || firstUrl(it.captures?.[locale]), id, v, e, it.edit_url)
       }
       continue
     }
@@ -106,10 +112,19 @@ export function buildHealthIndex (manifest, stacks = {}) {
     if (i < 0) { i = w.sigs.length; w.sigs.push(sig) }
     w.pages[page] = i
   }
+  // edit links of the pages in the kept open list only, at most EDIT_MAX of them (worst first, like the list)
+  const kept = open.slice(0, OPEN_MAX)
+  const edit = Object.create(null); let links = 0
+  for (const [key] of kept) {
+    if (links >= EDIT_MAX) break
+    const { step, page } = parseHealthKey(key)
+    const k = `${step}|${page}`
+    if (edits.has(k) && !Object.hasOwn(edit, k)) { edit[k] = edits.get(k); links++ }
+  }
   return {
     schema: HEALTH_INDEX_SCHEMA, checks, totals: { ...totals, pages: pages.size },
     groups: [...groups.values()].map(({ fails, unsure, ...g }) => ({ ...g, top: [...fails, ...unsure].slice(0, TOP_KEEP) })),
-    open: open.slice(0, OPEN_MAX), open_total: open.length, truncated: open.length > OPEN_MAX, passed
+    open: kept, open_total: open.length, truncated: open.length > OPEN_MAX, passed, edit
   }
 }
 

package/src/lib/integrations-cli.mjs

@@ -80,7 +80,10 @@ export async function hostedAuth ({ env, account = null, root, config, vars = pr
 const atHour = (v, d = 5) => { const n = Number(String(v ?? '').split(':')[0]); return Number.isInteger(n) && n >= 0 && n <= 23 ? n : d }
 const weekdayOf = (v, d = 1) => WEEKDAYS[String(v || '').slice(0, 3).toLowerCase()] || (Number(v) >= 1 && Number(v) <= 7 ? Number(v) : d)
 const when = (s) => s.every === 'manual' ? 'on demand' : `${s.every === 'week' ? `weekly on ${Object.keys(WEEKDAYS)[s.weekday - 1]}` : 'daily'} at ${String(s.at_hour).padStart(2, '0')}:00 UTC`
-const scheduleLine = (s) => `${s.id}  ${s.scenario_id} on ${s.environment} (${s.base_url}) · ${when(s)}${s.enabled ? '' : ' · paused'}${s.pages_per_run ? ` · ${s.pages_per_run} pages` : ''}\n  next ${s.enabled && s.next_run_at ? s.next_run_at.slice(0, 16).replace('T', ' ') : '—'} · last ${s.last_run_at ? `${s.last_run_at.slice(0, 16).replace('T', ' ')} ${s.last_status}${s.last_run_id ? ` ${s.last_run_id}` : ''}` : '—'}${s.last_error ? `\n  ! ${s.last_error}` : ''}`
+/** The environment's base URL as the service takes it: one address, or one per locale (the same rule as walk: default is the fallback). */
+export const hostedBase = (env, baseUrl) => typeof env.base_url === 'string' ? baseUrl(env) : Object.fromEntries(Object.keys(env.base_url).map((k) => [k, baseUrl(env, k)]))
+const baseLine = (b) => typeof b === 'string' ? b : Object.entries(b || {}).map(([k, v]) => `${k} ${v}`).join(', ')
+const scheduleLine = (s) => `${s.id}  ${s.scenario_id} on ${s.environment} (${baseLine(s.base_url)}) · ${when(s)}${s.enabled ? '' : ' · paused'}${s.pages_per_run ? ` · ${s.pages_per_run} pages` : ''}${s.stack_steps?.length ? ` + stacks ${s.stack_steps.join(', ')}` : ''}${s.walking ? ` · reading stack pages ${s.walking.done}/${s.walking.total}` : ''}${s.last_health ? ` · health ${s.last_health.new} new, ${s.last_health.fixed} fixed` : ''}\n  next ${s.enabled && s.next_run_at ? s.next_run_at.slice(0, 16).replace('T', ' ') : '—'} · last ${s.last_run_at ? `${s.last_run_at.slice(0, 16).replace('T', ' ')} ${s.last_status}${s.last_run_id ? ` ${s.last_run_id}` : ''}` : '—'}${s.last_error ? `\n  ! ${s.last_error}` : ''}`
 
 /** The GitHub Actions workflow that walks a scenario on a schedule with the full CLI and shares the run. */
 export function githubScheduleWorkflow ({ scenario, scenarioId, env, every = 'day', at_hour = 5, weekday = 1, pm = 'npm', dependency = true, version = 'latest', node = 22, browsers = ['chromium'], secrets = [] }) {
@@ -188,19 +191,18 @@ export async function scheduleCmd ({ args, config, root, say, deps }) {
     const env = deps.environment(config, envName)
     if (scenario.environments && !scenario.environments.includes(envName)) throw new UserError(`${relative(root, file)} allows environments [${scenario.environments.join(', ')}], not ${envName}.`)
     if (env.kind === 'design' || env.base_url == null) throw new UserError(`${envName} has no web address; hosted runs open web pages.`)
-    if (typeof env.base_url !== 'string') throw new UserError(`${envName} has a base_url per locale; hosted runs take one address. Walk it in CI: kaloko schedule export github.`)
     const every = ['day', 'week', 'manual'].includes(args.every) ? args.every : 'day'
     const { project } = await deps.projectAndIssue({ cwd: root, config, scenario, branch: null })
     // health alerts (theme K): off, error (the service's default) or warning; unset keeps what the schedule has
     if (args['health-alert'] != null && !['off', 'error', 'warning'].includes(args['health-alert'])) throw new UsageError(`--health-alert takes off, error or warning, not ${args['health-alert']}.`)
-    const body = { scenario: await hostedScenario(scenario, file), environment: envName, base_url: deps.baseUrl(env), every, at_hour: atHour(args.at), weekday: weekdayOf(args.weekday), project: project?.slug || null, auth: await hostedAuth({ env, account: typeof args.account === 'string' ? args.account : null, root, config }), ...(typeof args['health-alert'] === 'string' ? { health_alert: args['health-alert'] } : {}) }
+    const body = { scenario: await hostedScenario(scenario, file), environment: envName, base_url: hostedBase(env, deps.baseUrl), every, at_hour: atHour(args.at), weekday: weekdayOf(args.weekday), project: project?.slug || null, auth: await hostedAuth({ env, account: typeof args.account === 'string' ? args.account : null, root, config }), ...(typeof args['health-alert'] === 'string' ? { health_alert: args['health-alert'] } : {}) }
     let s
     try { s = await client().request('POST', `/orgs/${org}/schedules`, body) } catch (e) {
       if (/HTTP 404/.test(e.message)) throw new UserError(`${e.message}\nWalk it on a schedule in CI instead: kaloko schedule export github --scenario ${relative(root, file)} --env ${envName}`)
       throw e
     }
     if (args.json) { say(JSON.stringify(s, null, 2)); return s }
-    say(`✓ ${s.created ? 'Scheduled' : 'Updated'} ${s.scenario_id} on ${envName} ${when(s)}: ${s.pages_per_run} pages per run${s.auth !== 'none' ? ` (${s.auth === 'basic' ? 'HTTP Basic' : 'saved session'})` : ''}. Runs are shared as you and land in the inbox.`)
+    say(`✓ ${s.created ? 'Scheduled' : 'Updated'} ${s.scenario_id} on ${envName} ${when(s)}: ${s.pages_per_run} pages per run${s.stack_steps?.length ? ` and the pages of ${s.stack_steps.join(', ')} (read without screenshots, each page counts)` : ''}${s.auth !== 'none' ? ` (${s.auth === 'basic' ? 'HTTP Basic' : 'saved session'})` : ''}. Runs are shared as you and land in the inbox.`)
     for (const k of s.skipped || []) say(`  - ${k.id}: not walked (${k.reason})`)
     if ((s.skipped || []).length) say('  Steps that click or type need the full walk: kaloko schedule export github')
     return s

package/src/lib/manifest-core.mjs

@@ -5,6 +5,8 @@
 import { packHelp } from './pack-help.mjs'
 import { isHealthCriterion, levelOf, healthSummary } from './health-core.mjs'
 import { stackChecks } from './seo-core.mjs'
+import { variantCheck, VARIANT_LIST_MAX } from './variants-core.mjs'
+import { trafficKey, mergeTraffic, trafficView } from './traffic-core.mjs'
 
 const RANK = { fail: 4, needs_review: 3, not_evaluated: 2, pass: 1, not_reached: 0 }
 export const worst = (list) => list.reduce((a, b) => (RANK[b] > RANK[a] ? b : a), 'not_reached')
@@ -247,7 +249,7 @@ export const stackFieldsOf = (node) => (node.fields?.length ? node.fields.map((f
  * captures: [{ item, locale, viewport, cap (capture record), ev (valid evaluation or null), files: { png, thumb?, html?, eval } }]
  * in walk order. Returns { node, index, file } where `file` is the index's path in the run.
  */
-export function assembleStack ({ node, base, environment = null, captures, attachments = [], rotation = null }) {
+export function assembleStack ({ node, base, environment = null, captures, attachments = [], rotation = null, traffic = null, variants = null }) {
   const fields = stackFieldsOf(node).map((f) => ({ id: f.id, label: f.label || f.id }))
   const crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null, ...(c.refs?.length ? { refs: c.refs } : {}), ...(c.from ? { from: c.from } : {}), ...(c.pack && c.acceptance ? { acceptance: true } : {}), ...(isHealthCriterion(c) ? { health: true, level: levelOf(c.id), check: c.check } : {}), ...(appliesOnEnv(c, environment) ? {} : { not_applicable: 'environment' }) }))
   // criteria limited to other environments do not decide the status of a page, and neither do health checks
@@ -256,17 +258,23 @@ export function assembleStack ({ node, base, environment = null, captures, attac
   for (const c of captures) {
     const { cap, ev } = c
     let it = byItem.get(c.item)
-    if (!it) { it = { id: c.item, path: cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size, ...(cap.item?.edit_url ? { edit_url: cap.item.edit_url } : {}), ...(cap.item?.content_ref ? { content_ref: cap.item.content_ref } : {}), ...(cap.item && 'last_checked' in cap.item ? { last_checked: cap.item.last_checked } : {}) }; byItem.set(c.item, it) }
+    // a locale variant (#176) carries the source page's path: the item is the source page, whichever locale came first
+    const variant = !!cap.item?.source_path
+    if (!it) { it = { id: c.item, path: cap.item?.source_path || cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size, variant, ...(cap.item?.edit_url ? { edit_url: cap.item.edit_url } : {}), ...(cap.item?.content_ref ? { content_ref: cap.item.content_ref } : {}), ...(cap.item && 'last_checked' in cap.item ? { last_checked: cap.item.last_checked } : {}) }; byItem.set(c.item, it) }
+    else if (it.variant && !variant && cap.item) {
+      // the source page's own capture names the item: its address, title and index fields
+      Object.assign(it, { url: cap.url, title: cap.item.title || cap.fields?.title || cap.metadata?.title || it.title, fields: cap.fields || it.fields, variant: false, ...(cap.item.edit_url ? { edit_url: cap.item.edit_url } : {}), ...(cap.item.content_ref ? { content_ref: cap.item.content_ref } : {}) })
+    }
     // the structured data types of the page (JSON-LD and microdata), from its first capture that read them
     if (cap.structured_data && !it.structured_data) it.structured_data = { types: cap.structured_data.types || [], invalid: cap.structured_data.invalid || 0 }
-    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: c.files.png, thumb: c.files.thumb || null, html: c.files.html || null, url: cap.url, size: cap.size ? (Array.isArray(cap.size) ? cap.size : [cap.size.width, cap.size.height]) : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), ...(c.live ? { live: c.live } : {}), ...Object.fromEntries(DIM_FIELDS.filter((k) => cap[k]).map((k) => [k, cap[k]])), eval: ev ? c.files.eval : null }
+    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: c.files.png, thumb: c.files.thumb || null, html: c.files.html || null, url: cap.url, ...(cap.item?.path && cap.item.path !== it.path ? { path: cap.item.path } : {}), size: cap.size ? (Array.isArray(cap.size) ? cap.size : [cap.size.width, cap.size.height]) : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), ...(c.live ? { live: c.live } : {}), ...Object.fromEntries(DIM_FIELDS.filter((k) => cap[k]).map((k) => [k, cap[k]])), eval: ev ? c.files.eval : null }
     // a criterion limited to other step states (#46) does not decide this capture
     // nor does an error-page check on a page that is no error page (errors pack HC601, HC605)
     for (const r of ev?.criteria || []) if (r.not_applicable === 'error_page') naPage.add(r.id)
     it.results[`${c.locale}|${c.viewport}`] = ev ? Object.fromEntries((ev.criteria || []).filter((r) => r.not_applicable !== 'state' && r.not_applicable !== 'error_page').map((r) => [r.id, [r.verdict, r.evidence ? String(r.evidence).slice(0, 200) : null, r.score ?? null]])) : Object.fromEntries(crit.filter((x) => x.type !== 'semantic').map((x) => [x.id, ['not_evaluated', null, null]]))
     if (!ev) it.stale = true
   }
-  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, ...it }) => {
+  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, variant: _v, ...it }) => {
     const per = Object.values(it.results)
     const verdictOf = (id) => worst(per.map((r) => r[id]?.[0]).filter(Boolean))
     const verdicts = crit.filter((c) => live.has(c.id)).map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
@@ -291,15 +299,20 @@ export function assembleStack ({ node, base, environment = null, captures, attac
   const criteria = judged.filter((c) => !c.health)
   const src = node.items || {}
   const source = ['urls', 'file', 'sitemap', 'robots', 'crawl', 'script'].find((k) => src[k]) || null
+  // traffic data (#157): Search Console and GA4 numbers per page, joined by URL (traffic-core.mjs)
+  const joined = traffic?.table ? joinTraffic(items, traffic.table) : null
   // cross-page checks (#151): a stack with the seo pack compares its pages with each other; advisory like the pack
-  const cross = hasSeoPack(node) ? stackChecks({ items, source }) : []
+  // locale variants (#176): pages without their own version in a walked locale, marked on the page and as HC1005
+  const vars = variantsOf(variants, items)
+  const varCheck = vars ? variantCheck(vars.locales) : null
+  const cross = [...(hasSeoPack(node) ? stackChecks({ items, source, traffic: joined?.matched ? traffic : null }) : []), ...(varCheck ? [varCheck] : [])]
   for (const x of cross) { const hit = new Set(x.items); for (const it of items) if (hit.has(it.id)) (it.cross_fails ||= []).push(x.id) }
   const health = [...judged.filter((c) => c.health).map(({ health: _h, ...c }) => c), ...cross.map(crossHealth)]
   const semanticSample = node.items?.semantic_sample ?? STACK_SEMANTIC_SAMPLE
   const file = `steps/${node.id}/items.json`
   // a rotating sample (items.rotate): per locale the window of this run and how much of the list runs have covered
   const rot = rotation && Object.keys(rotation).length ? rotation : null
-  const index = { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, ...(structured ? { structured_data: structured } : {}), ...(rot ? { rotation: rot } : {}), ...(cross.length ? { cross_page: cross.map(({ items: _i, ...x }) => x) } : {}), items }
+  const index = { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, ...(structured ? { structured_data: structured } : {}), ...(rot ? { rotation: rot } : {}), ...(vars ? { variants: vars.index } : {}), ...(cross.length ? { cross_page: cross.map(({ items: _i, ...x }) => x) } : {}), items }
   const thumbOf = (it) => { const c = Object.values(it.captures)[0]; const v = c && Object.values(c)[0]; return v ? v.thumb || v.png : null }
   const sample = [...items.filter((it) => it.status === 'fail'), ...items.filter((it) => it.status !== 'fail')].slice(0, 4).map((it) => ({ id: it.id, title: it.title, path: it.path, status: it.status, thumb: thumbOf(it) }))
   const status = !items.length ? 'skip' : summary.fail ? 'fail' : summary.partial || summary.skip ? 'partial' : 'pass'
@@ -309,14 +322,76 @@ export function assembleStack ({ node, base, environment = null, captures, attac
     ...base, status, by_locale, captures: {}, criteria, ...(health.length ? { health } : {}), semantic: {}, metadata: {}, session: node.session || null,
     execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : { strategy: 'playwright', instructions: 'Open every page of the stack and capture it.' },
     attachments: stepAttachments(attachments, { node: node.id }),
-    stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source, stale: items.filter((it) => it.stale).length, ...(structured ? { structured_data: structured } : {}), ...(rot ? { rotation: rot } : {}), ...(cross.length ? { cross_page: cross.map((x) => ({ id: x.id, verdict: x.verdict, pages: x.pages, affected: x.affected })) } : {}) }
+    stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source, stale: items.filter((it) => it.stale).length, ...(structured ? { structured_data: structured } : {}), ...(rot ? { rotation: rot } : {}), ...(vars ? { variants: vars.summary } : {}), ...(cross.length ? { cross_page: cross.map((x) => ({ id: x.id, verdict: x.verdict, pages: x.pages, affected: x.affected })) } : {}), ...(joined ? { traffic: trafficSummary(items, joined) } : {}) }
   }
   return { node: out, index, file }
 }
+/**
+ * Locale variants of a stack (#176) from the walk's `variants.<locale>.json` ({ [locale]: { mode, source_locale,
+ * pages, missing, shared, source? } }): marks each page with the locales it has no version in (`missing`, only where
+ * no capture of that locale exists, so a later walk that found one wins, or where the capture answered 4xx/5xx) and
+ * returns { locales (for HC1005), index
+ * (items.json), summary (the node) }, or null without variants.
+ */
+function variantsOf (variants, items) {
+  const all = Object.entries(variants || {}).filter(([, v]) => v?.mode === 'hreflang')
+  if (!all.length) return null
+  const byId = new Map(items.map((it) => [it.id, it]))
+  const sourceLocale = all.find(([, v]) => v.source)?.[1].source_locale || all[0][1].source_locale
+  const locales = {}
+  for (const [l, v] of all) {
+    if (v.source || l === v.source_locale) { locales[l] = { ...v, source: true, missing: [], shared: [] }; continue }
+    const missing = (v.missing || []).filter((m) => !byId.get(m.id)?.captures?.[l])
+    // a translation the hreflang names but that answers 4xx/5xx is walked, and missing all the same
+    for (const it of items) {
+      const c = Object.values(it.captures?.[l] || {}).find((x) => x?.http_status >= 400)
+      if (c) missing.push({ id: it.id, path: it.path, url: c.url, variant: c.path || null, reason: `error ${c.http_status}` })
+    }
+    for (const m of missing) { const it = byId.get(m.id); if (it && !(it.missing ||= []).includes(l)) it.missing.push(l) }
+    locales[l] = { ...v, missing, shared: v.shared || [] }
+  }
+  const cap = (list) => list.slice(0, VARIANT_LIST_MAX)
+  return {
+    locales,
+    index: { mode: 'hreflang', source_locale: sourceLocale, locales: Object.fromEntries(Object.entries(locales).map(([l, v]) => [l, v.source ? { source: true, pages: v.pages || 0 } : { pages: v.pages || 0, missing: cap(v.missing), shared: cap(v.shared), ...(v.missing.length > VARIANT_LIST_MAX ? { more_missing: v.missing.length - VARIANT_LIST_MAX } : {}) }])) },
+    summary: { mode: 'hreflang', source_locale: sourceLocale, missing: Object.fromEntries(Object.entries(locales).filter(([, v]) => !v.source).map(([l, v]) => [l, v.missing.length])), shared: Object.fromEntries(Object.entries(locales).filter(([, v]) => !v.source && v.shared.length).map(([l, v]) => [l, v.shared.length])) }
+  }
+}
+/**
+ * Puts the traffic of each page on it (it.traffic: clicks, impressions, ctr, position, sessions, conversions), looked
+ * up by every address its captures ended on, one per address, so the language versions of a page add up; the
+ * address asked for only when none of those is found. Rows that are paths without a host (GA4) join only when the
+ * stack walks one host. Returns { matched, note }.
+ */
+export function joinTraffic (items, table) {
+  const hosts = new Set()
+  for (const it of items) for (const vps of Object.values(it.captures || {})) for (const c of Object.values(vps || {})) { try { hosts.add(new URL(c?.url || it.url).host) } catch {} }
+  const paths = hosts.size <= 1
+  let matched = 0
+  for (const it of items) {
+    const hits = new Map()
+    for (const vps of Object.values(it.captures || {})) {
+      for (const c of Object.values(vps || {})) {
+        const k = c?.url ? trafficKey(c.url) : null
+        if (!k || hits.has(k)) continue
+        const t = table.of(c.url, { paths })
+        if (t) hits.set(k, t)
+      }
+    }
+    if (!hits.size && it.url) { const t = table.of(it.url, { paths }); if (t) hits.set(trafficKey(it.url), t) }
+    if (hits.size) { it.traffic = trafficView(mergeTraffic([...hits.values()])); matched++ }
+  }
+  return { matched, note: !paths && table.bare ? `${table.bare} GA4 path(s) without a host not joined: the stack walks ${hosts.size} hosts` : null }
+}
+/** The traffic of a stack in its node: pages with data and their clicks, impressions and sessions added up. */
+const trafficSummary = (items, { matched, note }) => {
+  const sum = (k) => items.reduce((s, it) => s + (it.traffic?.[k] || 0), 0)
+  return { pages: matched, of: items.length, clicks: sum('clicks'), impressions: sum('impressions'), sessions: sum('sessions'), ...(note ? { note } : {}) }
+}
 const hasSeoPack = (node) => (node.packs || []).includes('seo') || (node.criteria || []).some((c) => c.pack === 'seo')
 /** A cross-page check as a health entry of the stack node: counts of pages, evidence and the first addresses. */
 const crossHealth = (x) => ({
-  id: x.id, text: x.text, type: 'deterministic', pack: 'seo', level: x.level, verdict: x.verdict, by_locale: {}, cross_page: true,
+  id: x.id, text: x.text, type: 'deterministic', pack: x.pack || 'seo', level: x.level, verdict: x.verdict, by_locale: {}, cross_page: true,
   counts: x.verdict === 'fail' ? { pass: Math.max(0, x.pages - x.affected), fail: x.affected } : { pass: x.pages }, evidence: x.evidence,
   ...(x.groups.length ? { urls: x.groups.flatMap((g) => g.urls).slice(0, 20) } : {}),
   ...(packHelp(x.id) ? { help: { en: packHelp(x.id, 'en'), cs: packHelp(x.id, 'cs') } } : {})

package/src/lib/pack-help.mjs

@@ -24,6 +24,7 @@ export const PACK_HELP = {
   HC124: { cs: 'Každá stránka je svou kanonickou adresou', why: ['A canonical that points elsewhere asks search engines to drop the page; pointing at an error or noindex page drops both.', 'Kanonická adresa jinam žádá vyhledávač, aby stránku vynechal; když míří na chybovou stránku nebo noindex, vypadnou obě.'], fix: ['Point the canonical at the page itself, or take the copies out of the sitemap and the stack. The evidence shows where the clusters point.', 'Nastavte kanonickou adresu na stránku samotnou, nebo kopie vyřaďte ze sitemapy i ze stacku. Kam shluky míří, ukazuje důkaz.'] },
   HC125: { cs: 'Jazykové verze na sebe přes hreflang odkazují navzájem', why: ['Search engines ignore hreflang that is not confirmed from the other side, so the wrong language shows up in results.', 'Vyhledávač hreflang bez potvrzení z druhé strany ignoruje a ve výsledcích se ukáže špatný jazyk.'], fix: ['Give every language version the same complete set of alternates, including itself and ideally x-default, all pointing to addresses that answer 200.', 'Dejte všem jazykovým verzím stejnou úplnou sadu alternativ včetně sebe sama a ideálně x-default; všechny ať vedou na adresy, které odpovídají 200.'] },
   HC126: { cs: 'Stránky ze sitemapy odpovídají 200, nepřesměrují a jdou indexovat', why: ['A sitemap is the list of pages you want found; redirects, errors and noindex in it waste the crawl and erode trust in the whole list.', 'Sitemapa je seznam stránek, které chcete nechat najít; přesměrování, chyby a noindex v ní plýtvají procházením a podkopávají důvěru v celý seznam.'], fix: ['List the final addresses only: drop deleted pages, replace redirected ones with their target, and leave out pages with noindex.', 'Uvádějte jen cílové adresy: smazané stránky vyřaďte, přesměrované nahraďte cílem a stránky s noindex vynechte.'] },
+  HC127: { cs: 'Často zobrazované stránky nemají výrazně nižší míru prokliku', why: ['Searchers see the page but pick another result: the title and description in the results do not promise what they are looking for.', 'Lidé stránku ve výsledcích vidí, ale kliknou jinam: titulek a popis ve výsledcích neslibují to, co hledají.'], fix: ['Rewrite the title and meta description of the listed pages so they answer the query people see them for (Search Console shows the queries). Compare the CTR again after a few weeks.', 'Přepište titulek a meta popis uvedených stránek tak, aby odpovídaly dotazům, u kterých se zobrazují (dotazy ukáže Search Console). Míru prokliku porovnejte znovu za pár týdnů.'] },
   HC201: { cs: 'Účel stránky je jasný hned na první obrazovce', why: ['Visitors decide within seconds whether they are in the right place.', 'Návštěvník se během pár vteřin rozhodne, jestli je na správném místě.'], fix: ['Make the heading and first sentence say what the page is for and for whom.', 'Ať nadpis a první věta řeknou, k čemu stránka je a pro koho.'] },
   HC202: { cs: 'Jedna jasná hlavní akce', why: ['Several equally loud buttons make people hesitate; none leaves them without a next step.', 'Několik stejně výrazných tlačítek lidi zdrží; žádné je nechá bez dalšího kroku.'], fix: ['Give one action the primary style; make the others secondary or links.', 'Jedné akci dejte hlavní styl, ostatní udělejte vedlejší nebo jako odkazy.'] },
   HC203: { cs: 'Formulářová pole mají viditelný popisek', why: ['A placeholder disappears as people type; they forget what the field was.', 'Placeholder při psaní zmizí a lidé zapomenou, co do pole patří.'], fix: ['Add a <label for="…"> (or aria-label) to every visible input.', 'Ke každému viditelnému poli doplňte <label for="…"> (nebo aria-label).'] },
@@ -74,6 +75,7 @@ export const PACK_HELP = {
   HC1002: { cs: 'Vlastní hreflang stránky odpovídá jazyku, kódy jsou platné a sedí k adresám', why: ['A wrong own hreflang or a code such as en_UK makes search engines skip the whole set of language versions.', 'Špatný vlastní hreflang nebo kód typu en_UK způsobí, že vyhledávač celou sadu jazykových verzí přeskočí.'], fix: ['Use language-REGION codes with a hyphen (en-GB, pt-BR), name the page itself with its own language, and keep each code on the address of that language.', 'Používejte kódy jazyk-REGION se spojovníkem (en-GB, pt-BR), stránku samotnou označte jejím jazykem a každý kód dejte k adrese téhož jazyka.'] },
   HC1003: { cs: 'Text je v jazyce procházené verze', why: ['An untranslated page in a language version loses its visitors and looks like duplicate content of the source language.', 'Nepřeložená stránka v jazykové verzi ztratí návštěvníky a pro vyhledávač vypadá jako duplicita zdrojového jazyka.'], fix: ['Translate the page, or keep it out of this language version and its sitemap until it is translated. Kaloko counts common words, so short pages and close languages (Danish, Norwegian, Swedish) are not judged.', 'Stránku přeložte, nebo ji do překladu z této jazykové verze i sitemapy vyřaďte. Kaloko počítá běžná slova, takže krátké stránky a blízké jazyky (dánština, norština, švédština) nehodnotí.'] },
   HC1004: { cs: 'Ceny používají desetinný oddělovač daného jazyka', why: ['12.50 € reads oddly to a German or Czech customer and 12,50 $ to an American; it looks like the shop was not made for them.', 'Zápis 12.50 € působí na německého nebo českého zákazníka divně a 12,50 $ na amerického; vypadá to, že obchod nebyl dělaný pro ně.'], fix: ['Format prices with the locale (Intl.NumberFormat or your framework\'s number helper), not with a fixed pattern.', 'Ceny formátujte podle jazyka (Intl.NumberFormat nebo pomocník vašeho frameworku), ne pevným vzorem.'] },
+  HC1005: { cs: 'Každá stránka má v každém jazyce vlastní verzi (hreflang)', why: ['A page without its translation sends visitors of that language to the wrong one, and search shows them whatever is left; several pages pointing to one version usually mean a fallback to a listing or the home page.', 'Stránka bez překladu pošle návštěvníky toho jazyka jinam a vyhledávač jim ukáže, co zbude; když víc stránek míří na jednu verzi, jde obvykle o náhradu výpisem nebo úvodní stránkou.'], fix: ['Translate the page, or add <link rel="alternate" hreflang="…"> to its existing translation; a translation that answers an error needs fixing or a new address in the hreflang. The evidence names the locales and the reason; kaloko export findings lists every page.', 'Stránku přeložte, nebo jí doplňte <link rel="alternate" hreflang="…"> na překlad, který už existuje; překlad, který odpovídá chybou, opravte nebo v hreflang uveďte novou adresu. Jazyky a důvod jsou v důkazu, všechny stránky vypíše kaloko export findings.'] },
   HC1101: { cs: 'robots.txt odpovídá 200 a každý řádek dává smysl', why: ['Crawlers skip lines they do not understand, so a typo such as "Disalow" silently opens or closes part of the site; a server error stops crawling altogether.', 'Roboti přeskočí řádky, kterým nerozumí, takže překlep jako „Disalow“ potichu otevře nebo zavře část webu; chyba serveru procházení úplně zastaví.'], fix: ['Serve /robots.txt as text/plain with User-agent, Allow, Disallow and Sitemap lines only, and fix the lines the evidence names.', 'Servírujte /robots.txt jako text/plain jen s řádky User-agent, Allow, Disallow a Sitemap a opravte řádky z důkazu.'] },
   HC1102: { cs: 'robots.txt neblokuje procházené úvodní stránky', why: ['A Disallow that covers the home page or a language root removes the site from search, often after a staging setting reached production.', 'Disallow, který zakryje úvodní stránku nebo kořen jazykové verze, vyřadí web z vyhledávání; často jde o nastavení ze stagingu, které se dostalo na produkci.'], fix: ['Remove or narrow the rule the evidence names; list paths that must stay open under health.site.paths.', 'Odstraňte nebo zužte pravidlo z důkazu; cesty, které musí zůstat otevřené, uveďte v health.site.paths.'] },
   HC1103: { cs: 'robots.txt neblokuje AI roboty', why: ['GPTBot, ClaudeBot, PerplexityBot and others read robots.txt; blocked, the site does not appear in AI answers and assistants cannot open its pages for users.', 'GPTBot, ClaudeBot, PerplexityBot a další se řídí robots.txt; když jsou zablokovaní, web se v odpovědích AI neobjeví a asistenti jeho stránky uživatelům neotevřou.'], fix: ['If blocking was not decided on purpose, remove the Disallow for those user agents. If it was, set health.site.ai_crawlers: false.', 'Pokud blokování nebylo záměr, odstraňte Disallow pro tyto roboty. Pokud bylo, nastavte health.site.ai_crawlers: false.'] },

package/src/lib/packs.mjs

@@ -12,7 +12,7 @@ const det = (assert, extra = {}) => ({ type: 'deterministic', assert, ...extra }
 export const PACKS = {
   seo: {
     base: 100,
-    title: 'SEO basics: title, description, canonical, hreflang, Open Graph, robots, heading, viewport, structured data (JSON-LD); on a stack step also across its pages (duplicates, canonicals, hreflang pairs, sitemap pages)',
+    title: 'SEO basics: title, description, canonical, hreflang, Open Graph, robots, heading, viewport, structured data (JSON-LD); on a stack step also across its pages (duplicates, canonicals, hreflang pairs, sitemap pages; with traffic data, high impressions and low CTR)',
     criteria: ({ locales }) => [
       { id: 'HC101', text: 'Exactly one H1', check: det('count', { selector: 'h1', min: 1, max: 1 }) },
       { id: 'HC102', text: 'Title between 10 and 70 characters', check: det('title_matches', { pattern: '^.{10,70}$' }) },

package/src/lib/scenario.mjs

@@ -57,6 +57,9 @@ export function validateScenario (data) {
     if (node.kind === 'stack' && !node.items) problems.push(`node "${node.id}": stack steps need items (urls, file, sitemap, crawl or script)`)
     if (node.kind === 'stack' && node.items && ['urls', 'file', 'sitemap', 'robots', 'crawl', 'script'].filter((k) => node.items[k]).length !== 1) problems.push(`node "${node.id}": items needs exactly one source of urls, file, sitemap, robots, crawl or script`)
     if (node.kind !== 'stack' && (node.items || node.fields)) problems.push(`node "${node.id}": items and fields belong to stack steps`)
+    // locale variants (#176): the list comes from the source locale, so it must be one the scenario walks
+    if (node.kind === 'stack' && node.items?.source_locale && !node.items.variants) problems.push(`node "${node.id}": items.source_locale goes with items.variants: hreflang`)
+    if (node.kind === 'stack' && node.items?.variants && node.items.source_locale && Array.isArray(data.locales) && !data.locales.includes(node.items.source_locale)) problems.push(`node "${node.id}": items.source_locale ${node.items.source_locale} is not one of the scenario's locales (${data.locales.join(', ')})`)
     // app screens are reached by a script or a person as often as by a deep link
     // a manual screen may have no path: a person (or an imported walkthrough) shows how to get there
     if (node.kind === 'screen' && !node.path && (!data.platform || data.platform === 'web') && node.execution?.strategy !== 'manual') problems.push(`node "${node.id}": screen steps need a path`)
@@ -117,6 +120,8 @@ export function scenarioWarnings (data, { projectRequired = null } = {}) {
   const out = []
   if (!data || !Array.isArray(data.nodes)) return out
   for (const node of data.nodes) {
+    if (node.kind === 'stack' && node.items?.variants) out.push(`node "${node.id}": hosted runs (kaloko schedule add) do not group locale variants yet: there each language reads its own list and missing translations (HC1005) are not reported; kaloko walk and the scheduled GitHub workflow do`)
+    if (node.kind === 'stack' && node.items?.variants && (data.locales || []).length < 2) out.push(`node "${node.id}": items.variants: hreflang groups the language versions of a page, but the scenario walks ${(data.locales || []).length ? `one locale (${data.locales[0]})` : 'no locales'}; list the other locales under locales:`)
     if (node.kind === 'stack' && (node.packs || []).includes('errors')) out.push(`node "${node.id}": the errors pack is meant for error pages (404, 500, maintenance); on a stack of normal pages HC601 and HC605 stay not applicable. Remove it, or give the step expect_status when its pages are error pages`)
   }
   if (projectRequired && !data.project) out.push(`no project: ${projectRequired.reason}; add project: <slug>${projectRequired.projects.length ? ` (one of ${projectRequired.projects.join(', ')})` : ''}, or kaloko share may answer HTTP 404`)

package/src/lib/seo-core.mjs

@@ -2,8 +2,11 @@
 // service (worker/src/design.js, through manifest-core.mjs) assembles stacks with the same results.
 //   - cross-page checks of a stack step (#151): duplicate titles, descriptions and H1 within a language, canonicals
 //     that point elsewhere, hreflang that does not answer back, sitemap pages that are not indexable;
+//   - with traffic data (#157), pages seen often in search but clicked far less than the site's pages at similar
+//     positions (HC127);
 //   - locale checks of one capture (#159, the `locale` pack): html lang, the page's own hreflang, the language of the
 //     text and the decimal separator of prices against the walked locale.
+import { lowCtr, trafficLine } from './traffic-core.mjs'
 
 /** Comparable form of a URL: origin, path without a trailing slash (except the root), sorted query, no hash. */
 export function normUrl (href, base) {
@@ -44,7 +47,8 @@ export const STACK_CHECKS = [
   { id: 'HC123', text: 'H1 headings are unique within a language', field: 'h1' },
   { id: 'HC124', text: 'Every page is its own canonical, and no canonical points to an error or noindex page' },
   { id: 'HC125', text: 'hreflang alternates answer back: each language version links to the others and to itself' },
-  { id: 'HC126', text: 'Pages listed in the sitemap answer 200 without a redirect and are indexable' }
+  { id: 'HC126', text: 'Pages listed in the sitemap answer 200 without a redirect and are indexable' },
+  { id: 'HC127', text: 'Pages seen often in search are not clicked far less than the site\'s other pages at similar positions' }
 ]
 /** Most groups and addresses a check keeps (items.json, the node's health entry). */
 export const STACK_CHECK_GROUPS = 20
@@ -62,7 +66,9 @@ export function stackPages (items) {
       if (!c) continue
       const meta = c.meta || {}
       const url = c.url || it.url || null
-      const requested = it.path && /^https?:\/\//.test(it.path) ? it.path : url && it.path ? (() => { try { return new URL(it.path, url).href } catch { return url } })() : url
+      // a locale variant (#176) was opened at its own path, the item keeps the source page's
+      const path = c.path || it.path
+      const requested = path && /^https?:\/\//.test(path) ? path : url && path ? (() => { try { return new URL(path, url).href } catch { return url } })() : url
       out.push({ item: it.id, locale, url, requested, status: c.http_status ?? it.fields?.http ?? null, title: meta.title ?? it.fields?.title ?? null, description: meta.description ?? null, h1: Array.isArray(meta.h1) ? meta.h1[0] ?? null : meta.h1 ?? it.fields?.h1 ?? null, canonical: meta.canonical || null, robots: meta.robots || null, hreflang: (meta.hreflang || []).map((a) => ({ lang: String(a.lang || a.hreflang || '').toLowerCase(), href: a.href })).filter((a) => a.lang && a.href) })
     }
   }
@@ -178,19 +184,41 @@ function sitemapPages (def, pages) {
   return result(def, { verdict: affected.length ? 'fail' : 'pass', pages: known.length, affected, groups: list, evidence: affected.length ? `${new Set(affected).size} of ${known.length} sitemap pages are not indexable as listed: ${list.map((g) => `${g.value} ×${g.urls.length} (${g.urls.slice(0, 2).join(', ')})`).join('; ')}` : `${known.length} sitemap pages answer 200, without a redirect or noindex` })
 }
 
+/**
+ * HC127 (#157): pages with traffic data (items[].traffic) whose CTR is below `ratio` × the site's median CTR in their
+ * position band (traffic-core.mjs ctrMedians). Only with traffic data; pages it cannot judge are not counted.
+ */
+function lowCtrPages (def, items, traffic) {
+  const judged = []; const low = []
+  for (const it of items) {
+    const r = lowCtr(it.traffic, traffic.medians, traffic.low_ctr)
+    if (!r) continue
+    judged.push(it)
+    if (r.low) low.push({ it, ...r })
+  }
+  if (!judged.length) return null
+  low.sort((a, b) => b.it.traffic.impressions - a.it.traffic.impressions)
+  const groups = low.map(({ it, median }) => ({ value: trafficLine(it.traffic, median), urls: [shortUrl(it.url || it.path)] }))
+  return result(def, {
+    verdict: low.length ? 'fail' : 'pass', pages: judged.length, affected: low.map((x) => x.it.id), groups,
+    evidence: low.length ? `${low.length} of ${judged.length} pages with enough impressions are clicked less than half as often as the site's pages at similar positions: ${groups.slice(0, 3).map((g) => `${g.urls[0]}: ${g.value}`).join('; ')}` : `${judged.length} pages with enough impressions, each clicked about as often as the site's pages at similar positions`
+  })
+}
+
 /**
  * The cross-page checks of a stack step from its assembled items: [{ id, text, level, verdict, pages, affected,
  * evidence, groups: [{ locale?, value, urls, more? }], items: [affected item ids] }]. Checks without data (one page,
- * no canonicals, no hreflang, a source other than a sitemap for HC126) are left out.
+ * no canonicals, no hreflang, a source other than a sitemap for HC126, no traffic data for HC127) are left out.
  */
-export function stackChecks ({ items, source = null }) {
+export function stackChecks ({ items, source = null, traffic = null }) {
   const pages = stackPages(items)
   if (!pages.length) return []
   const def = (id) => STACK_CHECKS.find((c) => c.id === id)
   return [
     duplicates(def('HC121'), pages), duplicates(def('HC122'), pages), duplicates(def('HC123'), pages),
     canonicals(def('HC124'), pages), hreflangPairs(def('HC125'), pages),
-    source === 'sitemap' || source === 'robots' ? sitemapPages(def('HC126'), pages) : null
+    source === 'sitemap' || source === 'robots' ? sitemapPages(def('HC126'), pages) : null,
+    traffic?.medians ? lowCtrPages(def('HC127'), items, traffic) : null
   ].filter(Boolean)
 }