kaloko 0.20.1 → 0.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/schemas/scenario.v1.json

@@ -998,7 +998,7 @@
         },
         "full_page": {
           "type": "boolean",
-          "description": "Screenshot of the whole page (default true; false for stack pages: the first screen only)"
+          "description": "Screenshot of the whole page (default true, stack pages too); false keeps the first screen only"
         },
         "screenshot": {
           "enum": ["full", "thumb"],

package/skills/kaloko/reference/integrations.md

@@ -102,9 +102,12 @@ kaloko schedule hook <id>       # URL + secret that start the run after a deploy
 - Findings: `GET …/scenarios/<id>/findings` (MCP `list_findings`) groups a
   scenario's open results by check, site, locale and step, with a status
   people set (acknowledged, ignored with a reason) and fixed when no page
-  fails. A scenario may open one Jira / Linear issue per new finding
-  (`PUT …/findings/sync { tracker, min_severity }`, Developer / Tester): at
-  most 20 per run, a comment on big changes, closed when fixed. Switching it
+  fails. A scenario may open one issue per new finding in Jira, Linear,
+  GitHub Issues or Plane (`PUT …/findings/sync { tracker, min_severity,
+  github?, plane?, routes? }`, Developer / Tester; routes send checks or
+  packs to another tracker): at most 20 per run, a comment on big changes,
+  closed when fixed. With `traffic:`, findings and issues carry clicks,
+  impressions and impact. Switching it
   on or ignoring findings is the team's call, not an agent's.
 - Does not work for: native apps, local or private addresses (localhost, IPs,
   `.local`), header credentials, stacks listed by crawl, script or file.

package/skills/kaloko/reference/stacks.md

@@ -59,7 +59,7 @@ step script only to prepare each page, for example to dismiss a dialog
     - { id: author, label: Author, from: .author }
     - { id: cover, label: Cover, from: "article img@src" }
     - { id: links, label: Links, from: "count:main a" }
-  # capture: { full_page: true }            # default for stacks is the first screen only
+  # capture: { screenshot: thumb, full_page: false }  # whole pages by default; this is the smallest
   criteria:
     - { id: AC1, text: Has a cover image, check: { type: deterministic, assert: exists, selector: "article img" } }
     - { id: AC2, text: Reads as an article, check: { type: semantic, question: Does the page read as a complete magazine article? } }
@@ -253,20 +253,32 @@ stack, set:
   caps the calls of a whole evaluation (evaluation.md). Raise the sample only when the question
   really differs between pages, and tell the person what it costs
   (one call per page and viewport).
-- Stacks capture the first screen of each page (fast, small). Set
-  `capture: { full_page: true }` when the criteria are about the whole page.
-- Walking takes about 1–2 s per page. For a first look, use
+- Stacks capture the whole page, like every step (since 0.21.0; before, the
+  first screen only). Vision checks see what is below the fold, and so does a
+  reviewer. A typical long page then stores a screenshot of about 600 KB
+  (about 70 KB for the first screen) and a thumbnail of about 180 KB (about
+  25 KB), because the thumbnail is as tall as the page.
+- To keep a stack small, set on the step:
+  - `capture: { full_page: false }`: a sharp first screen of each page;
+  - `capture: { screenshot: thumb, full_page: false }`: the smallest, a
+    640 px thumbnail of the first screen. Recommend it for big monitors
+    (SEO crawls, catalogues of thousands of pages) whose checks read the
+    page and do not need the picture below the fold.
+  - `capture: { screenshot: thumb }` alone keeps a thumbnail of the whole
+    page, still several times the first screen.
+- Walking takes about 1–2 s per page, a little more for long pages captured
+  whole. For a first look, use
   `kaloko walk --limit 50`. Re-walk chosen pages with
   `--items clanek-7,clanek-12` (matches the id or the path; picked from
   every matching page, also outside this week's rotation, and such a
   partial walk leaves the rotation state alone).
 - A shared run holds at most 20000 files and 300 MB as stored (HTML and JSON
   travel gzip-compressed, about a tenth of their size on disk). Each page
-  stores about four files, so a stack of a few thousand first-screen pages
-  fits. For SEO crawls where the checks read the page, not the picture, set
-  `capture: { screenshot: thumb }`: only the 640 px thumbnail is kept. Split
-  larger catalogues by section (`match`) or walk a rotating sample
-  (`rotate: week`).
+  stores about four files. Whole pages fill 300 MB at roughly 400 pages;
+  `screenshot: thumb, full_page: false` lets the 20000 files be the limit
+  (about 5000 pages). Split larger catalogues by section (`match`) or walk a
+  rotating sample (`rotate: week`). When a whole-page stack fills most of a
+  run near the limit, `kaloko share` names it and suggests these settings.
 
 ## Reading the results
 

package/src/cli.mjs

@@ -48,6 +48,7 @@ import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
 import { specCmd, driftCmd } from './lib/spec-cli.mjs'
 import { hashFiles, missingHashes, uploadRunFiles, PROGRESS_FILE, fmtBytes } from './lib/upload.mjs'
+import { biggestSteps, stackSizeAdvice } from './lib/run-size.mjs'
 import { affectedFor, carryCaptures } from './lib/affected.mjs'
 import { formatAffected, selectedIds } from './lib/affected-core.mjs'
 import { healStep, formatHeal } from './lib/heal.mjs'
@@ -1178,14 +1179,6 @@ async function projectsWrite (sub, args) {
   if (sub !== 'sync' && slug === config.project && name && config.project_name && name !== config.project_name) say(`Note: kaloko.config.yml still says project_name: ${config.project_name}; change it there too, or kaloko projects sync would rename the project back.`)
 }
 
-/** The steps that take most of a run, as stored: " Largest steps: products 212 MB (1 390 files), …" or ''. */
-function biggestSteps (entries, n = 3) {
-  const by = new Map()
-  for (const e of entries) { const k = e.path.match(/^steps\/([^/]+)\//)?.[1]; if (!k) continue; const x = by.get(k) || { bytes: 0, files: 0 }; x.bytes += e.stored ?? e.bytes; x.files++; by.set(k, x) }
-  const top = [...by].sort((a, b) => b[1].bytes - a[1].bytes).slice(0, n)
-  return top.length ? ` Largest steps: ${top.map(([k, x]) => `${k} ${fmtBytes(x.bytes)} (${x.files} files)`).join(', ')}.` : ''
-}
-
 const commands = {
   async init (args) {
     const cwd = process.cwd()
@@ -2245,7 +2238,10 @@ const commands = {
     const resumed = (await readJson(join(run.dir, PROGRESS_FILE), null).catch(() => null))?.run === manifest.id
     try {
       if (!u) throw new Error('usage unavailable')
-      if (total > u.limits.max_run_bytes) throw new UserError(`This run is ${fmtBytes(total)}; the limit per run is ${fmtBytes(u.limits.max_run_bytes)}.${biggestSteps(entries)} Capture fewer viewports or locales; for a stack, lower items.limit, walk a rotating sample (items.rotate: week) or keep thumbnails only (capture: { screenshot: thumb }). An admin can also ask for a higher limit.`)
+      if (total > u.limits.max_run_bytes) throw new UserError(`This run is ${fmtBytes(total)}; the limit per run is ${fmtBytes(u.limits.max_run_bytes)}.${biggestSteps(entries)}${stackSizeAdvice({ entries, scenario, limit: u.limits.max_run_bytes, over: true })} Capture fewer viewports or locales; for a stack, lower items.limit, walk a rotating sample (items.rotate: week), keep the first screen only (capture: { full_page: false }) or, smallest, keep thumbnails of it only (capture: { screenshot: thumb, full_page: false }). An admin can also ask for a higher limit.`)
+      // a stack captured whole (the default) that fills most of a run close to the limit: say so before the next walk grows it
+      const near = stackSizeAdvice({ entries, scenario, limit: u.limits.max_run_bytes })
+      if (near) say(near)
       if (u.usage.bytes + fresh > u.limits.quota_bytes) throw new UserError(`Storage quota would be exceeded: ${fmtBytes(u.usage.bytes)} used + ${fmtBytes(fresh)} > ${fmtBytes(u.limits.quota_bytes)}. Delete old runs in Settings or ask for a higher quota.`)
       const recBytes = entries.filter((e) => /\.rec\./.test(e.path)).reduce((n, e) => n + e.bytes, 0)
       say(`${resumed ? 'Resuming the interrupted share: ' : ''}${files.size} files, ${fmtBytes(total)}${recBytes ? ` (recordings ${fmtBytes(recBytes)})` : ''}${missing ? `; ${fmtBytes(fresh)} new, the rest already stored` : ''} (organization uses ${fmtBytes(u.usage.bytes)} of ${fmtBytes(u.limits.quota_bytes)})`)

package/src/lib/capture.mjs

@@ -88,8 +88,9 @@ export function captureOptions (scenario, node) {
     mask: [...new Set(masks.flatMap((m) => m.selectors))],
     maskAuto: masks.some((m) => m.auto),
     annotate: o.annotate === true,
-    // stack pages default to the first screen: hundreds of full-page shots would swamp storage
-    fullPage: o.full_page != null ? o.full_page !== false : node?.kind !== 'stack',
+    // the whole page by default, stack pages too: a review needs what is below the fold (full_page: false for the
+    // first screen only; screenshot: thumb when a crawl of thousands of pages needs no picture)
+    fullPage: o.full_page !== false,
     // screenshot: thumb (#150): only the card thumbnail is stored, as the step's image too (SEO crawls of thousands of
     // pages need the page facts, not a sharp picture of each)
     thumbOnly: o.screenshot === 'thumb'
@@ -138,9 +139,45 @@ export async function settle (page) {
     await page.evaluate(async (overlay) => {
       const open = [...document.querySelectorAll(overlay)].some((el) => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0 })
       if (open) return
-      const step = innerHeight * 0.8
-      for (let y = 0; y < document.documentElement.scrollHeight; y += step) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 60)) }
-      scrollTo(0, 0)
+      // what scrolling changes on the fixed and sticky parts (a header that floats, a search panel that fades in):
+      // the capture waits until they are back as they were at the top, or until they stopped changing for 1 s (a
+      // widget revealed on scroll for good), at most 3 s
+      // fixed, sticky or inside such a part; asked once per element (the observer sees every class change of the page)
+      const floats = new WeakMap()
+      const floating = (el) => {
+        if (!el || el === document.body || el === document.documentElement) return false
+        if (!floats.has(el)) { const p = getComputedStyle(el).position; floats.set(el, p === 'fixed' || p === 'sticky' || floating(el.parentElement)) }
+        return floats.get(el)
+      }
+      const before = new Map()
+      let changed = performance.now()
+      const mo = new MutationObserver((list) => {
+        for (const m of list) {
+          const el = m.target
+          if (!(el === document.documentElement || el === document.body || floating(el))) continue
+          changed = performance.now()
+          const key = `${m.attributeName}`
+          const seen = before.get(el) || before.set(el, {}).get(el)
+          if (!(key in seen)) seen[key] = m.oldValue
+        }
+      })
+      // an empty class or style attribute looks the same as none
+      const same = (name, a, b) => name === 'class' || name === 'style' ? (a || '') === (b || '') : a === b
+      try {
+        mo.observe(document.documentElement, { subtree: true, attributes: true, attributeOldValue: true, attributeFilter: ['class', 'style', 'hidden', 'aria-expanded'] })
+        const step = innerHeight * 0.8
+        for (let y = 0; y < document.documentElement.scrollHeight; y += step) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 60)) }
+        scrollTo(0, 0)
+        const start = performance.now()
+        // the quiet second counts from the return to the top: a header that changed once on the first scroll and goes
+        // back a moment after the page is at the top again is not quiet yet
+        changed = Math.max(changed, start)
+        const back = () => [...before].every(([el, attrs]) => Object.entries(attrs).every(([name, value]) => same(name, el.getAttribute(name), value)))
+        // only what moves on the fixed and sticky parts: a carousel or spinner elsewhere does not hold the capture
+        const moving = () => (document.getAnimations?.() || []).some((a) => a.playState === 'running' && a.effect?.getComputedTiming?.().iterations !== Infinity && floating(a.effect?.target))
+        const quiet = () => performance.now() - changed >= 1000
+        while (performance.now() - start < 3000 && (moving() || !(back() || quiet()))) await new Promise((r) => setTimeout(r, 50))
+      } finally { mo.disconnect() }
     }, OVERLAY)
   } catch {}
   await page.waitForTimeout(250)
@@ -229,18 +266,21 @@ export async function captureStep ({ page, node, locale, viewports, run, console
       // (or 2× for documentation), so the canvas, boxes and diffs work the same for every device
       const dpr = await page.evaluate(() => devicePixelRatio).catch(() => 1)
       let shotScale = opts.scale
+      // a full-page capture resizes the page; resize handlers restart CSS transitions (a panel fading out again), and
+      // the image would catch them halfway. Transitions end at once and finite animations finish for the capture
       if (opts.scale === 2 && engine === 'chromium') {
         const cdp = await page.context().newCDPSession(page)
+        const still = await page.addStyleTag({ content: '*, *::before, *::after { transition: none !important }' }).catch(() => null)
         try {
           const doc = await page.evaluate(() => ({ w: Math.ceil(document.documentElement.scrollWidth), h: Math.ceil(document.documentElement.scrollHeight) }))
           const r = await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: opts.fullPage, clip: { x: 0, y: 0, width: opts.fullPage ? doc.w : width, height: opts.fullPage ? doc.h : height, scale: 2 / (dpr || 1) } })
           shot = Buffer.from(r.data, 'base64')
-        } finally { await cdp.detach().catch(() => {}) }
+        } finally { await cdp.detach().catch(() => {}); await still?.evaluate((el) => el.remove()).catch(() => {}) }
       } else {
         // WebKit and Firefox have no 2× capture of their own: 2× when the context renders at 2× or more, else 1×
         // (exactly 2×: a 3× or 2.625× device would give an image the masks and marks are not drawn for)
         if (opts.scale === 2 && dpr !== 2) shotScale = 1
-        shot = await page.screenshot({ fullPage: opts.fullPage, scale: shotScale === 2 ? 'device' : 'css' })
+        shot = await page.screenshot({ fullPage: opts.fullPage, scale: shotScale === 2 ? 'device' : 'css', animations: 'disabled' })
       }
       // secrets the CLI used (gate, accounts) never land in a capture, even if the page echoes them
       await writeFile(html, redact(maskHtml(await page.content(), masking?.attrs)))

package/src/lib/evaluate.mjs

@@ -449,7 +449,7 @@ function triageContext ({ config, root, settings, report, fetchImpl, uncertain =
               const video = side?.files?.webm || side?.files?.mp4
               // a recording that cannot be read costs its frames only, never the screen's findings
               if (video) try {
-                const frames = await chooseFrames({ page: await page(), file: join(runDir, video), taps: (side.taps || []).map((t) => t.t ?? t), max: Math.min(settings.frames_per_step, framesLeft), maxW: settings.frame_width || 640 })
+                const frames = await chooseFrames({ page: await page(), file: join(runDir, video), taps: (side.taps || []).map((t) => t.t ?? t), max: Math.min(settings.frames_per_step, framesLeft), maxW: settings.frame_width || 640, cacheDir })
                 framesLeft -= frames.length; report.triage.frames += frames.length
                 for (const batch of frameBatches(frames)) {
                   const r = await ask(w, { kind: 'motion', context: { ...context, frames: batch.map((f) => ({ t_ms: f.t, why: f.why })) }, images: batch.map((f) => f.data) }, { frames: batch.map((f) => f.t) })

package/src/lib/health-findings.mjs

@@ -8,6 +8,7 @@
 // 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'
+import { impactOf } from './traffic-core.mjs'
 
 export const HEALTH_FINDINGS_SCHEMA = 'kaloko.health-findings.v1'
 /** What a person may set; fixed is never set, it is derived. */
@@ -45,10 +46,13 @@ export function findingId (fp) {
 /**
  * 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 }.
+ * the newest run (last seen of what it checked); traffic: "step|page" → the page's Search Console and GA4 numbers
+ * (#157). Returns findings, worst first: { id, fingerprint, check, text, pack, site, locale, step, severity, count,
+ * unchecked, samples: [{ page, url, edit_url, traffic? }], first_seen, last_seen, traffic?, impact? }. With traffic,
+ * a finding adds up clicks and impressions of its pages that have numbers (`traffic.pages` of them) and its impact
+ * (the sum of each page's impact, traffic-core.mjs impactOf); without, it has neither.
  */
-export function groupFindings (rows, { checks = {}, edit = {}, seen = null } = {}) {
+export function groupFindings (rows, { checks = {}, edit = {}, seen = null, traffic = null } = {}) {
   const out = new Map()
   for (const r of rows || []) {
     const k = parseHealthKey(r.key)
@@ -64,9 +68,15 @@ export function groupFindings (rows, { checks = {}, edit = {}, seen = null } = {
     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 }
+    const ek = `${k.step}|${k.page}`
+    const t = traffic && Object.hasOwn(traffic, ek) && traffic[ek] && typeof traffic[ek] === 'object' ? traffic[ek] : null
+    if (t) {
+      const sum = (f.traffic ||= { clicks: 0, impressions: 0, pages: 0 })
+      sum.clicks += Number(t.clicks) || 0; sum.impressions += Number(t.impressions) || 0; sum.pages++
+      f.impact = (f.impact || 0) + impactOf(t, r.severity)
+    }
     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 })
+      f.samples.push({ page: k.page || null, url: r.url || null, edit_url: (edit && Object.hasOwn(edit, ek) ? edit[ek] : null) || null, ...(t ? { traffic: { clicks: Number(t.clicks) || 0, impressions: Number(t.impressions) || 0 } } : {}) })
     }
   }
   return [...out.values()].sort(worstFirst)
@@ -79,8 +89,8 @@ export const FINDINGS_SUMMARY_SCHEMA = 'kaloko.health-findings-summary.v1'
  * 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 })
+export function summarizeFindings (rows, { checks = {}, edit = {}, seen = null, fixed = [], previous = null, traffic = null } = {}) {
+  const list = groupFindings(rows, { checks, edit, seen, traffic })
   const at = new Map(list.map((f) => [f.id, f]))
   for (const g of groupFindings(fixed, { checks, edit })) {
     const f = at.get(g.id)
@@ -114,3 +124,54 @@ export const atLeastSeverity = (severity, min) => SEVERITIES.includes(min) && se
  * the issue last said.
  */
 export const countChanged = (before, now) => before != null && Math.abs(now - before) >= Math.max(3, Math.ceil(before * 0.25))
+
+// ---------- where issues go (#191) ----------
+
+/** Trackers the findings sync can open issues in. */
+export const SYNC_TRACKERS = ['jira', 'linear', 'github', 'plane']
+/** Routes a scenario may have; checks and packs per route. */
+export const ROUTE_MAX = 20
+const ROUTE_LIST_MAX = 50
+const CHECK_PATTERN = /^[A-Z]{1,6}[0-9]{0,6}\*?$/
+const PACK = /^[a-z][a-z0-9_-]{0,30}$/
+
+/**
+ * Routes of a sync setting from the API: [{ tracker, checks?: ['HC127', 'HC1*'], packs?: ['aeo'] }], in order. A check
+ * ends with * to take every check that starts so (HC1* is HC100 to HC199 and HC1000…). Throws an Error that says
+ * what is wrong; [] for none.
+ */
+export function cleanRoutes (list) {
+  if (list == null) return []
+  if (!Array.isArray(list)) throw new Error('routes is a list of { tracker, checks, packs }.')
+  if (list.length > ROUTE_MAX) throw new Error(`At most ${ROUTE_MAX} routes.`)
+  return list.map((r, i) => {
+    if (!r || typeof r !== 'object') throw new Error(`Route ${i + 1} is not an object.`)
+    const tracker = String(r.tracker || '')
+    if (!SYNC_TRACKERS.includes(tracker)) throw new Error(`Route ${i + 1}: tracker is ${SYNC_TRACKERS.join(', ')}.`)
+    const words = (v, name) => {
+      if (v == null) return []
+      if (!Array.isArray(v) || v.length > ROUTE_LIST_MAX) throw new Error(`Route ${i + 1}: ${name} is a list of at most ${ROUTE_LIST_MAX}.`)
+      return [...new Set(v.map((x) => String(x ?? '').trim()))]
+    }
+    const checks = words(r.checks, 'checks').map((c) => c.toUpperCase())
+    const packs = words(r.packs, 'packs').map((p) => p.toLowerCase())
+    const badCheck = checks.find((c) => !CHECK_PATTERN.test(c) || c === '*')
+    if (badCheck !== undefined) throw new Error(`Route ${i + 1}: ${badCheck.slice(0, 20) || '(empty)'} is not a check id (HC127) or a prefix (HC1*).`)
+    const badPack = packs.find((p) => !PACK.test(p))
+    if (badPack !== undefined) throw new Error(`Route ${i + 1}: ${badPack.slice(0, 20) || '(empty)'} is not a pack name (seo, aeo).`)
+    if (!checks.length && !packs.length) throw new Error(`Route ${i + 1}: name checks or packs.`)
+    return { tracker, ...(checks.length ? { checks } : {}), ...(packs.length ? { packs } : {}) }
+  })
+}
+
+const checkMatches = (pattern, check) => pattern.endsWith('*') ? String(check).startsWith(pattern.slice(0, -1)) : pattern === check
+/**
+ * The tracker a finding's issue goes to: the first route that names its check (or a prefix of it) or its pack, else
+ * the scenario's tracker.
+ */
+export function routeOf (f, routes = [], fallback = null) {
+  for (const r of routes || []) {
+    if ((r.checks || []).some((c) => checkMatches(c, f.check)) || (f.pack && (r.packs || []).includes(String(f.pack).toLowerCase()))) return r.tracker
+  }
+  return fallback
+}

package/src/lib/health-index.mjs

@@ -8,6 +8,7 @@
 // (worker/src/health-index.js); the shapes are documented in help/reference/health-api.md.
 import { healthOfNode, levelOf, findingSeverity, severityRank } from './health-core.mjs'
 import { worst } from './manifest-core.mjs'
+import { trafficView } from './traffic-core.mjs'
 
 export const HEALTH_INDEX_SCHEMA = 'kaloko.health-index.v1'
 export const HEALTH_AGGREGATE_SCHEMA = 'kaloko.health-aggregate.v1'
@@ -42,14 +43,16 @@ const firstUrl = (vps) => { for (const c of Object.values(vps || {})) if (c?.url
  * [{ locale, step, check, counts, top: [{ page, path, url, verdict, evidence }] }], open: [[key, severity, url]],
  * 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).
+ * (passedIn). edit maps "step|page" to the edit_url of a stack page with open results (findings link it); traffic
+ * maps "step|page" to the Search Console and GA4 numbers of such a page when its stack has `traffic:` (#157), for the
+ * same pages and bound (findings add them up, an issue shows them).
  */
 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 edits = new Map(); const visits = new Map()
   const totals = { results: 0, ...blank() }
-  const add = (step, locale, page, path, url, check, verdict, evidence, editUrl = null) => {
+  const add = (step, locale, page, path, url, check, verdict, evidence, editUrl = null, traffic = null) => {
     if (!VERDICTS.includes(verdict)) return
     pages.add(`${step}|${page}`)
     const gk = `${locale}\u0000${step}\u0000${check}`
@@ -63,6 +66,7 @@ export function buildHealthIndex (manifest, stacks = {}) {
     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))
+    if (traffic && typeof traffic === 'object') { const t = trafficView(traffic); if (t && Object.keys(t).length) visits.set(`${step}|${page}`, t) }
   }
   for (const n of manifest?.nodes || []) {
     if (n.kind === 'decision') continue
@@ -85,7 +89,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, it.edit_url)
+        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, it.traffic)
       }
       continue
     }
@@ -115,16 +119,18 @@ export function buildHealthIndex (manifest, stacks = {}) {
   // 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
+  const traffic = Object.create(null); let numbers = 0
   for (const [key] of kept) {
-    if (links >= EDIT_MAX) break
+    if (links >= EDIT_MAX && numbers >= 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++ }
+    if (links < EDIT_MAX && edits.has(k) && !Object.hasOwn(edit, k)) { edit[k] = edits.get(k); links++ }
+    if (numbers < EDIT_MAX && visits.has(k) && !Object.hasOwn(traffic, k)) { traffic[k] = visits.get(k); numbers++ }
   }
   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: kept, open_total: open.length, truncated: open.length > OPEN_MAX, passed, edit
+    open: kept, open_total: open.length, truncated: open.length > OPEN_MAX, passed, edit, ...(numbers ? { traffic } : {})
   }
 }
 

package/src/lib/run-size.mjs

@@ -0,0 +1,45 @@
+// What takes the room in a run before `kaloko share` sends it: the largest steps, and the advice for a stack whose
+// pages are captured whole (the default since 0.21.0) when it fills most of the per-run limit.
+import { fmtBytes } from './upload.mjs'
+import { captureOptions } from './capture.mjs'
+
+/** Bytes and files per step, as stored (entries from hashFiles: { path, bytes, stored? }), largest first. */
+export function stepSizes (entries) {
+  const by = new Map()
+  for (const e of entries) {
+    const k = e.path.match(/^steps\/([^/]+)\//)?.[1]
+    if (!k) continue
+    const x = by.get(k) || { bytes: 0, files: 0 }
+    x.bytes += e.stored ?? e.bytes; x.files++
+    by.set(k, x)
+  }
+  return [...by].sort((a, b) => b[1].bytes - a[1].bytes)
+}
+
+/** The steps that take most of a run: " Largest steps: products 212 MB (1 390 files), …" or ''. */
+export function biggestSteps (entries, n = 3) {
+  const top = stepSizes(entries).slice(0, n)
+  return top.length ? ` Largest steps: ${top.map(([k, x]) => `${k} ${fmtBytes(x.bytes)} (${x.files} files)`).join(', ')}.` : ''
+}
+
+/** Stack steps of the scenario whose pages are captured whole and kept sharp (no full_page: false, no thumb). */
+export function wholePageStacks (scenario) {
+  return new Set((scenario?.nodes || []).filter((n) => n.kind === 'stack').filter((n) => { const o = captureOptions(scenario, n); return o.fullPage && !o.thumbOnly }).map((n) => n.id))
+}
+
+const SMALL = 'capture: { full_page: false } keeps the first screen of each page, capture: { screenshot: thumb, full_page: false } is the smallest'
+
+/**
+ * Advice when a whole-page stack makes up most of a run that is near or over the limit, or ''.
+ * `over` words it for the refusal (appended to it); otherwise it is a warning of its own.
+ */
+export function stackSizeAdvice ({ entries, scenario, limit, over = false }) {
+  const total = entries.reduce((n, e) => n + (e.stored ?? e.bytes), 0)
+  if (!limit || total < limit * 0.8) return ''
+  const whole = wholePageStacks(scenario)
+  const hit = stepSizes(entries).find(([k, x]) => whole.has(k) && x.bytes > total / 2)
+  if (!hit) return ''
+  const [id, x] = hit
+  if (over) return ` The stack ${id} is ${fmtBytes(x.bytes)} of it because each page is captured whole.`
+  return `This run is ${fmtBytes(total)} of the ${fmtBytes(limit)} allowed per run, and the stack ${id} is ${fmtBytes(x.bytes)} of it because each page is captured whole. If its pictures below the fold are not needed, ${SMALL}.`
+}

package/src/lib/triage.mjs

@@ -4,6 +4,7 @@
 // CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID straight to Workers AI. Findings never change a verdict.
 import { join } from 'node:path'
 import { readFile } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 import { readJson, writeJson, sha256 } from './util.mjs'
 import { buildTriageRequest, parseTriage, mergeFindings, clefModelId, TRIAGE_PROMPT_VERSION, MAX_TRIAGE_IMAGES } from './triage-core.mjs'
 
@@ -77,15 +78,24 @@ export function hostedTriageSender (config, report) {
   return send
 }
 
+// bump when the choice of frames or their encoding changes, so cached frames are chosen again
+const FRAMES_VERSION = 1
+
 /**
  * Frames of a recording for the motion questions, chosen in a browser page: around each tap, where the picture changes
  * most between samples (a jump, a flash, a message), and the last frame. Returns [{ t, why, data }] in time order,
- * at most `max` frames, each a WebP data URL `maxW` wide.
+ * at most `max` frames, each a WebP data URL `maxW` wide. With `cacheDir` the frames are kept by the recording's
+ * content and the settings, so evaluating the same recording again sends the very same frames (and its triage answers
+ * from the cache) even when the browser decodes or encodes a frame differently the second time.
  */
-export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 1024 }) {
+export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 1024, cacheDir = null }) {
   if (!(max > 0)) return []
-  const src = `data:video/${file.endsWith('.mp4') ? 'mp4' : 'webm'};base64,${(await readFile(file)).toString('base64')}`
-  return page.evaluate(async ({ src, taps, max, maxW }) => {
+  const bytes = await readFile(file)
+  const cacheFile = cacheDir && join(cacheDir, `frames-${createHash('sha256').update(bytes).update(JSON.stringify({ taps, max, maxW, v: FRAMES_VERSION })).digest('hex')}.json`)
+  const kept = cacheFile && await readJson(cacheFile, null)
+  if (Array.isArray(kept)) return kept
+  const src = `data:video/${file.endsWith('.mp4') ? 'mp4' : 'webm'};base64,${bytes.toString('base64')}`
+  const frames = await page.evaluate(async ({ src, taps, max, maxW }) => {
     const v = document.createElement('video'); v.muted = true; v.preload = 'auto'; v.src = src
     // every wait has a limit: a stalled video must not hang the evaluation
     const within = (p, ms) => Promise.race([p, new Promise((ok, no) => setTimeout(() => no(new Error('the recording did not answer in time')), ms))])
@@ -96,13 +106,25 @@ export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 102
     const dur = Number.isFinite(v.duration) ? v.duration : 0
     if (!dur) return []
     const seek = (t) => within(new Promise((ok) => { v.onseeked = ok; v.currentTime = Math.min(Math.max(0, t), Math.max(0, dur - 0.01)) }), 5000)
+    // `seeked` (even at readyState 4) does not mean the frame can be painted yet: on a busy machine the first draw
+    // sometimes paints nothing, which read as a change from an empty picture and moved the chosen frames. A decoded
+    // frame is opaque, so the draw is repeated until its middle row holds one.
+    const draw = async (g, w, h) => {
+      const painted = () => { const row = g.getImageData(0, h >> 1, w, 1).data; for (let i = 3; i < row.length; i += 4) if (row[i]) return true; return false }
+      for (let tries = 0; ; tries++) {
+        g.clearRect(0, 0, w, h); g.drawImage(v, 0, 0, w, h)
+        if (painted()) return
+        if (tries >= 100) throw new Error('a frame of the recording could not be drawn')
+        await new Promise((ok) => setTimeout(ok, 20))
+      }
+    }
     const small = document.createElement('canvas'); small.width = 64; small.height = Math.max(1, Math.round(64 * v.videoHeight / v.videoWidth))
     const sg = small.getContext('2d', { willReadFrequently: true })
     // sampled differences: 4 samples a second, at most 240
     const step = Math.max(0.25, dur / 240)
     const diffs = []; let prev = null
     for (let t = 0; t <= dur; t += step) {
-      await seek(t); sg.drawImage(v, 0, 0, small.width, small.height)
+      await seek(t); await draw(sg, small.width, small.height)
       const px = sg.getImageData(0, 0, small.width, small.height).data
       if (prev) { let d = 0; for (let i = 0; i < px.length; i += 4) d += Math.abs(px[i] - prev[i]) + Math.abs(px[i + 1] - prev[i + 1]) + Math.abs(px[i + 2] - prev[i + 2]); diffs.push({ t, d: d / (px.length / 4) / 765 }) }
       prev = px
@@ -117,11 +139,13 @@ export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 102
     const list = chosen.length > max ? [...chosen.slice(0, max - 1), chosen.at(-1)] : chosen
     const big = document.createElement('canvas'); const s = Math.min(1, maxW / v.videoWidth)
     big.width = Math.round(v.videoWidth * s); big.height = Math.round(v.videoHeight * s)
-    const bg = big.getContext('2d')
+    const bg = big.getContext('2d', { willReadFrequently: true })
     const out = []
-    for (const f of list) { await seek(f.t); bg.drawImage(v, 0, 0, big.width, big.height); out.push({ t: Math.round(f.t * 1000), why: f.why, data: big.toDataURL('image/webp', 0.8) }) }
+    for (const f of list) { await seek(f.t); await draw(bg, big.width, big.height); out.push({ t: Math.round(f.t * 1000), why: f.why, data: big.toDataURL('image/webp', 0.8) }) }
     return out
   }, { src, taps, max, maxW })
+  if (cacheFile && frames.length) await writeJson(cacheFile, frames)
+  return frames
 }
 
 /** Frames in requests of MAX_TRIAGE_IMAGES, each overlapping the previous by one frame so a change at the seam is seen. */

package/viewer/index.html

@@ -2136,7 +2136,7 @@ function hlLocal () {
   return { checks, counts, findings, legacy: !!RUN.health_legacy };
 }
 /** The step's health checks that apply here, and how many of them are findings in this capture. */
-function hlStepList (n) { return n.item || n.kind === 'decision' ? [] : (n.health || []).filter((c) => !c.not_applicable); }
+function hlStepList (n) { return n.kind === 'decision' ? [] : (n.health || []).filter((c) => !c.not_applicable); }
 const hlCellSev = (c, v) => hlSev((c.by_locale?.[S.loc]?.[v.name] || (c.counts ? c : {})).verdict, c);
 const hlStepBad = (n, v) => hlStepList(n).filter((c) => hlCellSev(c, v)).length;
 // the service's answer adds what changed since the previous run, the adoptions and whether this person may adopt
@@ -2203,11 +2203,11 @@ function hlRow (n, v, cap, c) {
   const st = cellSt(r);
   const sev = hlSev(r.verdict, c);
   const hasBox = (cap?.boxes?.[c.id] || []).some((b) => b.w > 0 && b.h > 0);
-  const ad = hlAdoption(n.id, c.id);
+  const ad = hlAdoption(n.stack || n.id, c.id);
   // a cross-page check of a stack (#151) compares pages with each other: no single page can adopt it
   const adopt = c.cross_page ? '' : ad ? `<p class="note">${esc(T(ad.applied_at ? 'hlApplied' : 'hlAdopted')(ad.criterion?.id || hlAcId(c.id)))}</p>`
     : hlCanAdopt() ? `<div data-hl-adopt-box="${esc(c.id)}"><button type="button" class="btn" data-hl-adopt="${esc(c.id)}">${T('hlAdopt')}</button></div>`
-      : !APP() ? `<details class="fixhelp"><summary>${T('hlAdopt')}</summary><p>${esc(T('hlAdoptLocal')(hlAcId(c.id)))}</p><code class="ev hl-cmd">kaloko health adopt ${esc(n.id)}:${esc(c.id)} --text "${esc(c.text)}"</code></details>` : '';
+      : !APP() ? `<details class="fixhelp"><summary>${T('hlAdopt')}</summary><p>${esc(T('hlAdoptLocal')(hlAcId(c.id)))}</p><code class="ev hl-cmd">kaloko health adopt ${esc(n.stack || n.id)}:${esc(c.id)} --text "${esc(c.text)}"</code></details>` : '';
   return `<li class="st-${st}" data-hl="${esc(c.id)}" data-where="${esc(hasBox ? 'page' : c.target?.kind || '')}" tabindex="0"><span class="mark">${MARK[st]}</span><span><span class="id">${esc(c.id)}</span>${esc(critText(c))}${sev ? `<span class="hl-sev hl-sev--${sev}">${T('hls_' + sev)}</span>` : ''}${c.pack ? `<span class="acb st-skip" style="margin-left:6px">${esc(c.pack)}</span>` : ''}</span><div class="acbody">${r.evidence ? (humanEvidence(r.evidence) ? `<span class="ev ev--text">${esc(humanEvidence(r.evidence))}</span>` : `<code class="ev">${esc(r.evidence)}</code>`) : r.reason ? `<span class="ev ev--text">${esc(r.reason)}</span>` : ''}${c.urls?.length && sev ? `<p class="note hl-urls">${c.urls.map(esc).join(', ')}</p>` : ''}${isFocusCheck(c) ? focusStrip(n, v, cap) : ''}${helpBlock(c, st)}${adopt}</div></li>`;
 }
 /** The step's Health tab: its health checks, findings first, each with its evidence, help and Adopt. */
@@ -2257,13 +2257,15 @@ document.addEventListener('submit', async (e) => {
   const text = f.querySelector('textarea').value.replace(/\s+/g, ' ').trim();
   if (!text) { f.querySelector('textarea').focus(); return; }
   const btn = f.querySelector('[type=submit]'); btn.disabled = true;
+  // a page of a stack adopts for its stack step
+  const step = n.stack || n.id;
   try {
-    const res = await fetch(`${APP().api}/orgs/${APP().org}/runs/${APP().run}/health/adopt`, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ step: n.id, check: c.id, ...(text !== c.text ? { text } : {}) }) });
+    const res = await fetch(`${APP().api}/orgs/${APP().org}/runs/${APP().run}/health/adopt`, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ step, check: c.id, ...(text !== c.text ? { text } : {}) }) });
     if (res.status === 401) throw sessionLost();
     const data = await res.json().catch(() => ({}));
     if (!res.ok) { toast(data.error || `HTTP ${res.status}`); btn.disabled = false; return; }
     const ad = data.adoption || data;
-    S.hl ||= { adoptions: [] }; S.hl.adoptions = [...(S.hl.adoptions || []).filter((a) => !(a.step === n.id && hlId(a.check) === c.id)), { id: ad.id, step: n.id, check: c.id, text: ad.text || text, criterion: ad.criterion || null, applied_at: ad.applied_at || null }];
+    S.hl ||= { adoptions: [] }; S.hl.adoptions = [...(S.hl.adoptions || []).filter((a) => !(a.step === step && hlId(a.check) === c.id)), { id: ad.id, step, check: c.id, text: ad.text || text, criterion: ad.criterion || null, applied_at: ad.applied_at || null }];
     toast(T('hlAdopted')(ad.criterion?.id || hlAcId(c.id)));
     openLb(S.open, S.lbVp, { keepFrame: true });
   } catch (err) { toast(err.message); btn.disabled = false; }
@@ -2512,9 +2514,20 @@ function ensureItemNode (n, data, it) {
   const crit = (data.criteria || n.criteria).map((c) => {
     const by_locale = {};
     for (const [key, res] of Object.entries(it.results || {})) { const [l, vp] = key.split('|'); const r = res[c.id]; if (r) ((by_locale[l] ||= {})[vp] = { verdict: r[0], evidence: r[1], score: r[2] }); }
-    return { id: c.id, text: c.text, type: c.type, pack: c.pack || null, by_locale, evidence: null };
+    return { id: c.id, text: c.text, type: c.type, pack: c.pack || null, ...(c.level ? { level: c.level } : {}), ...(c.acceptance ? { acceptance: true } : {}), ...(c.health ? { health: true } : {}), by_locale, evidence: null };
   }).filter((c) => Object.keys(c.by_locale).length);
-  const node = { id, item: true, itemId: it.id, stack: n.id, kind: 'screen', title: it.title || it.path, path: it.path, edit_url: it.edit_url || null, content_ref: it.content_ref || null, purpose: n.purpose, captures: it.captures || {}, criteria: crit, by_locale: it.by_locale || {}, status: it.status, attachments: it.attachments || [], semantic: {}, metadata: {}, execution: n.execution, session: n.session };
+  // the page's health checks get the Health tab, as on a step: kaloko marks them (health: true);
+  // runs from before the mark tell them by the pack outside acceptance or by the HC id
+  const marked = (data.criteria || n.criteria).some((c) => 'health' in c);
+  const isHealth = (c) => marked ? !!c.health : hlLegacyCrit(c) || /^HC[0-9]/.test(c.id);
+  const captures = it.captures || {};
+  const health = crit.filter(isHealth).map((c) => {
+    const hid = hlId(c.id); if (hid === c.id) return c;
+    // a run from before the split names the check AC…: its highlight boxes answer to the HC id too
+    for (const vps of Object.values(captures)) for (const cap of Object.values(vps || {})) if (cap?.boxes?.[c.id] && !cap.boxes[hid]) cap.boxes[hid] = cap.boxes[c.id];
+    return { ...c, sid: c.id, id: hid };
+  });
+  const node = { id, item: true, itemId: it.id, stack: n.id, kind: 'screen', title: it.title || it.path, path: it.path, edit_url: it.edit_url || null, content_ref: it.content_ref || null, purpose: n.purpose, captures, criteria: crit.filter((c) => !isHealth(c)), health, by_locale: it.by_locale || {}, status: it.status, attachments: it.attachments || [], semantic: {}, metadata: {}, execution: n.execution, session: n.session };
   ITEM_NODES.set(id, node);
   return node;
 }