kaloko 0.5.2 → 0.6.0

package/src/lib/design-notes.mjs

@@ -0,0 +1,191 @@
+// "What changed" notes of a design version (batch G, #3): a short plain-language changelog per changed step against
+// the previous version, built from what the service already knows (revision ids, screenshot hashes per viewport,
+// the text the step spec captured from the DOM, the token set of each revision). Pure and dependency-free apart from
+// the token module, so the CLI (preview, --notes) and the Worker (publishing) share it.
+import { flattenTokens } from './tokens.mjs'
+
+export const NOTES_SCHEMA = 'qawalk.version-notes.v1'
+export const NOTE_LIMITS = { summary: 2000, step: 1000, texts: 6, tokens: 40 }
+
+/** Text in the reader's language: an edited note is one string for everyone, a generated one has en and cs. */
+export const noteText = (t, lang = 'en') => (t == null ? '' : typeof t === 'string' ? t : t[lang] || t.en || '')
+
+const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
+const quote = (s, lang) => (lang === 'cs' ? `„${s}“` : `“${s}”`)
+const short = (s, n = 60) => (s.length > n ? s.slice(0, n - 1) + '…' : s)
+const list = (items, lang) => {
+  if (items.length < 2) return items.join('')
+  return `${items.slice(0, -1).join(', ')} ${lang === 'cs' ? 'a' : 'and'} ${items[items.length - 1]}`
+}
+
+/**
+ * The texts a capture shows: accessible names of the spec's elements (from the DOM), the H1 and the page title.
+ * `names` may be the spec's elements or a plain list of names (the Worker extracts them in SQL).
+ */
+export function textsOf ({ names = [], h1 = [], title = null } = {}) {
+  const out = new Set()
+  for (const n of [...[].concat(h1 || []), ...names.map((x) => (x && typeof x === 'object' ? x.name : x))]) {
+    const t = clean(n)
+    if (t && t.length > 1 && !/^[\d\s.,:/-]+$/.test(t)) out.add(t)
+  }
+  if (title && clean(title)) out.add(clean(title))
+  return out
+}
+
+/** Texts that appeared and disappeared; one of each becomes "from → to" when that reads naturally. */
+export function textChanges (before, after) {
+  const removed = [...before].filter((t) => !after.has(t))
+  const added = [...after].filter((t) => !before.has(t))
+  if (!removed.length && !added.length) return null
+  const out = { kind: 'text', added: added.slice(0, NOTE_LIMITS.texts), removed: removed.slice(0, NOTE_LIMITS.texts) }
+  if (added.length > NOTE_LIMITS.texts) out.more_added = added.length - NOTE_LIMITS.texts
+  if (removed.length > NOTE_LIMITS.texts) out.more_removed = removed.length - NOTE_LIMITS.texts
+  return out
+}
+
+/** Token changes between two DTCG sets (resolved values): changed, added and removed names. */
+export function tokenChanges (before, after) {
+  const flat = (set) => { try { return new Map(set ? flattenTokens(set).map((t) => [t.name, JSON.stringify(t.value)]) : []) } catch { return new Map() } }
+  const a = flat(before), b = flat(after)
+  const show = (v) => { try { const x = JSON.parse(v); return typeof x === 'string' || typeof x === 'number' ? String(x) : v } catch { return v } }
+  const changed = [], added = [], removed = []
+  for (const [name, v] of b) { if (!a.has(name)) added.push(name); else if (a.get(name) !== v) changed.push({ name, from: show(a.get(name)), to: show(v) }) }
+  for (const name of a.keys()) if (!b.has(name)) removed.push(name)
+  if (!changed.length && !added.length && !removed.length) return null
+  return { changed: changed.slice(0, NOTE_LIMITS.tokens), added: added.slice(0, NOTE_LIMITS.tokens), removed: removed.slice(0, NOTE_LIMITS.tokens), count: changed.length + added.length + removed.length }
+}
+
+/** One change as a sentence. */
+function changeText (c, lang) {
+  const cs = lang === 'cs'
+  switch (c.kind) {
+    case 'new': return cs ? 'Nový krok.' : 'New step.'
+    case 'removed': return cs ? 'Krok z flow zmizel.' : 'Removed from the flow.'
+    case 'locales': return cs ? `Nově i v jazycích ${c.added.join(', ')}.` : `Now also in ${c.added.join(', ')}.`
+    case 'text': {
+      const parts = []
+      const [a] = c.added, [r] = c.removed
+      if (c.added.length === 1 && c.removed.length === 1 && !c.more_added && !c.more_removed) parts.push(`${quote(short(r), lang)} → ${quote(short(a), lang)}`)
+      else {
+        if (c.added.length) parts.push(`${cs ? 'nově' : 'new'} ${c.added.map((t) => quote(short(t, 40), lang)).join(', ')}${c.more_added ? (cs ? ` a ${c.more_added} dalších` : ` and ${c.more_added} more`) : ''}`)
+        if (c.removed.length) parts.push(`${cs ? 'zmizelo' : 'gone'} ${c.removed.map((t) => quote(short(t, 40), lang)).join(', ')}${c.more_removed ? (cs ? ` a ${c.more_removed} dalších` : ` and ${c.more_removed} more`) : ''}`)
+      }
+      return `${cs ? 'Text' : 'Text'}: ${parts.join('; ')}.`
+    }
+    case 'look': return c.viewports?.length ? (cs ? `Vypadá jinak na ${list(c.viewports, lang)}.` : `Looks different on ${list(c.viewports, lang)}.`) : (cs ? 'Vypadá jinak.' : 'Looks different.')
+    case 'same_look': return cs ? 'Vypadá stejně, změnil se jen kód stránky.' : 'Looks the same; only the page code changed.'
+    case 'tokens': return cs ? `Používá novou sadu tokenů (${c.count} ${c.count === 1 ? 'změna' : c.count < 5 ? 'změny' : 'změn'}).` : `Uses the new token set (${c.count} change${c.count === 1 ? '' : 's'}).`
+    case 'not_rendered': return cs ? 'Zatím bez nového snímku.' : 'Not rendered yet.'
+    default: return ''
+  }
+}
+
+export const stepText = (changes, lang) => changes.map((c) => changeText(c, lang)).filter(Boolean).join(' ')
+
+/**
+ * Builds the notes from the facts of each changed step. `steps`: [{ step, title, locales, reason: new|changed|removed,
+ * look: [viewports whose screenshot differs] | null (no captures to compare), texts: { before: Set, after: Set } | null,
+ * tokens: boolean (the revision's token set changed), files: boolean }], `tokens`: tokenChanges() of the version or
+ * null, `unchanged`: count of unchanged step×locale, `from`: the previous version { version, id } or null.
+ */
+export function buildNotes ({ steps = [], tokens = null, unchanged = 0, from = null }) {
+  const out = []
+  for (const s of steps) {
+    const changes = []
+    if (s.reason === 'new') changes.push({ kind: 'new' })
+    else if (s.reason === 'removed') changes.push({ kind: 'removed' })
+    else {
+      if (s.new_locales?.length) changes.push({ kind: 'locales', added: s.new_locales })
+      if (s.texts) { const t = textChanges(s.texts.before, s.texts.after); if (t) changes.push(t) }
+      if (s.look == null) changes.push({ kind: 'not_rendered' })
+      else if (s.look.length) changes.push({ kind: 'look', viewports: s.look })
+      if (s.tokens && tokens) changes.push({ kind: 'tokens', count: tokens.count })
+      if (s.look && !s.look.length && !changes.some((c) => c.kind === 'text' || c.kind === 'tokens' || c.kind === 'locales')) changes.push({ kind: 'same_look' })
+    }
+    out.push({ step: s.step, title: s.title || s.step, locales: s.locales || [], reason: s.reason, changes, text: { en: stepText(changes, 'en'), cs: stepText(changes, 'cs') } })
+  }
+  return { schema: NOTES_SCHEMA, from, summary: summaryOf(out, tokens, unchanged), steps: out, tokens, unchanged }
+}
+
+function summaryOf (steps, tokens, unchanged) {
+  const mk = (lang) => {
+    const cs = lang === 'cs'
+    const changed = steps.filter((s) => s.reason !== 'removed')
+    const removed = steps.filter((s) => s.reason === 'removed')
+    const parts = []
+    if (!steps.length) parts.push(cs ? 'Beze změny proti předchozí verzi.' : 'Nothing changed since the previous version.')
+    else {
+      const names = (xs) => xs.slice(0, 6).map((s) => s.title).join(', ') + (xs.length > 6 ? (cs ? ` a ${xs.length - 6} dalších` : ` and ${xs.length - 6} more`) : '')
+      if (changed.length) parts.push(cs ? `Změněno: ${names(changed)}.` : `Changed: ${names(changed)}.`)
+      if (removed.length) parts.push(cs ? `Odebráno: ${names(removed)}.` : `Removed: ${names(removed)}.`)
+      if (unchanged) parts.push(cs ? `Beze změny: ${unchanged} (počítáno po jazycích).` : `Unchanged: ${unchanged} (counted per locale).`)
+    }
+    if (tokens?.changed?.length) {
+      const shown = tokens.changed.slice(0, 3)
+      const t = shown.map((c) => `${c.name} ${c.from} → ${c.to}`).join(', ')
+      const more = tokens.count - shown.length
+      parts.push(cs ? `Tokeny: ${t}${more ? ` a ${more} ${more === 1 ? 'další' : 'dalších'}` : ''}.` : `Tokens: ${t}${more ? ` and ${more} more` : ''}.`)
+    } else if (tokens?.count) parts.push(cs ? `Sada tokenů: ${tokens.count} ${tokens.count === 1 ? 'změna' : tokens.count < 5 ? 'změny' : 'změn'}.` : `Token set: ${tokens.count} change${tokens.count === 1 ? '' : 's'}.`)
+    return parts.join(' ')
+  }
+  return { en: mk('en'), cs: mk('cs') }
+}
+
+/**
+ * Notes someone wrote (an agent with --notes, a person in the canvas): JSON { summary, steps: { id: text } } or text
+ * where lines "step-id: text" (optionally as a list item) belong to that step and the rest is the summary.
+ */
+export function parseNotes (input, stepIds = []) {
+  if (input == null || input === '') return null
+  let obj = input
+  if (typeof input === 'string') {
+    const s = input.trim()
+    if (s.startsWith('{')) { try { obj = JSON.parse(s) } catch { obj = s } } else obj = s
+  }
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    const steps = {}
+    const src = obj.steps && typeof obj.steps === 'object' ? obj.steps : {}
+    for (const [k, v] of Array.isArray(src) ? src.map((x) => [x?.step, x?.text]) : Object.entries(src)) { const t = clean(typeof v === 'string' ? v : v?.text ?? v?.en ?? ''); if (k && t) steps[String(k)] = t.slice(0, NOTE_LIMITS.step) }
+    const summary = typeof obj.summary === 'string' ? obj.summary.trim().slice(0, NOTE_LIMITS.summary) : null
+    return summary || Object.keys(steps).length ? { summary, steps } : null
+  }
+  const ids = new Set(stepIds)
+  const steps = {}
+  const rest = []
+  let current = null
+  for (const line of String(obj).split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:[-*]\s+)?(?:\*\*|`)?([A-Za-z0-9][A-Za-z0-9._-]*)(?:\*\*|`)?\s*:\s+(.*)$/)
+    if (m && ids.has(m[1])) { current = m[1]; steps[current] = clean(m[2]); continue }
+    if (current && /^\s{2,}\S/.test(line)) { steps[current] = clean(`${steps[current]} ${line}`); continue }
+    current = null
+    rest.push(line)
+  }
+  for (const k of Object.keys(steps)) steps[k] = steps[k].slice(0, NOTE_LIMITS.step)
+  const summary = rest.join('\n').replace(/^\s*#+\s.*$/gm, '').trim().slice(0, NOTE_LIMITS.summary) || null
+  return summary || Object.keys(steps).length ? { summary, steps } : null
+}
+
+/** Generated notes with the edits applied: an edited summary or step text replaces the generated one. */
+export function mergeNotes (auto, edited, { by = null, at = null, titles = {} } = {}) {
+  const base = auto ? JSON.parse(JSON.stringify(auto)) : { schema: NOTES_SCHEMA, from: null, summary: null, steps: [], tokens: null, unchanged: 0 }
+  if (!edited) return base
+  if (edited.summary) { base.summary = edited.summary; base.summary_edited = true }
+  for (const [id, text] of Object.entries(edited.steps || {})) {
+    const s = base.steps.find((x) => x.step === id)
+    if (s) { s.text = text; s.edited = true } else base.steps.push({ step: id, title: titles[id] || id, locales: [], reason: 'note', changes: [], text, edited: true })
+  }
+  if (by) base.edited_by = by
+  if (at) base.edited_at = at
+  return base
+}
+
+/** The notes as plain text for the terminal and MCP. */
+export function notesText (notes, { lang = 'en', title = '' } = {}) {
+  if (!notes) return 'No notes.'
+  const lines = []
+  if (title) lines.push(title)
+  const sum = noteText(notes.summary, lang)
+  if (sum) lines.push(sum)
+  for (const s of notes.steps || []) lines.push(`- ${s.step}${s.title && s.title !== s.step ? ` (${s.title})` : ''}${s.locales?.length ? ` [${s.locales.join(', ')}]` : ''}: ${noteText(s.text, lang)}${s.edited ? '' : ''}`)
+  return lines.join('\n')
+}

package/src/lib/docs-core.mjs

@@ -0,0 +1,450 @@
+// Living documentation (docs/DOCS-CHANGELOG.md, phases 2 and 3), the parts the CLI and the service share: where a
+// Markdown file sits in the docs (Diátaxis folders, sibling translations `guide.cs.md`), front matter, sections with
+// their step references, the guide as training steps, the translations report, stale sections, changelog items
+// without pictures, and a small Markdown renderer. No I/O and no Node built-ins: the worker imports this file too.
+import { findStepRefs, parseStepRef, parseChangelog, parseEntry } from './changelog-core.mjs'
+
+export const KINDS = ['tutorials', 'how-to', 'reference', 'explanation']
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/
+export const LANG = /^[a-z]{2}(-[A-Z]{2})?$/
+export const MAX_PAGE = 200 * 1024
+
+// ---------- files and paths ----------
+
+/**
+ * Where a file of the docs folder goes: `how-to/pay.md` → { path: 'how-to/pay', lang: null }, `how-to/pay.cs.md` →
+ * lang cs, `index.md` and `README.md` → the folder itself (`''`, `how-to`). Null for files that are not pages
+ * (not Markdown, hidden, or with a path the service does not take).
+ */
+export function docFile (rel) {
+  const p = String(rel || '').replace(/\\/g, '/').replace(/^\.?\//, '')
+  if (!/\.(md|markdown)$/i.test(p) || p.split('/').some((s) => !s || s.startsWith('.') || s.startsWith('_'))) return null
+  const parts = p.split('/')
+  let name = parts.pop().replace(/\.(md|markdown)$/i, '')
+  let lang = null
+  const m = name.match(/^(.+)\.([a-z]{2}(?:-[A-Z]{2})?)$/)
+  if (m) { name = m[1]; lang = m[2] }
+  if (/^(index|readme)$/i.test(name)) name = ''
+  const path = [...parts, name].filter(Boolean).join('/')
+  if (path && !path.split('/').every((s) => SEGMENT.test(s))) return null
+  if (path.length > 200) return null
+  return { path, lang }
+}
+
+/** Is this a page path the service stores ('' is the docs index)? */
+export const validDocPath = (p) => p === '' || (typeof p === 'string' && p.length <= 200 && p.split('/').every((s) => SEGMENT.test(s)))
+
+/** The Diátaxis kind of a page from its first folder (tutorials, how-to, reference, explanation), else null. */
+export function kindOf (path) {
+  const top = String(path || '').split('/')[0].toLowerCase()
+  const alias = { tutorial: 'tutorials', howto: 'how-to', 'how-tos': 'how-to', guides: 'how-to', explanations: 'explanation', concepts: 'explanation' }
+  const k = alias[top] || top
+  return KINDS.includes(k) ? k : null
+}
+
+// ---------- front matter ----------
+
+/** `---` front matter with a flat YAML subset (scalars, quoted strings, [a, b] lists, true/false, numbers). */
+export function frontMatter (md) {
+  const text = String(md || '').replace(/^/, '').replace(/\r/g, '')
+  const m = text.match(/^---\n([\s\S]*?)\n---[ \t]*(?:\n|$)/)
+  if (!m) return { data: {}, body: text }
+  const data = {}
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/)
+    if (!kv) continue
+    data[kv[1]] = scalar(kv[2].trim())
+  }
+  return { data, body: text.slice(m[0].length) }
+}
+function scalar (v) {
+  if (v === '') return ''
+  if (/^\[.*\]$/.test(v)) return v.slice(1, -1).split(',').map((x) => scalar(x.trim())).filter((x) => x !== '')
+  if (/^".*"$/.test(v) || /^'.*'$/.test(v)) return v.slice(1, -1)
+  if (v === 'true' || v === 'false') return v === 'true'
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v)
+  return v.replace(/\s+#.*$/, '')
+}
+
+/** The title of a page: front matter title, else its first `# ` heading, else the last part of its path. */
+export function docTitle (md, path = '') {
+  const { data, body } = frontMatter(md)
+  if (typeof data.title === 'string' && data.title.trim()) return data.title.trim().slice(0, 200)
+  const h = body.match(/^#\s+(.+?)\s*#*\s*$/m)
+  if (h) return stripInline(h[1]).slice(0, 200)
+  const last = String(path || '').split('/').pop()
+  return last ? last.replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase()) : 'Documentation'
+}
+
+/** The order of a page in the sidebar: front matter order / sidebar_position / nav_order, else null. */
+export const docOrder = (data) => [data?.order, data?.sidebar_position, data?.nav_order].find((x) => typeof x === 'number') ?? null
+
+const stripInline = (s) => String(s).replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[`*_]/g, '').trim()
+
+// ---------- sections ----------
+
+/** A heading id: lower case, accents dropped, words joined by dashes. */
+export function slugify (s) {
+  return String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/<[^>]+>/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'section'
+}
+
+/** Lines of a body with whether each is inside a fenced code block. */
+function fenced (lines) {
+  let inside = false
+  return lines.map((l) => { const fence = /^\s{0,3}(```|~~~)/.test(l); const was = inside; if (fence) inside = !inside; return was || fence })
+}
+
+/**
+ * The sections of a page body: text before the first heading (id '', level 0), then one per heading of level 1–3,
+ * each with its own text (up to the next heading of any of these levels) and its step references.
+ */
+export function sections (body) {
+  const lines = String(body || '').replace(/\r/g, '').split('\n')
+  const code = fenced(lines)
+  const out = []; const used = new Map()
+  let cur = { id: '', level: 0, title: '', lines: [] }
+  for (let i = 0; i < lines.length; i++) {
+    const h = !code[i] && lines[i].match(/^(#{1,3})\s+(.+?)\s*#*\s*$/)
+    if (h) {
+      out.push(cur)
+      let id = slugify(stripInline(h[2]))
+      const n = (used.get(id) || 0) + 1; used.set(id, n); if (n > 1) id = `${id}-${n}`
+      cur = { id, level: h[1].length, title: stripInline(h[2]), lines: [], heading: lines[i] }
+      continue
+    }
+    cur.lines.push(lines[i])
+  }
+  out.push(cur)
+  return out.filter((s) => s.level || s.lines.some((l) => l.trim())).map((s) => { const text = s.lines.join('\n'); return { id: s.id, level: s.level, title: s.title, text, refs: findStepRefs(text).filter((r) => r.parsed).map((r) => r.ref) } })
+}
+
+// ---------- training mode ----------
+
+/**
+ * A guide as training steps: every block (list item or paragraph) that shows a step becomes one step whose caption is
+ * the block's words and whose picture is its last step reference (the "after" of a before/after pair). A picture on
+ * its own line belongs to the text right above it. Returns [{ caption, ref, alt, refs }].
+ */
+export function trainingSteps (body) {
+  const blocks = []
+  const lines = String(body || '').replace(/\r/g, '').split('\n')
+  const code = fenced(lines)
+  let cur = null
+  const flush = () => { if (cur && cur.join('\n').trim()) blocks.push(cur.join('\n')); cur = null }
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (code[i]) { flush(); continue }
+    if (/^#{1,6}\s/.test(l)) { flush(); blocks.push({ heading: l.replace(/^#+\s+/, '').trim() }); continue }
+    if (/^\s{0,3}([-*+]|\d+[.)])\s+/.test(l)) { flush(); cur = [l.replace(/^\s{0,3}([-*+]|\d+[.)])\s+/, '')]; continue }
+    if (!l.trim()) { if (cur && i + 1 < lines.length && /^\s{2,}\S/.test(lines[i + 1])) { cur.push(''); continue } flush(); continue }
+    if (cur && /^\s+\S/.test(l)) { cur.push(l.trim()); continue }
+    if (!cur) cur = []
+    cur.push(l.trim())
+  }
+  flush()
+  const steps = []
+  let heading = null
+  let pendingText = null
+  for (const b of blocks) {
+    if (typeof b === 'object') { heading = b.heading; pendingText = null; continue }
+    const refs = findStepRefs(b).filter((r) => r.parsed)
+    const words = b.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/<!--[\s\S]*?-->/g, '').replace(/[ \t]+/g, ' ').replace(/\s*\n\s*/g, '\n').trim()
+    if (!refs.length) { pendingText = words || null; continue }
+    const caption = words || pendingText || heading || refs[refs.length - 1].alt || ''
+    const last = refs[refs.length - 1]
+    steps.push({ caption, ref: last.ref, alt: last.alt, refs: refs.map((r) => r.ref), heading })
+    pendingText = null
+  }
+  return steps
+}
+
+// ---------- the sidebar ----------
+
+/**
+ * The sidebar of a set of pages (one language): the index first, then the Diátaxis folders in their order, then
+ * other folders; inside a folder by front matter order, then title. [{ path, title, kind, children: [...] }]
+ */
+export function buildNav (pages) {
+  const byPath = new Map(pages.map((p) => [p.path, p]))
+  const top = new Map()
+  for (const p of pages) {
+    if (p.path === '') continue
+    const [first] = p.path.split('/')
+    if (!top.has(first)) top.set(first, { path: first, title: byPath.get(first)?.title || folderTitle(first), kind: kindOf(first), order: byPath.get(first)?.order ?? null, page: byPath.has(first), children: [] })
+    if (p.path !== first) top.get(first).children.push({ path: p.path, title: p.title, kind: kindOf(p.path), order: p.order ?? null, page: true })
+  }
+  const rank = (n) => { const i = KINDS.indexOf(kindOf(n.path)); return i < 0 ? 10 : i }
+  const sort = (a, b) => (a.order ?? 1e9) - (b.order ?? 1e9) || String(a.title).localeCompare(String(b.title))
+  const list = [...top.values()].sort((a, b) => rank(a) - rank(b) || sort(a, b))
+  for (const n of list) n.children.sort(sort)
+  return [...(byPath.has('') ? [{ path: '', title: byPath.get('').title, kind: null, page: true, children: [] }] : []), ...list]
+}
+const FOLDERS = { tutorials: 'Tutorials', 'how-to': 'How-to guides', reference: 'Reference', explanation: 'Explanation' }
+export const folderTitle = (f) => FOLDERS[kindOf(f)] && kindOf(f) === f ? FOLDERS[f] : String(f).replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase())
+
+/** The nav flattened in reading order (for previous / next links). */
+export const navOrder = (nav) => nav.flatMap((n) => [...(n.page ? [n.path] : []), ...n.children.map((c) => c.path)])
+
+// ---------- translations ----------
+
+/**
+ * Which translations are missing or older than their original. `pages`: [{ path, lang (null = the original
+ * language), hash, front, updated (ISO, optional) }]; `languages`: the configured languages, the first is the
+ * original's. A translation is outdated when its front matter `source_hash` (a prefix of the original's SHA-256)
+ * differs from the original, or, without one, when the original changed later (git dates). Returns
+ * { languages, missing: [{ path, lang }], outdated: [{ path, lang, why }], orphans: [{ path, lang }] }.
+ */
+export function translationReport (pages, languages = []) {
+  const langs = [...new Set((languages || []).filter((l) => LANG.test(l)))]
+  const base = langs[0] || null
+  const others = langs.slice(1)
+  const originals = new Map(); const translations = new Map()
+  for (const p of pages) {
+    if (!p.lang || p.lang === base) originals.set(p.path, p)
+    else translations.set(`${p.path}|${p.lang}`, p)
+  }
+  const missing = []; const outdated = []; const orphans = []
+  for (const [path, o] of originals) {
+    for (const l of others) {
+      const t = translations.get(`${path}|${l}`)
+      if (!t) { missing.push({ path, lang: l }); continue }
+      const want = t.front?.source_hash ? String(t.front.source_hash) : null
+      if (want && o.hash && !o.hash.startsWith(want.toLowerCase())) outdated.push({ path, lang: l, why: 'source_hash' })
+      else if (!want && o.updated && t.updated && o.updated > t.updated) outdated.push({ path, lang: l, why: 'older' })
+    }
+  }
+  for (const t of translations.values()) if (!originals.has(t.path)) orphans.push({ path: t.path, lang: t.lang })
+  return { languages: langs, missing, outdated, orphans }
+}
+
+// ---------- stale sections ----------
+
+/**
+ * Sections whose pictures changed since the text was published. `recorded`: { ref: { hash, run } | null } taken when
+ * the page's text last changed; `current`: { ref: { hash, run, app_version, started_at } | null } now. A reference
+ * that had no picture then is not stale (it is new). Returns [{ section, title, refs: [{ ref, changed_in, run }] }].
+ */
+export function staleSections (body, recorded = {}, current = {}) {
+  const out = []
+  for (const s of sections(body)) {
+    const refs = []
+    for (const ref of new Set(s.refs)) {
+      const was = recorded?.[ref]; const now = current?.[ref]
+      if (!was?.hash || !now?.hash || was.hash === now.hash) continue
+      refs.push({ ref, changed_in: now.app_version || (now.started_at ? String(now.started_at).slice(0, 10) : null), run: now.run || null, was_run: was.run || null })
+    }
+    if (refs.length) out.push({ section: s.id, title: s.title, refs })
+  }
+  return out
+}
+
+// ---------- changelog items without pictures ----------
+
+const VISIBLE = ['Added', 'Changed', 'Removed']
+/**
+ * User-visible changelog items (Added, Changed, Removed) without a step reference, in Unreleased and the newest
+ * release. `<!-- no picture -->` in an item says it has nothing to show. [{ section, group, item }]
+ */
+export function itemsWithoutPictures (changelogText) {
+  const { sections: secs } = parseChangelog(changelogText)
+  const pick = [secs.find((s) => s.unreleased), secs.find((s) => !s.unreleased)].filter(Boolean)
+  const out = []
+  for (const s of pick) {
+    for (const g of parseEntry(s.body).groups) {
+      if (!VISIBLE.includes(g.name)) continue
+      for (const it of g.items) {
+        if (findStepRefs(it).some((r) => r.parsed) || /<!--\s*no[ -]picture\s*-->/i.test(it)) continue
+        out.push({ section: s.unreleased ? 'Unreleased' : s.version, group: g.name, item: it.split('\n')[0].replace(/<!--[\s\S]*?-->/g, '').trim().slice(0, 200) })
+      }
+    }
+  }
+  return out
+}
+
+// ---------- links between pages ----------
+
+/**
+ * Where a link in a page points: another page of the docs ({ path, hash }) for relative `.md` links (sibling
+ * translations included), else null (external links, anchors and anything else stay as written).
+ */
+export function docLink (fromPath, href, { isIndex = false } = {}) {
+  const h = String(href || '')
+  if (/^[a-z][a-z0-9+.-]*:|^\/\/|^#|^\//i.test(h)) return null
+  const [file, hash = ''] = h.split('#')
+  if (!/\.(md|markdown)$/i.test(file)) return null
+  const dir = isIndex ? String(fromPath || '').split('/').filter(Boolean) : String(fromPath || '').split('/').filter(Boolean).slice(0, -1)
+  for (const seg of file.split('/')) {
+    if (seg === '..') dir.pop()
+    else if (seg && seg !== '.') dir.push(seg)
+  }
+  const f = docFile(dir.join('/'))
+  return f ? { path: f.path, lang: f.lang, hash } : null
+}
+
+// ---------- Markdown to HTML ----------
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+export const escapeHtml = esc
+
+/** Inline Markdown: code, bold, italics, links (safe schemes; `link(href)` may rewrite or drop them). Images are removed. */
+export function inlineHtml (s, { link = null } = {}) {
+  let out = esc(String(s).replace(/!\[[^\]]*\]\([^)]*\)/g, ''))
+  const codes = []
+  out = out.replace(/`([^`]+)`/g, (_, c) => { codes.push(`<code>${c}</code>`); return `\u0000${codes.length - 1}\u0000` })
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>').replace(/__([^_]+)__/g, '<b>$1</b>').replace(/(^|[\s(])_([^_]+)_(?=$|[\s).,;:!?])/g, '$1<i>$2</i>').replace(/(^|[\s(])\*([^*\s][^*]*)\*(?=$|[\s).,;:!?])/g, '$1<i>$2</i>')
+  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_, t, href) => {
+    const raw = href.replace(/&amp;/g, '&')
+    const target = link ? link(raw) : raw
+    if (target == null) return t
+    return /^(https?:\/\/|\/|#|mailto:|\.{0,2}\/?[A-Za-z0-9._/-]+(\.html)?(#[A-Za-z0-9_-]*)?$)/.test(target) && !/^javascript:/i.test(target) ? `<a href="${esc(target)}"${/^https?:/.test(target) ? ' rel="noopener"' : ''}>${t}</a>` : t
+  })
+  return out.replace(/\u0000(\d+)\u0000/g, (_, i) => codes[Number(i)])
+}
+
+const LIST = /^(\s{0,3})([-*+]|\d{1,9}[.)])\s+(.*)$/
+const IMG = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g
+
+/**
+ * Markdown to HTML for docs: headings (with ids), paragraphs, lists (nested by indentation), fenced code,
+ * blockquotes, tables, rules, inline formatting and pictures. `picture(images)` gets the images of one block
+ * ([{ alt, src, ref }]) and returns their HTML; `link(href)` rewrites links; `notice(sectionId)` adds HTML right
+ * under a section heading (stale notes); `headingIds` is filled with { level, id, title }. Raw HTML is escaped.
+ */
+export function renderMarkdown (body, opts = {}) {
+  const ids = opts.headingIds || []
+  const used = new Map()
+  const text = String(body || '').replace(/\r/g, '').replace(/<!--[\s\S]*?-->/g, '')
+  const html = blocks(text.split('\n'), { ...opts, ids, used, top: true })
+  return html
+}
+
+function picturesOf (text) {
+  const imgs = []
+  const words = String(text).replace(IMG, (_, alt, src) => { imgs.push({ alt, src, ref: parseStepRef(src) }); return ' ' })
+  return { imgs, words: words.replace(/[ \t]+\n/g, '\n').trim() }
+}
+
+function blocks (lines, o) {
+  const out = []
+  let i = 0
+  const para = []
+  const flush = () => {
+    if (!para.length) return
+    const { imgs, words } = picturesOf(para.join('\n'))
+    if (words) out.push(`<p>${inlineHtml(words.replace(/\n/g, ' '), o)}</p>`)
+    if (imgs.length) out.push(pics(imgs, o))
+    para.length = 0
+  }
+  while (i < lines.length) {
+    const l = lines[i]
+    const fence = l.match(/^\s{0,3}(```+|~~~+)\s*([\w-]*)/)
+    if (fence) {
+      flush()
+      const buf = []; i++
+      while (i < lines.length && !lines[i].trim().startsWith(fence[1])) buf.push(lines[i++])
+      i++
+      out.push(`<pre class="dc-code"><code${fence[2] ? ` class="language-${esc(fence[2])}"` : ''}>${esc(buf.join('\n'))}</code></pre>`)
+      continue
+    }
+    const h = l.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/)
+    if (h) {
+      flush()
+      const level = h[1].length
+      const title = h[2]
+      let id = slugify(stripInline(title))
+      const n = (o.used.get(id) || 0) + 1; o.used.set(id, n); if (n > 1) id = `${id}-${n}`
+      if (level <= 3) o.ids.push({ level, id, title: stripInline(title) })
+      const tag = `h${Math.min(6, level)}`
+      out.push(`<${tag} id="${esc(id)}">${inlineHtml(title, o)}${level > 1 && level <= 3 ? ` <a class="dc-anchor" href="#${esc(id)}" aria-hidden="true">#</a>` : ''}</${tag}>`)
+      if (level <= 3 && o.notice) { const x = o.notice(id); if (x) out.push(x) }
+      i++
+      continue
+    }
+    if (/^\s{0,3}([-*_])(\s*\1){2,}\s*$/.test(l)) { flush(); out.push('<hr>'); i++; continue }
+    if (/^\s{0,3}>/.test(l)) {
+      flush()
+      const buf = []
+      while (i < lines.length && /^\s{0,3}>/.test(lines[i])) buf.push(lines[i++].replace(/^\s{0,3}>\s?/, ''))
+      out.push(`<blockquote>${blocks(buf, { ...o, notice: null })}</blockquote>`)
+      continue
+    }
+    if (/^\s*\|.*\|\s*$/.test(l) && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(lines[i + 1])) {
+      flush()
+      const row = (x) => x.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim())
+      const head = row(l); i += 2
+      const rows = []
+      while (i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])) rows.push(row(lines[i++]))
+      out.push(`<div class="dc-table"><table><thead><tr>${head.map((c) => `<th>${inlineHtml(c, o)}</th>`).join('')}</tr></thead><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${inlineHtml(c, o)}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`)
+      continue
+    }
+    const li = l.match(LIST)
+    if (li) {
+      flush()
+      const ordered = /\d/.test(li[2])
+      const start = ordered ? Number(li[2].replace(/\D/g, '')) : 1
+      const items = []
+      while (i < lines.length) {
+        const m = lines[i].match(LIST)
+        if (!m || /\d/.test(m[2]) !== ordered || m[1].length > 3) break
+        const indent = m[1].length + m[2].length + 1
+        const item = [m[3]]; i++
+        while (i < lines.length) {
+          const n = lines[i]
+          if (!n.trim()) {
+            // a blank line keeps the item open when indented text follows
+            if (i + 1 < lines.length && /^\s{2,}\S/.test(lines[i + 1])) { item.push(''); i++; continue }
+            break
+          }
+          if (LIST.test(n) && n.match(/^\s*/)[0].length < 2) break
+          if (/^\s{2,}/.test(n)) { item.push(n.replace(new RegExp(`^\\s{0,${Math.max(2, indent)}}`), '')); i++; continue }
+          if (/^(#{1,6}\s|\s{0,3}(```|~~~|>))/.test(n)) break
+          item.push(n.trim()); i++
+        }
+        items.push(item)
+        while (i < lines.length && !lines[i].trim() && i + 1 < lines.length && LIST.test(lines[i + 1]) && lines[i + 1].match(LIST)[1].length <= 3 && /\d/.test(lines[i + 1].match(LIST)[2]) === ordered) i++
+      }
+      const tag = ordered ? 'ol' : 'ul'
+      out.push(`<${tag}${ordered && start !== 1 ? ` start="${start}"` : ''}>${items.map((it) => `<li>${listItem(it, o)}</li>`).join('')}</${tag}>`)
+      continue
+    }
+    if (!l.trim()) { flush(); i++; continue }
+    para.push(l); i++
+  }
+  flush()
+  return out.join('\n')
+}
+
+/** A list item: its first paragraph inline (tight lists), the rest as blocks (nested lists, pictures, code). */
+function listItem (lines, o) {
+  const first = []
+  let i = 0
+  while (i < lines.length && lines[i].trim() && !LIST.test(lines[i]) && !/^\s{0,3}(```|~~~)/.test(lines[i])) first.push(lines[i++])
+  const { imgs, words } = picturesOf(first.join('\n'))
+  const rest = lines.slice(i)
+  return `${words ? inlineHtml(words.replace(/\n/g, ' '), o) : ''}${imgs.length ? pics(imgs, o) : ''}${rest.some((l) => l.trim()) ? blocks(rest, { ...o, notice: null }) : ''}`
+}
+
+function pics (imgs, o) {
+  if (o.picture) return o.picture(imgs)
+  return `<div class="dc-pics">${imgs.map((i) => /^https?:\/\//.test(i.src) || (!i.ref && /^[A-Za-z0-9._/-]+$/.test(i.src)) ? `<img src="${esc(i.src)}" alt="${esc(i.alt)}" loading="lazy">` : `<span class="dc-missing">${esc(i.alt || i.src)}</span>`).join('')}</div>`
+}
+
+// ---------- search ----------
+
+/** Plain words of a page for search and snippets (no Markdown syntax, no pictures, no comments). */
+export function plainText (md) {
+  return frontMatter(md).body.replace(/<!--[\s\S]*?-->/g, ' ').replace(/```[\s\S]*?```/g, ' ').replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/^#+\s+/gm, '').replace(/^\s*([-*+]|\d+[.)])\s+/gm, '').replace(/[`*_>|]/g, '').replace(/\s+/g, ' ').trim()
+}
+
+/** Where `q` occurs in a text: a short snippet around the first hit, or null. Case and accents do not matter. */
+export function snippet (text, q, width = 160) {
+  const fold = (s) => s.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase()
+  const words = fold(String(q || '')).split(/\s+/).filter((w) => w.length > 1)
+  if (!words.length) return null
+  const t = String(text || '')
+  const f = fold(t)
+  if (!words.every((w) => f.includes(w))) return null
+  const at = f.indexOf(words[0])
+  const start = Math.max(0, at - Math.floor(width / 3))
+  return `${start ? '…' : ''}${t.slice(start, start + width).trim()}${start + width < t.length ? '…' : ''}`
+}