kaloko 0.5.2 → 0.7.0

package/src/lib/changelog.mjs

@@ -259,7 +259,7 @@ export async function releaseProduct ({ root, config, product, version = null, d
   const tag = tagFor(src.pattern, v)
   const commit = (await tagExists(root, tag)) ? ((await out('git', ['rev-list', '-n', '1', tag], root)) || '').trim() : ((await out('git', ['rev-parse', 'HEAD'], root)) || '').trim()
   const payload = {
-    product: { slug: product.slug, name: product.name, projects: product.projects, modules: product.modules, reference_env: product.reference_env, default_scenario: product.default_scenario, implicit: product.implicit, version_source: { source: src.source, ...(src.path ? { path: src.path } : {}), pattern: src.pattern, ...(src.tool ? { tool: src.tool } : {}) }, ...(product.publish ? { publish: product.publish } : {}), ...(await repoUrl(root)) },
+    product: await productPayload(root, product, src),
     release: { product: product.slug, version: v, date: section?.date || day, changelog: md, source_hash: sha256(md), tag: (await tagExists(root, tag)) ? tag : null, commit: /^[0-9a-f]{40}$/.test(commit) ? commit : null, ...(runs ? { runs } : {}) }
   }
   if (dryRun) return { version: v, date: payload.release.date, file, section: !!section, finalized, source: src, notes, payload, items: parseEntry(md).groups.reduce((n, g) => n + g.items.length, 0), refs: refs.length }
@@ -268,6 +268,81 @@ export async function releaseProduct ({ root, config, product, version = null, d
   const rec = await client.request('POST', `/orgs/${config.org}/releases`, payload.release)
   return { version: v, date: payload.release.date, file, section: !!section, finalized, source: src, notes, release: rec, product: saved.product, items: parseEntry(md).groups.reduce((n, g) => n + g.items.length, 0), refs: refs.length }
 }
+/** The product as the service records it (POST /products): from the config, with the version source found. */
+export async function productPayload (root, product, src) {
+  return { slug: product.slug, name: product.name, projects: product.projects, modules: product.modules, reference_env: product.reference_env, default_scenario: product.default_scenario, implicit: product.implicit, version_source: { source: src.source, ...(src.path ? { path: src.path } : {}), pattern: src.pattern, ...(src.tool ? { tool: src.tool } : {}) }, ...(product.publish ? { publish: product.publish } : {}), ...(await repoUrl(root)) }
+}
+
+// ---------- products on the service ----------
+
+/**
+ * `kaloko products sync`: every product of the config (or the one asked for) on Kaloko with its name, projects,
+ * modules, version source, reference environment, default scenario and who should read it (publish:, which the
+ * service applies only for someone who manages the product), without recording a release. A product the service
+ * refuses (a project it does not know or the person may not map) is reported and the others still go.
+ */
+export async function syncProducts ({ root, config, client = null, only = null, dryRun = false }) {
+  const all = productsOf(config, root)
+  if (typeof only === 'string' && only && !all.some((p) => p.slug === only)) throw new UserError(`No product ${only} in the config (${all.map((x) => x.slug).join(', ')}).`)
+  const out = []
+  for (const product of all.filter((p) => !only || p.slug === only)) {
+    const src = await detectVersionSource(root, product)
+    const payload = await productPayload(root, product, src)
+    const item = { slug: product.slug, implicit: product.implicit, name: product.name, projects: product.projects, modules: product.modules, version_source: payload.version_source, version: src.version || null, payload }
+    if (dryRun) { out.push(item); continue }
+    try {
+      const saved = await client.request('POST', `/orgs/${config.org}/products`, payload)
+      out.push({ ...item, ok: true, created: saved.created ?? null, publish: saved.product?.publish || null, url: saved.page || saved.url || null, changelog: saved.url || null, notes: saved.notes || [] })
+    } catch (e) { out.push({ ...item, ok: false, error: String(e.message || e).split('\n')[0] }) }
+  }
+  return { dry_run: dryRun, from_config: !!Object.keys(config.products || {}).length, products: out }
+}
+
+/** What `kaloko products sync` did, for people. */
+export function formatSync (r) {
+  const lines = []
+  const n = r.products.length
+  lines.push(r.dry_run ? `${n} product(s) would go to Kaloko; dry run, nothing sent.` : `${r.products.filter((p) => p.ok).length} of ${n} product(s) on Kaloko; no release recorded.`)
+  if (!r.from_config) lines.push('  No products: in kaloko.config.yml, so the project is the product (its own changelog and docs).')
+  for (const p of r.products) {
+    const what = [`${p.projects.length ? `projects ${p.projects.join(', ')}` : 'the whole organization'}`, p.modules.length ? `modules ${p.modules.join(', ')}` : null, `version from ${p.version_source.source}${p.version ? ` (${p.version})` : ''}`].filter(Boolean).join(' · ')
+    const name = typeof p.name === 'object' && p.name ? Object.values(p.name)[0] : p.name
+    lines.push(`  ${p.ok === false ? '✗' : r.dry_run ? '·' : p.created ? '+' : '✓'} ${p.slug}${name && name !== p.slug ? ` (${name})` : ''}: ${what}`)
+    if (p.url) lines.push(`    ${p.url}`)
+    if (p.error) lines.push(`    ! ${p.error}`)
+    for (const x of p.notes || []) lines.push(`    ! ${x}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * `kaloko products list`: the products the service has that the person reads, and the products of the config the
+ * service does not have yet (kaloko products sync puts them there).
+ */
+export async function listProducts ({ root, config, client }) {
+  const service = await client.request('GET', `/orgs/${config.org}/products`)
+  const local = Object.keys(config.products || {}).length ? productsOf(config, root) : []
+  const known = new Set(service.map((p) => p.slug))
+  return { products: service, missing: local.filter((p) => !known.has(p.slug)).map((p) => p.slug) }
+}
+
+/** The list for people. */
+export function formatList (r) {
+  const lines = []
+  if (!r.products.length) lines.push('No product on Kaloko that you read yet. kaloko products sync puts the products of kaloko.config.yml there; kaloko release and kaloko docs publish do it too.')
+  for (const p of r.products) {
+    const name = typeof p.name === 'object' && p.name ? (p.name.en || Object.values(p.name)[0]) : p.name
+    const docs = p.docs ? `docs ${p.docs.versions.join(', ')}${p.docs.languages?.length ? ` (${p.docs.languages.join(', ')})` : ''}` : 'no docs yet'
+    const rel = p.latest_release ? `${p.latest_release.version} on ${p.latest_release.released_on}` : 'no release yet'
+    lines.push(`${p.slug}${name && name !== p.slug ? ` (${name})` : ''}${p.implicit ? ' · the project\'s own' : ''}: ${rel} · ${docs} · read by ${p.readers}${p.public_url ? ` (${p.public_url})` : ''}`)
+    if (p.modules?.length) lines.push(`  modules: ${p.modules.join(', ')}`)
+    if (p.projects?.length) lines.push(`  projects: ${p.projects.join(', ')}`)
+    if (p.url) lines.push(`  ${p.url}`)
+  }
+  if (r.missing.length) lines.push(`In kaloko.config.yml but not on Kaloko yet: ${r.missing.join(', ')}. Run kaloko products sync.`)
+  return lines.join('\n')
+}
+
 async function repoUrl (root) {
   const r = await repoSlug(root)
   return r?.host === 'github' ? { repo: `https://github.com/${r.slug}` } : r?.host === 'gitlab' ? { repo: `https://gitlab.com/${r.slug}` } : {}
@@ -276,8 +351,9 @@ async function repoUrl (root) {
 // ---------- init and doctor ----------
 
 /** The config block `kaloko init --docs=changelog|full` adds (comments say what each line does). */
-export function docsConfigBlock ({ products = null } = {}) {
+export function docsConfigBlock ({ products = null, full = false } = {}) {
   const lines = ['', '# Visual changelog: kaloko changelog draft writes the Unreleased entry with step references,', '# kaloko release <version> records the release and its pictures (docs/DOCS-CHANGELOG.md on kaloko.app)', 'docs:', '  changelog: CHANGELOG.md', '  version_source: auto       # git-tag | package.json | release-please | changesets | semantic-release']
+  if (full) lines.push('  dir: docs                  # guides with step references; kaloko docs publish sends them, kaloko docs check checks them', '  # languages: [en, cs]      # the first is the originals\' language; translations sit next to them (guide.cs.md)')
   if (products?.length) {
     lines.push('# one product per app in this repository; scenarios say which one they show (product: <slug>)', 'products:')
     for (const p of products) lines.push(`  ${p.slug}:`, `    name: ${JSON.stringify(p.name)}`, `    version: { source: package.json, path: ${p.path} }`, `    docs: { changelog: ${p.dir}/CHANGELOG.md }`)
@@ -298,13 +374,73 @@ export async function detectProducts (root) {
   return out.length > 1 ? out : []
 }
 
-/** Diátaxis folders and an index for `kaloko init --docs=full` (only what is missing). */
+/**
+ * Diátaxis folders and an index for `kaloko init --docs=full` (only what is missing). Each folder's README says what
+ * belongs there and carries a template in a comment (comments never show on Kaloko or in exports).
+ */
 export const DOCS_SKELETON = {
-  'docs/index.md': '# Documentation\n\nGuides for the people who use the product. Pictures are step references\n(`![](kaloko:<scenario>/<step>)`) that always show the newest accepted screen.\n\n- [Tutorials](tutorials/) — learn by doing, start to finish\n- [How-to guides](how-to/) — one task each\n- [Reference](reference/) — the facts to look up\n- [Explanation](explanation/) — why it works this way\n',
-  'docs/tutorials/README.md': '# Tutorials\n',
-  'docs/how-to/README.md': '# How-to guides\n',
-  'docs/reference/README.md': '# Reference\n',
-  'docs/explanation/README.md': '# Explanation\n'
+  'docs/index.md': '# Documentation\n\nGuides for the people who use the product. Pictures are step references\n(`![](kaloko:<scenario>/<step>)`) that always show the newest accepted screen.\n\n- [Tutorials](tutorials/README.md): learn by doing, start to finish\n- [How-to guides](how-to/README.md): one task each\n- [Reference](reference/README.md): the facts to look up\n- [Explanation](explanation/README.md): why it works this way\n',
+  'docs/tutorials/README.md': `# Tutorials
+
+A tutorial takes a newcomer through a first success, start to finish, on a path that always works.
+
+<!-- Template (copy into a new file, e.g. first-order.md):
+---
+title: Your first order
+order: 1
+---
+# Your first order
+
+In ten minutes you will have placed an order and seen it in your account.
+
+1. Open the shop and put a tea in the cart.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Checkout** and pay with a test card.
+   ![Payment](kaloko:checkout/payment)
+
+You have placed your first order. Next: [track it](../how-to/track-an-order.md).
+-->
+`,
+  'docs/how-to/README.md': `# How-to guides
+
+One task per page, for someone who already knows what they want to do.
+
+<!-- Template (copy into a new file, e.g. pay-with-apple-pay.md):
+# Pay with Apple Pay
+
+1. Open the cart and choose **Checkout**.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Apple Pay** above the card form and confirm on your phone or Mac.
+   ![Payment](kaloko:checkout/payment)
+
+If the button is missing, your browser has no Apple Pay set up.
+-->
+`,
+  'docs/reference/README.md': `# Reference
+
+Facts to look up: fields, limits, settings, keyboard shortcuts. Tables and lists, no story.
+
+<!-- Template (copy into a new file, e.g. order-states.md):
+# Order states
+
+| State | What it means |
+|---|---|
+| Paid | The payment went through; the order waits for packing. |
+| Shipped | The parcel left the warehouse. |
+
+![Order detail](kaloko:account/order-detail)
+-->
+`,
+  'docs/explanation/README.md': `# Explanation
+
+Why things work the way they do: background, choices, trade-offs.
+
+<!-- Template (copy into a new file, e.g. why-we-hold-payments.md):
+# Why a payment waits a day
+
+Card payments are confirmed the next morning, so a cancelled order costs the customer nothing.
+-->
+`
 }
 
 /**

package/src/lib/ci.mjs

@@ -209,3 +209,74 @@ export function addPreviewEnvironment (text, name = 'preview') {
   const at = m.index + m[0].length
   return text.slice(0, at) + '\n' + block + text.slice(at)
 }
+
+// ---------- releases (docs/DOCS-CHANGELOG.md → release-tool integrations) ----------
+
+const TOOL_SNIPPETS = {
+  'release-please': { after: 'googleapis/release-please-action (id: release)', when: '${{ steps.release.outputs.release_created }}', version: '${{ steps.release.outputs.version }}' },
+  changesets: { after: 'changesets/action (id: changesets)', when: "${{ steps.changesets.outputs.published == 'true' }}", version: '' },
+  'semantic-release': { after: 'npx semantic-release', when: null, version: '' }
+}
+
+/**
+ * .github/workflows/kaloko-release.yml: when a GitHub release is published (release-please, semantic-release with
+ * @semantic-release/github and changesets all publish one) or by hand, `kaloko release <version> --no-write` records
+ * it on Kaloko: the entry the release tool wrote, the accepted runs that are its pictures, and the docs of that
+ * version. `products`: [{ slug, pattern }] (tag patterns such as v* or shop-v*); several products get one step each.
+ */
+export function releaseWorkflow ({ products = [{ slug: null, pattern: 'v*' }], pm = 'npm', dependency = true, version = 'latest', node = 22, tool = null }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const several = products.length > 1
+  const steps = products.map((p) => {
+    const prefix = String(p.pattern || 'v*').split('*')[0]
+    const flag = several || p.slug ? ` --product ${q(p.slug)}` : ''
+    return `      - name: Record ${p.slug || 'the release'} on Kaloko
+${several ? `        if: startsWith(env.TAG, '${prefix}')\n` : ''}        run: ${k} release "\${TAG#${prefix}}"${flag} --no-write`
+  }).join('\n')
+  return `# Kaloko: record every release on Kaloko once your release tool has published it: its changelog entry with
+# before/after pictures, the accepted runs that are its reference, and the docs of that version.
+# Written by kaloko ci github --release${tool ? ` (${tool} found)` : ''}. Secret: KALOKO_TOKEN (tester role, upload scope).
+# kaloko release --no-write only reads CHANGELOG.md; the release tool keeps writing it.
+name: Kaloko release
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag of the release to record (e.g. v2.4.0)
+        required: true
+permissions:
+  contents: read
+jobs:
+  record:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      GH_TOKEN: \${{ github.token }}
+      KALOKO_AGENT: github-actions
+      TAG: \${{ github.event.release.tag_name || inputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.release.tag_name || inputs.tag }}
+          fetch-depth: 0   # the tags and the history since the previous release
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}${steps}
+`
+}
+
+/** The step to paste into an existing release workflow, right after the release tool's own step. */
+export function releaseSnippet ({ tool = null, pm = 'npm', dependency = true, version = 'latest', product = null }) {
+  const { kaloko: k } = runner({ pm, dependency, version })
+  const s = TOOL_SNIPPETS[tool] || { after: 'the step that publishes the release', when: null, version: '' }
+  return `# after ${s.after}:
+      - name: Record the release on Kaloko
+${s.when ? `        if: ${s.when}\n` : ''}        run: ${k} release${s.version ? ` ${s.version}` : ''}${product ? ` --product ${q(product)}` : ''} --no-write
+        env:
+          KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+`
+}

package/src/lib/design-cli.mjs

@@ -297,11 +297,31 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
   return { pushed: toPush.length, pulled: toPull.length, conflicts: conflicts.length ? conflicts : null, seq: after.seq }
 }
 
-/** Publishes the draft head as a version (a run of the design environment). */
+/** The notes an agent or person wrote for a version: --notes <file> or --notes - (stdin); null without the option. */
+export async function readNotesArg (value, stdin = process.stdin) {
+  if (value == null || value === false) return null
+  if (value === true) throw new UserError('--notes takes a file (Markdown, text or JSON) or - for standard input.')
+  if (value === '-') { const chunks = []; for await (const c of stdin) chunks.push(c); return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8') }
+  try { return await readFile(value, 'utf8') } catch { throw new UserError(`--notes: cannot read ${value}.`) }
+}
+
+/** What publishing the draft now would write as "what changed" (kaloko share --notes-preview). */
+export async function previewNotes ({ config, scenario, client, args, say }) {
+  const branch = typeof args.branch === 'string' ? args.branch : 'main'
+  const r = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions/draft/notes?branch=${enc(branch)}`)
+  if (args.json) { say(JSON.stringify(r, null, 2)); return r }
+  const { notesText } = await import('./design-notes.mjs')
+  say(`What publishing now would say (${r.changed} changed, ${r.unchanged} unchanged${r.notes?.from ? ` since v${r.notes.from.version}` : ''}):\n\n${notesText(r.notes, { lang: args.lang === 'cs' ? 'cs' : 'en' })}\n\nWrite your own in a file (a summary, then "step-id: what changed" lines) and publish with kaloko share --notes <file>.`)
+  return r
+}
+
+/** Publishes the draft head as a version (a run of the design environment), with "what changed" notes. */
 export async function publishVersion ({ config, scenario, client, args, say }) {
   const branch = typeof args.branch === 'string' ? args.branch : 'main'
-  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}) })
+  const notes = await readNotesArg(args.notes)
+  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}), ...(notes ? { notes } : {}) })
   say(`Version v${r.version}${r.name ? ` "${r.name}"` : ''} · ${r.changed} changed, ${r.unchanged} unchanged${r.changed_steps.length ? ` (${r.changed_steps.join(', ')})` : ''}\n${r.url}`)
+  if (r.notes) { const { notesText } = await import('./design-notes.mjs'); say(`\nWhat changed${notes ? ' (your notes over the generated ones)' : ''}:\n${notesText(r.notes)}`) }
   return r
 }
 

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')
+}