@leftoff/cli 0.9.17-beta.8 → 0.9.17

package/ui/session-catchup.js

@@ -6,6 +6,8 @@
 // The recap's lines come from the transcript, so they go in as text afterwards
 // ([data-scu], fillSessionCatchup), never as markup.
 import { copyButtonHtml, fillCopy } from './copy-msg.js' // 0.9.11: Copy on Claude's messages
+import { mdInline } from './changelog-md.js'
+const SCU_MD = /^(goal|next|b-\d+)$/
 
 export function catchupButtonHtml(s, { esc, icon = () => '', busy = false } = {}) {
   if (!s || s.agent || String(s.id || '').startsWith('agent:')) return ''
@@ -107,7 +109,9 @@ export function fillSessionCatchup(root, ui) {
   if (!root || !root.querySelectorAll) return 0
   const t = sessionCatchupTexts(ui)
   let n = 0
-  for (const el of root.querySelectorAll('[data-scu]')) { el.textContent = t[el.getAttribute('data-scu')] || ''; n++ }
+  // 0.9.19: the recap's own words (goal, lines, Next) render `code` and **bold**: mdInline escapes
+  // everything first, so a line is still never markup of its own; the rest stays plain text
+  for (const el of root.querySelectorAll('[data-scu]')) { const k = el.getAttribute('data-scu'), v = t[k] || ''; if (SCU_MD.test(k)) el.innerHTML = mdInline(v, { links: false }); else el.textContent = v; n++ }
   const by = root.querySelector('[data-scu="by"]')
   if (by && !by.textContent) by.hidden = true
   const cb = root.querySelector('.scu .msg-copy') // 0.9.11: Copy's words, as an attribute

package/ui/side-fold.js

@@ -0,0 +1,124 @@
+// 2026-10-29 A calmer session panel (Joel: "very noisy and SUPER SCROLLY").
+// The top stays open (the head, Catch me up / Walk, the newest checkpoint's
+// Stopped + Next, PRs, To do); everything else is a one-line header with a
+// count ("Files · 12"), closed until you open it. Open/closed is kept per
+// device (localStorage lo-side-fold-v1), not per session. Pure builders,
+// unit-tested (test/unit/calmside-1029.test.mjs); app.js wires them.
+
+export const FOLD_KEY = 'lo-side-fold-v1'
+
+const escD = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+// { key: true | false } in one key; anything unreadable is "nothing chosen yet"
+export function createFoldStore(storage) {
+  const read = () => { try { const o = JSON.parse((storage && storage.getItem(FOLD_KEY)) || '{}'); return o && typeof o === 'object' && !Array.isArray(o) ? o : {} } catch { return {} } }
+  return {
+    open(key, dflt = false) { const v = read()[key]; return typeof v === 'boolean' ? v : !!dflt },
+    set(key, open) {
+      if (!key || !/^[\w.-]{1,40}$/.test(key)) return
+      const o = read(); o[key] = !!open
+      try { storage && storage.setItem(FOLD_KEY, JSON.stringify(o)) } catch {}
+    },
+  }
+}
+
+// A section as one line: "Files · 12", a chevron; its body under it when open.
+// body: the section's own markup (it keeps its id, so its painter still works).
+export function foldHtml({ key, title, count = null, body = '', open = false, cls = '' }, { esc = escD } = {}) {
+  if (!body) return ''
+  const n = count == null || count === '' ? '' : '<span class="fs-fold-n"> · ' + esc(String(count)) + '</span>'
+  return '<details class="fs-fold' + (cls ? ' ' + cls : '') + '" data-fold="' + esc(key) + '"' + (open ? ' open' : '') + '>' +
+    '<summary class="fs-fold-h"><span class="fs-fold-t">' + esc(title) + n + '</span><svg class="fs-fold-c" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg></summary>' +
+    '<div class="fs-fold-b">' + body + '</div></details>'
+}
+
+// ------------------------------------------------------------ checkpoints
+
+// A path as the reader knows it: relative to the session's repo / worktree root,
+// else ~/ for the home folder. /Users/<u>/…/worktrees/<name>/src/a.js -> src/a.js
+export function relPath(p, { roots = [], home = '' } = {}) {
+  let s = String(p == null ? '' : p).trim()
+  if (!s) return ''
+  const rs = roots.filter((r) => typeof r === 'string' && r.length > 1).map((r) => r.replace(/\/+$/, '')).sort((a, b) => b.length - a.length)
+  for (const r of rs) if (s === r) return '.'; else if (s.startsWith(r + '/')) return s.slice(r.length + 1)
+  // a worktree folder of a tool (…/worktrees/<name>/rest): the rest
+  const wt = /^(?:\/Users\/[^/]+|\/home\/[^/]+|~)\/(?:[^/]+\/)*?(?:\.?worktrees|\.claude\/worktrees)\/[^/]+\/(.+)$/.exec(s)
+  if (wt) return wt[1]
+  const h = String(home || '').replace(/\/+$/, '')
+  if (h && s.startsWith(h + '/')) return '~/' + s.slice(h.length + 1)
+  const mh = /^\/(?:Users|home)\/[^/]+\/(.+)$/.exec(s)
+  if (mh) return '~/' + mh[1]
+  return s
+}
+// The roots a session's paths are relative to (worktree first, then repo, then its folder)
+export function rootsOf(s) {
+  const r = (s && s.repo) || {}
+  return [s && s.worktree && s.worktree.path, r.worktree, r.root, s && s.cwd].filter((x) => typeof x === 'string' && x.startsWith('/'))
+}
+
+// Files touched as chips: the first five, then "+N more" that opens the rest.
+export const FILES_SHOWN = 5
+export function filesTouchedHtml(files, { roots = [], home = '' } = {}, { esc = escD } = {}) {
+  const list = (Array.isArray(files) ? files : []).map((f) => String(f || '')).filter(Boolean)
+  if (!list.length) return ''
+  const chip = (f) => '<span class="chip mono" data-tip="' + esc(f) + '">' + esc(relPath(f, { roots, home })) + '</span>'
+  const first = list.slice(0, FILES_SHOWN), rest = list.slice(FILES_SHOWN)
+  return '<div class="files">' + first.map(chip).join('') +
+    (rest.length ? '<details class="files-more"><summary class="linkish">+' + rest.length + ' more</summary>' + rest.map(chip).join('') + '</details>' : '') + '</div>'
+}
+
+// Text a checkpoint was written from that wasn't a prompt: Claude Code's
+// wrappers (<task-notification>, <system-reminder>, a slash command's output…),
+// the same list the mod skips (mod/hooks/core.js NOT_A_PROMPT).
+const WRAPPER = /^\s*(?:Working on:\s*[“"]\s*)?(?:<(?:local-command-stdout|local-command-stderr|command-name|command-message|command-args|local-command-caveat|system-reminder|bash-input|bash-stdout|bash-stderr|user-prompt-submit-hook|task-notification|user-memory-input)\b|\[Request interrupted by user|Caveat: The messages below were generated)/
+export function isWrapperCp(cp) {
+  if (!cp) return false
+  return WRAPPER.test(String(cp.doing || '')) || (!String(cp.doing || '').trim() && WRAPPER.test(String(cp.stoppedAt || '')))
+}
+// Junk: a wrapper checkpoint written within a few minutes of another one (the
+// same moment twice). A lone one stays: it's all there is.
+export const JUNK_NEAR_MS = 5 * 60e3
+export function dropJunkCps(list) {
+  const all = Array.isArray(list) ? list : []
+  const t = (cp) => Date.parse((cp && cp.createdAt) || '')
+  return all.filter((cp) => !(isWrapperCp(cp) && all.some((o) => o !== cp && !isWrapperCp(o) && Math.abs(t(o) - t(cp)) <= JUNK_NEAR_MS)))
+}
+
+// ------------------------------------------------------------ status history
+
+// One small shape per change, the word and time in its tip (shape + word, never color alone).
+export const STATUS_SHAPE = { needs_input: '▲', active: '●', background: '◐', waiting: '◆', dormant: '○', stale: '◌', ended: '■' }
+export function statusStripHtml(changes, { label = {}, clock = (x) => x } = {}, { esc = escD } = {}) {
+  const list = (Array.isArray(changes) ? changes : []).slice(-24)
+  if (!list.length) return ''
+  return '<div class="sstrip" role="list" aria-label="Status history">' + list.map((c) => {
+    const w = label[c.status] || c.status || ''
+    const tip = w + ' · ' + clock(c.at)
+    return '<span class="ss s-' + esc(c.status) + '" role="listitem" tabindex="0" data-tip="' + esc(tip) + '" aria-label="' + esc(tip) + '">' + esc(STATUS_SHAPE[c.status] || '·') + '</span>'
+  }).join('') + '</div>'
+}
+
+// ------------------------------------------------------------ answered from the board
+
+// Where an answer came from, in the words of what actually happened. Older
+// answers said "over Tailscale" for anything from another device, the relay
+// included (src/answers.js whereFrom before 2026-10-29); they read right now.
+export function whereWords(w) {
+  let s = String(w || '').trim()
+  if (!s) return ''
+  const old = /^over Tailscale(?: as (.+?))?(?: \(through the relay\))?(?: \(relay\))?(?: · (.+))?$/.exec(s)
+  if (old && /\(through the relay\)|\(relay\)/.test(s)) return 'from ' + (old[1] || 'a paired device') + ' · via relay' + (old[2] ? ' · ' + old[2] : '')
+  return s
+}
+export const ANSWERED_SHOWN = 3
+// The newest three, "Show all N" for the rest (a <details>, so it stays put through redraws)
+export function answeredHtml(answers, { clock = (x) => x } = {}, { esc = escD } = {}) {
+  const list = (Array.isArray(answers) ? answers : []).slice().reverse()
+  if (!list.length) return ''
+  const row = (a) => '<li><span class="t">' + esc(clock(a.at)) + '</span><b>' + esc(a.summary) + '</b>' + (a.what ? ' · <span class="mono">' + esc(String(a.what).slice(0, 160)) + '</span>' : '') +
+    '<span class="where">' + esc(whereWords(a.where)) + (a.delivered === false ? ' · not picked up' : '') + '</span></li>'
+  const first = list.slice(0, ANSWERED_SHOWN), rest = list.slice(ANSWERED_SHOWN)
+  return '<ul class="answered">' + first.map(row).join('') + '</ul>' +
+    (rest.length ? '<details class="answered-more"><summary class="linkish">Show all ' + list.length + '</summary><ul class="answered">' + rest.map(row).join('') + '</ul></details>' : '') +
+    '<div class="hint">Also in answers.md in this session’s folder.</div>'
+}

package/ui/walk-lines.js

@@ -0,0 +1,119 @@
+// 2026-10-30 (walkthrough round 3) Line references for "Ask about this change":
+// click a line number in a walkthrough's diff to pick it, shift-click or drag
+// for a range, Cmd/Ctrl-click to add another range (another file, another
+// step). On a phone: tap to pick, tap another line of the same snippet to
+// stretch it, tap in another snippet to add one. The picks show as chips over
+// the ask box; asking puts each ref and its exact lines into the chat box.
+//
+// A pick is a run of rows of ONE drawn patch (a step's snippet, a file in the
+// Files view), by row index into diff-view.js's parsePatch rows, so it means
+// the same lines in the unified and the split view. Pure: no DOM here.
+import { parsePatch } from './diff-view.js'
+
+const rowsCache = new Map()
+// patch -> parsePatch(patch).rows (kept a little while: the same patch is asked for often)
+export function rowsOf(patch) {
+  const k = String(patch == null ? '' : patch)
+  let r = rowsCache.get(k)
+  if (!r) { r = parsePatch(k).rows; rowsCache.set(k, r); if (rowsCache.size > 300) rowsCache.delete(rowsCache.keys().next().value) }
+  return r
+}
+const isLine = (r) => r && (r.k === 'add' || r.k === 'del' || r.k === 'ctx')
+
+// The numbers a run of rows covers: the new side when any row has a new number
+// (what the file reads now), else the old side (only removed lines).
+export function rangeInfo(rows, a, b) {
+  const lo = Math.min(a, b), hi = Math.max(a, b)
+  const ls = (rows || []).slice(lo, hi + 1).filter(isLine)
+  if (!ls.length) return null
+  const ns = ls.filter((r) => r.n != null).map((r) => r.n)
+  const side = ns.length ? 'new' : 'old'
+  const xs = side === 'new' ? ns : ls.map((r) => r.o).filter((x) => x != null)
+  return { side, from: Math.min(...xs), to: Math.max(...xs), lines: ls.length }
+}
+// "src/x.js:12–18", "repo · src/x.js:40", "src/x.js:7–9 (old)" for removed lines only.
+// label: the path as a person reads it (semdiff.js pathLabel)
+export function refLabel(label, info) {
+  if (!info) return String(label || '')
+  return String(label || '') + ':' + (info.from === info.to ? info.from : info.from + '–' + info.to) + (info.side === 'old' ? ' (old)' : '')
+}
+// The exact lines, the way the walkthrough's model reads them: "+ 13 │ text",
+// "- o12 │ text" (removed, its old number), "  14 │ text" (unchanged).
+export function refLinesText(rows, a, b, { max = 80 } = {}) {
+  const lo = Math.min(a, b), hi = Math.max(a, b)
+  const ls = (rows || []).slice(lo, hi + 1).filter(isLine)
+  const out = ls.slice(0, max).map((r) => (r.k === 'add' ? '+ ' + r.n : r.k === 'del' ? '- o' + r.o : '  ' + r.n) + ' │ ' + r.t)
+  if (ls.length > max) out.push('  … ' + (ls.length - max) + ' more lines')
+  return out.join('\n')
+}
+
+// ---------------------------------------------------------------- picking
+// A pick: { k (which drawn patch), file, step, x (where it started), a, b }.
+// ev: { shift, add (Cmd/Ctrl), touch } -> the new list (never the same array).
+const inside = (p, ri) => ri >= p.a && ri <= p.b
+export function mergePicks(list) {
+  const out = []
+  for (const p of list) {
+    const q = out.find((o) => o.k === p.k && p.a <= o.b + 1 && p.b >= o.a - 1)
+    if (q) { q.a = Math.min(q.a, p.a); q.b = Math.max(q.b, p.b) } else out.push({ ...p })
+  }
+  return out
+}
+export function pickLine(list, at, ev = {}) {
+  const cur = (list || []).map((p) => ({ ...p }))
+  const one = { k: at.k, file: at.file, step: at.step || null, x: at.ri, a: at.ri, b: at.ri }
+  const lastOf = () => { for (let i = cur.length - 1; i >= 0; i--) if (cur[i].k === at.k) return i; return -1 }
+  if (ev.shift) {
+    const i = lastOf()
+    if (i < 0) return mergePicks([...cur, one])
+    const p = cur[i]; p.a = Math.min(p.x, at.ri); p.b = Math.max(p.x, at.ri)
+    return mergePicks(cur)
+  }
+  if (ev.add) {
+    const i = cur.findIndex((p) => p.k === at.k && inside(p, at.ri))
+    if (i >= 0) { cur.splice(i, 1); return cur }
+    return mergePicks([...cur, one])
+  }
+  if (ev.touch) {
+    const i = cur.findIndex((p) => p.k === at.k && inside(p, at.ri))
+    if (i >= 0) { cur.splice(i, 1); return cur } // a tap on a picked line lets it go
+    const j = lastOf()
+    if (j >= 0 && j === cur.length - 1) { const p = cur[j]; p.a = Math.min(p.x, at.ri); p.b = Math.max(p.x, at.ri); return mergePicks(cur) } // a second tap stretches it
+    return mergePicks([...cur, one])
+  }
+  if (cur.length === 1 && cur[0].k === at.k && cur[0].a === at.ri && cur[0].b === at.ri) return []
+  return [one]
+}
+// dragging: the pick at index i stretched from where it started to ri
+export function dragTo(list, i, ri) {
+  const cur = (list || []).map((p) => ({ ...p }))
+  const p = cur[i]
+  if (!p) return cur
+  p.a = Math.min(p.x, ri); p.b = Math.max(p.x, ri)
+  return cur
+}
+
+// ---------------------------------------------------------------- asking
+// picks + how to read each one -> [{ label, text, step }] ; read(p) -> { rows, label, stepTitle }
+export function describePicks(list, read) {
+  const out = []
+  for (const p of list || []) {
+    const r = read(p)
+    if (!r || !r.rows) continue
+    const info = rangeInfo(r.rows, p.a, p.b)
+    if (!info) continue
+    out.push({ label: refLabel(r.label, info), text: refLinesText(r.rows, p.a, p.b), stepTitle: r.stepTitle || '', info })
+  }
+  return out
+}
+// The words that go into the chat box: each ref with its lines in a diff
+// fence, then the question. refs: describePicks' answer.
+export function refsPrompt(refs, question) {
+  const q = String(question || '').trim()
+  if (!refs || !refs.length) return q
+  const blocks = refs.map((r) => {
+    const fence = /```/.test(r.text) ? '~~~~' : '```'
+    return '`' + r.label + '`' + (r.stepTitle ? ' (' + r.stepTitle + ')' : '') + ':\n' + fence + 'diff\n' + r.text + '\n' + fence
+  })
+  return (refs.length === 1 ? 'About these lines:' : 'About these ' + refs.length + ' places:') + '\n\n' + blocks.join('\n\n') + (q ? '\n\n' + q : '')
+}

package/ui/walk-md.js

@@ -0,0 +1,40 @@
+// 0.9.19 (Joel: "Should we rendering md in the walk through? (and when
+// downloaded)"): a walkthrough's words are Markdown the model wrote, so they
+// render the way the board renders Claude's replies: the same renderer
+// (ui/handoffs.js renderDoc, ui/changelog-md.js mdInline), which escapes
+// everything first (raw HTML shows as text and never runs) and makes a link
+// only for https (new tab, rel=noopener). Titles are inline only (code, bold,
+// italic; no links, since a title sits in buttons and tips); a step's why gets
+// paragraphs, lists and fenced code too. The export uses the same HTML with no
+// copy buttons (it has no script). Copy as Markdown stays the raw text.
+import { mdInline } from './changelog-md.js'
+import { renderDoc } from './handoffs.js'
+import { codeCopyButton } from './code-copy.js'
+
+// a title: inline only
+export function walkInline(s) { return mdInline(String(s == null ? '' : s), { links: false, em: true }) }
+// a callout or the summary: inline, with https links
+export function walkInlineLinks(s) { return mdInline(String(s == null ? '' : s), { links: true, em: true }) }
+// The export links out to nothing (one offline file): a link there is its words,
+// with the address after them in brackets when the words aren't the address.
+export function unlink(html) {
+  return String(html).replace(/<a href="([^"]*)"(?: target="_blank" rel="noopener")?>([\s\S]*?)<\/a>/g, (_, href, inner) =>
+    inner.replace(/<[^>]+>/g, '') === href || inner.replace(/<[^>]+>/g, '') === href.replace(/&amp;/g, '&') ? '<span class="u">' + inner + '</span>' : inner + ' <span class="u">(' + href + ')</span>')
+}
+// a step's why: blocks (paragraphs, lists, fenced code), no file links
+export function walkBlock(s, { exported = false } = {}) {
+  const h = renderDoc(String(s == null ? '' : s), { files: false })
+  return exported ? unlink(h.split(codeCopyButton()).join('')) : h
+}
+// the export's inline words: rendered, nothing linked
+export function walkInlineExport(s) { return unlink(walkInlineLinks(s)) }
+// the same words as plain text, for a data-tip, an aria-label or the deck's "now" line
+export function mdPlain(s) {
+  return String(s == null ? '' : s)
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\*\*(.+?)\*\*/g, '$1')
+    .replace(/~~(.+?)~~/g, '$1')
+    .replace(/(^|[^\w*])\*([^*\s][^*]*?)\*(?![\w*])/g, '$1$2')
+    .replace(/(^|[^\w])_([^_\s][^_]*?)_(?!\w)/g, '$1$2')
+}

package/ui/walk-pop.js

@@ -15,20 +15,39 @@ export function sizeWords(z) {
   if (z.files === 0) return { kind: 'none', text: 'No changes yet' }
   return { kind: 'some', text: plural(z.files, 'file') + ' · +' + n0(z.add) + ' −' + n0(z.del) }
 }
-export function sizeLineHtml(z, { esc, icon }) {
+export function sizeLineHtml(z, { esc, icon, reviewed = null }) {
   const w = sizeWords(z)
   if (!w) return ''
-  return w.kind === 'none'
+  return (w.kind === 'none'
     ? '<span class="fs-wt-meta none">' + icon('circle-dashed') + esc(w.text) + '</span>'
-    : '<span class="fs-wt-meta">' + esc(w.text) + '</span>'
+    : '<span class="fs-wt-meta">' + esc(w.text) + '</span>') + walkBadgeHtml(walkProgress(z, reviewed), { esc, icon })
+}
+// 2026-10-30 (asked: "if you've gone through a walk through, should we have a way of denoting that
+// in the right sidebar where that button is?"): the walkthrough you last opened for this scope
+// (change-size's walk: { fp, steps, changed }) and how many of its steps you marked reviewed ->
+// null (never opened, or nothing marked yet) | { kind: 'part' | 'done', text, tip }
+export function walkProgress(z, reviewed) {
+  const wk = z && z.walk
+  const n = wk && Number(wk.steps)
+  const r = Math.max(0, Math.min(n || 0, Number(reviewed) || 0))
+  if (!n || !r) return null
+  const ch = wk.changed > 0 ? wk.changed + (wk.changed === 1 ? ' file' : ' files') + ' changed since' : ''
+  const done = r >= n
+  const text = (done ? 'Reviewed' : r + ' of ' + n + ' reviewed') + (ch ? ' · ' + ch : '')
+  const tip = (done ? 'You marked every step of this walkthrough reviewed' : 'You marked ' + r + ' of its ' + n + ' steps reviewed') + (ch ? '; ' + ch + ' it was written' : '')
+  return { kind: done ? 'done' : 'part', text, tip }
+}
+export function walkBadgeHtml(p, { esc, icon }) {
+  if (!p) return ''
+  return '<span class="fs-wt-rv fs-wt-rv-' + p.kind + '" data-tip="' + esc(p.tip) + '">' + (p.kind === 'done' ? icon('check') : '<i class="wt-chg-g" aria-hidden="true"></i>') + '<span>' + esc(p.text) + '</span></span>'
 }
 
 // the button (and, on touch, its (i)); data-pop names the popover it explains itself with
-export function walkButtonHtml(s, { esc, icon, on = false, size = null }) {
+export function walkButtonHtml(s, { esc, icon, on = false, size = null, reviewed = null }) {
   const id = esc(s.id)
   return '<span class="fs-wt-wrap">' +
     '<button type="button" class="btn fs-wt' + (on ? ' on' : '') + (sizeWords(size) && sizeWords(size).kind === 'none' ? ' none' : '') + '" data-action="' + (on ? 'wt-close' : 'wt-open') + '" data-id="' + id + '" aria-pressed="' + on + '" data-pop="wt">' +
-      icon('git-compare') + '<span class="fs-wt-l"><span class="fs-wt-v">Walk me through it</span><span class="fs-wt-size" data-id="' + id + '">' + sizeLineHtml(size, { esc, icon }) + '</span></span></button>' +
+      icon('git-compare') + '<span class="fs-wt-l"><span class="fs-wt-v">Walk me through it</span><span class="fs-wt-size" data-id="' + id + '">' + sizeLineHtml(size, { esc, icon, reviewed }) + '</span></span></button>' +
     '<button type="button" class="fs-pop-i" data-pop-open="wt" data-id="' + id + '" aria-label="What Walk me through it does" aria-expanded="false">' + icon('info') + '</button>' +
   '</span>'
 }

package/ui/walk-spots.js

@@ -0,0 +1,89 @@
+// 2026-10-30 (walkthrough round 3) "Next spot to really look at": the button in
+// the walkthrough's toolbar (and the n key) jumps to the next place that
+// deserves a real look, across steps, in reading order: the lines a callout
+// flags, the spots the model named (src/semdiff.js validateSpots), and, when
+// it named none, this file's heuristic: each Core snippet, plus risky-looking
+// changes anywhere (removed logic, auth and permissions, config and
+// migrations, error handling). Supporting snippets only when nothing else is
+// left. Each spot carries a short reason, shown as a tag at the line. Pure.
+import { parsePatch } from './diff-view.js'
+
+export const SPOT_WORDS = { look: 'Look closely', assumption: 'Assumption', untested: 'Untested' }
+const AUTH_WORDS = ['auth', 'permission', 'role', 'admin', 'token', 'secret', 'password', 'passwd', 'csrf', 'session', 'login', 'logout', 'acl', 'grant', 'privilege', 'sudo', 'jwt', 'oauth', 'cookie', 'signature', 'verify']
+// a word on its own or the start of a camelCase part ("isAdmin", "checkPermission", "AUTH_KEY")
+const AUTH = new RegExp('(?:(?<![A-Za-z])(?:' + AUTH_WORDS.join('|') + ')|(?<![A-Za-z])(?:' + AUTH_WORDS.map((x) => x.toUpperCase()).join('|') + ')|(?<=[a-z])(?:' + AUTH_WORDS.map((x) => x[0].toUpperCase() + x.slice(1)).join('|') + ')|(?<![A-Za-z])(?:' + AUTH_WORDS.map((x) => x[0].toUpperCase() + x.slice(1)).join('|') + '))')
+const ERR = /\b(catch|throw|throws|raise|except|finally|reject|rescue|panic|recover|try)\b|\.catch\(|\berr(or)?s?\b/i
+const MIGRATION = /(^|\/)(migrations?|migrate|db\/schema)(\/|\.)|\.sql$/i
+const CONFIG = /(^|\/)(config|settings|\.github\/workflows)(\/|\.|$)|\.(ya?ml|toml|ini|conf)$|(^|\/)(Dockerfile|package\.json|\.env\.example|wrangler\.toml|tsconfig\.json)$/i
+const COMMENT = /^\s*(\/\/|#|\*|\/\*|--|;)/
+
+const isLine = (r) => r.k === 'add' || r.k === 'del' || r.k === 'ctx'
+const sideOf = (r) => (r.k === 'del' ? 'old' : 'new')
+const numOf = (r) => (r.k === 'del' ? r.o : r.n)
+
+// One snippet (a patch, its file) -> { why, side, line, risk } or null when nothing in it changed.
+export function snippetRisk(patch, file) {
+  const rows = parsePatch(patch).rows
+  const ch = rows.filter((r) => r.k === 'add' || r.k === 'del')
+  if (!ch.length) return null
+  const at = (r, why, risk = true) => ({ why, side: sideOf(r), line: numOf(r), risk })
+  const first = ch.find((r) => r.k === 'add') || ch[0] // what the file reads now, when there's any
+  if (MIGRATION.test(String(file || ''))) return at(first, 'Migration')
+  // removed logic: a run of 3+ removed code lines with (almost) nothing added in its place
+  for (let i = 0; i < rows.length; i++) {
+    if (rows[i].k !== 'del') continue
+    let j = i, dels = 0, adds = 0
+    while (j < rows.length && (rows[j].k === 'del' || rows[j].k === 'add')) { if (rows[j].k === 'del' && rows[j].t.trim() && !COMMENT.test(rows[j].t)) dels++; if (rows[j].k === 'add' && rows[j].t.trim()) adds++; j++ }
+    if (dels >= 3 && adds * 2 < dels) return at(rows[i], 'Removed logic')
+    i = j - 1
+  }
+  const code = ch.filter((r) => r.t.trim() && !COMMENT.test(r.t))
+  const a = code.find((r) => AUTH.test(r.t))
+  if (a) return at(a, 'Auth / permissions')
+  const e = code.find((r) => ERR.test(r.t))
+  if (e) return at(e, 'Error handling')
+  if (CONFIG.test(String(file || ''))) return at(first, 'Config')
+  return at(first, 'Core change', false)
+}
+
+// data (a walkthrough) + its steps in reading order -> the spots, in order:
+// [{ step, snip, hunk, file, side, line, why, kind }] (kind: callout | model | risk | core | sup)
+export function spotsFor(data, order) {
+  const steps = order || (data && data.steps) || []
+  const model = data && Array.isArray(data.spots) ? data.spots : []
+  const main = [], sup = []
+  for (const st of steps) {
+    const core = st.tag === 'Core'
+    const snips = st.snippets || []
+    snips.forEach((sn, i) => {
+      const here = []
+      const lineIn = (side, line) => parsePatch(sn.patch).rows.some((r) => isLine(r) && (side === 'old' ? r.o : r.n) === line)
+      for (const c of st.callouts || []) if (c.hunk === sn.hunk && lineIn(c.side, c.line)) here.push({ side: c.side, line: c.line, why: SPOT_WORDS[c.kind] || SPOT_WORDS.look, kind: 'callout' })
+      for (const m of model) if (m.step === st.id && m.hunk === sn.hunk && lineIn(m.side, m.line) && !here.some((x) => x.side === m.side && x.line === m.line)) here.push({ side: m.side, line: m.line, why: m.why || 'Worth a look', kind: 'model' })
+      if (!here.length && !model.length) {
+        const r = snippetRisk(sn.patch, sn.file)
+        if (r && (r.risk || core)) here.push({ side: r.side, line: r.line, why: r.why, kind: r.risk ? 'risk' : 'core' })
+        else if (r) sup.push({ step: st.id, snip: i, hunk: sn.hunk, file: sn.file, side: r.side, line: r.line, why: 'Supporting', kind: 'sup' })
+      } else if (!here.length && core) {
+        // the model named spots, just none here: a Core snippet still gets one
+        const r = snippetRisk(sn.patch, sn.file)
+        if (r) here.push({ side: r.side, line: r.line, why: r.risk ? r.why : 'Core change', kind: r.risk ? 'risk' : 'core' })
+      }
+      here.sort((x, y) => x.line - y.line)
+      for (const x of here) main.push({ step: st.id, snip: i, hunk: sn.hunk, file: sn.file, ...x })
+    })
+  }
+  return main.length ? main : sup
+}
+
+// The spot after (dir 1) or before (-1) index cur, wrapping; -1 when there are none.
+export function nextSpotIndex(n, cur, dir = 1) {
+  if (!n) return -1
+  if (cur == null || cur < 0) return dir > 0 ? 0 : n - 1
+  return ((cur + dir) % n + n) % n
+}
+// "2 of 7 spots" once you've started, "7 spots" before
+export function spotCountWords(n, cur) {
+  if (!n) return 'No spots'
+  return (cur != null && cur >= 0 ? (cur + 1) + ' of ' + n : String(n)) + (n === 1 ? ' spot' : ' spots')
+}