@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/printer/summary.ts

@@ -0,0 +1,601 @@
+/**
+ * One-line summaries: a snippet squeezed into a target width while keeping its
+ * *shape* (which commands run, how they are combined), e.g.
+ *
+ *   cd …/harness-port && pnpm run build … > …/build.log 2>&1 && echo done
+ *
+ * The summary is a tree of structure tokens (command names, operators,
+ * keywords) and reducible parts. Starting from everything shown (with
+ * multi-line strings cut to their first line, here-doc bodies and comments
+ * omitted), it repeatedly applies the reduction with the lowest cost per
+ * column it saves (counting at most the columns still needed) until the line
+ * fits. Costs encode the priorities, cheapest first:
+ *
+ *   shorten long strings, substitutions, words (head and closing quote kept)   1
+ *   paths and redirection targets → their tail (`…/file.txt`)                  1.2
+ *   collapse assignment values (`FOO=…`; short ones cost double)              4
+ *   hide plain arguments (strings, words)       ┐ hidden runs merge into      3
+ *   hide long flags (`--frozen-lockfile`)       │ one `…` whose tooltip       3.5
+ *   shorten path tails further                  │ lists them                  4
+ *   hide paths                                  │                             6
+ *   hide short flags (`-rn`)                    ┘                             8
+ *   hide subcommands (`git status`)                                         80
+ *   collapse compound bodies (`for …; do …; done`)                             60
+ *   drop trailing statements of a list (`a; b; …`)                            100
+ *   command names that are paths → their tail                                 150
+ *   (and finally a hard cut at the width)
+ *
+ * Hiding an item of 6 columns or fewer costs double. Command names,
+ * operators, keywords and `]`/`]]` are never reduced.
+ *
+ * Every `…` keeps what it hides: truncated atoms carry the full text as a
+ * tooltip, hidden arguments and collapsed bodies carry their source.
+ */
+
+import type * as A from '../parser/ast.ts'
+import { parse } from '../parser/parser.ts'
+import { Highlight, simpleCommandRoles } from './highlight.ts'
+
+export interface SummaryOptions {
+  /** Target width in columns (default 80). */
+  width?: number
+}
+
+export interface SummaryResult {
+  /** The summary as plain text (`…` marks truncation). At most `width` columns, never a newline. */
+  text: string
+  /** `<span class="mash sum">…</span>`: highlighted, with `el` ellipsis spans and `title` tooltips. */
+  html: string
+  /** Number of reductions applied. */
+  reductions: number
+}
+
+type Kind = 'cmd' | 'sc' | 'flag' | 'lflag' | 'path' | 'str' | 'word' | 'val' | 'target'
+
+interface Atom { k: 'atom'; start: number; end: number; kind: Kind; limit?: number; tail?: boolean; pos: number }
+interface Tok { k: 'tok'; text: string; cls?: string }
+interface ArgItem { node: Atom; hidden: boolean; fixed?: boolean }
+interface Args { k: 'args'; items: ArgItem[] }
+interface Elide { k: 'elide'; inner: S; start: number; end: number; collapsed: boolean; size: number }
+interface List { k: 'list'; items: S[]; seps: string[]; spans: [number, number][]; keep: number; pos: number }
+interface Fold { k: 'fold'; start: number; end: number }
+type S = Tok | Atom | Args | Elide | List | Fold | S[]
+
+interface Piece {
+  text: string
+  src?: [number, number]
+  cls?: string
+  el?: boolean
+  title?: string
+  /** Pieces of one truncated atom share a wrapper (its full text as tooltip). */
+  wrap?: { title: string }
+}
+
+const ELLIPSIS = '…'
+const tok = (text: string, cls?: string): Tok => ({ k: 'tok', text, cls })
+const SP = tok(' ')
+
+/** Parse and summarize. Unparsable input falls back to a whitespace-collapsed, cut source. */
+export function summarize(source: string, options: SummaryOptions = {}): SummaryResult {
+  let script: A.Script
+  try {
+    script = parse(source)
+  } catch {
+    const width = options.width ?? 80
+    const flat = source.replace(/\s+/g, ' ').trim()
+    const text = flat.length <= width ? flat : flat.slice(0, Math.max(0, width - 1)) + ELLIPSIS
+    const html = flat.length <= width
+      ? `<span class="mash sum">${esc(flat)}</span>`
+      : `<span class="mash sum">${esc(flat.slice(0, Math.max(0, width - 1)))}<span class="el" title="${esc(source)}">${ELLIPSIS}</span></span>`
+    return { text, html, reductions: 0 }
+  }
+  return summarizeScript(script, source, options)
+}
+
+export function summarizeScript(script: A.Script, source: string, options: SummaryOptions = {}): SummaryResult {
+  const width = Math.max(4, options.width ?? 80)
+  const b = new Builder(source)
+  const root = b.list(script.body)
+  const atomWidth = (a: Atom): number => atomPieces(a, source).reduce((n, p) => n + p.text.length, 0)
+
+  const lineWidth = (): number => render(root, source).reduce((n, p) => n + p.text.length, 0)
+  const undos: (() => void)[] = []
+  for (let iter = 0; iter < 5000; iter++) {
+    const overflow = lineWidth() - width
+    if (overflow <= 0) break
+    const cands: Cand[] = []
+    collect(root, cands, { atomWidth, src: source, width: (n) => render(n, source).reduce((m, p) => m + p.text.length, 0) })
+    let best: Cand | null = null
+    let bestScore = Infinity
+    for (const c of cands) {
+      if (c.saving <= 0) continue
+      const score = c.cost / Math.min(c.saving, overflow + 1)
+      if (score < bestScore || (score === bestScore && best && c.key > best.key)) {
+        best = c
+        bestScore = score
+      }
+    }
+    if (!best) break
+    undos.push(best.apply())
+  }
+  // Relax: greedy steps can overshoot. Newest first, undo each reduction the
+  // line no longer needs (restoring the exact state when it is still needed:
+  // reductions of one atom do not commute).
+  let reductions = undos.length
+  if (lineWidth() <= width) {
+    for (let i = undos.length - 1; i >= 0; i--) {
+      const snap = snapshot(root)
+      undos[i]()
+      if (lineWidth() > width) restore(root, snap)
+      else reductions--
+    }
+  }
+  let pieces = render(root, source)
+  if (pieces.reduce((n, p) => n + p.text.length, 0) > width) {
+    pieces = hardCut(pieces, width, source)
+    reductions++
+  }
+  const hl = new Highlight(script, source)
+  return { text: pieces.map((p) => p.text).join(''), html: toHtml(pieces, hl), reductions }
+}
+
+// ---------------------------------------------------------------------------
+// AST → summary tree
+// ---------------------------------------------------------------------------
+
+class Builder {
+  readonly src: string
+  private pos = 0
+
+  constructor(src: string) {
+    this.src = src
+  }
+
+  private atom(span: A.Span, kind: Kind): Atom {
+    return { k: 'atom', start: span.start, end: span.end, kind, pos: this.pos++ }
+  }
+
+  private classify(w: A.Word): Kind {
+    const text = this.src.slice(w.span.start, w.span.end)
+    if (/^--./.test(text)) return 'lflag'
+    if (/^-[^-\s]/.test(text)) return 'flag'
+    const bare = text.replace(/^["']|["']$/g, '')
+    // paths: start like one (`/`, `~`, `./`, `$HOME/`, `dir/`), no blanks, no regex/substitution syntax
+    if (/^(~|\.{0,2}\/|\$\{?\w+\}?\/|[\w.@+-]+\/)/.test(bare) && !/[\s^\\|()`]/.test(bare) && !/^\w\/.*\/.*\/\w*$/.test(bare)) return 'path'
+    if (w.parts.every((p) => p.type === 'Lit' || p.type === 'Escaped')) return 'word'
+    return 'str'
+  }
+
+  list(stmts: A.Stmt[]): S {
+    const items = stmts.map((s) => this.stmt(s))
+    const seps = stmts.slice(0, -1).map((s) => (s.background ? ' ' : '; '))
+    return { k: 'list', items, seps, spans: stmts.map((s) => [s.span.start, s.span.end]), keep: stmts.length, pos: this.pos++ }
+  }
+
+  private stmt(s: A.Stmt): S {
+    return s.background ? [this.command(s.command), SP, tok('&', 'op')] : this.command(s.command)
+  }
+
+  private body(stmts: A.Stmt[]): S {
+    if (stmts.length === 0) return []
+    const start = stmts[0].span.start
+    const end = stmts[stmts.length - 1].span.end
+    return { k: 'elide', inner: this.list(stmts), start, end, collapsed: false, size: end - start }
+  }
+
+  private redirs(rs: A.Redirect[]): S {
+    return rs.map((r) => {
+      if (r.heredoc) return [SP, tok(this.src.slice(r.span.start, r.span.end), 'rd'), { k: 'fold', start: r.heredoc.body.span.start, end: r.heredoc.body.span.end } as Fold]
+      const opText = this.src.slice(r.span.start, r.target.span.start)
+      if (/^\d*[<>]&$/.test(opText.trim()) || r.target.span.end <= r.target.span.start) return [SP, tok(this.src.slice(r.span.start, r.span.end), 'rd')]
+      return [SP, tok(opText, 'rd'), this.atom(r.target.span, this.classify(r.target) === 'path' ? 'target' : 'val')]
+    })
+  }
+
+  private assign(a: A.Assign): S {
+    const valueStart = a.value ? a.value.span.start : a.span.end
+    const name = tok(this.src.slice(a.span.start, valueStart), 'asg')
+    if (!a.value || a.value.span.end <= a.value.span.start) return name
+    return [name, this.atom(a.value.span, 'val')]
+  }
+
+  private command(c: A.Command): S {
+    switch (c.type) {
+      case 'SimpleCommand': {
+        const out: S[] = []
+        for (const a of c.assigns) out.push(this.assign(a), SP)
+        const items: ArgItem[] = []
+        let name: S | null = null
+        let roles: ReturnType<typeof simpleCommandRoles> = []
+        try {
+          roles = simpleCommandRoles(c)
+        } catch {
+          // display only
+        }
+        c.words.forEach((w, i) => {
+          if (w.type === 'Assign') {
+            items.push({ node: { ...this.atom(w.span, 'str') }, hidden: false })
+            return
+          }
+          if (!name) {
+            name = this.atom(w.span, 'cmd')
+            return
+          }
+          const text = this.src.slice(w.span.start, w.span.end)
+          // known roles refine the guess: files and directories shorten to their tail, patterns and code to their head
+          const role = roles[i]
+          let kind = this.classify(w)
+          if ((role === 'dir' || role === 'file') && kind !== 'flag' && kind !== 'lflag') kind = 'path'
+          else if ((role === 'pattern' || role === 'code') && kind === 'path') kind = 'str'
+          else if (role === 'subcommand') kind = 'sc'
+          items.push({ node: this.atom(w.span, kind), hidden: false, fixed: text === ']' || text === ']]' })
+        })
+        if (name) out.push(name)
+        else if (out.length) out.pop()
+        if (items.length) out.push(SP, { k: 'args', items })
+        out.push(this.redirs(c.redirs))
+        return out
+      }
+      case 'Pipeline': {
+        const prefix = this.src.slice(c.span.start, c.stages[0].span.start).trim().replace(/\s+/g, ' ')
+        const out: S[] = prefix ? [tok(prefix, 'kw'), SP] : []
+        c.stages.forEach((st, i) => {
+          if (i > 0) out.push(SP, tok(c.pipeStderr[i - 1] ? '|&' : '|', 'op'), SP)
+          out.push(this.command(st))
+        })
+        return out
+      }
+      case 'AndOr': {
+        const out: S[] = []
+        c.items.forEach((it, i) => {
+          if (i > 0) out.push(SP, tok(c.ops[i - 1], 'op'), SP)
+          out.push(this.command(it))
+        })
+        return out
+      }
+      case 'FunctionDef':
+        return [tok(`${c.name}()`, 'fn'), SP, this.command(c.body)]
+      case 'Group':
+        return [tok('{', 'kw'), SP, this.body(c.body), tok(';', 'op'), SP, tok('}', 'kw'), this.redirs(c.redirs)]
+      case 'Subshell':
+        return [tok('(', 'kw'), SP, this.body(c.body), SP, tok(')', 'kw'), this.redirs(c.redirs)]
+      case 'If': {
+        const out: S[] = []
+        c.clauses.forEach((cl, i) => {
+          out.push(i === 0 ? tok('if', 'kw') : [tok(';', 'op'), SP, tok('elif', 'kw')], SP, this.list(cl.cond), tok(';', 'op'), SP, tok('then', 'kw'), SP, this.body(cl.body))
+        })
+        if (c.elseBody) out.push(tok(';', 'op'), SP, tok('else', 'kw'), SP, this.body(c.elseBody))
+        out.push(tok(';', 'op'), SP, tok('fi', 'kw'), this.redirs(c.redirs))
+        return out
+      }
+      case 'Loop':
+        return [tok(c.kind, 'kw'), SP, this.list(c.cond), tok(';', 'op'), SP, tok('do', 'kw'), SP, this.body(c.body), tok(';', 'op'), SP, tok('done', 'kw'), this.redirs(c.redirs)]
+      case 'For':
+      case 'Select': {
+        const head: S[] = [tok(c.type === 'For' ? 'for' : 'select', 'kw'), SP, tok(c.variable, 'var')]
+        if (c.items !== null) {
+          head.push(SP, tok('in', 'kw'))
+          if (c.items.length) head.push(SP, { k: 'args', items: c.items.map((w) => ({ node: this.atom(w.span, this.classify(w)), hidden: false })) })
+        }
+        return [head, tok(';', 'op'), SP, tok('do', 'kw'), SP, this.body(c.body), tok(';', 'op'), SP, tok('done', 'kw'), this.redirs(c.redirs)]
+      }
+      case 'ArithFor': {
+        const exprs = [c.init, c.cond, c.step].filter((e): e is A.ArithExpr => e !== null)
+        const from = exprs.length ? exprs[exprs.length - 1].span.end : c.span.start
+        const close = this.src.indexOf('))', from)
+        return [this.atom({ start: c.span.start, end: close + 2 }, 'str'), tok(';', 'op'), SP, tok('do', 'kw'), SP, this.body(c.body), tok(';', 'op'), SP, tok('done', 'kw'), this.redirs(c.redirs)]
+      }
+      case 'Case': {
+        const items: S[] = []
+        c.items.forEach((it, i) => {
+          if (i > 0) items.push(SP)
+          it.patterns.forEach((p, j) => {
+            if (j > 0) items.push(tok('|', 'op'))
+            items.push(this.atom(p.span, 'word'))
+          })
+          items.push(tok(')', 'op'))
+          if (it.body.length) items.push(SP, this.list(it.body))
+          items.push(SP, tok(it.terminator, 'op'))
+        })
+        const start = c.items[0]?.span.start ?? c.span.start
+        const end = c.items[c.items.length - 1]?.span.end ?? c.span.start
+        const region: S = c.items.length ? { k: 'elide', inner: items, start, end, collapsed: false, size: end - start } : []
+        return [tok('case', 'kw'), SP, this.atom(c.word.span, 'word'), SP, tok('in', 'kw'), SP, region, SP, tok('esac', 'kw'), this.redirs(c.redirs)]
+      }
+      case 'ArithCommand':
+      case 'CondCommand': {
+        let end = c.redirs.length > 0 ? c.redirs[0].span.start : c.span.end
+        while (end > c.span.start && /\s/.test(this.src[end - 1])) end--
+        return [this.atom({ start: c.span.start, end }, 'str'), this.redirs(c.redirs)]
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+function closeLen(src: string, a: Atom): number {
+  if (a.end - a.start <= 2 || a.kind === 'path' || a.kind === 'target') return 0
+  return `'")}\``.includes(src[a.end - 1]) ? 1 : 0
+}
+
+/** The pieces showing an atom under its current limit. */
+function atomPieces(a: Atom, src: string): Piece[] {
+  const { start: s, end: e } = a
+  const full = src.slice(s, e)
+  const nlAt = full.indexOf('\n')
+  const lineEnd = nlAt >= 0 ? s + nlAt : e
+  const forced = nlAt >= 0
+  const wrap = { title: full }
+  // paths keep their tail whenever they are shortened
+  const tailMode = a.tail || (a.limit !== undefined && (a.kind === 'path' || a.kind === 'target'))
+  if (tailMode && !forced) {
+    // path tail: `…/file.txt`, or the last limit-1 characters
+    let slash = -1
+    for (let i = e - 2; i > s; i--) {
+      if (src[i] === '/') {
+        slash = i
+        break
+      }
+    }
+    let from = slash > s ? slash : s
+    if (a.limit !== undefined && e - from + 1 > a.limit) from = Math.max(s, e - Math.max(1, a.limit - 1))
+    if (from <= s) return [{ text: full, src: [s, e] }]
+    return [{ text: ELLIPSIS, el: true, wrap }, { text: src.slice(from, e), src: [from, e], wrap }]
+  }
+  if (!forced && (a.limit === undefined || a.limit >= e - s)) return [{ text: full, src: [s, e] }]
+  const close = closeLen(src, a)
+  const visibleEnd = forced ? lineEnd : e
+  let headEnd = visibleEnd
+  if (a.limit !== undefined) headEnd = Math.min(visibleEnd, s + Math.max(0, a.limit - 1 - close))
+  // never end the head inside a line with trailing blanks
+  while (headEnd > s && /\s/.test(src[headEnd - 1])) headEnd--
+  const out: Piece[] = []
+  if (headEnd > s) out.push({ text: src.slice(s, headEnd), src: [s, headEnd], wrap })
+  out.push({ text: ELLIPSIS, el: true, wrap })
+  if (close && (a.limit === undefined || a.limit > 1)) out.push({ text: src.slice(e - close, e), src: [e - close, e], wrap })
+  return out
+}
+
+function render(node: S, src: string, out: Piece[] = []): Piece[] {
+  if (Array.isArray(node)) {
+    for (const n of node) render(n, src, out)
+    return out
+  }
+  switch (node.k) {
+    case 'tok':
+      out.push({ text: node.text, cls: node.cls })
+      break
+    case 'atom':
+      out.push(...atomPieces(node, src))
+      break
+    case 'fold':
+      out.push({ text: ELLIPSIS, el: true, title: src.slice(node.start, node.end) })
+      break
+    case 'elide':
+      if (node.collapsed) out.push({ text: ELLIPSIS, el: true, title: src.slice(node.start, node.end) })
+      else render(node.inner, src, out)
+      break
+    case 'list': {
+      const n = node.items.length
+      for (let i = 0; i < Math.min(node.keep, n); i++) {
+        if (i > 0) out.push({ text: node.seps[i - 1], cls: node.seps[i - 1].trim() ? 'op' : undefined })
+        render(node.items[i], src, out)
+      }
+      if (node.keep < n) {
+        if (node.keep > 0) out.push({ text: node.seps[node.keep - 1], cls: 'op' })
+        out.push({ text: ELLIPSIS, el: true, title: src.slice(node.spans[node.keep][0], node.spans[n - 1][1]) })
+      }
+      break
+    }
+    case 'args': {
+      let i = 0
+      let first = true
+      while (i < node.items.length) {
+        if (!first) out.push({ text: ' ' })
+        first = false
+        const it = node.items[i]
+        if (!it.hidden) {
+          render(it.node, src, out)
+          i++
+          continue
+        }
+        let j = i
+        while (j < node.items.length && node.items[j].hidden) j++
+        out.push({ text: ELLIPSIS, el: true, title: src.slice(node.items[i].node.start, node.items[j - 1].node.end) })
+        i = j
+      }
+      break
+    }
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Reductions
+// ---------------------------------------------------------------------------
+
+/** A possible reduction: `cost` (information lost) and the columns it saves. `apply` returns its undo. */
+type Cand = { cost: number; saving: number; key: number; apply: () => () => void }
+interface Ctx {
+  atomWidth: (a: Atom) => number
+  width: (n: S) => number
+  src: string
+}
+
+function collect(node: S, cands: Cand[], ctx: Ctx, inArgs = false): void {
+  if (Array.isArray(node)) {
+    for (const n of node) collect(n, cands, ctx)
+    return
+  }
+  switch (node.k) {
+    case 'atom':
+      atomCands(node, cands, ctx, inArgs)
+      return
+    case 'elide': {
+      if (node.collapsed) return
+      collect(node.inner, cands, ctx)
+      cands.push({ cost: 60, saving: ctx.width(node.inner) - 1, key: node.size, apply: () => { node.collapsed = true; return () => { node.collapsed = false } } })
+      return
+    }
+    case 'list': {
+      const shown = Math.min(node.keep, node.items.length)
+      for (let i = 0; i < shown; i++) collect(node.items[i], cands, ctx)
+      if (node.keep > 1) {
+        const last = node.keep - 1
+        // dropping the last shown statement: when others are already dropped, it merges into their `…`
+        const saving = ctx.width(node.items[last]) + (node.keep < node.items.length ? node.seps[last - 1].length : -1)
+        cands.push({ cost: 100, saving, key: node.pos, apply: () => { node.keep--; return () => { node.keep++ } } })
+      }
+      return
+    }
+    case 'args':
+      node.items.forEach((it, i) => {
+        if (it.hidden) return
+        collect(it.node, cands, ctx, true)
+        if (it.fixed) return
+        const w = ctx.atomWidth(it.node)
+        // short items say a lot per column: hiding them costs double
+        // subcommands are nearly structure (`git status`): hidden only after compound bodies collapse
+        const cost = { str: 3, word: 3, val: 3, cmd: 3, sc: 80, lflag: 3.5, target: 6, path: 6, flag: 8 }[it.node.kind] * (w <= 6 ? 2 : 1)
+        const merges = (node.items[i - 1]?.hidden ? 1 : 0) + (node.items[i + 1]?.hidden ? 1 : 0)
+        // alone it becomes `…`; next to a hidden run it disappears with its space
+        const saving = merges === 0 ? w - 1 : merges === 1 ? w + 1 : w + 3
+        cands.push({ cost, saving, key: it.node.pos, apply: () => { it.hidden = true; return () => { it.hidden = false } } })
+      })
+      return
+    default:
+      return
+  }
+}
+
+function atomCands(a: Atom, cands: Cand[], ctx: Ctx, inArgs: boolean): void {
+  const w = ctx.atomWidth(a)
+  const shorten = (cost: number, minKeep: number): void => {
+    // shorten by half at a time (at least to minKeep); re-scored every round
+    const limit = Math.max(minKeep, Math.ceil(w / 2))
+    if (limit < w) cands.push({ cost, saving: w - limit, key: a.pos, apply: () => { const old = a.limit; a.limit = limit; return () => { a.limit = old } } })
+  }
+  const toTail = (cost: number): void => {
+    a.tail = true
+    const tw = ctx.atomWidth(a)
+    a.tail = false
+    if (tw < w) cands.push({ cost, saving: w - tw, key: a.pos, apply: () => { a.tail = true; return () => { a.tail = false } } })
+  }
+  switch (a.kind) {
+    case 'str':
+    case 'word':
+      if (w > 12) shorten(1, 12)
+      return
+    case 'path':
+    case 'target':
+      if (w <= 12) return // short paths (`/dev/null`) are clearer whole; they can still be hidden as arguments
+      if (!a.tail) toTail(1.2)
+      else shorten(4, a.kind === 'target' ? 6 : 8)
+      return
+    case 'val':
+      if (w > 12) shorten(1, 12)
+      else if (w > 1) cands.push({ cost: w <= 6 ? 8 : 4, saving: w - 1, key: a.pos, apply: () => { const old = a.limit; a.limit = 1; return () => { a.limit = old } } })
+      return
+    case 'cmd':
+      if (inArgs) return
+      // only command names that are paths (`/usr/local/bin/x`, `./scripts/build.sh`) shrink
+      if (!ctx.src.slice(a.start, a.end).includes('/')) return
+      if (!a.tail) toTail(150)
+      else shorten(150, 6)
+      return
+    default:
+      return
+  }
+}
+
+/** The reduction state of a tree (limits, tails, hidden args, collapsed bodies, list lengths). */
+function snapshot(node: S, out: unknown[] = []): unknown[] {
+  if (Array.isArray(node)) {
+    for (const n of node) snapshot(n, out)
+    return out
+  }
+  switch (node.k) {
+    case 'atom': out.push(node.limit, node.tail); break
+    case 'elide': out.push(node.collapsed); snapshot(node.inner, out); break
+    case 'list': out.push(node.keep); for (const it of node.items) snapshot(it, out); break
+    case 'args': for (const it of node.items) { out.push(it.hidden); snapshot(it.node, out) } break
+    default: break
+  }
+  return out
+}
+
+function restore(node: S, snap: unknown[], at = { i: 0 }): void {
+  if (Array.isArray(node)) {
+    for (const n of node) restore(n, snap, at)
+    return
+  }
+  switch (node.k) {
+    case 'atom': node.limit = snap[at.i++] as number | undefined; node.tail = snap[at.i++] as boolean | undefined; break
+    case 'elide': node.collapsed = snap[at.i++] as boolean; restore(node.inner, snap, at); break
+    case 'list': node.keep = snap[at.i++] as number; for (const it of node.items) restore(it, snap, at); break
+    case 'args': for (const it of node.items) { it.hidden = snap[at.i++] as boolean; restore(it.node, snap, at) } break
+    default: break
+  }
+}
+
+/** Cut the rendered line at `width` columns, ending in an ellipsis that holds the rest. */
+function hardCut(pieces: Piece[], width: number, src: string): Piece[] {
+  const out: Piece[] = []
+  let used = 0
+  const budget = width - 1
+  let restStart: number | null = null
+  for (const p of pieces) {
+    if (used + p.text.length <= budget) {
+      out.push(p)
+      used += p.text.length
+      continue
+    }
+    const room = budget - used
+    if (room > 0) {
+      const text = p.text.slice(0, room)
+      out.push({ ...p, text, src: p.src ? [p.src[0], p.src[0] + room] : undefined, el: false })
+      used += room
+    }
+    if (p.src && restStart === null) restStart = p.src[0] + Math.max(0, room)
+    break
+  }
+  out.push({ text: ELLIPSIS, el: true, title: restStart !== null ? src.slice(restStart) : src })
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// HTML
+// ---------------------------------------------------------------------------
+
+const esc = (s: string): string => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!)
+
+function pieceHtml(p: Piece, hl: Highlight): string {
+  if (p.el) return `<span class="el"${p.title !== undefined ? ` title="${esc(p.title)}"` : ''}>${esc(p.text)}</span>`
+  if (p.src) {
+    return hl.runs(p.src[0], p.src[1]).map((r) => {
+      const cls = r.cls || p.cls
+      return cls ? `<span class="${cls}">${esc(r.text)}</span>` : esc(r.text)
+    }).join('')
+  }
+  return p.cls ? `<span class="${p.cls}">${esc(p.text)}</span>` : esc(p.text)
+}
+
+function toHtml(pieces: Piece[], hl: Highlight): string {
+  let html = ''
+  for (let i = 0; i < pieces.length; i++) {
+    const p = pieces[i]
+    if (p.wrap) {
+      let inner = ''
+      let j = i
+      while (j < pieces.length && pieces[j].wrap === p.wrap) inner += pieceHtml(pieces[j++], hl)
+      html += `<span class="tr" title="${esc(p.wrap.title)}">${inner}</span>`
+      i = j - 1
+      continue
+    }
+    html += pieceHtml(p, hl)
+  }
+  return `<span class="mash sum">${html}</span>`
+}