kaloko 0.15.0 → 0.16.0

package/src/lib/capture.mjs

@@ -16,8 +16,8 @@ export function browserVersion (page) {
   try { const b = page.context().browser(); const v = b?.version?.(); return v ? `${b.browserType?.().name?.() || 'browser'} ${v}` : null } catch { return null }
 }
 
-export async function encodeImage (page, png, { format = 'webp', quality = 0.82, thumbWidth = 640, thumbQuality = 0.8, marks = [], scale = 1, masks = [] } = {}) {
-  const result = await page.evaluate(async ({ dataUrl, format, quality, thumbWidth, thumbQuality, marks, scale, masks }) => {
+export async function encodeImage (page, png, { format = 'webp', quality = 0.82, thumbWidth = 640, thumbQuality = 0.8, marks = [], scale = 1, masks = [], outline = null } = {}) {
+  const result = await page.evaluate(async ({ dataUrl, format, quality, thumbWidth, thumbQuality, marks, scale, masks, outline }) => {
     const img = new Image()
     await new Promise((res, rej) => { img.onload = res; img.onerror = rej; img.src = dataUrl })
     const full = document.createElement('canvas'); full.width = img.width; full.height = img.height
@@ -30,6 +30,12 @@ export async function encodeImage (page, png, { format = 'webp', quality = 0.82,
       for (let i = -h; i < w; i += 12 * scale) { g.beginPath(); g.moveTo(x + i, y + h); g.lineTo(x + i + h, y); g.stroke() }
       g.restore()
     }
+    // a detail's element (details:): a ring around it, a few pixels out so it never covers the element itself
+    if (outline) {
+      const gap = 5 * scale; const x = outline.x * scale - gap; const y = outline.y * scale - gap; const w = outline.w * scale + gap * 2; const h = outline.h * scale + gap * 2
+      const ring = () => { g.beginPath(); if (g.roundRect) g.roundRect(x, y, w, h, 6 * scale); else g.rect(x, y, w, h) }
+      g.save(); ring(); g.strokeStyle = '#151514'; g.lineWidth = 5 * scale; g.stroke(); ring(); g.strokeStyle = '#ffe452'; g.lineWidth = 3 * scale; g.stroke(); g.restore()
+    }
     for (const m of marks) {
       const r = 13 * scale; const x = Math.max(r + 2, m.x * scale); const y = Math.max(r + 2, m.y * scale)
       g.beginPath(); g.arc(x, y, r, 0, Math.PI * 2); g.fillStyle = '#ffe452'; g.fill(); g.lineWidth = 2 * scale; g.strokeStyle = '#151514'; g.stroke()
@@ -50,7 +56,7 @@ export async function encodeImage (page, png, { format = 'webp', quality = 0.82,
     const t = document.createElement('canvas'); t.width = tw; t.height = th
     const tg = t.getContext('2d'); tg.imageSmoothingEnabled = true; tg.imageSmoothingQuality = 'high'; tg.drawImage(src, 0, 0, tw, th)
     return { image: await blob(full, format === 'png' ? 'image/png' : 'image/webp', quality), thumb: await blob(t, 'image/webp', thumbQuality) }
-  }, { dataUrl: `data:image/png;base64,${png.toString('base64')}`, format, quality, thumbWidth, thumbQuality, marks, scale, masks })
+  }, { dataUrl: `data:image/png;base64,${png.toString('base64')}`, format, quality, thumbWidth, thumbQuality, marks, scale, masks, outline })
   return { image: Buffer.from(result.image.bytes), thumb: Buffer.from(result.thumb.bytes), imageType: result.image.type, thumbType: result.thumb.type }
 }
 
@@ -95,6 +101,7 @@ import { checkLinks, checkHreflang, requester, walkCache, NETWORK_ASSERTS, isola
 import { keyboardChecks, needsKeyboard, KEYBOARD_ASSERTS } from './keyboard.mjs'
 import { repeatRegions, resolveIgnore } from './stability.mjs'
 import { applyVariant, engineOf, markEngineGaps, variantFields } from './dimensions.mjs'
+import { detailsFor, detailFacts, detailBox, detailName, DETAIL_PADDING } from './detail.mjs'
 import { liveValueChecks } from './assertions.mjs'
 
 /** Probe arguments derived from the node's criteria. */
@@ -253,6 +260,8 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         image = paths.step(stepId, locale, viewport, 'png'); thumbWritten = false
         await writeFile(image, shot)
       }
+      // named details for guides (details:): from the same masked page as the screenshot, with the same mask boxes
+      const details = item ? [] : await captureDetails({ page, node, locale, viewport, run, stepId, maskRects, scale: shotScale, engine, dpr })
       // network checks (internal links, hreflang pairs) run once per page, outside the page, with a walk-wide cache
       const net = (node.criteria || []).filter((c) => c.check.type === 'deterministic' && NETWORK_ASSERTS.has(c.check.assert))
       if (net.length) {
@@ -297,7 +306,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         Object.assign(result.checks, kb.checks)
         result.boxes = { ...result.boxes, ...kb.boxes }
         keyboard = kb.keyboard
-        for (const s of keyboard?.shots || []) await addCapture(run.dir, { type: 'attachment', kind: 'focus', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, title: scrubText(redact(`Focus ${s.n}: ${s.name}`), mask.auto ? mask : null), file: s.file, at: new Date().toISOString() })
+        for (const s of keyboard?.shots || []) await addCapture(run.dir, { type: 'attachment', kind: 'focus', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, n: s.n, title: scrubText(redact(`Focus ${s.n}: ${s.name}`), mask.auto ? mask : null), file: s.file, at: new Date().toISOString() })
       }
       const record = {
         schema: 'qawalk.capture.v1',
@@ -318,6 +327,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         ...(ignore.length ? { ignore } : {}),
         ...(unstable ? { unstable } : {}),
         ...(keyboard ? { keyboard } : {}),
+        ...(details.length ? { details } : {}),
         ...(item ? { item: { id: item.id, path: item.path, ...(item.title ? { title: item.title } : {}), ...(item.purpose ? { purpose: item.purpose } : {}) } } : {}),
         ...(fields ? { fields: { ...(await page.evaluate(readFields, fields).catch(() => ({}))), ...(fields.some((f) => (f.from || f.id) === 'http') ? Object.fromEntries(fields.filter((f) => (f.from || f.id) === 'http').map((f) => [f.id, extra.http_status ?? result.http_status ?? null])) : {}) } } : {}),
         files: { png: relative(run.dir, image), image: relative(run.dir, image), thumb: thumbWritten ? relative(run.dir, thumb) : null, html: relative(run.dir, html) }
@@ -341,6 +351,42 @@ export async function captureStep ({ page, node, locale, viewports, run, console
   return results
 }
 
+/**
+ * The named details of a step in one capture (details:, detail.mjs): each element in its section or card (detailBox),
+ * outlined, as an attachment of kind detail with the element's box inside the picture. The page is masked here as for
+ * the screenshot: masked text is already replaced, `maskRects` (document pixels) are drawn as boxes, and a detail whose
+ * masks cannot be drawn is not stored. Returns the capture record's `details`: { id, file, box, size, context } or
+ * { id, error } for an element that was not found or not visible.
+ */
+async function captureDetails ({ page, node, locale, viewport, run, stepId, maskRects = [], scale = 1, engine = 'chromium', dpr = 1 }) {
+  const list = detailsFor(node, viewport)
+  const out = []
+  for (const d of list) {
+    const facts = await page.evaluate(detailFacts, { selector: d.selector, context: d.context || null }).catch((e) => ({ error: String(e.message).split('\n')[0].slice(0, 200) }))
+    if (!facts || facts.error) { out.push({ id: d.id, error: `${d.selector}: ${facts?.error || 'not found'}` }); continue }
+    const { crop, el, by } = detailBox(facts, { context: d.context || null, padding: d.padding ?? DETAIL_PADDING })
+    // documentation runs (scale 2) get 2× details, the way the screenshot is taken
+    let png; let k = 1
+    if (scale === 2 && engine === 'chromium') {
+      const cdp = await page.context().newCDPSession(page)
+      try { png = Buffer.from((await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: true, clip: { x: crop.x, y: crop.y, width: crop.w, height: crop.h, scale: 2 / (dpr || 1) } })).data, 'base64'); k = 2 } finally { await cdp.detach().catch(() => {}) }
+    } else png = await page.screenshot({ fullPage: true, clip: { x: crop.x, y: crop.y, width: crop.w, height: crop.h }, scale: 'css', animations: 'disabled', caret: 'hide' })
+    const masks = maskRects.map((r) => ({ ...r, x: r.x - crop.x, y: r.y - crop.y })).filter((r) => r.x < crop.w && r.y < crop.h && r.x + r.w > 0 && r.y + r.h > 0)
+    let image
+    try { image = (await encodeImage(page, png, { format: 'png', masks, outline: el, scale: k })).image } catch (error) {
+      if (masks.length) { out.push({ id: d.id, error: `the masks could not be drawn (${String(error.message).slice(0, 120)}); not stored` }); continue }
+      image = png
+    }
+    const file = runPaths(run.dir).step(stepId, locale, viewport, `detail-${d.id}.png`)
+    await writeFile(file, image)
+    const name = detailName(d, locale)
+    const entry = { id: d.id, file: relative(run.dir, file), box: el, size: [crop.w, crop.h], context: by }
+    out.push(entry)
+    await addCapture(run.dir, { type: 'attachment', kind: 'detail', node: node.id, locale, viewport, id: d.id, name, title: name, file: entry.file, box: el, size: entry.size, at: new Date().toISOString() })
+  }
+  return out
+}
+
 /**
  * A focus shot of the keyboard walk with the mask on: the page masked for the moment of the shot, boxes drawn over
  * the masked places in the clip, the page restored (the focus stays where the walk put it).

package/src/lib/changelog-core.mjs

@@ -14,10 +14,13 @@ const PARAMS = {
   media: /^(video|image)$/
 }
 export const REF_SCHEME = 'kaloko:'
+/** A named detail of a step (details: in the scenario, src/lib/detail.mjs DETAIL_ID): `kaloko:<scenario>/<step>#<id>`. */
+const DETAIL = /^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$/
 
 /**
- * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=&media=]`, or the short `kaloko:<step>`
- * that means a step of the product's default scenario. `version` is a released version, `latest` (default) or `prev`
+ * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=&media=][#<detail>]`, or the short
+ * `kaloko:<step>` that means a step of the product's default scenario. `#<detail>` asks for a named detail of the step
+ * (details: in the scenario) instead of the whole screen. `version` is a released version, `latest` (default) or `prev`
  * (the release before the one the text belongs to); `state` picks a variant of the capture (dark, webkit, reduce: the
  * dimension values in the capture key); `media` is `video` (play the step's recording; docs check warns when the
  * accepted run has none) or `image` (never play it). Without `media` the recording plays when the run has one.
@@ -26,13 +29,16 @@ export const REF_SCHEME = 'kaloko:'
 export function parseStepRef (ref) {
   const s = String(ref || '').trim()
   if (!s.startsWith(REF_SCHEME)) return null
-  const rest = s.slice(REF_SCHEME.length)
+  let rest = s.slice(REF_SCHEME.length)
+  const hi = rest.indexOf('#')
+  const detail = hi < 0 ? null : rest.slice(hi + 1)
+  if (hi >= 0) { rest = rest.slice(0, hi); if (!DETAIL.test(detail)) return null }
   const qi = rest.indexOf('?')
   const path = qi < 0 ? rest : rest.slice(0, qi)
   let parts
   try { parts = path.split('/').map((p) => decodeURIComponent(p)) } catch { return null }
   if (!parts.length || parts.length > 2 || parts.some((p) => !ID.test(p))) return null
-  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null, media: null }
+  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null, media: null, detail }
   const q = new URLSearchParams(qi < 0 ? '' : rest.slice(qi + 1))
   for (const [k, v] of q) {
     if (!(k in PARAMS)) return null
@@ -44,10 +50,10 @@ export function parseStepRef (ref) {
 }
 
 /** The reference text of a parsed (or hand-built) reference; parameters in a fixed order. */
-export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null, media = null }) {
+export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null, media = null, detail = null }) {
   const path = `${scenario ? `${encodeURIComponent(scenario)}/` : ''}${encodeURIComponent(step)}`
   const q = Object.entries({ locale, viewport, version, state, media }).filter(([, v]) => v != null && v !== '')
-  return `${REF_SCHEME}${path}${q.length ? `?${q.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}` : ''}`
+  return `${REF_SCHEME}${path}${q.length ? `?${q.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}` : ''}${detail ? `#${detail}` : ''}`
 }
 
 /** Every image with a step reference in a Markdown text: { alt, ref, parsed, index }; broken ones have parsed null. */

package/src/lib/cli-args.mjs

@@ -44,8 +44,11 @@ export const HIDDEN = {
   ci: ['wait', 'github-env', 'dotenv']
 }
 
-/** Commands whose unknown options stop the command instead of a warning: they delete, publish or change access. */
-export const STRICT = new Set(['prune', 'trash', 'restore', 'keep', 'archive', 'public', 'release', 'comment'])
+/**
+ * Commands whose unknown options stop the command instead of a warning: they delete, publish or change access. A
+ * "command sub" entry makes only that sub-command strict (kaloko projects lists, kaloko projects create writes).
+ */
+export const STRICT = new Set(['prune', 'trash', 'restore', 'keep', 'archive', 'public', 'release', 'comment', 'projects create', 'projects rename', 'projects sync'])
 
 /**
  * argv → { _: positional, <option>: value | true }. `--key=value` splits at the first `=` only; `--key value` takes
@@ -140,6 +143,6 @@ export function checkOptions (help, name, args) {
   const unknown = Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
   if (!unknown.length) return []
   const lines = unknown.map((k) => { const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}` })
-  if (STRICT.has(name)) throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
+  if (STRICT.has(name) || STRICT.has(`${name} ${args._?.[0]}`)) throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
   return lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`)
 }

package/src/lib/detail.mjs

@@ -0,0 +1,102 @@
+// Named details of a step (`details:` in the scenario): pictures for user guides and docs that show one element in
+// the part of the page around it (its section or card), outlined, in every locale and viewport. The capture
+// (capture.mjs captureDetails) reads the element and its ancestors in the page (detailFacts, self-contained: it runs
+// in the browser), chooses the box here (detailBox, plain arithmetic, unit-tested) and stores the picture as an
+// attachment of kind `detail` with the element's box inside the picture, so the canvas and docs can point at it.
+import { stateOfKey } from './manifest-core.mjs'
+import { localized } from './util.mjs'
+
+/** The smallest context worth showing in a guide (CSS px); narrower viewports cap the width. */
+export const DETAIL_MIN = { w: 480, h: 240 }
+export const DETAIL_PADDING = 16
+export const DETAIL_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$/
+export const CONTEXTS = ['section', 'card', 'page']
+
+/** The details of a step that apply to a capture key (a detail with `states:` is taken in those states only). */
+export function detailsFor (node, key) {
+  const state = stateOfKey(key)
+  return (node?.details || []).filter((d) => d && DETAIL_ID.test(d.id || '') && d.selector && (!Array.isArray(d.states) || !d.states.length || d.states.includes(state)))
+}
+
+/** A detail's name in a locale (`name` may be one text or one per locale). */
+export const detailName = (d, locale) => localized(d.name, locale) || d.id
+
+/**
+ * Runs in the page (keep it self-contained): the element `selector` names and its ancestors up to <body>, as boxes in
+ * document pixels, with what kind of container each is. `landmark`: an HTML section element or landmark role;
+ * `card`: an article, list item, fieldset, group, an element whose class says card/tile/panel/box, or one with its own
+ * frame (a border, a shadow, or rounded corners on a background). A `context` that is a CSS selector is looked up
+ * with closest() and returned as `custom` ('missing' when the element is not inside one, 'invalid' for a bad selector).
+ */
+export function detailFacts ({ selector, context = null }) {
+  let el
+  try { el = document.querySelector(selector) } catch { return { error: 'invalid selector' } }
+  if (!el) return { error: 'not found' }
+  const sx = scrollX; const sy = scrollY
+  const box = (e) => { const r = e.getBoundingClientRect(); return { x: r.left + sx, y: r.top + sy, w: r.width, h: r.height } }
+  const b = box(el)
+  if (!b.w || !b.h) return { error: 'not visible' }
+  const LANDMARK = /^(main|section|article|aside|nav|header|footer|form|dialog|fieldset)$/
+  const ROLES = /^(main|region|dialog|alertdialog|form|navigation|complementary|banner|contentinfo|search)$/
+  const CARDROLES = /^(article|listitem|group)$/
+  const CARDCLASS = /(^|[-_\s])(card|tile|panel|box|modal|popover|widget)s?([-_\s]|$)/i
+  const clear = (c) => !c || c === 'transparent' || /rgba\([^)]*,\s*0\)$/.test(c)
+  let custom = null
+  if (context && !['section', 'card', 'page'].includes(context)) {
+    try { const c = el.closest(context); custom = c ? box(c) : 'missing' } catch { custom = 'invalid' }
+  }
+  const ancestors = []
+  for (let a = el.parentElement; a && a !== document.body && a !== document.documentElement; a = a.parentElement) {
+    const cs = getComputedStyle(a)
+    const tag = a.tagName.toLowerCase(); const role = a.getAttribute('role') || ''
+    const cls = typeof a.className === 'string' ? a.className : (a.className?.baseVal || '')
+    const framed = (parseFloat(cs.borderTopWidth) > 0 && cs.borderTopStyle !== 'none' && parseFloat(cs.borderBottomWidth) > 0) || cs.boxShadow !== 'none' || (parseFloat(cs.borderTopLeftRadius) > 0 && !clear(cs.backgroundColor))
+    ancestors.push({ ...box(a), tag, landmark: LANDMARK.test(tag) || ROLES.test(role), card: ['article', 'li', 'fieldset'].includes(tag) || CARDROLES.test(role) || CARDCLASS.test(cls) || framed })
+  }
+  return { el: b, ancestors, custom, viewport: { w: innerWidth, h: innerHeight }, doc: { w: document.documentElement.scrollWidth, h: document.documentElement.scrollHeight } }
+}
+
+/**
+ * The picture of a detail from the facts of the page: { crop, el, by } in CSS pixels, `crop` in the document, `el`
+ * (the element) inside the crop, `by` what chose the box.
+ * - `context` unset: the nearest ancestor that is a section or landmark or a card and at least DETAIL_MIN (on a narrow
+ *   screen at least 90 % of its width); none: the element with room around it, DETAIL_MIN centred on it.
+ * - 'section' or 'card': the nearest ancestor of that kind and at least that big; 'page': one screen (the viewport)
+ *   around the element; a CSS selector: the nearest ancestor that matches it, whatever its size.
+ * Then `padding` around it (16 px by default), at most one screen wide and high around the element (the element
+ * itself always fits), inside the document.
+ */
+export function detailBox (facts, { context = null, padding = DETAIL_PADDING, min = DETAIL_MIN } = {}) {
+  const { el, ancestors = [], viewport, doc } = facts
+  const pad = Number.isFinite(padding) && padding >= 0 ? padding : DETAIL_PADDING
+  // on a phone a card rarely spans the whole width: 90 % of the screen is wide enough
+  const minW = Math.min(min.w, Math.floor(viewport.w * 0.9)); const minH = Math.min(min.h, viewport.h)
+  const big = (b) => b.w >= minW && b.h >= minH
+  const holds = (b) => b.x <= el.x + 0.5 && b.y <= el.y + 0.5 && b.x + b.w >= el.x + el.w - 0.5 && b.y + b.h >= el.y + el.h - 0.5
+  const cx = el.x + el.w / 2; const cy = el.y + el.h / 2
+  let ctx = null; let by = null
+  if (context === 'page') { ctx = { x: cx - viewport.w / 2, y: cy - viewport.h / 2, w: viewport.w, h: viewport.h }; by = 'page' }
+  else if (context && !CONTEXTS.includes(context)) { if (facts.custom && typeof facts.custom === 'object') { ctx = facts.custom; by = 'selector' } }
+  else {
+    const kind = context === 'section' ? (a) => a.landmark : context === 'card' ? (a) => a.card : (a) => a.landmark || a.card
+    const hit = ancestors.find((a) => kind(a) && big(a) && holds(a))
+    if (hit) { ctx = hit; by = context || (hit.landmark ? 'section' : 'card') }
+  }
+  if (!ctx) { const w = Math.max(minW, el.w); const h = Math.max(minH, el.h); ctx = { x: cx - w / 2, y: cy - h / 2, w, h }; by = 'element' }
+  let x = ctx.x - pad; let y = ctx.y - pad; let w = ctx.w + pad * 2; let h = ctx.h + pad * 2
+  // at most one screen around the element: a long section or a wide page is cut around it, never through it
+  const fit = (start, size, cap, center, lo, hi) => {
+    if (size <= cap) return [start, size]
+    const s = Math.min(Math.max(center - cap / 2, start), start + size - cap)
+    return [Math.min(s, lo), Math.max(cap, hi - Math.min(s, lo))]
+  }
+  ;[x, w] = fit(x, w, viewport.w, cx, el.x - pad, el.x + el.w + pad)
+  ;[y, h] = fit(y, h, viewport.h, cy, el.y - pad, el.y + el.h + pad)
+  // inside the document: moved in first, cut only when the document is smaller
+  const keep = (start, size, total) => { const s = Math.max(0, Math.min(start, total - size)); return [s, Math.min(size, total - s)] }
+  ;[x, w] = keep(x, w, doc.w)
+  ;[y, h] = keep(y, h, doc.h)
+  const crop = { x: Math.floor(x), y: Math.floor(y), w: 0, h: 0 }
+  crop.w = Math.max(1, Math.min(Math.ceil(x + w), doc.w) - crop.x); crop.h = Math.max(1, Math.min(Math.ceil(y + h), doc.h) - crop.y)
+  return { crop, el: { x: Math.round(el.x - crop.x), y: Math.round(el.y - crop.y), w: Math.round(el.w), h: Math.round(el.h) }, by }
+}

package/src/lib/docs-export.mjs

@@ -15,7 +15,8 @@ export const ZIP_FORMATS = ['md', 'docusaurus', 'vitepress', 'mkdocs', 'html']
 export function assetFile (pic) {
   const ext = (String(pic.file || pic.path || '').match(/\.(png|jpe?g|webp|gif)$/i) || [, 'png'])[1].toLowerCase()
   const safe = (s) => String(s || '').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 60)
-  return `assets/${safe(pic.scenario)}--${safe(pic.step?.id || pic.step)}--${safe(pic.locale)}--${safe(pic.viewport)}--${safe(String(pic.run?.id || pic.run || '').split('-').pop())}.${ext}`
+  // a named detail (#<detail>) is its own picture next to the screen of the same step
+  return `assets/${safe(pic.scenario)}--${safe(pic.step?.id || pic.step)}${pic.detail?.id ? `--${safe(pic.detail.id)}` : ''}--${safe(pic.locale)}--${safe(pic.viewport)}--${safe(String(pic.run?.id || pic.run || '').split('-').pop())}.${ext}`
 }
 
 /**

package/src/lib/docs.mjs

@@ -81,11 +81,13 @@ export async function collectDocs (root, product) {
  * What needs attention in the docs, from the repository alone: broken references (not kaloko:<scenario>/<step>),
  * references to scenarios or steps the scenario files do not have (`scenarios`: Map id → Set of step ids), short
  * references without a default scenario, missing and outdated translations, and user-visible changelog items without a
- * picture. Returns { pages, broken, unknown, translations, changelog_without_pictures }.
+ * picture; with `details` (Map '<scenario>/<step>' → Set of detail ids) also references to a detail the step does not
+ * declare (a warning: readers see the whole screen). Returns { pages, broken, unknown, missing_details, translations,
+ * changelog_without_pictures }.
  */
-export async function localCheck ({ root, product, scenarios = null }) {
+export async function localCheck ({ root, product, scenarios = null, details = null }) {
   const { dir, pages } = await collectDocs(root, product)
-  const broken = []; const unknown = []
+  const broken = []; const unknown = []; const missingDetails = []
   for (const p of pages) {
     for (const r of p.refs) {
       if (!r.parsed) { broken.push({ file: p.file, ref: r.ref }); continue }
@@ -94,28 +96,29 @@ export async function localCheck ({ root, product, scenarios = null }) {
       if (!scenarios) continue
       if (!scenarios.has(sc)) unknown.push({ file: p.file, ref: r.ref, why: `No scenario ${sc} in the scenario files.` })
       else if (!scenarios.get(sc).has(r.parsed.step)) unknown.push({ file: p.file, ref: r.ref, why: `Scenario ${sc} has no step ${r.parsed.step}.` })
+      else if (r.parsed.detail && details && !details.get(`${sc}/${r.parsed.step}`)?.has(r.parsed.detail)) missingDetails.push({ file: p.file, ref: r.ref, why: `Step ${sc}/${r.parsed.step} declares no detail ${r.parsed.detail}; add it under details: and walk the step again.` })
     }
   }
   const languages = docsLanguages(product, pages)
   const translations = translationReport(pages.map((p) => ({ path: p.path, lang: p.lang, hash: p.hash, front: p.front, updated: p.updated })), languages)
   let changelog = []
   try { changelog = itemsWithoutPictures(await readFile(changelogFile(root, product), 'utf8')) } catch {}
-  return { dir, pages, languages, broken, unknown, translations, changelog_without_pictures: changelog }
+  return { dir, pages, languages, broken, unknown, missing_details: missingDetails, translations, changelog_without_pictures: changelog }
 }
 
 /** The check with the service's half (stale sections, references without an accepted picture), when a client is given. */
-export async function docsCheck ({ root, config, product, client = null, scenarios = null, version = 'latest' }) {
-  const local = await localCheck({ root, product, scenarios })
+export async function docsCheck ({ root, config, product, client = null, scenarios = null, details = null, version = 'latest' }) {
+  const local = await localCheck({ root, product, scenarios, details })
   let service = null; let serviceError = null
   if (client && config.org) {
     try { service = await client.request('GET', `/orgs/${config.org}/docs/check?${new URLSearchParams({ product: product.slug, version })}`) } catch (e) { serviceError = String(e.message || e).split('\n')[0].slice(0, 200) }
   }
   const errors = local.broken.length + local.unknown.length + (service ? service.stale.length + service.unresolved.length : 0)
-  const warnings = local.translations.missing.length + local.translations.outdated.length + local.changelog_without_pictures.length + (service?.no_recording?.length || 0)
+  const warnings = local.translations.missing.length + local.translations.outdated.length + local.changelog_without_pictures.length + local.missing_details.length + (service?.no_recording?.length || 0) + (service?.no_detail?.length || 0)
   return {
     product: product.slug, version, dir: relative(root, local.dir) || '.', pages: local.pages.length, languages: local.languages,
-    broken: local.broken, unknown: local.unknown, translations: local.translations, changelog_without_pictures: local.changelog_without_pictures,
-    service: service ? { published: service.published, published_at: service.published_at || null, stale: service.stale, unresolved: service.unresolved, no_recording: service.no_recording || [], stale_checked: service.stale_checked !== false, url: service.url } : null,
+    broken: local.broken, unknown: local.unknown, missing_details: local.missing_details, translations: local.translations, changelog_without_pictures: local.changelog_without_pictures,
+    service: service ? { published: service.published, published_at: service.published_at || null, stale: service.stale, unresolved: service.unresolved, no_recording: service.no_recording || [], no_detail: service.no_detail || [], stale_checked: service.stale_checked !== false, url: service.url } : null,
     service_error: serviceError, errors, warnings, ok: errors === 0
   }
 }
@@ -130,9 +133,11 @@ export function formatCheck (r) {
     list('✗ stale sections (the screen changed since the text was published)', r.service.stale, (x) => `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''} § ${x.title || 'intro'}: the screen changed${x.refs[0]?.changed_in ? ` in ${x.refs[0].changed_in}` : ''} — check the text (${x.refs.map((y) => y.ref).join(', ')})`)
     list('✗ references without an accepted picture', r.service.unresolved, (x) => `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''}: ${x.ref}`)
     list('! media=video, but the accepted run has no recording of the step (readers see the picture; walk it with --record)', r.service.no_recording || [], (x) => `${x.release ? `changelog ${x.release}` : `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''}`}: ${x.ref}${x.run ? ` (run ${x.run})` : ''}`)
+    list('! #detail that no accepted run has yet (readers see the whole screen; walk the step again)', r.service.no_detail || [], (x) => `${x.path || 'index'}${x.lang ? ` (${x.lang})` : ''}: ${x.ref}${x.run ? ` (run ${x.run})` : ''}`)
     if (!r.service.published) lines.push('  · nothing published yet: kaloko docs publish')
     else if (!r.service.stale_checked) lines.push('  · stale sections are checked on the Business plan')
   } else lines.push(`  · ${r.service_error ? `service: ${r.service_error}` : 'offline: stale sections and pictures need a token'}`)
+  list('! details the scenario does not declare', r.missing_details || [], (x) => `${x.file}: ${x.ref} — ${x.why}`)
   list('! missing translations', r.translations.missing, (x) => `${x.path || 'index'} → ${x.lang}`)
   list('! outdated translations (the original changed later)', r.translations.outdated, (x) => `${x.path || 'index'} (${x.lang})${x.why === 'source_hash' ? ': source_hash differs' : ''}`)
   list('! translations without an original', r.translations.orphans, (x) => `${x.path || 'index'} (${x.lang})`)

package/src/lib/evidence-core.mjs

@@ -1,4 +1,4 @@
-// Evidence for regulated work (qawalk.evidence.v1, schemas/evidence.v1.json; help/explanation/gxp.md): what a
+// Quality evidence (qawalk.evidence.v1, schemas/evidence.v1.json; help/explanation/quality-evidence.md): what a
 // downstream generator needs from an accepted run, without scraping the canvas or the PDF. Shared by the service
 // (worker/src/evidence.js) and the CLI (kaloko evidence, kaloko signoff --package / --verify): WebCrypto only, no node:
 // imports, so it runs in both.

package/src/lib/git.mjs

@@ -47,7 +47,7 @@ export async function projectAndIssue ({ cwd, config, scenario, branch, title =
   const project = scenario.project
     ? { slug: scenario.project, repo: repo?.slug || null, source: 'scenario' }
     : config.project
-      ? { slug: config.project, repo: repo?.slug || null, source: 'config' }
+      ? { slug: config.project, ...(config.project_name ? { name: String(config.project_name) } : {}), repo: repo?.slug || null, source: 'config' }
       : repo ? { slug: repo.slug.split('/').pop(), repo: repo.slug, source: 'git' } : { slug: cwd.split('/').pop(), repo: null, source: 'directory' }
   let issue = null
   const given = scenario.issue