kaloko 0.6.0 → 0.7.1

package/README.md

@@ -8,8 +8,8 @@ e-mail of the flow, checks the criteria and lays the whole flow out on a
 canvas: screens, branches, locales and evidence. People review and approve it
 there, and the newest captures double as documentation.
 
-- Product and guides: <https://kaloko.app>
-- Service (organizations, shared canvases, reviews): <https://kaloko.app>
+- Product, pricing and the service (organizations, shared canvases, reviews): <https://kaloko.app>
+- Guides: <https://kaloko.app/guides>
 
 Pages are walked in Chromium, WebKit and Firefox, on phone, tablet and
 desktop presets, in light and dark mode. Native apps too: Android, iOS,
@@ -201,6 +201,18 @@ what still waits for a person, so it can pass the link on. Agents never
 approve for people: their decisions are marked and do not count as a
 person's.
 
+To see what moved, compare a step with the accepted run side by side, as a
+pixel diff, with *Swipe* or with *Onion skin*; `G` shows one step in every
+locale and viewport at once. Comments can carry a box, an arrow or a line
+drawn on the screenshot. On Business and Enterprise an accepted run has a
+signed acceptance record (who approved what and when, criteria results,
+screenshot hashes) as PDF and JSON:
+
+```bash
+npx kaloko signoff <run-id> --out handover/   # download and check the record
+npx kaloko signoff --verify record.pdf         # check one someone handed you; no token needed
+```
+
 Every AI verdict comes with one sentence saying why. Criteria marked
 `vision: true`, and answers the text evaluator is unsure about, get a second
 look at the screenshot from a vision model (`ANTHROPIC_API_KEY`, or through
@@ -208,7 +220,8 @@ Kaloko); `kaloko build` lists what to act on with the score and the reason.
 The `a11y` pack walks the page with Tab (order, visible focus, traps, skip
 link) and reads names from the accessibility tree. Pixel diffs skip the
 regions a step ignores; `kaloko walk --stability 3` and `kaloko stability`
-find the clocks, ads and carousels worth ignoring.
+find the clocks, ads and carousels worth ignoring, and `kaloko stability --pull`
+brings in the regions reviewers marked on kaloko.app.
 
 ## A changelog with pictures
 
@@ -236,7 +249,9 @@ kaloko.app has a slider between before and after, switches language and
 screen size, and links each picture to its flow on the canvas. Share it with
 guests, readers from your company's domain, or publish it with a feed.
 Repositories with several apps list them under `products:` in
-`kaloko.config.yml`.
+`kaloko.config.yml`; `npx kaloko products sync` puts them on Kaloko before the
+first release, and Products in the app's menu lists each with its newest
+version, changelog and docs (`npx kaloko products list` in the terminal).
 
 When release-please, changesets or semantic-release makes your releases,
 `npx kaloko ci github --release` adds a workflow that records each published
@@ -274,12 +289,13 @@ back to the step. When it is done in the tracker, the comment on the step is
 resolved. A branch or pull request title that names the issue (`WEB-12`, or
 Linear's `eng-42`) links the run to it. Slack and Teams channels are chosen per
 project in Settings → Integrations, with the events each channel wants and
-quiet hours.
+quiet hours. Both come with the Team plan and up.
 
 ## Pages checked on a schedule
 
 A read-only scenario of public or gated pages can run on Kaloko's own
-browsers every morning, with nobody starting the CLI (Business plan):
+browsers every morning, with nobody starting the CLI (Business: 2,000 pages a
+month, Enterprise: 10,000):
 
 ```bash
 npx kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
@@ -297,8 +313,8 @@ Design the screens of a flow as live HTML with your own agent and skills, in the
 and QA use. A design environment (`kind: design`, a folder of steps) is walked and synced into a shared draft the
 team sees live; `kaloko share` there publishes a version of the flow (unchanged steps are stored once). An
 accepted version becomes the design reference, and `packs: [design]` checks every implementation run against
-it (pixels, structure, tokens, contrast). See `skills/kaloko/reference/design.md`, `docs/GLOSSARY.md` and
-`docs/SURFACES.md`.
+it (pixels, structure, tokens, contrast). Details: `skills/kaloko/reference/design.md` in the package and the
+[design guides](https://kaloko.app/guides/design-with-your-agent).
 
 ```bash
 npx kaloko start --scenario qa/flows/checkout.yml --env design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",

package/skills/kaloko/SKILL.md

@@ -76,7 +76,9 @@ with `--theirs`). Move to the trash runs you uploaded in this session that
 were superseded before anyone looked at them (debug rounds: no comments, no
 verdict), and run `kaloko prune` without `--yes` to see what a clean-up would do.
 Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
---apply`) and add step references to it and to guides. Write, translate and fix
+--apply`) and add step references to it and to guides. Put the products of the
+config on Kaloko (`kaloko products sync`: it records no release) and list them
+(`kaloko products list`). Write, translate and fix
 guides in the docs folder, run `kaloko docs check`, and export them for a docs
 site (`kaloko export --format …`) into a local folder.
 
@@ -118,13 +120,12 @@ they can do; never write secrets into the config, a scenario or a script.
 - Many pages of one template in one step (articles, products, an SEO
   catalogue from a sitemap or a listing), with an index on the canvas:
   [reference/stacks.md](reference/stacks.md)
-- Choosing playwright, agent or manual per step, and driving the shared
-  browser with your capabilities: [reference/execution.md](reference/execution.md)
-- Evaluation, thresholds, the vision evaluator and its reasons, reading
-  results: [reference/evaluation.md](reference/evaluation.md)
+- Choosing playwright, agent or manual per step, driving the shared
   browser with your capabilities, walking only the steps a change reaches
   (`--affected`), several locales at once, and selectors that moved
   (`--heal`): [reference/execution.md](reference/execution.md)
+- Evaluation, JEV thresholds, the vision evaluator and its reasons, reading
+  results: [reference/evaluation.md](reference/evaluation.md)
 - Screenshots, walkthroughs, Playwright reports and traces that an agent or a
   tool already produced, laid out as a run: [reference/import.md](reference/import.md)
 - Video of a step or a whole flow, traces (actions, requests, console) and the
@@ -132,12 +133,12 @@ they can do; never write secrets into the config, a scenario or a script.
   [reference/recording.md](reference/recording.md)
 - CI: a workflow that walks each pull request's preview deployment and
   comments on it (`kaloko ci github|gitlab`): [reference/ci.md](reference/ci.md)
-- Evaluation, JEV thresholds and reading results: [reference/evaluation.md](reference/evaluation.md)
 - Environments, access (gates, accounts, sign-in), e-mails, readonly and
   production rules, and what is yours to arrange for the project's stack:
   [reference/environments.md](reference/environments.md)
 - Sharing, review mode and approvals carried over unchanged steps, reviewer
-  feedback, mentions, inbox, verdicts and baselines, and cleaning up runs
+  feedback, mentions, inbox, verdicts and baselines, compare views, the
+  signed acceptance record (`kaloko signoff`), and cleaning up runs
   (trash, prune, keep, archive):
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
@@ -149,7 +150,7 @@ they can do; never write secrets into the config, a scenario or a script.
 - The visual changelog and guides with step references (`kaloko:<scenario>/<step>`):
   drafting the Unreleased entry, Diátaxis templates, translations, stale sections
   and `kaloko docs check`, training guides, exports, release tools in CI,
-  products, modules and versions, who reads it:
+  products, modules and versions (`kaloko products sync|list`), who reads it:
   [reference/docs.md](reference/docs.md)
 - Refreshing a manual, course or product documentation from the newest
   captures (latest URLs, changed steps, webhooks, export):

package/skills/kaloko/reference/docs.md

@@ -231,6 +231,13 @@ reads its entry and never rewrites the file; put your draft into the pull reques
 
 `kaloko doctor` warns when a product's version cannot be read or a scenario names no product while several exist.
 
+A product shows in the app (Products in the main menu, `/<org>/products`) once it is on Kaloko. `kaloko release` and
+`kaloko docs publish` put it there; to put the products of the config there before their first release, run
+`kaloko products sync` (`--product p` for one, `--dry-run` to see what it would send). It records no release, and
+`publish:` still needs an admin of the product's projects. `kaloko products list` shows the products on Kaloko with
+their newest version and docs, and names those of the config that are not there yet. After adding or renaming a
+product in the config, run `kaloko products sync` and say so in your summary.
+
 ## Readers
 
 The changelog page (`/<org>/products/<product>/changelog`, or `/<org>/projects/<project>/changelog`) and the docs
@@ -241,6 +248,6 @@ page. Never publish without the person asking.
 
 ## MCP
 
-`get_changelog` (releases with entries; `resolve: true` adds the pictures), `draft_changelog_entry` (the service's
+`list_products` (the products the caller reads, with the newest release, docs and readers), `get_changelog` (releases with entries; `resolve: true` adds the pictures), `draft_changelog_entry` (the service's
 half of a draft: changed screens with before/after references), `resolve_step_image` (one reference),
 `docs_check` (what needs attention in the published docs), `get_docs` (the docs, or one page).

package/skills/kaloko/reference/mcp.md

@@ -33,6 +33,7 @@ file.
 | `decide_step` | records your (the agent's) decision on a step: `approve`, or `return` with a `note`; marked as an agent's and not counted as a person's. Never use it to approve for a person |
 | `revoke_carried_approval` | revokes an approval carried over to a step that looks unchanged but should be looked at again (`run_id`, `step`) |
 | `get_step_assets` | documentation layer (Business): newest capture of every step of a scenario with stable image, HTML and metadata URLs (`scenario`, `step`, `locale`, `viewport`, `accepted`) |
+| `list_products` | the products the caller reads: name, modules, the projects it maps that the caller sees, the newest release, published docs (versions, languages), who reads it (and the public link), whether the caller manages it, links to its page, changelog and docs |
 | `get_changelog` | the visual changelog of a product (`product`, `version`, `resolve: true` for the pictures, `limit`): releases newest first with the entry as written and its groups; see [docs.md](docs.md) |
 | `draft_changelog_entry` | what accepted runs since the last release (or `since`) show differently, as a Keep a Changelog draft with before/after step references (`product`, `since`) |
 | `resolve_step_image` | one step reference (`ref` = `kaloko:<scenario>/<step>?…`, `product`, `version`, `locale`, `viewport`) as a signed image URL with its run, how the version was found and canvas links |

package/src/cli.mjs

@@ -259,6 +259,15 @@ Hosted runs (read-only scenarios on Kaloko's browsers, Business plan)
   schedule export github --scenario <file> --env <name> [--every day|week] [--at 5] [--out file] [--print]
                                     A GitHub Actions workflow that walks the scenario on a schedule with the full CLI
 
+Products (products: in kaloko.config.yml; without it the project is the product)
+  products sync [--product p] [--dry-run] [--json]
+                                    Put the products of the config on Kaloko: name, projects, modules, version
+                                    source, reference environment and default scenario, without recording a
+                                    release. They show under Products in the app with their changelog and docs;
+                                    publish: is applied only for an admin of the product's projects
+  products list [--json]            The products on Kaloko you read: newest release, docs, who reads them, and
+                                    the products of the config that are not on Kaloko yet
+
 Changelog (Keep a Changelog in CHANGELOG.md; pictures are step references kaloko:<scenario>/<step>)
   changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]
                                     The Unreleased entry since the last release: merged pull requests and commits
@@ -970,7 +979,7 @@ const commands = {
     try { written = await readFile(existsSync(file) ? file : join(cwd, LEGACY_CONFIG_FILE), 'utf8') } catch {}
     const org = typeof args.org === 'string' ? args.org : (written.match(/^org:\s*["']?([a-z0-9-]+)["']?\s*$/m) || [])[1]
     const base = serviceUrl({ share: { url: (written.match(/^share:[ \t]*\n(?:[ \t]+.*\n)*?[ \t]+url:[ \t]*["']?(https?:\/\/[^\s"']+)/m) || [])[1] } })
-    say(initNextSteps({ base, org, loggedIn: !!process.env.KALOKO_TOKEN, devServer: detected && !running ? detected : null, scenario: first && relative(cwd, first) }).join('\n'))
+    say(initNextSteps({ base, org, loggedIn: !!process.env.KALOKO_TOKEN, devServer: detected && !running ? detected : null, scenario: first && relative(cwd, first), products: /^products:/m.test(written) }).join('\n'))
     say(`Scenario template: ${join(packageRoot, 'templates', 'scenario.yml')}`)
   },
 
@@ -1187,7 +1196,12 @@ const commands = {
       if (lint.errors || lint.warnings) say(`\nPortable HTML: ${lint.errors} error(s), ${lint.warnings} warning(s); kaloko design lint lists them${lint.errors ? ' (errors stop kaloko sync: they break on the live step)' : ''}.`)
       return
     }
-    if (isApp(scenario.platform)) return walkApp({ config, root, run, scenario, env, args })
+    if (isApp(scenario.platform)) {
+      await walkApp({ config, root, run, scenario, env, args })
+      // an app walk ends with the verdicts like a web walk (--no-evaluate skips them; kaloko evaluate redoes them)
+      if (!args['no-evaluate']) await walkVerdicts({ prefetch: { done: async () => {} }, run, scenario, config, root })
+      return
+    }
     const pick = list(args.steps)
     const locales = list(args.locales) || run.meta.scope.locales
     const scope = run.meta.scope
@@ -2289,6 +2303,24 @@ const commands = {
     if (!r.ok || (args.strict && r.warnings)) process.exitCode = 1
   },
 
+  /** `kaloko products sync|list`: the products of the config on Kaloko, without a release; what the service has. */
+  async products (args) {
+    const sub = args._[0]
+    if (!['sync', 'list'].includes(sub)) throw new UserError('Usage: kaloko products sync [--product p] [--dry-run] [--json]\n       kaloko products list [--json]')
+    const { config, root } = await context(args)
+    const lib = await import('./lib/changelog.mjs')
+    if (sub === 'list') {
+      if (!config.org) throw new UserError('Set org: in the config first.')
+      const r = await lib.listProducts({ root, config, client: service(config) })
+      say(args.json ? JSON.stringify(r, null, 2) : lib.formatList(r))
+      return
+    }
+    if (!config.org && !args['dry-run']) throw new UserError('Set org: in the config first.')
+    const r = await lib.syncProducts({ root, config, client: args['dry-run'] ? null : service(config), only: typeof args.product === 'string' ? args.product : null, dryRun: !!args['dry-run'] })
+    say(args.json ? JSON.stringify(r, null, 2) : lib.formatSync(r))
+    if (r.products.some((p) => p.ok === false)) process.exitCode = 1
+  },
+
   /** `kaloko release <version>`: the version's changelog entry and its reference runs on the service. */
   async release (args) {
     const { config, root } = await context(args)

package/src/lib/changelog.mjs

@@ -273,6 +273,76 @@ export async function productPayload (root, product, src) {
   return { slug: product.slug, name: product.name, projects: product.projects, modules: product.modules, reference_env: product.reference_env, default_scenario: product.default_scenario, implicit: product.implicit, version_source: { source: src.source, ...(src.path ? { path: src.path } : {}), pattern: src.pattern, ...(src.tool ? { tool: src.tool } : {}) }, ...(product.publish ? { publish: product.publish } : {}), ...(await repoUrl(root)) }
 }
 
+// ---------- products on the service ----------
+
+/**
+ * `kaloko products sync`: every product of the config (or the one asked for) on Kaloko with its name, projects,
+ * modules, version source, reference environment, default scenario and who should read it (publish:, which the
+ * service applies only for someone who manages the product), without recording a release. A product the service
+ * refuses (a project it does not know or the person may not map) is reported and the others still go.
+ */
+export async function syncProducts ({ root, config, client = null, only = null, dryRun = false }) {
+  const all = productsOf(config, root)
+  if (typeof only === 'string' && only && !all.some((p) => p.slug === only)) throw new UserError(`No product ${only} in the config (${all.map((x) => x.slug).join(', ')}).`)
+  const out = []
+  for (const product of all.filter((p) => !only || p.slug === only)) {
+    const src = await detectVersionSource(root, product)
+    const payload = await productPayload(root, product, src)
+    const item = { slug: product.slug, implicit: product.implicit, name: product.name, projects: product.projects, modules: product.modules, version_source: payload.version_source, version: src.version || null, payload }
+    if (dryRun) { out.push(item); continue }
+    try {
+      const saved = await client.request('POST', `/orgs/${config.org}/products`, payload)
+      out.push({ ...item, ok: true, created: saved.created ?? null, publish: saved.product?.publish || null, url: saved.page || saved.url || null, changelog: saved.url || null, notes: saved.notes || [] })
+    } catch (e) { out.push({ ...item, ok: false, error: String(e.message || e).split('\n')[0] }) }
+  }
+  return { dry_run: dryRun, from_config: !!Object.keys(config.products || {}).length, products: out }
+}
+
+/** What `kaloko products sync` did, for people. */
+export function formatSync (r) {
+  const lines = []
+  const n = r.products.length
+  lines.push(r.dry_run ? `${n} product(s) would go to Kaloko; dry run, nothing sent.` : `${r.products.filter((p) => p.ok).length} of ${n} product(s) on Kaloko; no release recorded.`)
+  if (!r.from_config) lines.push('  No products: in kaloko.config.yml, so the project is the product (its own changelog and docs).')
+  for (const p of r.products) {
+    const what = [`${p.projects.length ? `projects ${p.projects.join(', ')}` : 'the whole organization'}`, p.modules.length ? `modules ${p.modules.join(', ')}` : null, `version from ${p.version_source.source}${p.version ? ` (${p.version})` : ''}`].filter(Boolean).join(' · ')
+    const name = typeof p.name === 'object' && p.name ? Object.values(p.name)[0] : p.name
+    lines.push(`  ${p.ok === false ? '✗' : r.dry_run ? '·' : p.created ? '+' : '✓'} ${p.slug}${name && name !== p.slug ? ` (${name})` : ''}: ${what}`)
+    if (p.url) lines.push(`    ${p.url}`)
+    if (p.error) lines.push(`    ! ${p.error}`)
+    for (const x of p.notes || []) lines.push(`    ! ${x}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * `kaloko products list`: the products the service has that the person reads, and the products of the config the
+ * service does not have yet (kaloko products sync puts them there).
+ */
+export async function listProducts ({ root, config, client }) {
+  const service = await client.request('GET', `/orgs/${config.org}/products`)
+  const local = Object.keys(config.products || {}).length ? productsOf(config, root) : []
+  const known = new Set(service.map((p) => p.slug))
+  return { products: service, missing: local.filter((p) => !known.has(p.slug)).map((p) => p.slug) }
+}
+
+/** The list for people. */
+export function formatList (r) {
+  const lines = []
+  if (!r.products.length) lines.push('No product on Kaloko that you read yet. kaloko products sync puts the products of kaloko.config.yml there; kaloko release and kaloko docs publish do it too.')
+  for (const p of r.products) {
+    const name = typeof p.name === 'object' && p.name ? (p.name.en || Object.values(p.name)[0]) : p.name
+    const docs = p.docs ? `docs ${p.docs.versions.join(', ')}${p.docs.languages?.length ? ` (${p.docs.languages.join(', ')})` : ''}` : 'no docs yet'
+    const rel = p.latest_release ? `${p.latest_release.version} on ${p.latest_release.released_on}` : 'no release yet'
+    lines.push(`${p.slug}${name && name !== p.slug ? ` (${name})` : ''}${p.implicit ? ' · the project\'s own' : ''}: ${rel} · ${docs} · read by ${p.readers}${p.public_url ? ` (${p.public_url})` : ''}`)
+    if (p.modules?.length) lines.push(`  modules: ${p.modules.join(', ')}`)
+    if (p.projects?.length) lines.push(`  projects: ${p.projects.join(', ')}`)
+    if (p.url) lines.push(`  ${p.url}`)
+  }
+  if (r.missing.length) lines.push(`In kaloko.config.yml but not on Kaloko yet: ${r.missing.join(', ')}. Run kaloko products sync.`)
+  return lines.join('\n')
+}
+
 async function repoUrl (root) {
   const r = await repoSlug(root)
   return r?.host === 'github' ? { repo: `https://github.com/${r.slug}` } : r?.host === 'gitlab' ? { repo: `https://gitlab.com/${r.slug}` } : {}

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}`)