kaloko 0.21.3 → 0.22.0

package/src/lib/dimensions.mjs

@@ -87,15 +87,29 @@ export function scenarioStates (scenario, pick = null) {
   return out.length > 1 ? out : null
 }
 
+/**
+ * The viewports kaloko init, kaloko draft and the templates write into a NEW scenario (#204, owner decision D4): a
+ * common Android phone width (360 CSS px; most phones in use are 360 to 414 wide, and 360 is the narrowest of them)
+ * and a laptop. No tablet by default: it adds captures most tasks do not need. An existing scenario keeps the sizes it
+ * names, and one without `viewports:` keeps UNSET_VIEWPORTS below, so no baseline changes.
+ */
+export const NEW_VIEWPORTS = Object.freeze({ desktop: [1280, 800], mobile: [360, 800] })
+/** A tablet when someone asks for one (`viewports: { …, tablet: [744, 1133] }` or the bare name `tablet`): iPad mini portrait. */
+export const TABLET_VIEWPORT = [744, 1133]
+// what a scenario without `viewports:` (and the bare names desktop and mobile) has always been captured at
+const UNSET_VIEWPORTS = { desktop: [1280, 800], mobile: [390, 844] }
+// bare names that are no device preset: the two above, and a tablet (an error before, so nothing changes for it)
+const NAMED_SIZES = { ...UNSET_VIEWPORTS, tablet: TABLET_VIEWPORT }
+
 /**
  * Viewports of a scenario: { name: [w, h] } as before, or names of device presets — as an array
  * (`[iphone-15, ipad-landscape, desktop]`) or as values (`phone: iphone-15`, `tablet: { device: ipad-portrait }`,
  * `tv: { device: tv-1080p, width: 1280, height: 720 }`). Returns { viewports: { name: [w, h] }, devices: { name: preset } }.
  * `fullScreen` (Design environments) sizes presets to the whole screen.
  */
-export function resolveViewports (spec, { fullScreen = false, fallback = { desktop: [1280, 800], mobile: [390, 844] } } = {}) {
+export function resolveViewports (spec, { fullScreen = false, fallback = NAMED_SIZES } = {}) {
   const viewports = {}; const devices = {}
-  const entries = spec == null ? Object.entries(fallback) : Array.isArray(spec) ? spec.map((s) => (typeof s === 'string' ? [s, s] : Object.entries(s)[0])) : Object.entries(spec)
+  const entries = spec == null ? Object.entries(fallback === NAMED_SIZES ? UNSET_VIEWPORTS : fallback) : Array.isArray(spec) ? spec.map((s) => (typeof s === 'string' ? [s, s] : Object.entries(s)[0])) : Object.entries(spec)
   for (const [name, value] of entries) {
     if (Array.isArray(value)) { viewports[name] = [Number(value[0]), Number(value[1])]; continue }
     const ref = typeof value === 'string' ? { device: value } : value || {}

package/src/lib/draft.mjs

@@ -2,6 +2,7 @@
 // themselves (title, description, H1, language). Read-only production scenario with the seo, a11y, perf and
 // console packs; the agent or person then sharpens purposes and criteria. No service or model call.
 import yaml from 'js-yaml'
+import { NEW_VIEWPORTS } from './dimensions.mjs'
 
 const decode = (s) => String(s || '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'").replace(/&nbsp;/g, ' ').replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
 const text = (html) => decode(String(html || '').replace(/<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim()
@@ -57,7 +58,7 @@ export function draftScenario (pages, { id, title } = {}) {
   const scenario = {
     schema: 'qawalk.scenario.v1', id: scenarioId, title: title || `Public pages of ${host}`, kind: 'flow', version: 1,
     locales: [...new Set(pages.map((p) => p.facts?.lang).filter(Boolean))].slice(0, 3).concat(pages.some((p) => p.facts?.lang) ? [] : ['en']),
-    viewports: { desktop: [1280, 800], mobile: [390, 844] },
+    viewports: { desktop: [...NEW_VIEWPORTS.desktop], mobile: [...NEW_VIEWPORTS.mobile] },
     environments: ['production'], readonly: true, lanes: ['Visitor'],
     nodes,
     edges: nodes.slice(1).map((n) => ({ from: nodes[0].id, to: n.id, label: 'visit', kind: 'alt' }))

package/src/lib/gate-cdp.mjs

@@ -0,0 +1,120 @@
+// The gate's headers per request and per redirect hop on Chromium (#224).
+//
+// Playwright applies headers given to route.continue() to every redirect the request causes and never routes the
+// redirected requests, so a gate header added there would reach a host the redirect leads to (audio on S3, an
+// identity provider). Chromium's Fetch domain pauses every redirect hop as a request of its own, so the headers can be
+// added hop by hop, only where the hop's URL is on a gate origin. The interception runs on a browser-level CDP session:
+// that one sees a request after Playwright's routing of the page (route handlers, mocks, the readonly policy), so a
+// handler's own header overrides, which Playwright repeats on every hop, never carry the gate along, and whatever
+// Playwright decided is final before the gate is added. Only URLs on gate origins are paused; a header added to a
+// hop is not carried to the next one by Chromium.
+//
+// One session per browser serves every prepared context in it; a request belongs to the context of its frame
+// (pages, popups, iframes, workers), so contexts of other environments or without a gate in the same browser are
+// left alone.
+
+const hubs = new WeakMap() // Browser → Promise<hub | null>
+
+/**
+ * Adds `gate.headers` to the context's requests to `gate.origins` (`gate.toGate` decides), per redirect hop.
+ * Resolves true when it is set up (Chromium), false when the caller has to add the headers some other way.
+ */
+export async function gateHeadersPerHop (context, gate) {
+  let browser = null
+  try { browser = context.browser?.() } catch {}
+  if (!browser || browser.browserType?.().name() !== 'chromium' || typeof browser.newBrowserCDPSession !== 'function') return false
+  if (!hubs.has(browser)) hubs.set(browser, startHub(browser).catch(() => null))
+  const hub = await hubs.get(browser)
+  if (!hub) return false
+  try { await hub.add(context, gate); return true } catch { return false }
+}
+
+/** Fetch pattern of a gate origin (`https://*.example.com` stays a wildcard); default ports are left out of URLs. */
+export function patternOf (origin) {
+  const m = String(origin).replace(/\/$/, '').match(/^(https?):\/\/(.+?)(?::(\d+))?$/)
+  if (!m) return null
+  const port = m[3] && !((m[1] === 'https' && m[3] === '443') || (m[1] === 'http' && m[3] === '80')) ? `:${m[3]}` : ''
+  return `${m[1]}://${m[2].toLowerCase()}${port}/*`
+}
+
+const hasFrame = (tree, id) => tree?.frame?.id === id || (tree?.childFrames || []).some((c) => hasFrame(c, id))
+
+async function startHub (browser) {
+  const session = await browser.newBrowserCDPSession()
+  const entries = new Set() // { context, gate, contextId }
+  const owners = new Map() // CDP frame or target id → entry
+  const pageSessions = new WeakMap()
+  const pageSession = (page) => {
+    if (!pageSessions.has(page)) pageSessions.set(page, page.context().newCDPSession(page))
+    return pageSessions.get(page)
+  }
+
+  // the browser context id of a Playwright context, from one of its pages
+  async function contextIdOf (entry) {
+    if (entry.contextId) return entry.contextId
+    for (const page of entry.context.pages()) {
+      try {
+        entry.contextId = (await (await pageSession(page)).send('Target.getTargetInfo')).targetInfo.browserContextId
+        return entry.contextId
+      } catch {}
+    }
+    return null
+  }
+
+  // the prepared context a request comes from: its frame is a target (page, popup, out-of-process iframe, worker)
+  // or a frame inside a page of one of the contexts
+  async function ownerOf (frameId) {
+    if (!frameId || !entries.size) return null
+    if (owners.has(frameId)) return owners.get(frameId)
+    const { targetInfos } = await session.send('Target.getTargets')
+    const target = targetInfos.find((t) => t.targetId === frameId)
+    for (const entry of entries) {
+      if (target) {
+        if (await contextIdOf(entry) === target.browserContextId) { owners.set(frameId, entry); return entry }
+        continue
+      }
+      for (const page of entry.context.pages()) {
+        try {
+          if (hasFrame((await (await pageSession(page)).send('Page.getFrameTree')).frameTree, frameId)) { owners.set(frameId, entry); return entry }
+        } catch {}
+      }
+    }
+    return null
+  }
+
+  async function paused (event) {
+    const entry = await ownerOf(event.frameId)
+    let headers
+    if (entry?.gate.toGate(event.request.url)) {
+      const have = new Set(Object.keys(event.request.headers).map((n) => n.toLowerCase()))
+      // headers the page set itself win, so an application's own Authorization header is left alone
+      const extra = Object.entries(entry.gate.headers).filter(([name]) => !have.has(name.toLowerCase()))
+      if (extra.length) headers = [...Object.entries(event.request.headers), ...extra].map(([name, value]) => ({ name, value: String(value) }))
+    }
+    await session.send('Fetch.continueRequest', { requestId: event.requestId, ...(headers ? { headers } : {}) })
+  }
+  session.on('Fetch.requestPaused', (event) => {
+    // a request is never left paused, whatever went wrong while looking at it
+    paused(event).catch(() => session.send('Fetch.continueRequest', { requestId: event.requestId }).catch(() => {}))
+  })
+
+  async function update () {
+    const patterns = [...new Set([...entries].flatMap((e) => e.gate.origins.map(patternOf).filter(Boolean)))]
+    if (patterns.length) await session.send('Fetch.enable', { patterns: patterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })) })
+    else await session.send('Fetch.disable')
+  }
+
+  return {
+    async add (context, gate) {
+      const entry = { context, gate, contextId: null }
+      const remove = () => {
+        entries.delete(entry)
+        for (const [id, owner] of owners) if (owner === entry) owners.delete(id)
+        return update()
+      }
+      entries.add(entry)
+      try { await update() } catch (error) { await remove().catch(() => {}); throw error }
+      context.once('close', () => { remove().catch(() => {}) })
+    }
+  }
+}

package/src/lib/health-catalogue.mjs

@@ -0,0 +1,122 @@
+// The catalogue of health checks (#206): every pack and every check it runs, with why it matters, its severity and
+// where it applies, in English and Czech. Built from the code that runs the checks (packs.mjs, pack-help.mjs, the
+// cross-page checks of seo-core.mjs, HC1005 of variants-core.mjs, the site checks of site.mjs), so the help pages it
+// writes (help/reference/health-checks.md and .cs.md, scripts/health-catalogue.mjs) cannot drift from the CLI.
+import { PACKS, PAGE_TYPES, CODE_ONLY_PACKS, errorPageOnly } from './packs.mjs'
+import { PACK_HELP, PACK_ORDER, PACK_NAMES } from './pack-help.mjs'
+import { CHECK_LEVEL } from './health-core.mjs'
+import { STACK_CHECKS } from './seo-core.mjs'
+import { VARIANT_CHECK } from './variants-core.mjs'
+import { SITE_CHECKS } from './site.mjs'
+
+/** What each pack is for, [en, cs]. */
+const ABOUT = {
+  seo: ['What search engines read from a page: the title, description, canonical, hreflang, Open Graph, robots, viewport and structured data. On a stack step it also compares the pages with each other.', 'Co si ze stránky přečtou vyhledávače: titulek, popis, kanonickou adresu, hreflang, Open Graph, robots, viewport a strukturovaná data. Na kroku typu stack navíc porovná stránky mezi sebou.'],
+  aeo: ['What AI search and assistants pick up: FAQ structured data, a short answer under the H1, llms.txt, a meta description, and the page as GPTBot gets it without JavaScript. Cheap signals from the page, not a ranking in any assistant.', 'Co převezmou AI vyhledávače a asistenti: strukturovaná data FAQ, krátkou odpověď pod H1, llms.txt, meta popis a stránku tak, jak ji bez JavaScriptu dostane GPTBot. Levné signály ze stránky, ne pozice v žádném asistentovi.'],
+  a11y: ['The part of WCAG 2.2 AA that can be measured on the page, a walk with the Tab key (without clicking or typing) and the accessibility tree. It does not replace an audit with a screen reader.', 'Část WCAG 2.2 AA, kterou jde na stránce změřit, průchod tabulátorem (bez klikání a psaní) a strom přístupnosti. Audit se čtečkou obrazovky nenahradí.'],
+  usability: ['Questions for the evaluator, picked by the page type of the step (`page`: landing, work, list, settings, form, doc), and labelled form fields.', 'Otázky pro evaluátor vybrané podle typu stránky kroku (`page`: landing, work, list, settings, form, doc) a popsaná formulářová pole.'],
+  perf: ['Lab values measured in the walk\'s browser: LCP, CLS, TTFB and page weight. Real visitors on slower phones may see other numbers.', 'Laboratorní hodnoty změřené v prohlížeči průchodu: LCP, CLS, TTFB a velikost stránky. Skuteční návštěvníci na pomalejších telefonech mohou vidět jiná čísla.'],
+  console: ['The evaluator reads the console errors of the step and says whether they touch what the step accepts or are noise from third-party scripts.', 'Evaluátor přečte chyby v konzoli kroku a řekne, jestli se týkají toho, co krok přijímá, nebo jde o šum cizích skriptů.'],
+  errors: ['For 404, 410, 500 and maintenance pages: a real error status, a way back, and no technical detail leaking out. Meant for steps that are error pages.', 'Pro stránky 404, 410, 500 a údržbu: skutečný chybový stav, cesta zpět a žádné technické podrobnosti navenek. Patří na kroky, které jsou chybovými stránkami.'],
+  locale: ['For multilingual sites: html lang, the page\'s own hreflang, the language of the text and the decimal separator of prices match the walked locale. Only in scenarios that list their `locales`.', 'Pro vícejazyčné weby: html lang, vlastní hreflang stránky, jazyk textu a desetinný oddělovač cen odpovídají procházenému jazyku. Jen ve scénářích, které uvádějí `locales`.'],
+  app: ['Native apps on Android, iOS and desktop: labelled controls, touch targets, cut-off text, crashes and a clear next step.', 'Nativní aplikace na Androidu, iOS a desktopu: popsané ovládací prvky, dotykové plochy, oříznutý text, pády a jasný další krok.'],
+  design: ['The implementation against the accepted design version: pixels, structure and tokens. The only pack that always counts for acceptance, so its ids are AC.', 'Implementace proti schválené verzi designu: pixely, struktura a tokeny. Jediný pack, který se vždy počítá do přijetí, proto má id AC.'],
+  site: ['Once per site and run, not per step: robots.txt, the sitemaps it lists, llms.txt and the redirects to https and to one host name. Off unless the scenario sets `health: { site: true }`, because they make requests of their own. They cannot be adopted as criteria.', 'Jednou za web a běh, ne za krok: robots.txt, sitemapy, které uvádí, llms.txt a přesměrování na https a na jednu podobu domény. Vypnuté, dokud scénář nenastaví `health: { site: true }`, protože posílají vlastní požadavky. Nejde je převzít jako kritéria.']
+}
+
+const WORDS = {
+  en: {
+    title: 'Health checks',
+    lead: [
+      'Every pack and every check it runs, listed from the same code the CLI runs, so the list matches the version you install. Health checks are advisory: the canvas shows them on the **Health** tab, and they never change the verdict of a step or a run. When a check matters to your team, adopt it as a criterion (`kaloko health adopt <step>:<check>`); from then on it counts for acceptance.',
+      'A step turns packs on with `packs: [seo, a11y]` in the scenario file ([Add criteria and packs](../how-to/add-criteria-and-packs.md)). The kinds of check, their options and the ids are in [Criteria, checks and packs](checks-and-packs.md).',
+      '**Severity** of a failed check: an **error** when people or search engines are shut out, a **warning** otherwise. An answer the evaluator was unsure about shows as **unsure**.'
+    ],
+    designOff: 'Off on design environments, where the steps are your own HTML served from a folder. To keep it on there, list it in `health: { design_packs: [...] }` in the scenario.',
+    designOn: 'Runs on design environments too.',
+    cols: ['Id', 'Check', 'Why it matters', 'Severity', 'Applies to'],
+    error: 'error', warning: 'warning', acceptance: 'acceptance criterion', hc1102: 'error on `production`, warning elsewhere',
+    every: 'every step with the pack', locales: 'scenarios with more than one locale', errorPages: 'error pages only (`expect_status`, or a page answering 4xx/5xx)',
+    pageTypes: (list) => `${list.length === 1 ? 'page type' : 'page types'} ${list.map((p) => `\`${p}\``).join(', ')}`,
+    stack: 'stack steps, across their pages', sitemap: 'stacks read from a sitemap', traffic: 'stacks with traffic data', variants: 'stacks with `items.variants: hreflang`',
+    site: 'once per site', production: 'once per site, on `production` only'
+  },
+  cs: {
+    title: 'Kontroly kondice',
+    lead: [
+      'Všechny packy a všechny kontroly, které spouštějí, vypsané ze stejného kódu, jaký spouští CLI, takže seznam odpovídá verzi, kterou si nainstalujete. Kontroly kondice jen radí: plachta je ukazuje na kartě **Kondice** a verdikt kroku ani běhu nikdy nemění. Když na kontrole vašemu týmu záleží, převezměte ji jako kritérium (`kaloko health adopt <krok>:<kontrola>`); od té chvíle se počítá do přijetí.',
+      'Krok si packy zapne přes `packs: [seo, a11y]` v souboru scénáře ([Přidat kritéria a packy](../how-to/add-criteria-and-packs.md)). Druhy kontrol, jejich volby a id najdete v [Kritéria, kontroly a packy](checks-and-packs.md).',
+      '**Závažnost** neúspěšné kontroly: **chyba**, když stránka zavře dveře lidem nebo vyhledávačům, jinak **varování**. Odpověď, kterou si evaluátor nebyl jistý, se ukáže jako **nejisté**.'
+    ],
+    designOff: 'Na designových prostředích, kde jsou kroky vaše vlastní HTML ze složky, je vypnutý. Pokud ho tam chcete, uveďte ho ve scénáři v `health: { design_packs: [...] }`.',
+    designOn: 'Běží i na designových prostředích.',
+    cols: ['Id', 'Kontrola', 'Proč na ní záleží', 'Závažnost', 'Kde platí'],
+    error: 'chyba', warning: 'varování', acceptance: 'akceptační kritérium', hc1102: 'chyba na `production`, jinde varování',
+    every: 'každý krok s packem', locales: 'scénáře s více jazyky', errorPages: 'jen chybové stránky (`expect_status` nebo stránka s odpovědí 4xx/5xx)',
+    pageTypes: (list) => `${list.length === 1 ? 'typ stránky' : 'typy stránek'} ${list.map((p) => `\`${p}\``).join(', ')}`,
+    stack: 'kroky typu stack, napříč stránkami', sitemap: 'stacky načtené ze sitemapy', traffic: 'stacky s daty o návštěvnosti', variants: 'stacky s `items.variants: hreflang`',
+    site: 'jednou za web', production: 'jednou za web, jen na `production`'
+  }
+}
+
+/** The checks of a pack: [{ id, text, where }], where says when the check applies (a key of WORDS or page types). */
+function checksOf (name) {
+  if (name === 'site') return SITE_CHECKS.map((c) => ({ id: c.id, text: c.text, where: c.id === 'HC1103' ? 'production' : 'site' }))
+  const pack = PACKS[name]
+  const seen = new Map()
+  for (const page of PAGE_TYPES) {
+    for (const c of pack.criteria({ locales: ['en', 'cs'], page, declared: true })) {
+      if (!seen.has(c.id)) seen.set(c.id, { id: c.id, text: c.text, pages: [] })
+      seen.get(c.id).pages.push(page)
+    }
+  }
+  const out = [...seen.values()].map((c) => ({
+    id: c.id,
+    text: c.text,
+    where: c.id === 'HC105' ? 'locales' : errorPageOnly({ pack: name, id: c.id }) ? 'errorPages' : c.pages.length < PAGE_TYPES.length ? c.pages : 'every'
+  }))
+  if (name === 'seo') for (const c of STACK_CHECKS) out.push({ id: c.id, text: c.text, where: c.id === 'HC126' ? 'sitemap' : c.id === 'HC127' ? 'traffic' : 'stack' })
+  if (name === 'locale') out.push({ id: VARIANT_CHECK.id, text: VARIANT_CHECK.text, where: 'variants' })
+  return out
+}
+
+/** The catalogue as data: [{ pack, name: [en, cs], about: [en, cs], design_off, checks: [{ id, text, cs, why, severity, where }] }]. */
+export function healthCatalogue () {
+  const missing = Object.keys(PACKS).filter((p) => !PACK_ORDER.includes(p))
+  if (missing.length) throw new Error(`health catalogue: no place for the pack(s) ${missing.join(', ')} in PACK_ORDER (pack-help.mjs)`)
+  return PACK_ORDER.map((pack) => {
+    return {
+      pack,
+      name: PACK_NAMES[pack],
+      about: ABOUT[pack],
+      design_off: CODE_ONLY_PACKS.includes(pack),
+      checks: checksOf(pack).map((c) => ({
+        id: c.id,
+        text: c.text,
+        cs: PACK_HELP[c.id]?.cs || null,
+        why: PACK_HELP[c.id]?.why || null,
+        severity: pack === 'design' ? 'acceptance' : c.id === 'HC1102' ? 'hc1102' : CHECK_LEVEL[c.id] || 'warning',
+        where: c.where
+      }))
+    }
+  })
+}
+
+// `<h1>` and the like read as code in the table; a pipe would end the cell
+const cell = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/<[a-z!/][^<>]*>/gi, (m) => `\`${m}\``)
+
+/** The help page in one language (`en` or `cs`), with front matter, as Markdown. */
+export function catalogueMarkdown (lang = 'en') {
+  const w = WORDS[lang === 'cs' ? 'cs' : 'en']
+  const i = lang === 'cs' ? 1 : 0
+  const where = (x) => Array.isArray(x) ? w.pageTypes(x) : w[x]
+  const out = ['---', `title: ${w.title}`, 'order: 9', '---', `# ${w.title}`, '', ...w.lead.flatMap((p) => [p, ''])]
+  for (const p of healthCatalogue()) {
+    out.push(`## ${p.name[i]} (\`${p.pack}\`)`, '', p.about[i], '')
+    if (!['site', 'app', 'design'].includes(p.pack)) out.push(p.design_off ? w.designOff : w.designOn, '')
+    out.push(`| ${w.cols.join(' | ')} |`, `|${w.cols.map(() => '---').join('|')}|`)
+    for (const c of p.checks) out.push(`| ${c.id} | ${cell(i ? c.cs || c.text : c.text)} | ${cell(c.why?.[i] || '')} | ${w[c.severity]} | ${where(c.where)} |`)
+    out.push('')
+  }
+  return out.join('\n')
+}

package/src/lib/init-detect.mjs

@@ -11,6 +11,7 @@ import { readFile, readdir, stat } from 'node:fs/promises'
 import { join, basename } from 'node:path'
 import { routeOf } from './affected-core.mjs'
 import { UsageError } from './util.mjs'
+import { NEW_VIEWPORTS } from './dimensions.mjs'
 
 const read = (root, f) => readFile(join(root, f), 'utf8').catch(() => null)
 const exists = (root, f) => stat(join(root, f)).then(() => true, () => false)
@@ -479,7 +480,7 @@ export function initScenario (d, { max = 6, project = null } = {}) {
     title: `Main pages of ${name}`,
     kind: 'flow', version: 1,
     locales: d.locales?.list?.slice(0, 6) || ['en'],
-    viewports: { desktop: [1280, 800], mobile: [390, 844] },
+    viewports: { desktop: [...NEW_VIEWPORTS.desktop], mobile: [...NEW_VIEWPORTS.mobile] },
     environments: ['local'],
     lanes: ['Visitor'],
     nodes,

package/src/lib/linkcheck.mjs

@@ -139,9 +139,18 @@ export function requester (request, cache = new Map(), scope = '') {
     if (cache.has(key)) return cache.get(key)
     const job = (async () => {
       try {
-        const headers = { ...(GATE.toGate(url) ? GATE.headers : {}), ...(ua ? { 'user-agent': ua } : {}), ...(lang ? { 'accept-language': lang } : {}) }
-        const res = await request.get(url, { maxRedirects: 5, timeout: 15000, failOnStatusCode: false, ...(Object.keys(headers).length ? { headers } : {}) })
-        const out = { status: res.status(), url: res.url() }
+        // redirects are followed by hand (at most 5): Playwright would hand the gate's headers to every hop, so a
+        // link that redirects to another host would carry them there
+        let at = url; let res
+        for (let hop = 0; ; hop++) {
+          const headers = { ...(GATE.toGate(at) ? GATE.headers : {}), ...(ua ? { 'user-agent': ua } : {}), ...(lang ? { 'accept-language': lang } : {}) }
+          res = await request.get(at, { maxRedirects: 0, timeout: 15000, failOnStatusCode: false, ...(Object.keys(headers).length ? { headers } : {}) })
+          const location = [301, 302, 303, 307, 308].includes(res.status()) ? res.headers().location : null
+          if (!location) break
+          if (hop >= 5) throw new Error('Max redirect count exceeded')
+          at = new URL(location, at).href
+        }
+        const out = { status: res.status(), url: at }
         if (!html && !parse) return out
         const text = await res.text()
         const body = text.length > BODY_MAX ? text.slice(0, BODY_MAX) : text

package/src/lib/pack-help.mjs

@@ -86,6 +86,23 @@ export const PACK_HELP = {
   HC501: { cs: 'Chyby v konzoli se netýkají toho, co krok přijímá', why: ['Separates real failures from third-party noise (analytics, extensions).', 'Odděluje skutečné chyby od šumu cizích skriptů (analytika, rozšíření).'], fix: ['If the AI says an error matters, fix that script; otherwise it is noise.', 'Pokud AI říká, že chyba vadí, opravte ten skript; jinak je to šum.'] }
 }
 
+/** The packs in the order people read them (the health catalogue, the scenario page), `site` (the site checks) last. */
+export const PACK_ORDER = ['seo', 'aeo', 'a11y', 'usability', 'perf', 'console', 'errors', 'locale', 'app', 'design', 'site']
+/** The name of each pack, [en, cs]. */
+export const PACK_NAMES = {
+  seo: ['SEO basics', 'Základy SEO'],
+  aeo: ['Answer engines', 'Odpovědní vyhledávače'],
+  a11y: ['Accessibility', 'Přístupnost'],
+  usability: ['Usability', 'Použitelnost'],
+  perf: ['Performance', 'Výkon'],
+  console: ['Console', 'Konzole'],
+  errors: ['Error pages', 'Chybové stránky'],
+  locale: ['Language versions', 'Jazykové verze'],
+  app: ['App screens', 'Obrazovky aplikací'],
+  design: ['Design reference', 'Reference designu'],
+  site: ['Site checks', 'Kontroly webu']
+}
+
 /** Help for one pack criterion in a language: { name, why, fix }, or null. */
 export function packHelp (id, lang = 'en') {
   const h = PACK_HELP[id] || PACK_HELP[String(id ?? '').replace(/^AC(?=[0-9])/, 'HC')]

package/src/lib/packs.mjs

@@ -156,6 +156,33 @@ export function expectedErrorStatus (node) {
 /** Whether a capture shows an error page: its step expects an error status, or the page answered 400 or more. */
 export const isErrorPage = (node, capture) => expectedErrorStatus(node) || (capture?.http_status ?? 0) >= 400
 
+/**
+ * Packs that check what only code shows: meta tags and crawlers (seo, aeo), a server's speed (perf), the browser
+ * console (console) and real error statuses (errors). A design environment serves the designer's own HTML from a local
+ * folder, so on a design run these say nothing about the design; they are off there unless the scenario lists them in
+ * `health: { design_packs: [...] }` (#205). a11y, usability and locale look at what people see and stay on.
+ */
+export const CODE_ONLY_PACKS = ['seo', 'aeo', 'perf', 'console', 'errors']
+
+/**
+ * The scenario as an environment walks it. On a design environment: the design reference checks are dropped (a design
+ * is not checked against itself) and so are the code-only packs the scenario does not keep on with
+ * `health.design_packs`; those packs are named in `scenario.packs_off` ({ seo: 'design' }), which the run manifest
+ * carries so the app can say why a pack is off. Other environments are left as they are. Mutates and returns the scenario.
+ */
+export function forEnvironment (scenario, env) {
+  if (env?.kind !== 'design' || !Array.isArray(scenario?.nodes)) return scenario
+  const keep = new Set(Array.isArray(scenario.health?.design_packs) ? scenario.health.design_packs : [])
+  const off = new Set()
+  const drop = (name) => CODE_ONLY_PACKS.includes(name) && !keep.has(name)
+  for (const n of scenario.nodes) {
+    if (Array.isArray(n.packs)) { for (const p of n.packs) if (drop(p)) off.add(p); n.packs = n.packs.filter((p) => !drop(p)) }
+    if (n.criteria) n.criteria = n.criteria.filter((c) => !['design_pixels', 'design_structure'].includes(c.check?.assert) && !(c.pack && drop(c.pack)))
+  }
+  if (off.size) scenario.packs_off = Object.fromEntries([...off].sort().map((p) => [p, 'design']))
+  return scenario
+}
+
 /** Page types a step (or the whole scenario) declares with `page`; the usability pack asks per type. */
 export const PAGE_TYPES = ['landing', 'work', 'list', 'settings', 'form', 'doc']
 

package/src/lib/stack-core.mjs

@@ -102,6 +102,15 @@ export function isoWeek (date = new Date()) {
   return { year, week, label: `${year}-W${String(week).padStart(2, '0')}`, index: Math.floor((monday - Date.UTC(1970, 0, 5)) / (7 * 86400000)) }
 }
 
+/**
+ * The date that picks the window of `rotate: week`: the start of the run, so every locale and step of one run walks
+ * the same week even when the walk crosses midnight into a new week (a run started on Sunday night). Falls back to now.
+ */
+export function rotationDate (startedAt) {
+  const d = startedAt ? new Date(startedAt) : null
+  return d && !Number.isNaN(d.getTime()) ? d : new Date()
+}
+
 /**
  * The window of a rotating sample: `limit` entries of `list` starting at (round × limit) mod length, wrapping around,
  * so consecutive rounds cover the whole list in ceil(length / limit) rounds. Returns { slice, offset }.

package/src/lib/stack.mjs

@@ -9,7 +9,7 @@ import { gunzipSync } from 'node:zlib'
 import { UserError, localized, readJson, writeJson } from './util.mjs'
 import { STACK_DEFAULT_FIELDS, STACK_SEMANTIC_SAMPLE, stackFieldsOf } from './manifest-core.mjs'
 import { variantItems, sitemapAlternates, pageAlternates, readHeadFrom } from './variants-core.mjs'
-import { DEFAULT_LIMIT, SITEMAP_MAX_BYTES, SITEMAP_MAX_CHILDREN, ROTATE_MODES, itemId, sitemapLocs, robotsSitemaps, sitemapsForLocale, handoffOf, isoWeek, rotateWindow, patternFor as corePatternFor, withLocale, sitemapPages, selectItems } from './stack-core.mjs'
+import { DEFAULT_LIMIT, SITEMAP_MAX_BYTES, SITEMAP_MAX_CHILDREN, ROTATE_MODES, itemId, sitemapLocs, robotsSitemaps, sitemapsForLocale, handoffOf, isoWeek, rotateWindow, rotationDate, patternFor as corePatternFor, withLocale, sitemapPages, selectItems } from './stack-core.mjs'
 
 /** How long items.resolve may take for one page (ms) before the page is walked without its edit link. */
 export const RESOLVE_TIMEOUT = 15000
@@ -18,7 +18,7 @@ export const DEFAULT_SEMANTIC_SAMPLE = STACK_SEMANTIC_SAMPLE
 export const DEFAULT_FIELDS = STACK_DEFAULT_FIELDS
 export const fieldsOf = stackFieldsOf
 // sources, filters and the rotating window are pure (stack-core.mjs): hosted runs on the service pick the same pages
-export { DEFAULT_LIMIT, SITEMAP_MAX_BYTES, SITEMAP_MAX_CHILDREN, ROTATE_MODES, itemId, sitemapLocs, robotsSitemaps, sitemapsForLocale, handoffOf, isoWeek, rotateWindow }
+export { DEFAULT_LIMIT, SITEMAP_MAX_BYTES, SITEMAP_MAX_CHILDREN, ROTATE_MODES, itemId, sitemapLocs, robotsSitemaps, sitemapsForLocale, handoffOf, isoWeek, rotateWindow, rotationDate }
 
 /** The text of a sitemap body: gzip (a .gz URL or the magic bytes 1f 8b) is unpacked, anything else read as UTF-8. */
 export function sitemapText (bytes, url = '') {

package/templates/ACCEPTANCE.md

@@ -35,7 +35,7 @@ Branches of the flow and the data that triggers them.
 
 ## Locales and viewports
 
-Locales; desktop 1280 × 800, mobile 390 × 844.
+Locales; desktop 1280 × 800, mobile 360 × 800 (a tablet, 744 × 1133, only when the task needs it).
 
 ## Environments and limits
 

package/templates/cs/ACCEPTANCE.md

@@ -35,7 +35,7 @@ Větve flow a data, která je vyvolají.
 
 ## Jazyky a viewporty
 
-Seznam jazyků; desktop 1280 × 800, mobil 390 × 844.
+Seznam jazyků; desktop 1280 × 800, mobil 360 × 800 (tablet 744 × 1133 jen tehdy, když ho úkol potřebuje).
 
 ## Prostředí a omezení
 

package/templates/scenario.yml

@@ -6,9 +6,9 @@ source: docs/tasks/TASK-123-example/ACCEPTANCE.md
 # project: shop           # optional: sort this flow into a project other than the config's / repository's
 version: 1
 locales: [en]
-viewports:
+viewports:                 # a tablet only when the task needs one: tablet: [744, 1133]
   desktop: [1280, 800]
-  mobile: [390, 844]
+  mobile: [360, 800]
 environments: [local, staging]
 # platform: android          # web (default) | android | ios | electron | desktop — an app instead of pages:
 #                            # the environment's app block in kaloko.config.yml names it, paths are deep links