kaloko 0.20.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "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/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/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/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;
 }