kaloko 0.5.2 → 0.7.0

package/src/lib/integrations-cli.mjs

@@ -0,0 +1,211 @@
+// Batch H in the CLI: `kaloko issue create|list` (Jira and Linear, #21) and `kaloko schedule …` (hosted runs, #16):
+// add a read-only scenario to Kaloko's own browsers, list, run, pause, resume and remove schedules, or write a GitHub
+// Actions workflow that walks it on a schedule with the full CLI (`schedule export github`).
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, relative, dirname, join } from 'node:path'
+import { UserError } from './util.mjs'
+import { gateOf, accountFor } from './access.mjs'
+import { secret } from './secrets.mjs'
+import { runner } from './ci.mjs'
+
+const RUN_ID = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]{3,120}$/
+const WEEKDAYS = { mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, sun: 7 }
+
+// ---------- kaloko issue ----------
+
+const issueLine = (i) => `${i.key.padEnd(10)} ${String(i.state).padEnd(8)} step ${i.step}${i.criterion ? ` (${i.criterion})` : ''} · ${i.title}\n           ${i.url}`
+
+/**
+ * `kaloko issue create --step <id> --to jira|linear [--criterion AC2] [--title …] [--note …] [--run id] [--locale l]
+ * [--viewport v] [--target KEY] [--json]` and `kaloko issue list [--run id] [--scenario id] [--state open] [--json]`.
+ */
+export async function issueCmd ({ args, config, client, runId, say }) {
+  const sub = args._[0]
+  const org = config.org
+  if (!org) throw new UserError('Set org: in the config first.')
+  if (sub === 'list') {
+    const q = new URLSearchParams(Object.entries({ run: typeof args.run === 'string' ? args.run : null, scenario: typeof args.scenario === 'string' ? args.scenario : null, state: typeof args.state === 'string' ? args.state : null }).filter(([, v]) => v))
+    const items = await client.request('GET', `/orgs/${org}/issues${q.size ? `?${q}` : ''}`)
+    if (args.json) { say(JSON.stringify(items, null, 2)); return items }
+    say(items.length ? items.map(issueLine).join('\n') : 'No issues created from steps yet.')
+    return items
+  }
+  if (sub !== 'create') throw new UserError('Usage: kaloko issue create --step <id> --to jira|linear [--criterion AC2] [--title "…"] [--note "…"] [--run id]\n       kaloko issue list [--run id] [--scenario id] [--state open|done|canceled] [--json]')
+  const to = String(args.to || '')
+  if (!['jira', 'linear'].includes(to)) throw new UserError('--to jira or --to linear says where the issue goes.')
+  if (typeof args.step !== 'string' || !args.step) throw new UserError('--step <id> names the step the issue is about.')
+  const run = typeof args.run === 'string' ? args.run : runId
+  if (!run || !RUN_ID.test(run)) throw new UserError('No shared run: pass --run <id>, or share the current run first (kaloko share).')
+  const body = { run_id: run, step: args.step, to, ...Object.fromEntries(['criterion', 'title', 'note', 'locale', 'viewport', 'target'].filter((k) => typeof args[k] === 'string' && args[k]).map((k) => [k, args[k]])) }
+  const issue = await client.request('POST', `/orgs/${org}/issues`, body)
+  if (args.json) { say(JSON.stringify(issue, null, 2)); return issue }
+  say(`✓ ${issue.key} in ${to === 'jira' ? 'Jira' : 'Linear'}${issue.screenshot ? ', with the screenshot' : ''}: ${issue.url}\n  The step got a comment that is resolved when the issue is done.`)
+  return issue
+}
+
+// ---------- kaloko schedule ----------
+
+/** A step script that only opens its page (export default async ({ page, url }) => { await page.goto(url(…)) }). */
+export function onlyNavigates (code) {
+  const s = String(code || '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1').trim()
+  return /^export\s+default\s+async\s*(?:function\s*\w*\s*)?\(\s*\{\s*page\s*,\s*url\s*\}\s*\)\s*(?:=>)?\s*\{\s*(?:await\s+page\.goto\(\s*url\(\s*\)\s*(?:,\s*\{[^{}]*\})?\s*\)\s*;?\s*)\}\s*;?$/.test(s)
+}
+
+/** The scenario as the service takes it: packs expanded, steps whose script only navigates marked hosted: open. */
+export async function hostedScenario (scenario, scenarioFile) {
+  const out = JSON.parse(JSON.stringify(scenario))
+  for (const n of out.nodes || []) {
+    const script = n.execution?.script
+    if (!script || /^open\.(m?js|cjs)$/.test(String(script).split('/').pop())) continue
+    try { if (onlyNavigates(await readFile(resolve(dirname(scenarioFile), script), 'utf8'))) n.hosted = 'open' } catch {}
+  }
+  return out
+}
+
+/** How the hosted browser gets past the environment's gate: HTTP Basic from its variables, or an account's cookies. */
+export async function hostedAuth ({ env, account = null, root, config, vars = process.env }) {
+  if (account) {
+    const file = accountFor(env, account, { root, config }).storage_state
+    let state
+    try { state = JSON.parse(await readFile(file, 'utf8')) } catch { throw new UserError(`No saved session for ${account} in ${env.name} (${relative(process.cwd(), file)}). Sign in once with kaloko auth save --env ${env.name} --account ${account}, then schedule again.`) }
+    return { cookies: (state.cookies || []).map(({ name, value, domain, path, expires, httpOnly, secure, sameSite }) => ({ name, value, domain, path, expires, httpOnly, secure, sameSite })) }
+  }
+  const gate = gateOf(env)
+  if (gate.basic) return { basic: { user: secret(gate.basic.user_env, `HTTP Basic user for ${env.name}`, vars), password: secret(gate.basic.password_env, `HTTP Basic password for ${env.name}`, vars) } }
+  if (gate.headers && Object.keys(gate.headers).length) throw new UserError(`${env.name} is behind header credentials (access.headers); hosted runs send HTTP Basic or a saved session only. Walk it in CI: kaloko schedule export github.`)
+  return null
+}
+
+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 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 = [] }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const cron = every === 'week' ? `0 ${at_hour} * * ${weekday % 7}` : `0 ${at_hour} * * *`
+  const engines = browsers.some((b) => b !== 'chromium') ? ` --browsers ${browsers.join(',')}` : ''
+  const names = [...new Set(secrets.filter((n) => /^[A-Z_][A-Z0-9_]*$/.test(n)))]
+  return `# Kaloko: walk ${scenarioId} on ${env} ${every === 'week' ? 'every week' : 'every day'} and share the run.
+# Written by kaloko schedule export github. Secrets: KALOKO_TOKEN (tester role, upload scope; on Enterprise a service
+# account's)${names.length ? `; ${names.join(', ')} (the environment's credentials, as in kaloko.config.yml)` : ''}.
+name: Kaloko ${scenarioId} on ${env}
+on:
+  schedule:
+    - cron: '${cron}'   # UTC
+  workflow_dispatch:
+concurrency:
+  group: kaloko-schedule-${scenarioId}-${env}
+  cancel-in-progress: false
+permissions:
+  contents: read
+jobs:
+  walk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+      KALOKO_AGENT: github-actions
+${names.map((n) => `      ${n}: \${{ secrets.${n} }}`).join('\n')}${names.length ? '\n' : ''}    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}      - run: ${k} browser install --with-deps${engines}
+      - name: Walk, evaluate, share
+        run: |
+          ${k} start --scenario ${scenario} --env ${env}
+          ${k} walk
+          ${k} evaluate
+          ${k} share
+`
+}
+
+/** Variable names the environment and the scenario's accounts read their secrets from. */
+export function secretNames (env, scenario = {}) {
+  const out = []
+  const gate = gateOf(env)
+  if (gate.basic) out.push(gate.basic.user_env, gate.basic.password_env)
+  for (const spec of Object.values(gate.headers || {})) if (spec && typeof spec === 'object' && spec.env) out.push(spec.env)
+  const used = new Set(Object.values(scenario.sessions || {}).map((s) => s?.account).filter(Boolean))
+  for (const [key, a] of Object.entries(env.accounts || {})) if (used.has(key)) out.push(a.user_env, a.password_env, a.totp_env)
+  return out.filter(Boolean)
+}
+
+/**
+ * `kaloko schedule add --scenario <file> --env <name> [--every day|week|manual] [--at 5] [--weekday mon] [--account key]`,
+ * `list`, `run <id>`, `pause <id>`, `resume <id>`, `remove <id>`, `export github --scenario <file> --env <name>`.
+ * deps: { loadScenario, environment, baseUrl, projectAndIssue, packageRoot, service }.
+ */
+export async function scheduleCmd ({ args, config, root, say, deps }) {
+  const [sub, id] = args._
+  const org = config.org
+  const client = () => deps.service(config)
+  if (sub === 'export') {
+    if (id !== 'github') throw new UserError('Usage: kaloko schedule export github --scenario <file> --env <name> [--every day|week] [--at 5] [--weekday mon] [--out file] [--print] [--force]')
+    const file = typeof args.scenario === 'string' ? resolve(root, args.scenario) : null
+    if (!file) throw new UserError('--scenario <file> names the scenario to walk.')
+    const envName = typeof args.env === 'string' ? args.env : null
+    if (!envName) throw new UserError('--env <name> names the environment (production, staging …).')
+    const scenario = await deps.loadScenario(file)
+    // only the names of its variables are needed here: the workflow reads the values from repository secrets
+    if (!config.environments?.[envName]) throw new UserError(`Unknown environment "${envName}". Known: ${Object.keys(config.environments || {}).join(', ')}`)
+    const env = { name: envName, ...config.environments[envName] }
+    if (scenario.environments && !scenario.environments.includes(envName)) throw new UserError(`${relative(root, file)} allows environments [${scenario.environments.join(', ')}], not ${envName}.`)
+    let pkg = null
+    try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) } catch {}
+    const pm = existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : existsSync(join(root, 'bun.lockb')) || existsSync(join(root, 'bun.lock')) ? 'bun' : 'npm'
+    const version = JSON.parse(await readFile(join(deps.packageRoot, 'package.json'), 'utf8')).version
+    const every = args.every === 'week' ? 'week' : 'day'
+    const content = githubScheduleWorkflow({ scenario: relative(root, file), scenarioId: scenario.id, env: envName, every, at_hour: atHour(args.at), weekday: weekdayOf(args.weekday), pm, dependency: !!(pkg && ({ ...pkg.dependencies, ...pkg.devDependencies }).kaloko), version: `^${version}`, browsers: [...new Set(['chromium', ...(scenario.browsers || []), ...(config.walk?.browsers || [])])], secrets: secretNames(env, scenario) })
+    if (args.print) { say(content); return { content } }
+    const out = resolve(root, typeof args.out === 'string' ? args.out : `.github/workflows/kaloko-${scenario.id.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${envName}.yml`)
+    if (existsSync(out) && !args.force) throw new UserError(`${relative(process.cwd(), out)} exists; pass --force to replace it (or --print to compare).`)
+    await mkdir(dirname(out), { recursive: true })
+    await writeFile(out, content)
+    say(`Wrote ${relative(process.cwd(), out)}: ${scenario.id} on ${envName} ${every === 'week' ? 'every week' : 'every day'} at ${String(atHour(args.at)).padStart(2, '0')}:00 UTC with the full walk (clicks, forms, every criterion).\nNext: add the repository secret KALOKO_TOKEN${secretNames(env, scenario).length ? ` and ${secretNames(env, scenario).join(', ')}` : ''}, then commit the workflow.`)
+    return { file: out }
+  }
+  if (!org) throw new UserError('Set org: in the config first.')
+  if (sub === 'list' || !sub) {
+    const data = await client().request('GET', `/orgs/${org}/schedules`)
+    if (args.json) { say(JSON.stringify(data, null, 2)); return data }
+    if (!data.configured) { say('Hosted runs are not enabled on this service. Walk on a schedule in CI: kaloko schedule export github --scenario <file> --env <name>'); return data }
+    say(`${data.usage.pages} of ${data.usage.budget} hosted pages used in ${data.usage.month}${data.plan_allows ? '' : ' (hosted runs come with the Business plan)'}`)
+    say(data.schedules.length ? data.schedules.map(scheduleLine).join('\n') : 'No schedules yet: kaloko schedule add --scenario <file> --env <name> --every day')
+    return data
+  }
+  if (sub === 'add') {
+    const file = typeof args.scenario === 'string' ? resolve(root, args.scenario) : null
+    if (!file) throw new UserError('--scenario <file> names a read-only scenario.')
+    const envName = typeof args.env === 'string' ? args.env : null
+    if (!envName) throw new UserError('--env <name> names the environment (its base_url is what the hosted browser opens).')
+    const scenario = await deps.loadScenario(file)
+    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 })
+    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 }) }
+    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.`)
+    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
+  }
+  if (!id) throw new UserError(`Usage: kaloko schedule ${sub} <schedule id> (kaloko schedule list shows them)`)
+  const path = `/orgs/${org}/schedules/${encodeURIComponent(id)}`
+  if (sub === 'run') { await client().request('POST', `${path}/run`); say(`✓ ${id} starts within 15 minutes; the run lands in your inbox.`); return }
+  if (sub === 'pause' || sub === 'resume') { const s = await client().request('PATCH', path, { enabled: sub === 'resume' }); say(`✓ ${id} ${s.enabled ? `resumed: ${when(s)}` : 'paused'}`); return s }
+  if (sub === 'remove') { await client().request('DELETE', path); say(`✓ ${id} removed; its runs stay.`); return }
+  throw new UserError('Usage: kaloko schedule add|list|run|pause|resume|remove|export github (kaloko help)')
+}

package/src/lib/keyboard.mjs

@@ -14,14 +14,23 @@ function describeFocus () {
   const path = (e) => { const p = []; for (; e && e.nodeType === 1; e = e.parentElement || e.getRootNode()?.host) { let i = 1; for (let s = e.previousElementSibling; s; s = s.previousElementSibling) i++; p.unshift(`${e.tagName.toLowerCase()}:${i}`) } return p.join('/') }
   const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim()
   const name = clean(el.getAttribute('aria-label') || (el.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean).map((i) => document.getElementById(i)?.innerText || '').join(' ') || el.innerText || el.getAttribute('alt') || el.getAttribute('title') || el.value || el.getAttribute('placeholder') || [...el.querySelectorAll('img[alt]')].map((i) => i.alt).join(' '))
-  const r = el.getBoundingClientRect(); const cs = getComputedStyle(el)
+  // a visually hidden radio or checkbox shows itself and its focus through its label (segmented switches)
+  let shown = el
+  const own = getComputedStyle(el); const ob = el.getBoundingClientRect()
+  // a small radio or checkbox inside its label: the label is the control people see, and its focus style lives there
+  const wrap = el.labels && [...el.labels].find((l) => l.contains(el))
+  if (wrap && ob.width <= 16 && ob.height <= 16) { const b = wrap.getBoundingClientRect(); if (b.width > ob.width && b.height > 0) shown = wrap }
+  if (shown === el && el.labels && el.labels.length && (Number(own.opacity) <= 0.05 || ob.width < 2 || ob.height < 2)) shown = [...el.labels].find((l) => { const b = l.getBoundingClientRect(); return b.width > 0 && b.height > 0 && getComputedStyle(l).visibility !== 'hidden' }) || el
+  const r = shown.getBoundingClientRect(); const cs = getComputedStyle(shown)
   let fixed = false
   for (let e = el; e && e.nodeType === 1; e = e.parentElement) { const p = getComputedStyle(e).position; if (p === 'fixed' || p === 'sticky') { fixed = true; break } }
   const visible = r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && Number(cs.opacity) > 0.05 && r.right + scrollX > 0 && r.bottom + scrollY > 0
   const inView = r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth
   let obscured = false
   if (visible && inView) {
-    const hit = document.elementFromPoint(Math.min(innerWidth - 1, Math.max(0, r.left + r.width / 2)), Math.min(innerHeight - 1, Math.max(0, r.top + r.height / 2)))
+    // an inline link wrapped over lines: test its first line box, not the middle of the bounding box (a neighbour may sit there)
+    const line = getComputedStyle(el).display === 'inline' && el.getClientRects().length > 1 ? el.getClientRects()[0] : r
+    const hit = document.elementFromPoint(Math.min(innerWidth - 1, Math.max(0, line.left + line.width / 2)), Math.min(innerHeight - 1, Math.max(0, line.top + line.height / 2)))
     obscured = !!hit && !(hit === el || el.contains(hit) || hit.contains(el) || (el.labels && [...el.labels].some((l) => l.contains(hit))))
   }
   const cls = typeof el.className === 'string' && el.className.trim() ? '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.') : ''
@@ -30,7 +39,10 @@ function describeFocus () {
     desc: `${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}${cls}`,
     x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height),
     visible, fixed, obscured, dialog: !!el.closest('dialog[open], [aria-modal=true]'), main: !!el.closest('main, [role=main]'),
-    tabindex: el.getAttribute('tabindex')
+    tabindex: el.getAttribute('tabindex'),
+    // focus inside content the page cannot see into: an iframe, or an element that is not focusable itself (the host
+    // of a closed shadow tree, e.g. a third-party widget wrapping its own iframe)
+    embedded: el.tagName === 'IFRAME' || !el.matches('a[href], area[href], button, input, select, textarea, summary, iframe, [tabindex], [contenteditable]:not([contenteditable=false])')
   }
 }
 
@@ -43,9 +55,18 @@ function focusByPath (key) {
     el = kids[i - 1]
     if (!el) return null
   }
-  el.scrollIntoView({ block: 'center', inline: 'nearest' }); el.focus({ preventScroll: true })
-  const r = el.getBoundingClientRect()
-  return { x: r.left, y: r.top, w: r.width, h: r.height, vw: innerWidth, vh: innerHeight }
+  // a visually hidden radio or checkbox: its label is what shows the focus (as in describeFocus)
+  const ob = el.getBoundingClientRect()
+  // a small radio or checkbox inside its label: the label (as in describeFocus)
+  const wrap = el.labels && [...el.labels].find((l) => l.contains(el))
+  const wb = wrap && ob.width <= 16 && ob.height <= 16 ? wrap.getBoundingClientRect() : null
+  const shown = wb && wb.width > ob.width && wb.height > 0 ? wrap : el.labels && el.labels.length && (Number(getComputedStyle(el).opacity) <= 0.05 || ob.width < 2 || ob.height < 2) ? [...el.labels].find((l) => { const b = l.getBoundingClientRect(); return b.width > 0 && b.height > 0 }) || el : el
+  shown.scrollIntoView({ block: 'center', inline: 'nearest' }); el.focus({ preventScroll: true })
+  const r = shown.getBoundingClientRect()
+  // an inline element wrapped over lines draws its ring around each line box: their outlines, not the bounding box
+  const rects = getComputedStyle(shown).display === 'inline' ? [...shown.getClientRects()].filter((q) => q.width > 0 && q.height > 0) : []
+  const lines = rects.length > 1 ? Math.round(rects.reduce((sum, q) => sum + 2 * (q.width + q.height), 0)) : null
+  return { x: r.left, y: r.top, w: r.width, h: r.height, vw: innerWidth, vh: innerHeight, lines }
 }
 
 // In the page: static facts for the order check (positive tabindex, controls taken out of the tab order, click-only).
@@ -53,7 +74,11 @@ function orderFacts () {
   const visible = (e) => { const r = e.getBoundingClientRect(); const cs = getComputedStyle(e); return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' }
   const d = (e) => `${e.tagName.toLowerCase()}${e.id ? '#' + e.id : ''}${typeof e.className === 'string' && e.className.trim() ? '.' + e.className.trim().split(/\s+/).slice(0, 2).join('.') : ''}`
   const pos = [...document.querySelectorAll('[tabindex]')].filter((e) => Number(e.getAttribute('tabindex')) > 0 && visible(e))
-  const removed = [...document.querySelectorAll('a[href][tabindex^="-"], button[tabindex^="-"], input[tabindex^="-"]:not([type=hidden]), select[tabindex^="-"], textarea[tabindex^="-"]')].filter((e) => visible(e) && !e.closest('[aria-hidden=true], [inert]'))
+  // roving tabindex (WAI-ARIA composite widgets: tabs, radio groups, toolbars, menus, listboxes, grids, trees): the
+  // widget is one tab stop and arrow keys move inside it, so its other items rightly carry tabindex="-1"
+  const widget = '[role=tablist], [role=radiogroup], [role=toolbar], [role=menu], [role=menubar], [role=listbox], [role=grid], [role=treegrid], [role=tree]'
+  const roving = (e) => { const w = e.parentElement && e.parentElement.closest(widget); return !!w && [...w.querySelectorAll('a[href], button, input, select, textarea, [tabindex]')].some((x) => x !== e && x.closest(widget) === w && !x.disabled && !/^-/.test(x.getAttribute('tabindex') || '') && visible(x)) }
+  const removed = [...document.querySelectorAll('a[href][tabindex^="-"], button[tabindex^="-"], input[tabindex^="-"]:not([type=hidden]), select[tabindex^="-"], textarea[tabindex^="-"]')].filter((e) => visible(e) && !e.closest('[aria-hidden=true], [inert]') && !roving(e))
   const clickOnly = [...document.querySelectorAll('[role=button], [role=link], [role=tab], [role=menuitem], [role=checkbox], [onclick]')].filter((e) => visible(e) && !e.matches('a[href], button, input, select, textarea, summary, [tabindex], [contenteditable=true]') && !e.closest('a[href], button'))
   const box = (e) => { const r = e.getBoundingClientRect(); return { x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), w: Math.round(r.width), h: Math.round(r.height) } }
   return { positive: pos.slice(0, 5).map(d), positiveCount: pos.length, removed: removed.slice(0, 5).map(d), removedCount: removed.length, clickOnly: clickOnly.slice(0, 5).map(d), clickOnlyCount: clickOnly.length, boxes: [...removed, ...clickOnly].slice(0, 5).map(box), innerHeight }
@@ -97,8 +122,9 @@ export function focusDelta (focusedPng, plainPng) {
 }
 
 /** Verdict of one focus stop from its delta and size: ok, weak (below 3:1), none (no visible change). */
-export function focusVerdict (delta, w, h) {
-  const perimeter = 2 * (Math.max(1, w) + Math.max(1, h))
+export function focusVerdict (delta, w, h, edge = null) {
+  // edge: the length of the element's outline inside the viewport (a tall panel shows only its sides)
+  const perimeter = edge > 0 ? edge : 2 * (Math.max(1, w) + Math.max(1, h))
   if (delta.strong >= perimeter * 0.75) return 'ok'
   if (delta.changed >= perimeter * 0.5) return 'weak'
   return 'none'
@@ -136,7 +162,8 @@ export async function keyboardChecks (page, criteria, { maxStops = 60, focusChec
         const f = await page.evaluate(describeFocus).catch(() => null)
         if (!f) { keyboard.complete = true; break } // focus went back to the browser: the whole page was walked
         if (stops.length && f.key === stops[0].key) { keyboard.complete = true; break }
-        if (f.tag === 'iframe') { if (stops.at(-1)?.key === f.key) { if (++iframeRun > 30) break; continue } } else iframeRun = 0
+        // Tab moves inside an iframe or a closed widget while the page still reports the same element: count it once
+        if (f.embedded) { if (stops.at(-1)?.key === f.key) { if (++iframeRun > 30) break; continue } } else iframeRun = 0
         if (seen.has(f.key)) { const from = seen.get(f.key); const cycle = stops.slice(from); trap = { at: from, size: cycle.length, dialog: cycle.every((s) => s.dialog), first: cycle[0] }; break }
         seen.set(f.key, stops.length)
         stops.push(f)
@@ -196,7 +223,7 @@ export async function keyboardChecks (page, criteria, { maxStops = 60, focusChec
       // visible focus: each stop focused and unfocused, the same area compared (keyboard modality stays on)
       const verdicts = new Map()
       if (want.has('a11y_focus_visible') || shots > 0) {
-        const candidates = stops.map((s, i) => ({ s, n: i + 1 })).filter(({ s }) => s.visible && s.tag !== 'iframe').slice(0, Math.max(want.has('a11y_focus_visible') ? focusChecks : 0, shots))
+        const candidates = stops.map((s, i) => ({ s, n: i + 1 })).filter(({ s }) => s.visible && !s.embedded).slice(0, Math.max(want.has('a11y_focus_visible') ? focusChecks : 0, shots))
         for (const { s, n } of candidates) {
           const pos = await page.evaluate(focusByPath, s.key).catch(() => null)
           if (!pos || !pos.w || !pos.h) continue
@@ -212,7 +239,10 @@ export async function keyboardChecks (page, criteria, { maxStops = 60, focusChec
           await page.evaluate(() => { let a = document.activeElement; while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement; a?.blur?.() })
           const plain = await page.screenshot({ clip, scale: 'css', animations: 'disabled', caret: 'hide' })
           const delta = focusDelta(focused, plain)
-          verdicts.set(n, { v: s.obscured ? 'obscured' : focusVerdict(delta, pos.w, pos.h), contrast: delta.contrast })
+          // only the edges of the element inside the viewport can show the indicator
+          const vw = Math.min(pos.vw, pos.x + pos.w) - Math.max(0, pos.x); const vh = Math.min(pos.vh, pos.y + pos.h) - Math.max(0, pos.y)
+          const edge = (pos.y >= 0 ? vw : 0) + (pos.y + pos.h <= pos.vh ? vw : 0) + (pos.x >= 0 ? vh : 0) + (pos.x + pos.w <= pos.vw ? vh : 0)
+          verdicts.set(n, { v: s.obscured ? 'obscured' : focusVerdict(delta, pos.w, pos.h, pos.lines || edge), contrast: delta.contrast })
         }
         if (want.has('a11y_focus_visible')) {
           const bad = [...verdicts].filter(([, x]) => x.v !== 'ok')

package/src/lib/onboarding.mjs

@@ -14,7 +14,7 @@ export const sampleUrl = (base, org) => `${String(base).replace(/\/$/, '')}/${or
  * Lines printed at the end of `kaloko init`. `devServer` ({ command, url }) when init found the app's dev server but it
  * is not answering yet; `scenario` the path of the first scenario init drafted, which then is the first real flow.
  */
-export function initNextSteps ({ base, org, loggedIn = false, devServer = null, scenario = null }) {
+export function initNextSteps ({ base, org, loggedIn = false, devServer = null, scenario = null, products = false }) {
   const o = realOrg(org)
   const steps = [
     loggedIn ? 'Signed in already (KALOKO_TOKEN found).' : 'npx kaloko login   (approve a token in the browser; or put KALOKO_TOKEN from Settings → API tokens into .env)'
@@ -23,6 +23,8 @@ export function initNextSteps ({ base, org, loggedIn = false, devServer = null,
   steps.push(o ? `Try a review on the sample run: ${sampleUrl(base, o)}` : 'Set org: in kaloko.config.yml, then open <service>/<org>/sample to try a review on the sample run.')
   if (scenario) steps.push(`Your first real flow: npx kaloko start --scenario ${scenario} --env local && npx kaloko walk`)
   else steps.push('Your first real flow: npx kaloko draft <your app URL>   (public pages), or ask your agent:', `   "${FIRST_FLOW_PROMPT}"`)
+  // products: in the config show up in the app (Products) once they are on Kaloko, before any release
+  if (products) steps.push('Put the products of kaloko.config.yml on Kaloko: npx kaloko products sync   (they show under Products with their changelog and docs)')
   const lines = ['Next:']
   let n = 0
   for (const s of steps) lines.push(s.startsWith('   "') ? `  ${s}` : `  ${++n}. ${s}`)

package/src/lib/screens-cli.mjs

@@ -0,0 +1,36 @@
+// `kaloko screens`: the screen library from the terminal (batch G): the newest capture of every step of the
+// organization's flows, searched on the service (GET /orgs/<org>/screens), one line per screen with its canvas link.
+import { UserError } from './util.mjs'
+
+const FILTERS = ['project', 'product', 'module', 'scenario', 'locale', 'viewport', 'device', 'status', 'environment', 'limit', 'cursor']
+
+/** The query string of a search from CLI arguments: words are the query, --designs adds design versions. */
+export function screensQuery (args) {
+  const p = new URLSearchParams()
+  const q = (args._ || []).join(' ').trim() || (typeof args.q === 'string' ? args.q : '')
+  if (q) p.set('q', q)
+  for (const k of FILTERS) if (typeof args[k] === 'string' || typeof args[k] === 'number') p.set(k, String(args[k]))
+  if (args.designs || args.source === 'all') p.set('source', 'all')
+  else if (args.source === 'design') p.set('source', 'design')
+  if (args.all) p.set('group', 'none')
+  return p
+}
+
+export function formatScreens (r) {
+  if (!r.items.length) return 'No screen matches.'
+  const lines = r.items.map((it) => {
+    const where = [it.locale, it.viewport].filter(Boolean).join('/')
+    const st = it.status ? `${it.status}`.padEnd(8) : ''.padEnd(8)
+    const tag = it.source === 'design' ? ` [design${it.version ? ` v${it.version}` : ''}]` : ''
+    return `${st} ${it.scenario.id}/${it.step.id} ${where}${tag}  ${it.step.title || ''}${it.url ? `  ${it.url}` : it.path ? `  ${it.path}` : ''}\n         ${it.canvas}`
+  })
+  if (r.next) lines.push(`… more: kaloko screens ${r.filters?.q ? `"${r.filters.q}" ` : ''}--cursor ${r.next}`)
+  return lines.join('\n')
+}
+
+export async function screensCmd ({ config, client, args, say }) {
+  if (!config.org) throw new UserError('Set org: in kaloko.config.yml (or run kaloko login) to search the screen library.')
+  const r = await client.request('GET', `/orgs/${config.org}/screens?${screensQuery(args)}`)
+  say(args.json ? JSON.stringify(r, null, 2) : formatScreens(r))
+  return r
+}

package/src/lib/service.mjs

@@ -7,13 +7,26 @@ export function serviceUrl (config, vars = process.env) {
   return url.replace(/^https:\/\/app\.qawalk\.com$/, 'https://kaloko.app')
 }
 
+/** Which CI runs this (github, gitlab, …), or null on a laptop: the service counts a team's first run from CI. */
+export function ciName (vars = process.env) {
+  if (vars.GITHUB_ACTIONS === 'true') return 'github'
+  if (vars.GITLAB_CI) return 'gitlab'
+  if (vars.CIRCLECI) return 'circleci'
+  if (vars.BUILDKITE) return 'buildkite'
+  if (vars.JENKINS_URL) return 'jenkins'
+  if (vars.BITBUCKET_BUILD_NUMBER) return 'bitbucket'
+  if (vars.TF_BUILD) return 'azure'
+  return vars.CI && vars.CI !== 'false' ? 'ci' : null
+}
+
 export function service (config) {
   const base = serviceUrl(config) + '/api/v1'
   const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
   const token = process.env[tokenEnv]
   if (!token) throw new UserError(`Set ${tokenEnv} (create a token in Kaloko → Settings).`)
   // an agent names itself (KALOKO_AGENT, e.g. "claude-code"); the service shows it in presence, history and audit (#42)
-  const headers = { Authorization: `Bearer ${token}`, ...(process.env.KALOKO_AGENT ? { 'X-QAwalk-Agent': process.env.KALOKO_AGENT.slice(0, 60) } : {}) }
+  const ci = ciName()
+  const headers = { Authorization: `Bearer ${token}`, ...(process.env.KALOKO_AGENT ? { 'X-QAwalk-Agent': process.env.KALOKO_AGENT.slice(0, 60) } : {}), ...(ci ? { 'X-Kaloko-CI': ci } : {}) }
   const check = async (res, what) => {
     if (res.ok) return res.json()
     const body = await res.json().catch(() => ({}))
@@ -36,6 +49,12 @@ export function service (config) {
       const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
       return check(res, `${method} ${path}`)
     },
+    /** A request whose answer is not JSON (an export): the response, or an error with the service's message. */
+    async raw (method, path, body) {
+      const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
+      if (!res.ok) { const b = await res.json().catch(() => ({})); throw new UserError(`${method} ${path} → HTTP ${res.status}: ${b.error || res.statusText}`) }
+      return res
+    },
     async fetch (path) {
       const res = await fetch(base + path, { headers })
       if (!res.ok) { const body = await res.json().catch(() => ({})); throw new UserError(`GET ${path} → HTTP ${res.status}: ${body.error || res.statusText}`) }