Claude Code Track Changes

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import { atom, read, update } from 'claude-code'
6import type { Elements, EngineInterface, Register, RenderNode, RenderSurface } from 'claude-code'
7import type { Doc, DocRow, PaneState, PaneView, RedlineComment, RedlineSettings as Settings } from '../types'
8import { adfRows, isAdf } from './adf'
9import type { ChangesPal, ChangesPost, ChangesProps } from './changes'
10import { address, changesOf, compareGrids, compareLines, summaryOf } from './compare'
11import type { Change, GridComparison, LinesComparison } from './compare'
12import { readCsv } from './csv'
13import { startReading, stopReading, TooSlow } from './deadline'
14import { readDocx } from './docx'
15import { extOf, fingerprintOf, folderOf, kindOf, matchParent, nameOf, stemOf, TRACKED } from './family'
16import type { Candidate } from './family'
17import type { FileBarProps } from './filebar'
18import { contentKey, shortKey } from './hash'
19import { htmlRows } from './html'
20import { layoutGrid, layoutLines } from './layout'
21import type { DRow, Laid } from './layout'
22import { markdownRows } from './md'
23import { feedbackPrompt, isAbsolutePath, normalizePath, noteName, PROMPT_HEADER, shortPath } from './model'
24import { makeDocx, makeXlsx } from './officegen'
25import { PALETTE } from './palette'
26import { pandaRows } from './panda'
27import { readPdf } from './pdf'
28import type { SpinnerProps } from './spinner'
29import { cutTo, sanitizeLine, stripControls } from './text'
30import { readXlsx } from './xlsx'
31
32/*
33 * Everything here that reaches files, programs or the store does so through `$`,
34 * which a mod may only hand to functions in this same file: so the storage,
35 * the tracking and the writer live here, and the pure work (comparing, matching
36 * families, laying out) in modules of its own.
37 */
38
39// ════ store ════
40
41/**
42 * Where versions are kept: the plugin's own folder under the Claude Code
43 * configuration folder, never in the project. Each file's content is stored
44 * once, whatever number of versions share it.
45 */
46
47// ── What is kept ──
48
49export type Who = 'claude' | 'you' | 'first' | 'restore' | 'keep' | 'example'
50
51export type Version = {
52  id: string
53  family: string
54  path: string
55  /** The content's key; null when the file was deleted. */
56  key: string | null
57  size: number
58  /** When the version was noted, ms since the epoch. */
59  at: number
60  by: Who
61  turn?: string
62  /** A word on how it came about: "stopped partway", "before restoring". */
63  note?: string
64  /** A few words of what it holds, for matching new files to it. */
65  fp?: string[]
66}
67
68export type Family = {
69  id: string
70  /** The name people know it by: its first file's name. */
71  name: string
72  kind: string
73  /** The file it lives in, where Keep this version puts it. */
74  home: string
75  /** Every file it has been, in order. */
76  paths: string[]
77  versions: string[]
78}
79
80export type TurnChange = { family: string; before: string | null; after: string }
81
82export type Turn = {
83  id: string
84  start: number
85  end: number
86  by: 'claude' | 'example'
87  status: 'done' | 'stopped' | 'failed'
88  changes: TurnChange[]
89}
90
91/** A new file Claude Code Track Changes isn't sure about: asked once in the pane. */
92export type Ask = { version: string; path: string; guess: { family: string; path: string }; others: { family: string; path: string }[] }
93
94/** A file on disk as last noted. */
95export type Known = { key: string; size: number; mtime: number; family: string }
96
97/** A file that couldn't be kept, and why, in plain words. */
98export type Skipped = { path: string; reason: string }
99
100export type Index = {
101  v: 1
102  folder: string
103  files: Record<string, Known>
104  families: Record<string, Family>
105  versions: Record<string, Version>
106  turns: Turn[]
107  /** Answers to "is this a new version of that?", by "new path → old path": yes or no. */
108  answers: Record<string, 'yes' | 'no'>
109  asks: Ask[]
110  skipped: Skipped[]
111  /** The turn running now: its id and when it started. */
112  running: { id: string; start: number } | null
113  /** Whether the folder has been noted once: the first look records, it shows nothing. */
114  isReady: boolean
115}
116
117export const emptyIndex = (folder: string): Index => ({ v: 1, folder, files: {}, families: {}, versions: {}, turns: [], answers: {}, asks: [], skipped: [], running: null, isReady: false })
118
119// ── Limits ──
120
121/** Claude Code reads files of up to 4 MiB for a mod; larger ones come through Python, up to 50 MB. */
122export const READ_MAX = 4 * 1024 * 1024
123export const BIG_MAX = 50 * 1024 * 1024
124/** Content is stored in pieces a mod can read back (4 MiB at most). */
125const PIECE = 3_000_000
126
127export const isTracked = (path: string) => TRACKED.includes(extOf(path))
128
129/**
130 * A root (`/`, `C:/`, a network share), a home folder or the folder of them:
131 * too broad to watch.
132 */
133export const isHomeOrRoot = (dir: string) =>
134  /^(?:[A-Z]:)?\/?$|^\/\/[^/]+(?:\/[^/]+)?\/?$|^(?:[A-Z]:|\/mnt\/[a-z]|\/var)?\/(?:home|Users)(?:\/[^/]+)?\/?$|^\/(?:var\/)?root\/?$/i.test(dir)
135
136// ── Where it is kept ──
137
138/** The session's tracking state, set at session.start. */
139export const vault = {
140  /** The data folder: <Claude config>/track-changes. */
141  data: '',
142  /** This project's folder in it. */
143  project: '',
144  folder: '',
145  index: emptyIndex(''),
146  /** The note-taking in progress, so a tool waits for the turn's start to be noted. */
147  pending: null as Promise<void> | null,
148}
149
150/** A document's newest version. */
151export const latestOf = (fam: Family): Version | undefined => vault.index.versions[fam.versions[fam.versions.length - 1] ?? '']
152
153export async function dataFolder($: EngineInterface): Promise<string> {
154  const config = await $.env.get('CLAUDE_CONFIG_DIR')
155  if (config) return `${config.replace(/\\/g, '/').replace(/\/$/, '')}/track-changes`
156  const home = (await $.env.get('HOME')) || (await $.env.get('USERPROFILE')) || ''
157  return `${home.replace(/\\/g, '/').replace(/\/$/, '')}/.claude/track-changes`
158}
159
160export async function openVault($: EngineInterface, folder: string) {
161  vault.data = await dataFolder($)
162  vault.folder = folder
163  const last = folder.split('/').filter(Boolean).pop() ?? 'root'
164  vault.project = `${vault.data}/projects/${last.replace(/[^\w.-]+/g, '_').slice(0, 40)}-${shortKey(folder.toLowerCase())}`
165  vault.index = emptyIndex(folder)
166  try {
167    const text = await $.fs.read(`${vault.project}/index.json`)
168    const parsed = JSON.parse(text) as Index
169    if (parsed && parsed.v === 1 && parsed.files && parsed.families) vault.index = { ...emptyIndex(folder), ...parsed, folder }
170  } catch {
171    /* a first look at this folder */
172  }
173}
174
175export async function saveIndex($: EngineInterface) {
176  await $.fs.write(`${vault.project}/index.json`, JSON.stringify(vault.index))
177}
178
179export const blobPath = (key: string, part: number) => `${vault.project}/store/${key.slice(0, 2)}/${key}.${part}`
180
181/** Stores a file's content (base64) once; a second store of the same content costs nothing. */
182export async function putBlob($: EngineInterface, key: string, base64: string) {
183  if (await $.fs.exists(blobPath(key, 0))) {
184    const first = await $.fs.stat(blobPath(key, 0)).catch(() => undefined)
185    if (first && first.size > 0) return
186  }
187  const parts = Math.max(1, Math.ceil(base64.length / PIECE))
188  // Later pieces first, so a store cut short never looks whole.
189  for (let k = parts - 1; k >= 0; k -= 1) await $.fs.write(blobPath(key, k), (k === 0 ? `${parts}\n` : '') + base64.slice(k * PIECE, (k + 1) * PIECE))
190}
191
192/** A stored content's base64, or null when it is no longer kept. */
193export async function getBlob($: EngineInterface, key: string): Promise<string | null> {
194  try {
195    const first = await $.fs.read(blobPath(key, 0))
196    const newline = first.indexOf('\n')
197    if (newline < 0) return null
198    const parts = Number(first.slice(0, newline))
199    const out = [first.slice(newline + 1)]
200    for (let k = 1; k < parts; k += 1) out.push(await $.fs.read(blobPath(key, k)))
201    const text = out.join('')
202    return contentKey(text) === key ? text : null
203  } catch {
204    return null
205  }
206}
207
208/** Lets go of a stored content: a mod can't delete files, so each piece is emptied, which frees its space. */
209export async function dropBlob($: EngineInterface, key: string) {
210  try {
211    const first = await $.fs.read(blobPath(key, 0))
212    const parts = Number(first.slice(0, first.indexOf('\n'))) || 1
213    for (let k = 0; k < parts; k += 1) await $.fs.write(blobPath(key, k), '')
214  } catch {
215    /* already gone */
216  }
217}
218
219// ════ python ════
220
221/**
222 * Python 3, only when it is already on the computer, only for documents over
223 * 4 MB (the most Claude Code lets a mod read). It runs the bundled
224 * scripts/read_file.py, which prints one file's bytes as base64. The command
225 * is fixed text; the file's path goes on standard input.
226 */
227
228type Python = 'python3' | 'py' | 'python'
229
230export const py = { cmd: null as Python | 'none' | null, home: '' }
231
232function startScript($: EngineInterface, python: Python, input: string) {
233  if (python === 'python3') return $.process.spawn({ argv: ['python3', '-I', './scripts/read_file.py'], cwd: $.plugin.root, input })
234  if (python === 'py') return $.process.spawn({ argv: ['py', '-3', '-I', './scripts/read_file.py'], cwd: $.plugin.root, input })
235  return $.process.spawn({ argv: ['python', '-I', './scripts/read_file.py'], cwd: $.plugin.root, input })
236}
237
238/** A script's standard output, or 'timeout', or null when it could not start or wrote too much. */
239async function collect($: EngineInterface, stream: ReturnType<typeof startScript>, timeoutMs: number): Promise<string | null | 'timeout'> {
240  const parts: string[] = []
241  let size = 0
242  const iterator = stream[Symbol.asyncIterator]()
243  const stop = new AbortController()
244  const timer = $.clock.sleep(timeoutMs, { signal: stop.signal }).then(
245    () => 'timeout' as const,
246    () => 'stopped' as const,
247  )
248  try {
249    for (;;) {
250      const step = await Promise.race([iterator.next(), timer])
251      if (step === 'timeout') {
252        await iterator.return?.(undefined as never)
253        return 'timeout'
254      }
255      if (step === 'stopped' || step.done) break
256      if (step.value.stream !== 'stdout') continue
257      size += step.value.text.length
258      if (size > 70 * 1024 * 1024) {
259        await iterator.return?.(undefined as never)
260        return null
261      }
262      parts.push(step.value.text)
263    }
264  } catch {
265    return null
266  } finally {
267    stop.abort()
268  }
269  return parts.join('')
270}
271
272/** Where a Mac keeps a real Python 3: Apple's developer tools or Xcode, python.org's installer, Homebrew, MacPorts. */
273const MAC_PYTHONS = [
274  '/Library/Developer/CommandLineTools/usr/bin/python3',
275  '/Applications/Xcode.app/Contents/Developer/usr/bin/python3',
276  '/Library/Frameworks/Python.framework/Versions/Current/bin/python3',
277  '/usr/local/bin/python3',
278  '/opt/homebrew/bin/python3',
279  '/opt/local/bin/python3',
280  '/opt/anaconda3/bin/python3',
281  '/opt/miniconda3/bin/python3',
282]
283
284/** A Mac where /usr/bin/python3 can only be Apple's stub (running it pops up Apple's offer to install developer tools). */
285async function isMacWithoutPython($: EngineInterface): Promise<boolean> {
286  if (!(await $.fs.exists('/System/Library/CoreServices/SystemVersion.plist'))) return false
287  const own = py.home ? [`${py.home}/.pyenv/shims/python3`, `${py.home}/miniconda3/bin/python3`, `${py.home}/anaconda3/bin/python3`, `${py.home}/.local/bin/python3`] : []
288  for (const path of [...MAC_PYTHONS, ...own]) if (await $.fs.exists(path)) return false
289  return true
290}
291
292/**
293 * Runs read_file.py with Python 3: python3, then py -3 (the Windows
294 * launcher), then python, until one answers. The one that worked is
295 * remembered for the session; so is finding none (/track-changes setup asks again).
296 */
297export async function runPython($: EngineInterface, input: string, timeoutMs: number): Promise<string | 'none' | 'timeout'> {
298  if (py.cmd === 'none') return 'none'
299  if (py.cmd === null && (await isMacWithoutPython($))) {
300    py.cmd = 'none'
301    return 'none'
302  }
303  const order: Python[] = py.cmd ? [py.cmd] : ['python3', 'py', 'python']
304  for (const python of order) {
305    const out = await collect($, startScript($, python, input), timeoutMs)
306    if (out === 'timeout') return 'timeout'
307    if (out !== null && out.startsWith('LPP1')) {
308      py.cmd = python
309      return out
310    }
311  }
312  py.cmd = 'none'
313  return 'none'
314}
315
316/** A document over 4 MB as base64, through Python; or why it can't be read. */
317export async function readBigBase64($: EngineInterface, path: string): Promise<string | { reason: string }> {
318  const out = await runPython($, path, 60_000)
319  if (out === 'none') return { reason: 'it is over 4 MB, and files that size need Python 3 on this computer (run /track-changes setup to check)' }
320  if (out === 'timeout') return { reason: 'reading it took too long' }
321  const newline = out.indexOf('\n')
322  const head = newline < 0 ? out : out.slice(0, newline)
323  if (head.startsWith('LPP1 error')) return { reason: head.slice(11).trim().slice(0, 200) || 'it could not be read' }
324  return out.slice(newline + 1).replace(/\s+/g, '')
325}
326
327// ════ writer ════
328
329/**
330 * Writing files back, only when the person clicks Restore or Keep this
331 * version (and for /track-changes examples). A mod can write text files only, so
332 * Word, Excel and PDF files are written by the computer's own tools, run
333 * without a shell, with fixed arguments and the file paths as the only
334 * variable parts:
335 *
336 * - Windows: certutil -decode, and PowerShell's Move-Item with the paths in
337 *   environment variables (never in the command text)
338 * - macOS: base64 -D, mv -n
339 * - Linux: openssl base64 -d, or Python 3, and mv -n
340 *
341 * Every write is read back and checked against what was meant.
342 */
343
344export type Os = 'windows' | 'mac' | 'linux'
345
346export const host = { os: 'linux' as Os, tmp: '', pluginRoot: '' }
347
348export async function detectOs($: EngineInterface, folder: string): Promise<Os> {
349  if (/^[a-z]:\//i.test(folder) || folder.startsWith('//')) return 'windows'
350  if (await $.fs.exists('/System/Library/CoreServices/SystemVersion.plist')) return 'mac'
351  return 'linux'
352}
353
354const native = (path: string) => (host.os === 'windows' ? path.replace(/\//g, '\\') : path)
355
356export class WriteError extends Error {}
357
358/** Why a write failed, in words a person can act on. */
359function why(text: string, name: string): string {
360  if (/being used|EBUSY|locked|sharing violation|process cannot access/i.test(text)) return `${name} is open in another app (maybe Excel or Word). Close it there and try again.`
361  if (/denied|EACCES|EPERM|read-only/i.test(text)) return `Claude Code Track Changes isn't allowed to change ${name}. Check that it isn't read-only.`
362  return `${name} couldn't be written: ${text.replace(/\s+/g, ' ').slice(0, 160)}`
363}
364
365
366/** Decodes a base64 file into `target` with whichever tool this computer has. */
367async function decode($: EngineInterface, from: string, target: string): Promise<{ ok: true } | { ok: false; text: string }> {
368  const attempts: (readonly string[])[] =
369    host.os === 'windows'
370      ? [['certutil', '-f', '-decode', native(from), native(target)]]
371      : host.os === 'mac'
372        ? [['base64', '-D', '-i', from, '-o', target]]
373        : [
374            ['openssl', 'base64', '-d', '-A', '-in', from, '-out', target],
375            ['python3', '-I', './scripts/write_file.py', from, target],
376          ]
377  let last = 'no tool on this computer could write it'
378  for (const argv of attempts) {
379    try {
380      const cwd = argv[0] === 'python3' ? host.pluginRoot : undefined
381      const run = await $.process.run(argv, { timeoutMs: 60_000, ...(cwd ? { cwd } : {}) })
382      if (run.exitCode === 0) return { ok: true }
383      last = run.stderr || run.stdout || `exit ${run.exitCode}`
384    } catch (error) {
385      last = String((error as { message?: unknown })?.message ?? error)
386    }
387  }
388  return { ok: false, text: last }
389}
390
391/** Whether `path` now holds exactly `base64`. */
392async function holds($: EngineInterface, path: string, base64: string): Promise<boolean> {
393  try {
394    const st = await $.fs.stat(path)
395    if (st.size > 4 * 1024 * 1024) return st.size === Math.floor((base64.length * 3) / 4) - (base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0)
396    return contentKey((await $.fs.read(path, { as: 'bytes' })).base64) === contentKey(base64)
397  } catch {
398    return false
399  }
400}
401
402/** The bytes as text when they are valid UTF-8 (a byte order mark kept), else null. */
403const decodeUtf8 = (bytes: Uint8Array): string | null => {
404  const text = new TextDecoder().decode(bytes)
405  const hasMark = bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
406  const whole = hasMark && !text.startsWith('\ufeff') ? `\ufeff${text}` : text
407  const again = new TextEncoder().encode(whole)
408  if (again.length !== bytes.length) return null
409  for (let k = 0; k < bytes.length; k += 1) if (again[k] !== bytes[k]) return null
410  return whole
411}
412
413export function bytesOf(base64: string): Uint8Array {
414  const binary = atob(base64)
415  const bytes = new Uint8Array(binary.length)
416  for (let k = 0; k < binary.length; k += 1) bytes[k] = binary.charCodeAt(k)
417  return bytes
418}
419
420export function base64Of(bytes: Uint8Array): string {
421  let binary = ''
422  for (let k = 0; k < bytes.length; k += 0x8000) binary += String.fromCharCode(...bytes.subarray(k, k + 0x8000))
423  return btoa(binary)
424}
425
426/**
427 * Writes `base64` into `target`, exactly. Text files (valid UTF-8, without
428 * NUL bytes) are written by the mod itself; anything else by the computer's
429 * own tool. Throws a WriteError with words for the person when it fails.
430 */
431export async function writeExactly($: EngineInterface, target: string, base64: string) {
432  const name = nameOf(target)
433  const bytes = bytesOf(base64)
434  const text = bytes.includes(0) ? null : decodeUtf8(bytes)
435  if (text !== null && !/\.(xlsx|xlsm|docx|pdf)$/i.test(target)) {
436    try {
437      await $.fs.write(target, text)
438    } catch (error) {
439      throw new WriteError(why(String((error as { message?: unknown })?.message ?? error), name))
440    }
441    if (!(await holds($, target, base64))) throw new WriteError(`${name} didn't come out as expected. Try again, or open it to check.`)
442    return
443  }
444  const from = `${host.tmp}/${crypto.randomUUID()}.b64`
445  await $.fs.write(from, base64)
446  try {
447    const done = await decode($, from, target)
448    if (!done.ok) throw new WriteError(why(done.text, name))
449    if (!(await holds($, target, base64))) throw new WriteError(`${name} didn't come out as expected (it may be open in another app). Close it and try again.`)
450  } finally {
451    // A mod can't delete files: the temporary copy is emptied.
452    await $.fs.write(from, '').catch(() => undefined)
453  }
454}
455
456/** Moves a file to `to` (a path that doesn't exist yet), its folder made if needed. Never overwrites. */
457export async function moveFile($: EngineInterface, from: string, to: string) {
458  const name = nameOf(from)
459  if (await $.fs.exists(to)) throw new WriteError(`${nameOf(to)} already exists in the Older versions folder.`)
460  let result: { exitCode: number; stderr: string; stdout: string }
461  try {
462    if (host.os === 'windows') {
463      result = await $.process.run(
464        [
465          'powershell.exe',
466          '-NoProfile',
467          '-NonInteractive',
468          '-Command',
469          '$ErrorActionPreference = "Stop"; New-Item -ItemType Directory -Force -Path (Split-Path -LiteralPath $env:TRACK_CHANGES_TO) | Out-Null; Move-Item -LiteralPath $env:TRACK_CHANGES_FROM -Destination $env:TRACK_CHANGES_TO',
470        ],
471        { env: { TRACK_CHANGES_FROM: native(from), TRACK_CHANGES_TO: native(to) }, timeoutMs: 60_000 },
472      )
473    } else {
474      const folder = to.slice(0, to.lastIndexOf('/'))
475      const made = await $.process.run(['mkdir', '-p', '--', folder], { timeoutMs: 20_000 })
476      if (made.exitCode !== 0) throw new WriteError(why(made.stderr, 'the Older versions folder'))
477      result = await $.process.run(['mv', '-n', '--', from, to], { timeoutMs: 60_000 })
478    }
479  } catch (error) {
480    if (error instanceof WriteError) throw error
481    throw new WriteError(why(String((error as { message?: unknown })?.message ?? error), name))
482  }
483  if (result.exitCode !== 0 || !(await $.fs.exists(to)) || (await $.fs.exists(from))) throw new WriteError(why(result.stderr || result.stdout || 'the move did not happen', name))
484}
485
486/** A free name in a folder: "budget_v2.xlsx", else "budget_v2 (2).xlsx", "(3)"… */
487export async function freeName($: EngineInterface, folder: string, name: string): Promise<string> {
488  const dot = name.lastIndexOf('.')
489  const stem = dot > 0 ? name.slice(0, dot) : name
490  const ext = dot > 0 ? name.slice(dot) : ''
491  for (let k = 1; k < 200; k += 1) {
492    const candidate = `${folder}/${k === 1 ? name : `${stem} (${k})${ext}`}`
493    if (!(await $.fs.exists(candidate))) return candidate
494  }
495  throw new WriteError(`The Older versions folder already has too many copies of ${name}.`)
496}
497
498// ════ versions ════
499
500/**
501 * A stored version, read back as a document: the same readers Lazy Panda
502 * Panel uses, for every kind of file Claude Code Track Changes tracks. Read once per
503 * content, then kept for a while.
504 */
505
506const DOC_MAX_ROWS = 20_000
507const DOC_MAX_LINE = 20_000
508const docCache = new Map<string, Doc>()
509
510const kindName = (ext: string) => (ext === 'docx' ? 'Word document' : ext === 'pdf' ? 'PDF' : ext === 'xlsx' || ext === 'xlsm' ? 'workbook' : 'file')
511
512/** Rows made safe to draw and to compare: tables as cells joined by a bar, never padded (padding would change with the widest cell). */
513function cleanRows(rows: (DocRow & { cells?: string[]; isHeader?: boolean })[]): DocRow[] {
514  return rows.slice(0, DOC_MAX_ROWS).map(row => {
515    const { cells, isHeader, spans, ...rest } = row
516    void spans
517    const text = stripControls(cells ? cells.join(' │ ') : row.style === 'th' || row.style === 'td' ? row.text.split(' | ').join(' │ ') : row.text)
518    return { ...rest, text: text.length > DOC_MAX_LINE ? `${text.slice(0, DOC_MAX_LINE)}…` : text, ...(cells ? { style: isHeader ? ('th' as const) : ('td' as const) } : {}) }
519  })
520}
521
522/** An empty document of the kind a file is: what a deleted file, or one not there yet, compares as. */
523export const emptyOf = (path: string): Doc => (['xlsx', 'xlsm', 'csv', 'tsv'].includes(extOf(path)) ? { kind: 'grid', path, sheets: [] } : { kind: 'lines', path, rows: [], isFormatted: !['txt'].includes(extOf(path)) })
524
525/** A locked Office file is not a zip but an older compound file. */
526const isLocked = (bytes: Uint8Array) => bytes[0] === 0xd0 && bytes[1] === 0xcf && bytes[2] === 0x11 && bytes[3] === 0xe0
527
528export async function parseBytes(path: string, bytes: Uint8Array): Promise<Doc> {
529  const ext = extOf(path)
530  try {
531    if (['xlsx', 'xlsm', 'docx'].includes(ext) && isLocked(bytes)) {
532      return { kind: 'error', path, message: `This ${kindName(ext)} is locked, so only its own app can open it and its changes can’t be shown here. Claude Code Track Changes still keeps its versions, and Restore still works.`, isNotice: true }
533    }
534    if (ext === 'xlsx' || ext === 'xlsm' || ext === 'docx' || ext === 'pdf') {
535      startReading(6000)
536      try {
537        if (ext === 'docx') {
538          const word = readDocx(bytes)
539          return { kind: 'lines', path, rows: cleanRows(word.rows), isFormatted: true, ...(word.note ? { note: word.note } : {}) }
540        }
541        if (ext === 'pdf') {
542          const pdf = await readPdf(bytes)
543          if (pdf.kind === 'error') return { ...pdf, path }
544          return { kind: 'lines', path, rows: cleanRows(pdf.rows), isFormatted: true, ...(pdf.note ? { note: pdf.note } : {}) }
545        }
546        return { ...readXlsx(bytes), path }
547      } finally {
548        stopReading()
549      }
550    }
551    const text = stripControls(new TextDecoder('utf-8').decode(bytes))
552    if (ext === 'csv' || ext === 'tsv') {
553      const { sheet, isCut } = readCsv(text, ext)
554      return { kind: 'grid', path, sheets: [sheet], ...(isCut ? { note: 'Only the first 5,000 rows and 60 columns are compared.' } : {}) }
555    }
556    if (ext === 'md' || ext === 'markdown') return { kind: 'lines', path, rows: cleanRows(markdownRows(text)), isFormatted: true }
557    if (ext === 'html' || ext === 'htm') return { kind: 'lines', path, rows: cleanRows(htmlRows(text)), isFormatted: true }
558    if (ext === 'adf') {
559      let parsed: unknown
560      try {
561        parsed = JSON.parse(text)
562      } catch {
563        parsed = undefined
564      }
565      if (isAdf(parsed)) return { kind: 'lines', path, rows: cleanRows(adfRows(parsed)), isFormatted: true }
566      return { kind: 'error', path, message: 'This version isn’t a Confluence page Claude Code Track Changes can read (it may have been saved halfway).' }
567    }
568    const rows: DocRow[] = text.split('\n').map((line, i) => ({ text: line.replace(/\t/g, '  '), anchor: `line ${i + 1}`, unit: 'line' }))
569    if (rows.length > 1 && rows[rows.length - 1]?.text === '') rows.pop()
570    return { kind: 'lines', path, rows: cleanRows(rows) }
571  } catch (error) {
572    if (error instanceof TooSlow) return { kind: 'error', path, message: `This ${kindName(ext)} takes too long to read here. Open it in its own app to see it.` }
573    return { kind: 'error', path, message: `This version couldn’t be read (it may have been saved halfway): ${sanitizeLine(error instanceof Error ? error.message : String(error), 200)}.` }
574  }
575}
576
577/** A version as a document; a deleted file is an empty one. */
578export async function readVersion($: EngineInterface, v: Version): Promise<Doc> {
579  if (v.key === null) return emptyOf(v.path)
580  const id = `${v.key}|${extOf(v.path)}`
581  const hit = docCache.get(id)
582  if (hit) return { ...hit, path: v.path }
583  const base64 = await getBlob($, v.key)
584  if (base64 === null) return { kind: 'error', path: v.path, message: 'This version is no longer kept (older versions are let go after a while: see /track-changes settings).' }
585  const doc = await parseBytes(v.path, bytesOf(base64))
586  docCache.set(id, doc)
587  for (const key of docCache.keys()) if (docCache.size > 12 && key !== id) docCache.delete(key)
588  return doc
589}
590
591// ════ tracker ════
592
593/**
594 * Noting what changed. At the start of Claude's turn the working folder is
595 * noted (only files that changed since are read); at its end, whatever
596 * changed becomes the newest version of its document, however Claude saved it.
597 */
598
599const DEPTH = 3
600const ENTRIES = 4000
601const MAX_DOCS = 400
602const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '__pycache__', 'venv', 'Older versions'])
603
604
605// ── Looking at the folder ──
606
607type Seen = { size: number; mtime: number }
608
609/**
610 * The documents in the working folder: 3 levels down, 4,000 entries at most,
611 * never through a link or a Windows junction, never in hidden folders,
612 * node_modules and the like, a home folder or a drive's root.
613 */
614export async function scanFolder($: EngineInterface, folder: string, extra: readonly string[] = []): Promise<{ found: Map<string, Seen>; isCut: boolean }> {
615  const found = new Map<string, Seen>()
616  if (isHomeOrRoot(folder)) return { found, isCut: false }
617  let left = ENTRIES
618  let isCut = false
619  const realRoot = (await $.fs.stat(folder, { resolve: true }).catch(() => undefined))?.realPath?.replace(/\\/g, '/')
620  const walk = async (dir: string, depth: number) => {
621    if (left <= 0) {
622      isCut = true
623      return
624    }
625    let entries
626    try {
627      entries = await $.fs.list(dir)
628    } catch {
629      return
630    }
631    left -= entries.length
632    for (const entry of entries) {
633      if (entry.isLink || entry.name.startsWith('.') || entry.name.startsWith('~$')) continue
634      const path = `${dir.replace(/\/$/, '')}/${entry.name}`
635      if (entry.kind === 'dir') {
636        if (depth <= 0 || SKIP_DIRS.has(entry.name)) continue
637        // A junction can pass for a folder: one that leads outside where it sits is never entered.
638        if (realRoot) {
639          const real = (await $.fs.stat(path, { resolve: true }).catch(() => undefined))?.realPath?.replace(/\\/g, '/')
640          if (!real || !real.toLowerCase().startsWith(`${realRoot.toLowerCase().replace(/\/$/, '')}/`)) continue
641        }
642        await walk(path, depth - 1)
643      } else if (entry.kind === 'file' && isTracked(entry.name)) {
644        found.set(path, { size: entry.size, mtime: entry.mtimeMs })
645      }
646    }
647  }
648  await walk(folder, DEPTH)
649  // Files Claude wrote deeper down still count.
650  for (const path of extra) {
651    if (found.has(path) || !isTracked(path)) continue
652    const st = await $.fs.stat(path).catch(() => undefined)
653    if (st && st.kind === 'file' && !st.isLink) found.set(path, { size: st.size, mtime: st.mtimeMs })
654  }
655  if (found.size > MAX_DOCS) {
656    // The most recently changed first; the rest wait.
657    const keep = [...found.entries()].sort((a, b) => b[1].mtime - a[1].mtime).slice(0, MAX_DOCS)
658    return { found: new Map(keep), isCut: true }
659  }
660  return { found, isCut }
661}
662
663/** Reads a file and stores its content: its key, or why it couldn't be kept. */
664async function capture($: EngineInterface, path: string, seen: Seen): Promise<{ key: string } | { reason: string }> {
665  if (seen.size > BIG_MAX) return { reason: `it is ${mb(seen.size)}, and Claude Code Track Changes keeps files up to 50 MB` }
666  let base64: string
667  if (seen.size > READ_MAX) {
668    const got = await readBigBase64($, path)
669    if (typeof got !== 'string') return got
670    base64 = got
671  } else {
672    try {
673      base64 = (await $.fs.read(path, { as: 'bytes' })).base64
674    } catch (error) {
675      const text = String((error as { message?: unknown })?.message ?? error)
676      // Windows: Excel and Word hold the files they have open.
677      if (/ENOENT/.test(text)) return { reason: 'it was gone before it could be read' }
678      // Windows: Excel and Word hold the files they have open, so they can't be read.
679      return { reason: 'it couldn’t be read; it may be open in another app such as Excel (close it there, and it’s caught at the end of Claude’s next turn)' }
680    }
681  }
682  const key = contentKey(base64)
683  await putBlob($, key, base64)
684  return { key }
685}
686
687const mb = (size: number) => `${(size / (1024 * 1024)).toFixed(1)} MB`
688
689const newId = () => crypto.randomUUID().slice(0, 13)
690
691// ── Versions and families ──
692
693function addFamily(path: string): Family {
694  const id = newId()
695  const fam: Family = { id, name: nameOf(path), kind: kindOf(path) ?? 'text', home: path, paths: [path], versions: [] }
696  vault.index.families[id] = fam
697  return fam
698}
699
700function addVersion(fam: Family, v: Omit<Version, 'id' | 'family'>): Version {
701  const version: Version = { ...v, id: newId(), family: fam.id }
702  vault.index.versions[version.id] = version
703  fam.versions.push(version.id)
704  if (!fam.paths.includes(v.path)) fam.paths.push(v.path)
705  return version
706}
707
708
709export const familyOfPath = (path: string): Family | undefined => {
710  const known = vault.index.files[path]
711  if (known) return vault.index.families[known.family]
712  return Object.values(vault.index.families).find(f => f.paths.includes(path))
713}
714
715// ── Noting the folder ──
716
717type Look = { now: Map<string, Seen>; isCut: boolean }
718
719/** Paths Claude wrote with Write or Edit this session, wherever they are below the working folder. */
720export const written = new Set<string>()
721
722async function look($: EngineInterface): Promise<Look> {
723  const { found, isCut } = await scanFolder($, vault.folder, [...written])
724  return { now: found, isCut }
725}
726
727/**
728 * Brings the record up to date with the folder as it is: what changed since
729 * it was last noted is read and stored, and comes back as edits, new files
730 * and deletions. Nothing is attributed here.
731 */
732async function difference($: EngineInterface, l: Look) {
733  const idx = vault.index
734  const edits: { path: string; key: string; seen: Seen }[] = []
735  const created: { path: string; key: string; seen: Seen }[] = []
736  const deleted: string[] = []
737  const skipped: Skipped[] = []
738  for (const [path, seen] of l.now) {
739    const known = idx.files[path]
740    if (known && known.size === seen.size && known.mtime === seen.mtime) continue
741    const got = await capture($, path, seen)
742    if ('reason' in got) {
743      skipped.push({ path, reason: got.reason })
744      continue
745    }
746    if (known && known.key === got.key) {
747      // Touched, not changed.
748      known.mtime = seen.mtime
749      continue
750    }
751    ;(known ? edits : created).push({ path, key: got.key, seen })
752  }
753  for (const path of Object.keys(idx.files)) {
754    if (l.now.has(path)) continue
755    // Past the folder's limits is not deleted: only a file truly gone is.
756    if (l.isCut && (await $.fs.exists(path).catch(() => true))) continue
757    if (await $.fs.exists(path).catch(() => false)) continue
758    deleted.push(path)
759  }
760  return { edits, created, deleted, skipped }
761}
762
763async function fingerprint($: EngineInterface, v: Version): Promise<string[]> {
764  if (v.fp) return v.fp
765  if (v.key === null) return []
766  try {
767    v.fp = fingerprintOf(await readVersion($, v))
768  } catch {
769    v.fp = []
770  }
771  return v.fp
772}
773
774/**
775 * The start of a turn (or a first look): whatever changed since Claude's last
776 * turn ended was changed by the person (or by another app), so it is noted as
777 * theirs, and only what Claude does from here is shown as Claude's.
778 */
779export async function noteStart($: EngineInterface, turnId: string) {
780  const idx = vault.index
781  if (idx.running) return
782  const startedAt = Date.now()
783  const l = await look($)
784  const d = await difference($, l)
785  const by: Who = idx.isReady ? 'you' : 'first'
786  for (const e of d.edits) {
787    const fam = familyOfPath(e.path) ?? addFamily(e.path)
788    addVersion(fam, { path: e.path, key: e.key, size: e.seen.size, at: startedAt, by })
789    idx.files[e.path] = { key: e.key, size: e.seen.size, mtime: e.seen.mtime, family: fam.id }
790  }
791  for (const e of d.created) {
792    // A file the person added between turns is a document of its own (or one they had before).
793    const fam = familyOfPath(e.path) ?? addFamily(e.path)
794    addVersion(fam, { path: e.path, key: e.key, size: e.seen.size, at: startedAt, by })
795    idx.files[e.path] = { key: e.key, size: e.seen.size, mtime: e.seen.mtime, family: fam.id }
796  }
797  for (const path of d.deleted) {
798    const fam = familyOfPath(path)
799    if (fam) addVersion(fam, { path, key: null, size: 0, at: startedAt, by })
800    delete idx.files[path]
801  }
802  idx.skipped = d.skipped
803  idx.isReady = true
804  idx.running = { id: turnId, start: startedAt }
805  await saveIndex($)
806}
807
808export type TurnResult = { turn: Turn | null; asks: Ask[]; skipped: Skipped[] }
809
810/**
811 * The end of Claude's turn: each change becomes the newest version of its
812 * document. A file changed in place is its own next version; a new file joins
813 * the document it came from (by type, folder, name and content) or starts one;
814 * a deleted file is a version with nothing in it; a file moved or renamed
815 * keeps its document.
816 */
817export async function noteEnd($: EngineInterface, status: Turn['status'], by: 'claude' | 'example' = 'claude', retry?: () => Promise<void>): Promise<TurnResult> {
818  const idx = vault.index
819  const running = idx.running ?? { id: newId(), start: Date.now() }
820  idx.running = null
821  const l = await look($)
822  let d = await difference($, l)
823  // A file read halfway through a save: looked at again once, a moment later.
824  if (retry && d.skipped.length > 0) {
825    await retry()
826    const again = await difference($, await look($))
827    d = { edits: [...d.edits, ...again.edits], created: [...d.created, ...again.created], deleted: [...new Set([...d.deleted, ...again.deleted])], skipped: again.skipped }
828  }
829  const endedAt = Date.now()
830  const startOf = new Map<string, string | null>()
831  const touched: string[] = []
832  const note = status === 'stopped' ? 'stopped partway' : status === 'failed' ? 'ended with an error' : undefined
833  const remember = (fam: Family) => {
834    if (!startOf.has(fam.id)) startOf.set(fam.id, latestOf(fam)?.id ?? null)
835    if (!touched.includes(fam.id)) touched.push(fam.id)
836  }
837  const stamp = (path: string, key: string, seen: Seen, fam: Family) => (idx.files[path] = { key, size: seen.size, mtime: seen.mtime, family: fam.id })
838  // A version's time is when it was noted; the file's own time only orders what happened in the turn.
839  const base = (path: string, key: string | null, size: number, at: number) => ({ path, key, size, at: Math.min(Math.max(at, running.start), endedAt), by: by as Who, turn: running.id, ...(note ? { note } : {}) })
840
841  // Renamed or moved: a file gone and a new one with the same content.
842  const gone = new Set(d.deleted)
843  const fresh: typeof d.created = []
844  for (const c of d.created) {
845    const from = [...gone].find(path => idx.files[path]?.key === c.key && kindOf(path) === kindOf(c.path))
846    if (from) {
847      gone.delete(from)
848      const fam = vault.index.families[idx.files[from]!.family]!
849      remember(fam)
850      addVersion(fam, { ...base(c.path, c.key, c.seen.size, c.seen.mtime || endedAt), note: `moved from ${nameOf(from)}` })
851      if (fam.home === from) fam.home = c.path
852      delete idx.files[from]
853      stamp(c.path, c.key, c.seen, fam)
854    } else fresh.push(c)
855  }
856  // Changes in the order they happened, so an edit and a copy both read in turn.
857  type Event = { at: number; run: () => Promise<void> }
858  const events: Event[] = []
859  for (const e of d.edits) {
860    events.push({
861      at: e.seen.mtime,
862      run: async () => {
863        const fam = familyOfPath(e.path) ?? addFamily(e.path)
864        remember(fam)
865        addVersion(fam, base(e.path, e.key, e.seen.size, e.seen.mtime || endedAt))
866        stamp(e.path, e.key, e.seen, fam)
867      },
868    })
869  }
870  const asks: Ask[] = []
871  for (const c of fresh) {
872    events.push({
873      at: c.seen.mtime,
874      run: async () => {
875        const probe: Version = { id: '', family: '', ...base(c.path, c.key, c.seen.size, c.seen.mtime || endedAt) }
876        const fp = await fingerprint($, probe)
877        const candidates: Candidate[] = []
878        for (const fam of Object.values(idx.families)) {
879          if (fam.kind !== kindOf(c.path)) continue
880          const last = latestOf(fam)
881          // Its newest version that has content: what a copy would be made from.
882          const source = [...fam.versions].reverse().map(id => idx.versions[id]).find(v => v && v.key !== null)
883          if (!last || !source) continue
884          // Names say most; content is read only for candidates with a name or folder in common.
885          const isNear = folderOf(source.path) === folderOf(c.path) || stemOf(source.path) === stemOf(c.path)
886          candidates.push({ family: fam.id, path: source.path, ...(isNear ? { fingerprint: await fingerprint($, source) } : {}) })
887        }
888        let match = matchParent(c.path, fp, candidates)
889        // An answer the person gave before wins.
890        const answered = match.best ? idx.answers[`${c.path}→${match.best.path}`] : undefined
891        if (answered === 'yes' && match.best) match = { ...match, verdict: 'sure' }
892        if (answered === 'no') match = { verdict: 'none', others: [] }
893        const parent = match.verdict !== 'none' && match.best ? idx.families[match.best.family] : undefined
894        if (parent && match.verdict === 'sure') {
895          remember(parent)
896          addVersion(parent, { ...probe, fp })
897          stamp(c.path, c.key, c.seen, parent)
898          return
899        }
900        const fam = addFamily(c.path)
901        remember(fam)
902        const v = addVersion(fam, { ...probe, fp })
903        stamp(c.path, c.key, c.seen, fam)
904        if (parent && match.best) {
905          asks.push({ version: v.id, path: c.path, guess: { family: parent.id, path: match.best.path }, others: match.others.map(o => ({ family: o.family, path: o.path })) })
906        }
907      },
908    })
909  }
910  for (const path of gone) {
911    events.push({
912      at: endedAt,
913      run: async () => {
914        const fam = familyOfPath(path)
915        if (fam) {
916          remember(fam)
917          addVersion(fam, base(path, null, 0, endedAt))
918        }
919        delete idx.files[path]
920      },
921    })
922  }
923  events.sort((a, b) => a.at - b.at)
924  for (const e of events) await e.run()
925  idx.skipped = d.skipped
926  idx.asks = [...idx.asks.filter(a => idx.versions[a.version]), ...asks]
927  let turn: Turn | null = null
928  if (touched.length > 0) {
929    turn = {
930      id: running.id,
931      start: running.start,
932      end: endedAt,
933      by,
934      status,
935      changes: touched.map(family => ({ family, before: startOf.get(family) ?? null, after: latestOf(idx.families[family]!)!.id })),
936    }
937    idx.turns.push(turn)
938  }
939  await saveIndex($)
940  return { turn, asks, skipped: d.skipped }
941}
942
943// ── Answers to "is this a new version of that?" ──
944
945/**
946 * Moves a document's versions into another document: "Yes, report_final.docx
947 * is a new version of report.docx." The turns that showed it as a new
948 * document now show it as that document's change.
949 */
950export async function joinFamily($: EngineInterface, versionId: string, intoFamily: string, answerFor?: string) {
951  const idx = vault.index
952  const v = idx.versions[versionId]
953  const into = idx.families[intoFamily]
954  if (!v || !into) return
955  const from = idx.families[v.family]
956  if (!from || from.id === into.id) return
957  for (const id of from.versions) {
958    const one = idx.versions[id]
959    if (!one) continue
960    one.family = into.id
961  }
962  into.versions = [...into.versions, ...from.versions].sort((a, b) => (idx.versions[a]?.at ?? 0) - (idx.versions[b]?.at ?? 0))
963  for (const p of from.paths) if (!into.paths.includes(p)) into.paths.push(p)
964  for (const [path, known] of Object.entries(idx.files)) if (known.family === from.id) idx.files[path] = { ...known, family: into.id }
965  for (const turn of idx.turns) {
966    const mine = turn.changes.find(c => c.family === from.id)
967    if (!mine) continue
968    const theirs = turn.changes.find(c => c.family === into.id)
969    if (theirs) {
970      // Both in one turn: from where the document was, to whichever is newer.
971      const a = idx.versions[theirs.after]
972      const b = idx.versions[mine.after]
973      theirs.after = (b?.at ?? 0) >= (a?.at ?? 0) ? mine.after : theirs.after
974      turn.changes = turn.changes.filter(c => c !== mine)
975    } else {
976      // The document's version from before this turn is where the change starts.
977      const before = into.versions.map(id => idx.versions[id]).filter((x): x is Version => !!x && x.at < turn.start && x.family === into.id).pop()
978      mine.family = into.id
979      mine.before = before?.id ?? null
980    }
981  }
982  delete idx.families[from.id]
983  if (answerFor) idx.answers[answerFor] = 'yes'
984  idx.asks = idx.asks.filter(a => a.version !== versionId)
985  await saveIndex($)
986}
987
988export async function answerNo($: EngineInterface, ask: Ask) {
989  vault.index.answers[`${ask.path}→${ask.guess.path}`] = 'no'
990  vault.index.asks = vault.index.asks.filter(a => a.version !== ask.version)
991  await saveIndex($)
992}
993
994// ── Versions made by the pane: restore and keep ──
995
996/** Notes a file Claude Code Track Changes itself just wrote, as a version of its document. */
997export async function noteWrite($: EngineInterface, fam: Family, path: string, key: string, by: Who, note: string) {
998  const st = await $.fs.stat(path).catch(() => undefined)
999  const v = addVersion(fam, { path, key, size: st?.size ?? 0, at: Date.now(), by, note })
1000  vault.index.files[path] = { key, size: st?.size ?? 0, mtime: st?.mtimeMs ?? 0, family: fam.id }
1001  await saveIndex($)
1002  return v
1003}
1004
1005/** Makes sure the file as it is now is kept as a version, so a restore can always be undone. */
1006export async function keepCurrent($: EngineInterface, fam: Family, path: string): Promise<Version | undefined> {
1007  const st = await $.fs.stat(path).catch(() => undefined)
1008  if (!st || st.kind !== 'file') return undefined
1009  const got = await capture($, path, { size: st.size, mtime: st.mtimeMs })
1010  if ('reason' in got) throw new Error(`${nameOf(path)} couldn't be saved first: ${got.reason}`)
1011  const last = [...fam.versions].reverse().map(id => vault.index.versions[id]).find(v => v?.path === path)
1012  if (last && last.key === got.key) return last
1013  return noteWrite($, fam, path, got.key, 'you', 'saved before restoring')
1014}
1015
1016/**
1017 * Reads a version's file again: a file read halfway through a save is read
1018 * whole once it is saved, and the version takes the whole file.
1019 */
1020export async function recapture($: EngineInterface, versionId: string) {
1021  const v = vault.index.versions[versionId]
1022  if (!v || v.key === null) return
1023  const st = await $.fs.stat(v.path).catch(() => undefined)
1024  if (!st || st.kind !== 'file') return
1025  const got = await capture($, v.path, { size: st.size, mtime: st.mtimeMs })
1026  if ('reason' in got) return
1027  v.key = got.key
1028  v.size = st.size
1029  delete v.fp
1030  const known = vault.index.files[v.path]
1031  if (known) vault.index.files[v.path] = { ...known, key: got.key, size: st.size, mtime: st.mtimeMs }
1032  await saveIndex($)
1033}
1034
1035export function forgetPath(path: string) {
1036  delete vault.index.files[path]
1037}
1038
1039// ── Keeping only so much ──
1040
1041export type Retention = { versions: number; days: number }
1042
1043/**
1044 * Keeps the newest `versions` versions of each document, and none older than
1045 * `days`; the newest of each is always kept. Stored content no version uses
1046 * any more is let go.
1047 */
1048export async function prune($: EngineInterface, keep: Retention) {
1049  const idx = vault.index
1050  const cutoff = Date.now() - keep.days * 24 * 60 * 60 * 1000
1051  for (const fam of Object.values(idx.families)) {
1052    const keepIds = new Set<string>()
1053    const list = fam.versions.map(id => idx.versions[id]).filter((v): v is Version => !!v)
1054    // The window: versions from the last `days`, and the one just before them, so the first change in the window still has its before.
1055    const firstRecent = list.findIndex(v => v.at >= cutoff)
1056    const from = Math.max(firstRecent < 0 ? list.length - 1 : firstRecent - 1, list.length - keep.versions, 0)
1057    list.forEach((v, k) => {
1058      const isOnDisk = Object.values(idx.files).some(f => f.key === v.key && f.family === fam.id && f.key !== null) && k === list.length - 1
1059      if (k >= from || isOnDisk) keepIds.add(v.id)
1060    })
1061    for (const id of fam.versions) if (!keepIds.has(id)) delete idx.versions[id]
1062    fam.versions = fam.versions.filter(id => keepIds.has(id))
1063  }
1064  idx.turns = idx.turns
1065    .map(t => ({ ...t, changes: t.changes.filter(c => idx.versions[c.after]).map(c => (c.before && !idx.versions[c.before] ? { ...c, before: null } : c)) }))
1066    .filter(t => t.changes.length > 0 && t.end >= cutoff)
1067  await dropUnused($)
1068  await saveIndex($)
1069}
1070
1071async function dropUnused($: EngineInterface) {
1072  const used = new Set<string>()
1073  for (const v of Object.values(vault.index.versions)) if (v.key) used.add(v.key)
1074  for (const f of Object.values(vault.index.files)) used.add(f.key)
1075  const store = `${vault.project}/store`
1076  let dirs
1077  try {
1078    dirs = await $.fs.list(store)
1079  } catch {
1080    return
1081  }
1082  for (const dir of dirs) {
1083    if (dir.kind !== 'dir') continue
1084    const entries = await $.fs.list(`${store}/${dir.name}`).catch(() => [])
1085    for (const entry of entries) {
1086      const m = /^(.+)\.0$/.exec(entry.name)
1087      if (m && entry.size > 0 && !used.has(m[1]!)) await dropBlob($, m[1]!)
1088    }
1089  }
1090}
1091
1092/** Space used by every project's saved versions, in bytes, and how many documents and versions. */
1093export async function spaceUsed($: EngineInterface): Promise<{ bytes: number; here: number; projects: number }> {
1094  let bytes = 0
1095  let here = 0
1096  let projects = 0
1097  const root = `${vault.data}/projects`
1098  const sum = async (dir: string, depth: number): Promise<number> => {
1099    let total = 0
1100    const entries = await $.fs.list(dir).catch(() => [])
1101    for (const e of entries) {
1102      if (e.kind === 'file') total += e.size
1103      else if (e.kind === 'dir' && depth > 0 && !e.isLink) total += await sum(`${dir}/${e.name}`, depth - 1)
1104    }
1105    return total
1106  }
1107  for (const p of await $.fs.list(root).catch(() => [])) {
1108    if (p.kind !== 'dir') continue
1109    projects += 1
1110    const size = await sum(`${root}/${p.name}`, 3)
1111    bytes += size
1112    if (`${root}/${p.name}` === vault.project) here = size
1113  }
1114  return { bytes, here, projects }
1115}
1116
1117/** Forgets every saved version of this folder; the files themselves are not touched. */
1118export async function clearProject($: EngineInterface) {
1119  const files = vault.index.files
1120  vault.index = { ...emptyIndex(vault.folder), files: {} }
1121  // What's on disk now is where tracking starts again.
1122  vault.index.isReady = false
1123  await dropUnused($)
1124  void files
1125  await saveIndex($)
1126}
1127
1128// ════ the pane ════
1129
1130const PANE = 'track-changes'
1131const TITLE = 'Track Changes'
1132
1133const DEFAULT_PANE: PaneState = {
1134  turn: null,
1135  doc: 0,
1136  family: null,
1137  before: null,
1138  after: null,
1139  view: 'changes',
1140  target: null,
1141  mode: 'auto',
1142  top: 0,
1143  left: 0,
1144  sheet: 0,
1145  focus: null,
1146  open: [],
1147  cell: null,
1148  isListOpen: false,
1149  isMoreOpen: false,
1150  isCommenting: false,
1151}
1152const DEFAULT_SETTINGS: Settings = { notices: true, autoOpen: false, tell: 'next', keepVersions: 20, keepDays: 7 }
1153
1154const pane = atom({ plugin: 'track-changes', key: 'pane' } as const, DEFAULT_PANE)
1155const tick = atom({ plugin: 'track-changes', key: 'tick' } as const, 0)
1156const flash = atom({ plugin: 'track-changes', key: 'flash' } as const, { key: 0, turn: null, fresh: [] })
1157const settings = atom({ plugin: 'track-changes', key: 'prefs' } as const, DEFAULT_SETTINGS)
1158const comments = atom({ plugin: 'track-changes', key: 'comments' } as const, [])
1159const notes = atom({ plugin: 'track-changes', key: 'notes' } as const, [])
1160const banner = atom({ plugin: 'track-changes', key: 'banner' } as const, null)
1161
1162/** What this session's hooks share; set again on each load by session.start. */
1163const session = {
1164  folder: '',
1165  /** How to open a file in the computer's own app; null over SSH or with no desktop. */
1166  opener: null as 'open' | 'xdg-open' | 'explorer' | null,
1167  /** Comments sent, waiting for Claude's turn to finish. */
1168  isSending: false,
1169  /** Space used, worked out when the settings open. */
1170  space: null as { bytes: number; here: number; projects: number } | null,
1171}
1172
1173const plural = (n: number, one: string, many = `${one}s`) => `${n.toLocaleString('en')} ${n === 1 ? one : many}`
1174const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n))
1175const megabytes = (bytes: number) => (bytes < 1024 * 1024 ? `${Math.max(bytes > 0 ? 1 : 0, Math.round(bytes / 1024))} KB` : `${(bytes / (1024 * 1024)).toFixed(1)} MB`)
1176const errorText = (error: unknown) => sanitizeLine(String((error as { message?: unknown })?.message ?? error), 200)
1177
1178// ── Words for times and people ──
1179
1180const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
1181const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
1182
1183/** A time as people say it: "2.14pm" today, "Tue 2.14pm" this week, "3 Oct 2.14pm" before. */
1184export function clock(ms: number, now = Date.now()): string {
1185  const d = new Date(ms)
1186  const h = d.getHours()
1187  const time = `${h % 12 === 0 ? 12 : h % 12}.${String(d.getMinutes()).padStart(2, '0')}${h < 12 ? 'am' : 'pm'}`
1188  if (d.toDateString() === new Date(now).toDateString()) return time
1189  if (now - ms < 6 * 24 * 60 * 60 * 1000 && ms < now) return `${DAYS[d.getDay()]} ${time}`
1190  return `${d.getDate()} ${MONTHS[d.getMonth()]} ${time}`
1191}
1192
1193const WHO: Record<Who, string> = { claude: 'by Claude', you: 'by you', first: 'as first seen', restore: 'restored by you', keep: 'kept by you', example: 'by Claude (example)' }
1194const whoOf = (v: Version) => `${WHO[v.by]}${v.note ? ` (${v.note})` : ''}`
1195const shortWho = (v: Version) => (v.by === 'claude' || v.by === 'example' ? 'Claude' : v.by === 'first' ? 'First seen' : 'You')
1196const isClaude = (v: Version) => v.by === 'claude' || v.by === 'example'
1197
1198const APPS: Record<string, string> = { xlsx: 'Excel', xlsm: 'Excel', csv: 'Excel', tsv: 'Excel', docx: 'Word', pdf: 'your PDF reader', html: 'your browser', htm: 'your browser' }
1199
1200// ── What the pane shows ──

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { DocRow, Span, Tone } from '../types'
6import { gap, plain, tableRows, tidy, trimSpaces } from './format'
7
8/**
9 * Atlassian Document Format (the JSON Confluence and Jira pages are stored
10 * and published as) read into formatted rows: headings, paragraphs with
11 * their marks, lists, task lists, panels, quotes, code, tables and rules.
12 *
13 * Every row's anchor carries the node's JSON path (`content[3].content[1]`)
14 * and its nearest heading, so a comment tells Claude exactly which node to
15 * edit.
16 */
17
18type AdfMark = { type?: string; attrs?: Record<string, unknown> }
19type AdfNode = {
20  type?: string
21  text?: string
22  attrs?: Record<string, unknown>
23  marks?: AdfMark[]
24  content?: AdfNode[]
25}
26
27/** Whether parsed JSON is an ADF document: `{ type: "doc", content: [...] }`. */
28export function isAdf(value: unknown): value is AdfNode {
29  return typeof value === 'object' && value !== null && (value as AdfNode).type === 'doc' && Array.isArray((value as AdfNode).content)
30}
31
32const str = (value: unknown) => (typeof value === 'string' ? value : value === undefined || value === null ? '' : String(value))
33
34/** Inline content with its marks: text, mentions, emoji, status lozenges, dates, links. */
35function inline(nodes: AdfNode[] | undefined, depth = 0): Span[] {
36  const out: Span[] = []
37  if (depth > MAX_DEPTH) return out
38  for (const node of nodes ?? []) {
39    if (!isNode(node)) continue
40    switch (node.type) {
41      case 'text': {
42        const span: Span = { t: node.text ?? '' }
43        for (const mark of node.marks ?? []) {
44          if (mark.type === 'strong') span.b = 1
45          if (mark.type === 'em') span.i = 1
46          if (mark.type === 'code') span.c = 1
47          if (mark.type === 'link') span.l = 1
48          if (mark.type === 'strike') span.s = 1
49        }
50        out.push(span)
51        break
52      }
53      case 'hardBreak':
54        out.push({ t: ' ' })
55        break
56      case 'mention':
57        out.push({ t: `@${str(node.attrs?.text).replace(/^@/, '') || 'someone'}`, l: 1 })
58        break
59      case 'emoji':
60        out.push({ t: str(node.attrs?.text) || str(node.attrs?.shortName) })
61        break
62      case 'status':
63        out.push({ t: ` ${str(node.attrs?.text).toUpperCase()} `, b: 1, c: 1 })
64        break
65      case 'date': {
66        const ms = Number(node.attrs?.timestamp)
67        out.push({ t: Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : 'date', c: 1 })
68        break
69      }
70      case 'inlineCard':
71        out.push({ t: str(node.attrs?.url) || 'link', l: 1 })
72        break
73      case 'placeholder':
74        out.push({ t: str(node.attrs?.text), d: 1 })
75        break
76      default:
77        // A node this reader does not know: whatever text it holds.
78        if (node.text) out.push({ t: node.text })
79        else if (node.content) out.push(...inline(node.content, depth + 1))
80        else if (typeof node.attrs?.text === 'string') out.push({ t: node.attrs.text, d: 1 })
81    }
82  }
83  return tidy(out)
84}
85
86/** Deeper than this, a page is not worth drawing: it is cut off there. */
87const MAX_DEPTH = 50
88const isNode = (value: unknown): value is AdfNode => typeof value === 'object' && value !== null && !Array.isArray(value)
89const INLINE_TYPES = new Set(['text', 'hardBreak', 'mention', 'emoji', 'status', 'date', 'inlineCard', 'placeholder', 'inlineExtension'])
90
91const TONES: Record<string, Tone> = { info: 'info', note: 'note', warning: 'warning', error: 'error', success: 'success', tip: 'tip' }
92const TONE_TITLE: Record<Tone, string> = { info: 'Info', note: 'Note', warning: 'Warning', error: 'Important', success: 'Success', tip: 'Tip' }
93
94export function adfRows(doc: AdfNode): DocRow[] {
95  const rows: DocRow[] = []
96  let heading: string | null = null
97
98  const where = (path: string) => `${path}${heading ? ` (under "${heading}")` : ''}`
99  const row = (spans: Span[], path: string, extra: Partial<DocRow>) => {
100    rows.push({ text: plain(spans), anchor: where(path), unit: 'node', spans, style: 'p', ...extra })
101  }
102
103  /** Walks a block node; `tone` and `depth` carry a panel's colour and a list's nesting. */
104  const walk = (node: AdfNode, path: string, ctx: { tone?: Tone; depth: number; quote?: boolean }, level = 0) => {
105    if (!isNode(node) || level > MAX_DEPTH) return
106    const kids = (Array.isArray(node.content) ? node.content : []).filter(isNode)
107    const into = (kid: AdfNode, i: number, next: typeof ctx) => walk(kid, `${path}.content[${i}]`, next, level + 1)
108    const styleFor = (): DocRow['style'] => (ctx.tone ? 'panel' : ctx.quote ? 'quote' : 'p')
109    switch (node.type) {
110      case 'heading': {
111        const spans = inline(kids)
112        heading = plain(spans).trim() || heading
113        const level = Number(node.attrs?.level ?? 1)
114        if (!ctx.tone) gap(rows)
115        row(spans, path, { style: ctx.tone ? 'panel' : level <= 1 ? 'h1' : level === 2 ? 'h2' : 'h3', ...(ctx.tone ? { tone: ctx.tone } : {}) })
116        if (level <= 1 && !ctx.tone) rows.push({ text: '', anchor: where(path), unit: 'node', style: 'rule' })
117        return
118      }
119      case 'paragraph': {
120        const spans = inline(kids)
121        if (plain(spans).trim() === '') return
122        if (!ctx.tone && ctx.depth === 0) gap(rows)
123        row(spans, path, { style: styleFor(), ...(ctx.tone ? { tone: ctx.tone } : {}) })
124        return
125      }
126      case 'rule':
127        gap(rows)
128        rows.push({ text: '', anchor: where(path), unit: 'node', style: 'rule' })
129        return
130      case 'codeBlock': {
131        gap(rows)
132        const code = plain(inline(kids))
133        for (const line of code.split('\n')) rows.push({ text: line, anchor: where(path), unit: 'node', style: 'code', spans: [{ t: line || ' ', c: 1 }] })
134        gap(rows)
135        return
136      }
137      case 'blockquote':
138        gap(rows)
139        kids.forEach((kid, i) => into(kid, i, { ...ctx, quote: true }))
140        return
141      case 'panel': {
142        const tone = TONES[str(node.attrs?.panelType)] ?? 'note'
143        gap(rows)
144        row([{ t: TONE_TITLE[tone], b: 1 }], path, { style: 'panel', tone })
145        kids.forEach((kid, i) => into(kid, i, { ...ctx, tone }))
146        gap(rows)
147        return
148      }
149      case 'expand':
150      case 'nestedExpand':
151        gap(rows)
152        row([{ t: `▾ ${str(node.attrs?.title) || 'Details'}`, b: 1 }], path, { style: 'h3' })
153        kids.forEach((kid, i) => into(kid, i, ctx))
154        return
155      case 'bulletList':
156      case 'orderedList':
157      case 'taskList':
158      case 'decisionList': {
159        if (ctx.depth === 0 && !ctx.tone) gap(rows)
160        const start = Number(node.attrs?.order ?? 1) || 1
161        kids.forEach((item, i) => {
162          const itemPath = `${path}.content[${i}]`
163          const marker =
164            node.type === 'orderedList'
165              ? `${start + i}.`
166              : node.type === 'taskList'
167                ? item.attrs?.state === 'DONE'
168                  ? '☑'
169                  : '☐'
170                : node.type === 'decisionList'
171                  ? '◆'
172                  : ['•', '◦', '▪'][ctx.depth % 3] ?? '•'
173          // A task list nested in a task list sits beside its items.
174          if (item.type === 'taskList' || item.type === 'bulletList' || item.type === 'orderedList') {
175            walk(item, itemPath, { ...ctx, depth: ctx.depth + 1 }, level + 1)
176            return
177          }
178          if (item.type === 'taskItem' || item.type === 'decisionItem') {
179            const spans = inline(item.content)
180            row(spans, itemPath, { style: 'li', indent: ctx.depth, marker, ...(item.attrs?.state === 'DONE' ? { spans: spans.map(s => ({ ...s, d: 1 as const })) } : {}) })
181            return
182          }
183          ;(item.content ?? []).filter(isNode).forEach((kid, j) => {
184            const kidPath = `${itemPath}.content[${j}]`
185            if (j === 0 && kid.type === 'paragraph') row(inline(kid.content), kidPath, { style: 'li', indent: ctx.depth, marker })
186            else walk(kid, kidPath, { ...ctx, depth: ctx.depth + 1 }, level + 1)
187          })
188        })
189        return
190      }
191      case 'table': {
192        gap(rows)
193        const kidsOf = (n: AdfNode) => (Array.isArray(n.content) ? n.content : []).filter(isNode)
194        const cells = kids.map(r => kidsOf(r).map(c => tidy(kidsOf(c).flatMap((part, k) => [...(k > 0 ? [{ t: ' ' }] : []), ...inline(part.content ?? [part])]))))
195        const header = kids[0] && kidsOf(kids[0]).every(c => c.type === 'tableHeader') ? 1 : 0
196        rows.push(...tableRows(cells, header, r => where(`${path}.content[${r}]`), 'node'))
197        gap(rows)
198        return
199      }
200      case 'mediaSingle':
201      case 'mediaGroup':
202      case 'media': {
203        const media = node.type === 'media' ? node : kids.find(kid => kid.type === 'media')
204        gap(rows)
205        // The picture itself lives in Confluence, not in the file: said plainly.
206        row([{ t: `▣ image${media?.attrs?.alt ? `: ${str(media.attrs.alt)}` : ''} (stored in Confluence, so it can’t be shown here)`, d: 1 }], path, { style: 'p' })
207        return
208      }
209      case 'extension':
210      case 'bodiedExtension':
211        gap(rows)
212        row([{ t: `⚙ ${str(node.attrs?.extensionKey) || 'macro'}`, d: 1 }], path, { style: 'p' })
213        return
214      case 'blockCard':
215      case 'embedCard':
216        gap(rows)
217        row([{ t: str(node.attrs?.url) || 'link', l: 1 }], path, { style: 'p' })
218        return
219      default: {
220        // A block this reader does not know: its text as a paragraph, or its blocks.
221        if (kids.some(kid => INLINE_TYPES.has(kid.type ?? ''))) {
222          const spans = inline(kids)
223          if (plain(spans).trim() !== '') {
224            gap(rows)
225            row(spans, path, { style: styleFor() })
226          }
227        } else kids.forEach((kid, i) => into(kid, i, ctx))
228      }
229    }
230  }
231
232  ;(doc.content ?? []).forEach((node, i) => walk(node, `content[${i}]`, { depth: 0 }))
233  return trimSpaces(rows)
234}
235

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { ClientKeyEvent, ClientModule } from 'claude-code'
6
7import type { DRow, SegKind } from './layout'
8
9/**
10 * The changes view inside the pane. It draws only the lines in view, which
11 * the hooks module lays out, and turns clicks and keys into posts: the hooks
12 * module owns the view.
13 *
14 * Changes that just arrived glow for a moment, on the view's own clock, so
15 * the eye goes straight to them.
16 */
17
18/** The theme keys the view paints with. */
19export type ChangesPal = { text: string; subtle: string; dim: string; accent: string; h3: string; code: string; error: string; success: string; warning: string; removedBg: string; addedBg: string; glowBg: string }
20
21export type ChangesProps = {
22  pal: ChangesPal
23  rows: DRow[]
24  /** The change the person is on: its lines get a bar at the left. */
25  focus: number | null
26  /** Bumped when new changes arrive; `fresh` are the changes that glow. */
27  flashKey: number
28  fresh: number[]
29  width: number
30  /** The scrollbar: first line in view, lines shown, lines in all. */
31  scroll: { top: number; shown: number; total: number }
32  /** A line under the view: "▼ 40 more lines below". */
33  below?: string
34}
35
36export type ChangesPost =
37  | { type: 'click'; y: number; x: number }
38  | { type: 'key'; key: string; shift?: true }
39
40type Local = { seen: number; glow: number }
41
42const FRAMES = 16
43
44const Changes: ClientModule<ChangesProps, Local> = (props, surface) => {
45  const { Box, Text } = surface.elements
46  const { pal } = props
47  if (surface.state === undefined) {
48    surface.setState({ seen: props.flashKey, glow: props.fresh.length > 0 ? FRAMES : 0 })
49    surface.every(90, () => {
50      const now = surface.state
51      if (now && now.glow > 0) surface.setState({ ...now, glow: now.glow - 1 })
52    })
53  } else if (props.flashKey !== surface.state.seen) {
54    surface.setState({ seen: props.flashKey, glow: FRAMES })
55  }
56  const glow = surface.state?.glow ?? 0
57  const fresh = new Set(props.fresh)
58
59  surface.onPointer(event => {
60    if (event.type !== 'down' || (event.button !== undefined && event.button !== 'left')) return
61    // One column for the focus bar comes first.
62    surface.post({ type: 'click', y: event.y, x: Math.max(0, event.x - 1) })
63  })
64  surface.onKey((event: ClientKeyEvent) => {
65    surface.post(event.shift ? { type: 'key', key: event.key, shift: true } : { type: 'key', key: event.key })
66  })
67
68  const look = (k: SegKind | undefined, isGlowing: boolean) => {
69    switch (k) {
70      case 'del':
71        return { color: pal.text, backgroundColor: pal.removedBg, strikethrough: true }
72      case 'add':
73        return { color: pal.text, backgroundColor: isGlowing ? pal.glowBg : pal.addedBg, underline: true }
74      case 'mdel':
75        return { color: pal.error }
76      case 'madd':
77        return { color: pal.success }
78      case 'mmod':
79        return { color: pal.warning }
80      case 'h1':
81      case 'h2':
82        return { color: pal.accent, bold: true }
83      case 'h3':
84        return { color: pal.h3, bold: true }
85      case 'th':
86        return { color: pal.text, bold: true }
87      case 'quote':
88        return { color: pal.subtle, italic: true }
89      case 'code':
90        return { color: pal.code }
91      case 'li':
92        return { color: pal.accent }
93      case 'num':
94      case 'sep':
95        return { color: pal.dim }
96      case 'head':
97        return { color: pal.dim }
98      case 'fold':
99        return { color: pal.accent, italic: true }
100      case 'dim':
101        return { color: pal.subtle }
102      case 'pic':
103        return { color: pal.warning }
104      case 'sel':
105        return { color: pal.text, inverse: true }
106      default:
107        return { color: pal.text }
108    }
109  }
110
111  const sc = props.scroll
112  const hasBar = sc.total > sc.shown
113  const thumb = hasBar ? Math.max(1, Math.round((props.rows.length * sc.shown) / sc.total)) : 0
114  const thumbAt = hasBar ? Math.round(((props.rows.length - thumb) * sc.top) / Math.max(1, sc.total - sc.shown)) : 0
115  return (
116    <Box flexDirection="column">
117      <Box flexDirection="row">
118        <Box flexDirection="column" width={props.width + 1}>
119          {props.rows.map((row, i) => {
120            const isFocus = row.change !== undefined && row.change === props.focus
121            const isGlowing = glow > 0 && row.change !== undefined && fresh.has(row.change)
122            return (
123              <Text key={`r${i}`} wrap="truncate-end">
124                <Text color={isGlowing ? pal.success : pal.accent}>{isFocus ? '▎' : isGlowing ? '▏' : ' '}</Text>
125                {row.segs.map((seg, k) => (
126                  <Text key={`s${k}`} {...look(seg.k, isGlowing)}>
127                    {seg.t}
128                  </Text>
129                ))}
130              </Text>
131            )
132          })}
133        </Box>
134        {hasBar && (
135          <Box flexDirection="column">
136            {props.rows.map((_, i) => (
137              <Text key={`b${i}`} color={pal.dim}>
138                {i >= thumbAt && i < thumbAt + thumb ? '┃' : ' '}
139              </Text>
140            ))}
141          </Box>
142        )}
143      </Box>
144      {props.below ? (
145        <Text color={pal.subtle} wrap="truncate-end">
146          {'  '}
147          ▾ {props.below}
148        </Text>
149      ) : null}
150    </Box>
151  )
152}
153export default Changes
154

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { DocRow, GridCell, GridSheet } from '../types'
6import { letters } from './csv'
7
8/**
9 * Comparing two versions of a document: pure, no `$`.
10 *
11 * Documents are compared paragraph by paragraph (or line by line), then word
12 * by word inside a changed paragraph. Spreadsheets line up columns first, then
13 * rows, so one row added near the top doesn't make every row below it look
14 * changed; then cell by cell, value and formula.
15 */
16
17// ── Sequences ──
18
19/** One step of an edit script: kept (both sides), removed (before only), added (after only). */
20export type Step = { op: '='; a: number; b: number } | { op: '-'; a: number } | { op: '+'; b: number }
21
22/**
23 * The shortest edit script between two sequences of keys (Myers' algorithm),
24 * with the shared start and end trimmed first. Past `maxEdits` it gives up
25 * and calls the middle all removed then all added; the caller pairs those up.
26 */
27export function editScript(a: readonly string[], b: readonly string[], maxEdits = 2000): Step[] {
28  let start = 0
29  while (start < a.length && start < b.length && a[start] === b[start]) start += 1
30  let endA = a.length
31  let endB = b.length
32  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
33    endA -= 1
34    endB -= 1
35  }
36  const head: Step[] = []
37  for (let k = 0; k < start; k += 1) head.push({ op: '=', a: k, b: k })
38  const tail: Step[] = []
39  for (let k = 0; k < a.length - endA; k += 1) tail.push({ op: '=', a: endA + k, b: endB + k })
40  const n = endA - start
41  const m = endB - start
42  const middle: Step[] = []
43  if (n === 0) for (let j = 0; j < m; j += 1) middle.push({ op: '+', b: start + j })
44  else if (m === 0) for (let i = 0; i < n; i += 1) middle.push({ op: '-', a: start + i })
45  else {
46    // Keys as small numbers, so the inner loop compares integers.
47    const ids = new Map<string, number>()
48    const id = (s: string) => {
49      let v = ids.get(s)
50      if (v === undefined) {
51        v = ids.size
52        ids.set(s, v)
53      }
54      return v
55    }
56    const A = Int32Array.from({ length: n }, (_, i) => id(a[start + i]!))
57    const B = Int32Array.from({ length: m }, (_, j) => id(b[start + j]!))
58    const max = Math.min(n + m, maxEdits)
59    const offset = max + 1
60    const v = new Int32Array(2 * max + 3)
61    const trace: Int32Array[] = []
62    let found = -1
63    for (let d = 0; d <= max && found < 0; d += 1) {
64      trace.push(v.slice(offset - d - 1, offset + d + 2))
65      for (let k = -d; k <= d; k += 2) {
66        let x = k === -d || (k !== d && v[offset + k - 1]! < v[offset + k + 1]!) ? v[offset + k + 1]! : v[offset + k - 1]! + 1
67        let y = x - k
68        while (x < n && y < m && A[x] === B[y]) {
69          x += 1
70          y += 1
71        }
72        v[offset + k] = x
73        if (x >= n && y >= m) {
74          found = d
75          break
76        }
77      }
78    }
79    if (found < 0) {
80      for (let i = 0; i < n; i += 1) middle.push({ op: '-', a: start + i })
81      for (let j = 0; j < m; j += 1) middle.push({ op: '+', b: start + j })
82    } else {
83      // Walk back through the saved frontiers.
84      let x = n
85      let y = m
86      const back: Step[] = []
87      for (let d = found; d > 0; d -= 1) {
88        const frame = trace[d]!
89        const at = (k: number) => frame[k + d + 1]!
90        const k = x - y
91        const prevK = k === -d || (k !== d && at(k - 1) < at(k + 1)) ? k + 1 : k - 1
92        const prevX = at(prevK)
93        const prevY = prevX - prevK
94        while (x > prevX && y > prevY) {
95          x -= 1
96          y -= 1
97          back.push({ op: '=', a: start + x, b: start + y })
98        }
99        if (x === prevX) {
100          y -= 1
101          back.push({ op: '+', b: start + y })
102        } else {
103          x -= 1
104          back.push({ op: '-', a: start + x })
105        }
106      }
107      while (x > 0 && y > 0) {
108        x -= 1
109        y -= 1
110        back.push({ op: '=', a: start + x, b: start + y })
111      }
112      middle.push(...back.reverse())
113    }
114  }
115  return [...head, ...middle, ...tail]
116}
117
118/**
119 * Pairs the removed and added items between two kept ones, when they are the
120 * same item edited: in order, each removed item with the next added item
121 * similar enough. Equal-sized runs pair one to one (an item edited in place)
122 * unless the two are nothing alike.
123 */
124function pairRuns(steps: Step[], similar: (a: number, b: number) => number, threshold: number, loose: number): PairedStep[] {
125  const out: PairedStep[] = []
126  let k = 0
127  while (k < steps.length) {
128    const step = steps[k]!
129    if (step.op === '=') {
130      out.push({ op: '=', a: step.a, b: step.b })
131      k += 1
132      continue
133    }
134    const dels: number[] = []
135    const adds: number[] = []
136    while (k < steps.length && steps[k]!.op !== '=') {
137      const s = steps[k]!
138      if (s.op === '-') dels.push(s.a)
139      else if (s.op === '+') adds.push(s.b)
140      k += 1
141    }
142    const isEven = dels.length === adds.length
143    let j = 0
144    const pending: PairedStep[] = []
145    for (const a of dels) {
146      // Look a few added items ahead for this one's edited copy.
147      let best = -1
148      let bestScore = 0
149      for (let t = j; t < Math.min(adds.length, j + 8); t += 1) {
150        const score = similar(a, adds[t]!)
151        if (score > bestScore) {
152          bestScore = score
153          best = t
154        }
155      }
156      const isPair = best >= 0 && (bestScore >= threshold || (isEven && best === j && bestScore >= loose))
157      if (isPair) {
158        for (; j < best; j += 1) pending.push({ op: '+', b: adds[j]! })
159        pending.push({ op: '~', a, b: adds[best]! })
160        j = best + 1
161      } else pending.push({ op: '-', a })
162    }
163    for (; j < adds.length; j += 1) pending.push({ op: '+', b: adds[j]! })
164    // Removed items read before added ones between two kept items.
165    out.push(...pending)
166  }
167  return out
168}
169
170type PairedStep = Step | { op: '~'; a: number; b: number }
171
172// ── Words ──
173
174/** A run of words: kept (0), removed (-1) or added (1). */
175export type Piece = { t: string; op: 0 | 1 | -1 }
176
177/** Words, numbers with their points and commas (12,000.50, 3.5%), runs of space, and any other character alone: so "78%." is the number and then the full stop. */
178const TOKEN = /\s+|[\p{L}\p{N}_'’$€£%]+(?:[.,\-/:][\p{L}\p{N}_'’$€£%]+)*|[^\s]/gu
179
180export const tokens = (text: string) => text.match(TOKEN) ?? []
181
182/** How alike two texts are, 0 to 1: the share of their words they have in common. */
183export function similarity(a: string, b: string): number {
184  if (a === b) return 1
185  const wa = tokens(a.toLowerCase()).filter(t => t.trim() !== '')
186  const wb = tokens(b.toLowerCase()).filter(t => t.trim() !== '')
187  if (wa.length === 0 || wb.length === 0) return 0
188  const count = new Map<string, number>()
189  for (const w of wa) count.set(w, (count.get(w) ?? 0) + 1)
190  let common = 0
191  for (const w of wb) {
192    const n = count.get(w) ?? 0
193    if (n > 0) {
194      common += 1
195      count.set(w, n - 1)
196    }
197  }
198  return (2 * common) / (wa.length + wb.length)
199}
200
201/**
202 * Word by word: what was removed and added inside a changed paragraph. A
203 * lone space between two changes joins them, so "red fox" becoming "blue
204 * cat" reads as one replacement, not four.
205 */
206export function wordPieces(before: string, after: string): Piece[] {
207  const a = tokens(before)
208  const b = tokens(after)
209  const raw: Piece[] = editScript(a, b, 600).map(s => (s.op === '=' ? { t: a[s.a]!, op: 0 as const } : s.op === '-' ? { t: a[s.a]!, op: -1 as const } : { t: b[s.b]!, op: 1 as const }))
210  // A kept space between changes goes with them.
211  for (let k = 1; k < raw.length - 1; k += 1) {
212    const p = raw[k]!
213    if (p.op === 0 && /^\s+$/.test(p.t) && raw[k - 1]!.op !== 0 && raw[k + 1]!.op !== 0) {
214      raw.splice(k, 1, { t: p.t, op: -1 }, { t: p.t, op: 1 })
215      k += 1
216    }
217  }
218  // Removed then added, never interleaved, within each changed stretch; neighbours of a kind merged.
219  const out: Piece[] = []
220  let k = 0
221  while (k < raw.length) {
222    if (raw[k]!.op === 0) {
223      const last = out[out.length - 1]
224      if (last && last.op === 0) last.t += raw[k]!.t
225      else out.push({ ...raw[k]! })
226      k += 1
227      continue
228    }
229    let del = ''
230    let add = ''
231    while (k < raw.length && raw[k]!.op !== 0) {
232      if (raw[k]!.op === -1) del += raw[k]!.t
233      else add += raw[k]!.t
234      k += 1
235    }
236    if (del) out.push({ t: del, op: -1 })
237    if (add) out.push({ t: add, op: 1 })
238  }
239  return out
240}
241
242// ── Documents ──
243
244/** One row of the comparison: kept, removed, added, or changed (with its words). */
245export type LineOp =
246  | { kind: 'same'; a: number; b: number }
247  | { kind: 'del'; a: number }
248  | { kind: 'add'; b: number }
249  | { kind: 'mod'; a: number; b: number; pieces: Piece[]; restyled?: string }
250
251export type LinesComparison = {
252  kind: 'lines'
253  before: DocRow[]
254  after: DocRow[]
255  ops: LineOp[]
256  /** What a row is called: "paragraph" for formatted documents, "line" for text. */
257  unit: string
258  counts: { changed: number; added: number; removed: number; pictures: { added: number; removed: number } }
259}
260
261const STYLE_NAMES: Record<string, string> = { h1: 'a title', h2: 'a heading', h3: 'a heading', li: 'a list item', quote: 'a quote', code: 'code', th: 'a table header', td: 'a table row', p: 'a paragraph', panel: 'a panel' }
262const rowKey = (r: DocRow) => `${r.style ?? ''}|${r.indent ?? 0}|${r.marker ?? ''}|${r.text}`
263const isBlank = (r: DocRow) => r.style === 'space' || (r.text.trim() === '' && r.pic === undefined && r.style !== 'rule')
264
265export function compareLines(before: DocRow[], after: DocRow[], isFormatted: boolean): LinesComparison {
266  const steps = editScript(before.map(rowKey), after.map(rowKey))
267  const paired = pairRuns(
268    steps,
269    (a, b) => {
270      const x = before[a]!
271      const y = after[b]!
272      if (x.text === y.text) return 1
273      // A picture is the same picture or another one, never an edited one.
274      if (x.pic !== undefined || y.pic !== undefined) return 0
275      const score = similarity(x.text, y.text)
276      // A heading in the same place, at the same level, renamed: still that heading.
277      const isHeading = /^h[123]$/.test(x.style ?? '') && x.style === y.style
278      return isHeading ? Math.max(score, 0.3) : score
279    },
280    0.5,
281    0.2,
282  )
283  const ops: LineOp[] = []
284  const counts = { changed: 0, added: 0, removed: 0, pictures: { added: 0, removed: 0 } }
285  for (const s of paired) {
286    if (s.op === '=') {
287      ops.push({ kind: 'same', a: s.a, b: s.b })
288      continue
289    }
290    if (s.op === '-') {
291      ops.push({ kind: 'del', a: s.a })
292      if (isBlank(before[s.a]!)) continue
293      if (before[s.a]!.pic !== undefined) counts.pictures.removed += 1
294      else counts.removed += 1
295      continue
296    }
297    if (s.op === '+') {
298      ops.push({ kind: 'add', b: s.b })
299      if (isBlank(after[s.b]!)) continue
300      if (after[s.b]!.pic !== undefined) counts.pictures.added += 1
301      else counts.added += 1
302      continue
303    }
304    const x = before[s.a]!
305    const y = after[s.b]!
306    const restyled = (x.style ?? 'p') !== (y.style ?? 'p') || (x.indent ?? 0) !== (y.indent ?? 0) ? `now ${STYLE_NAMES[y.style ?? 'p'] ?? 'restyled'}` : undefined
307    ops.push({ kind: 'mod', a: s.a, b: s.b, pieces: wordPieces(x.text, y.text), ...(restyled ? { restyled } : {}) })
308    counts.changed += 1
309  }
310  return { kind: 'lines', before, after, ops, unit: isFormatted ? 'paragraph' : 'line', counts }
311}
312
313// ── Spreadsheets ──
314
315export type GridOp = { kind: 'same' | 'mod'; a: number; b: number } | { kind: 'del'; a: number } | { kind: 'add'; b: number }
316
317export type SheetComparison = {
318  /** The sheet's name now (or, removed, as it was). */
319  name: string
320  /** Its old name, when renamed. */
321  was?: string
322  status: 'same' | 'changed' | 'added' | 'removed' | 'renamed'
323  before?: GridSheet
324  after?: GridSheet
325  rows: GridOp[]
326  cols: GridOp[]
327  /** Changed cells as "row:col" of `rows` and `cols` indexes, with what changed. */
328  cells: Map<string, { value: boolean; formula: boolean }>
329  counts: { cells: number; formulas: number; rowsAdded: number; rowsRemoved: number; colsAdded: number; colsRemoved: number }
330  merges: { added: string[]; removed: string[] }
331  isCut: boolean
332}
333
334export type GridComparison = { kind: 'grid'; sheets: SheetComparison[] }
335
336const EMPTY: GridCell = { v: '' }
337const cellAt = (sheet: GridSheet | undefined, r: number, c: number): GridCell => sheet?.rows[r]?.[c] ?? EMPTY
338
339const colNumber = (letters: string) => [...letters.toUpperCase()].reduce((n, ch) => n * 26 + ch.charCodeAt(0) - 64, 0)
340const REF = /(^|[^A-Za-z0-9_.'!$])(\$?)([A-Za-z]{1,3})(\$?)(\d+)(?![\d(A-Za-z_])/g
341
342/**
343 * A formula as its shape, wherever the cell is: references made relative to
344 * the cell, as Excel's R1C1 form. A row inserted above moves =SUM(B3:D3) to
345 * =SUM(B4:D4); both are "the three cells to the left", so neither is a change.
346 */
347export function formulaShape(formula: string | undefined, row: number, col: number): string {
348  if (!formula) return ''
349  // Text in quotes is left as it is.
350  return formula
351    .split(/("(?:[^"]|"")*")/)
352    .map((part, k) =>
353      k % 2 === 1
354        ? part
355        : part.replace(REF, (_, lead: string, absCol: string, letters: string, absRow: string, digits: string) => {
356            const c = colNumber(letters) - 1
357            const r = Number(digits) - 1
358            return `${lead}R${absRow ? r : `[${r - row}]`}C${absCol ? c : `[${c - col}]`}`
359          }),
360    )
361    .join('')
362    .toUpperCase()
363}
364
365const cellKey = (c: GridCell, row: number, col: number) => `${c.v}\u0001${formulaShape(c.f, row, col)}`
366
367/** How alike two lists of values are, as multisets: for lining up columns that moved. */
368function multisetSimilarity(a: string[], b: string[]): number {
369  const filled = (list: string[]) => list.filter(v => v !== '\u0001')
370  const x = filled(a)
371  const y = filled(b)
372  if (x.length === 0 && y.length === 0) return 1
373  if (x.length === 0 || y.length === 0) return 0
374  const count = new Map<string, number>()
375  for (const v of x) count.set(v, (count.get(v) ?? 0) + 1)
376  let common = 0
377  for (const v of y) {
378    const n = count.get(v) ?? 0
379    if (n > 0) {
380      common += 1
381      count.set(v, n - 1)
382    }
383  }
384  return (2 * common) / (x.length + y.length)
385}
386
387const widthOf = (sheet: GridSheet | undefined) => Math.max(sheet?.cols.length ?? 0, ...(sheet?.rows.slice(0, 1).map(r => r.length) ?? [0]))
388
389export function compareSheet(before: GridSheet | undefined, after: GridSheet | undefined): SheetComparison {
390  const name = after?.name ?? before?.name ?? ''
391  const rowsA = before?.rows ?? []
392  const rowsB = after?.rows ?? []
393  const nColsA = before ? widthOf(before) : 0
394  const nColsB = after ? widthOf(after) : 0
395  // Columns first, by what they hold top to bottom (the first 2,000 rows say enough).
396  const colValues = (rows: GridCell[][], c: number) => rows.slice(0, 2000).map((row, r) => cellKey(row[c] ?? EMPTY, r, c))
397  const colsA = Array.from({ length: nColsA }, (_, c) => colValues(rowsA, c))
398  const colsB = Array.from({ length: nColsB }, (_, c) => colValues(rowsB, c))
399  const colSteps = editScript(colsA.map(v => v.join('\u0002')), colsB.map(v => v.join('\u0002')), 200)
400  const colPairs = pairRuns(colSteps, (a, b) => multisetSimilarity(colsA[a]!, colsB[b]!), 0.5, 0.3)
401  const cols: GridOp[] = colPairs.map(s => (s.op === '=' || s.op === '~' ? { kind: 'same', a: s.a, b: s.b } : s.op === '-' ? { kind: 'del', a: s.a } : { kind: 'add', b: s.b }))
402  const kept = cols.filter((c): c is Extract<GridOp, { a: number; b: number }> => c.kind === 'same')
403  // Then rows, by the columns both versions have, so a column added doesn't change every row.
404  const rowSig = (row: GridCell[] | undefined, r: number, side: 'a' | 'b') => kept.map(c => cellKey(row?.[side === 'a' ? c.a : c.b] ?? EMPTY, r, side === 'a' ? c.a : c.b)).join('\u0002')
405  const sigA = rowsA.map((row, r) => rowSig(row, r, 'a'))
406  const sigB = rowsB.map((row, r) => rowSig(row, r, 'b'))
407  const rowSteps = editScript(sigA, sigB, 3000)
408  const rowPairs = pairRuns(
409    rowSteps,
410    (a, b) => {
411      let same = 0
412      let filled = 0
413      for (const c of kept) {
414        const x = cellAt(before, a, c.a)
415        const y = cellAt(after, b, c.b)
416        if (x.v === '' && y.v === '' && !x.f && !y.f) continue
417        filled += 1
418        if (cellKey(x, a, c.a) === cellKey(y, b, c.b)) same += 1
419      }
420      return filled === 0 ? 1 : same / filled
421    },
422    0.5,
423    0,
424  )
425  const rows: GridOp[] = []
426  const cells = new Map<string, { value: boolean; formula: boolean }>()
427  const counts = { cells: 0, formulas: 0, rowsAdded: 0, rowsRemoved: 0, colsAdded: 0, colsRemoved: 0 }
428  const isEmptyRow = (row: GridCell[] | undefined) => !row || row.every(c => c.v === '' && !c.f)
429  for (const s of rowPairs) {
430    if (s.op === '-') {
431      rows.push({ kind: 'del', a: s.a })
432      if (!isEmptyRow(rowsA[s.a])) counts.rowsRemoved += 1
433    } else if (s.op === '+') {
434      rows.push({ kind: 'add', b: s.b })
435      if (!isEmptyRow(rowsB[s.b])) counts.rowsAdded += 1
436    } else {
437      const index = rows.length
438      let isChanged = false
439      cols.forEach((c, ci) => {
440        if (c.kind !== 'same') return
441        const x = cellAt(before, s.a, c.a)
442        const y = cellAt(after, s.b, c.b)
443        const value = x.v !== y.v
444        const formula = formulaShape(x.f, s.a, c.a) !== formulaShape(y.f, s.b, c.b)
445        if (!value && !formula) return
446        cells.set(`${index}:${ci}`, { value, formula })
447        counts.cells += 1
448        if (formula) counts.formulas += 1
449        isChanged = true
450      })
451      rows.push({ kind: isChanged ? 'mod' : 'same', a: s.a, b: s.b })
452    }
453  }
454  for (const c of cols) {
455    if (c.kind === 'add' && colsB[c.b]!.some(v => v !== '\u0001')) counts.colsAdded += 1
456    if (c.kind === 'del' && colsA[c.a]!.some(v => v !== '\u0001')) counts.colsRemoved += 1
457  }
458  const mergesA = new Set(before?.merges ?? [])
459  const mergesB = new Set(after?.merges ?? [])
460  const merges = { added: [...mergesB].filter(m => !mergesA.has(m)), removed: [...mergesA].filter(m => !mergesB.has(m)) }
461  const isChanged = counts.cells + counts.rowsAdded + counts.rowsRemoved + counts.colsAdded + counts.colsRemoved + merges.added.length + merges.removed.length > 0
462  return {
463    name,
464    status: !before ? 'added' : !after ? 'removed' : isChanged ? 'changed' : 'same',
465    ...(before ? { before } : {}),
466    ...(after ? { after } : {}),
467    rows,
468    cols,
469    cells,
470    counts,
471    merges,
472    isCut: before?.isCut === true || after?.isCut === true,
473  }
474}
475
476/** How alike two sheets are by their rows: for telling a renamed sheet from a new one. */
477function sheetSimilarity(a: GridSheet, b: GridSheet): number {
478  const sig = (s: GridSheet) => s.rows.slice(0, 500).map((row, r) => row.map((cell, c) => cellKey(cell, r, c)).join('\u0002'))
479  return multisetSimilarity(sig(a), sig(b))
480}
481
482export function compareGrids(before: GridSheet[], after: GridSheet[]): GridComparison {
483  const byName = new Map(before.map(s => [s.name, s]))
484  const used = new Set<string>()
485  const out: SheetComparison[] = []
486  const unmatched = after.filter(s => !byName.has(s.name))
487  const orphans = before.filter(s => !after.some(t => t.name === s.name))
488  const renamedFrom = new Map<string, GridSheet>()
489  for (const fresh of unmatched) {
490    let best: GridSheet | undefined
491    let score = 0
492    for (const old of orphans) {
493      if (used.has(old.name)) continue
494      const sim = sheetSimilarity(old, fresh)
495      if (sim > score) {
496        score = sim
497        best = old
498      }
499    }
500    if (best && score >= 0.5) {
501      used.add(best.name)
502      renamedFrom.set(fresh.name, best)
503    }
504  }
505  for (const sheet of after) {
506    const old = byName.get(sheet.name) ?? renamedFrom.get(sheet.name)
507    const sc = compareSheet(old, sheet)
508    if (old && old.name !== sheet.name) out.push({ ...sc, was: old.name, status: 'renamed' })
509    else out.push(sc)
510  }
511  // Removed sheets go where they were, after the sheet that came before them.
512  for (const [k, sheet] of before.entries()) {
513    if (after.some(s => s.name === sheet.name) || used.has(sheet.name)) continue
514    const removed = compareSheet(sheet, undefined)
515    const prev = before[k - 1]
516    const at = prev ? out.findIndex(s => s.name === prev.name || s.was === prev.name) : -1
517    out.splice(at + 1, 0, removed)
518  }
519  return { kind: 'grid', sheets: out }
520}
521
522/** A cell's address in a version: "B6". */
523export const address = (col: number, row: number) => `${letters(col + 1)}${row + 1}`
524
525// ── The list of changes ──
526
527/** One change the person can step to: where it is, and a line saying what it is. */
528export type Change = {
529  /** For a grid, the sheet's index in the comparison; the row op (and column op) it is at. */
530  sheet?: number
531  op: number
532  col?: number
533  label: string
534  kind: 'changed' | 'added' | 'removed'
535}
536
537const quoteShort = (text: string, most = 40) => {
538  const flat = text.replace(/\s+/g, ' ').trim()
539  return flat.length > most ? `${flat.slice(0, most - 1)}…` : flat
540}
541
542/** Every change, in reading order, each with a one-line label. */
543export function changesOf(cmp: LinesComparison | GridComparison): Change[] {
544  const out: Change[] = []
545  if (cmp.kind === 'lines') {
546    let k = 0
547    while (k < cmp.ops.length) {
548      const op = cmp.ops[k]!
549      if (op.kind === 'same') {
550        k += 1
551        continue
552      }
553      if (op.kind === 'mod') {
554        const row = cmp.after[op.b]!
555        out.push({ op: k, kind: 'changed', label: `Changed: “${quoteShort(row.text)}”${op.restyled ? ` (${op.restyled})` : ''}` })
556        k += 1
557        continue
558      }
559      // A run of removed or added rows is one change.
560      const kind = op.kind
561      const startK = k
562      let n = 0
563      let first = ''
564      let pictures = 0
565      while (k < cmp.ops.length && cmp.ops[k]!.kind === kind) {
566        const o = cmp.ops[k]!
567        const row = o.kind === 'del' ? cmp.before[o.a]! : o.kind === 'add' ? cmp.after[o.b]! : undefined
568        if (row && !isBlank(row)) {
569          if (row.pic !== undefined) pictures += 1
570          else n += 1
571          if (!first) first = row.text
572        }
573        k += 1
574      }
575      if (n === 0 && pictures === 0) continue
576      const what = n > 0 ? (n === 1 ? `“${quoteShort(first)}”` : `${n} ${cmp.unit}s`) : ''
577      const pics = pictures > 0 ? `${pictures} picture${pictures === 1 ? '' : 's'}` : ''
578      out.push({ op: startK, kind: kind === 'add' ? 'added' : 'removed', label: `${kind === 'add' ? 'Added' : 'Removed'}: ${[what, pics].filter(Boolean).join(' and ')}` })
579    }
580    return out
581  }
582  cmp.sheets.forEach((sheet, si) => {
583    if (sheet.status === 'added') {
584      out.push({ sheet: si, op: 0, kind: 'added', label: `Sheet added: ${sheet.name}` })
585      return
586    }
587    if (sheet.status === 'removed') {
588      out.push({ sheet: si, op: 0, kind: 'removed', label: `Sheet removed: ${sheet.name}` })
589      return
590    }
591    if (sheet.status === 'renamed') out.push({ sheet: si, op: 0, kind: 'changed', label: `Sheet renamed: ${sheet.was} → ${sheet.name}` })
592    sheet.cols.forEach((c, ci) => {
593      if (c.kind === 'add') out.push({ sheet: si, op: 0, col: ci, kind: 'added', label: `${sheet.name}: column ${letters(c.b + 1)} added` })
594      if (c.kind === 'del') out.push({ sheet: si, op: 0, col: ci, kind: 'removed', label: `${sheet.name}: column ${letters(c.a + 1)} removed` })
595    })
596    let k = 0
597    while (k < sheet.rows.length) {
598      const op = sheet.rows[k]!
599      if (op.kind === 'del' || op.kind === 'add') {
600        const kind = op.kind
601        const startK = k
602        const firstRow = kind === 'add' ? (op as { b: number }).b : (op as { a: number }).a
603        let n = 0
604        while (k < sheet.rows.length && sheet.rows[k]!.kind === kind) {
605          n += 1
606          k += 1
607        }
608        out.push({
609          sheet: si,
610          op: startK,
611          kind: kind === 'add' ? 'added' : 'removed',
612          label: `${sheet.name}: ${n === 1 ? `row ${firstRow + 1}` : `rows ${firstRow + 1}–${firstRow + n}`} ${kind === 'add' ? 'added' : 'removed'}`,
613        })
614        continue
615      }
616      if (op.kind === 'mod') {
617        sheet.cols.forEach((c, ci) => {
618          const change = sheet.cells.get(`${k}:${ci}`)
619          if (!change || c.kind !== 'same') return
620          const x = cellAt(sheet.before, op.a, c.a)
621          const y = cellAt(sheet.after, op.b, c.b)
622          const where = address(c.b, op.b)
623          const label = change.value
624            ? `${where}: ${quoteShort(x.v || '(empty)', 24)} → ${quoteShort(y.v || '(empty)', 24)}${change.formula ? ' (formula changed)' : ''}`
625            : `${where}: formula changed`
626          out.push({ sheet: si, op: k, col: ci, kind: 'changed', label })
627        })
628      }
629      k += 1
630    }
631    for (const m of sheet.merges.added) out.push({ sheet: si, op: 0, kind: 'changed', label: `${sheet.name}: cells ${m} merged` })
632    for (const m of sheet.merges.removed) out.push({ sheet: si, op: 0, kind: 'changed', label: `${sheet.name}: cells ${m} unmerged` })
633  })
634  return out
635}
636
637const n = (count: number, one: string, many = `${one}s`) => `${count} ${count === 1 ? one : many}`
638
639/** The summary line: "7 changes · 3 cells · 1 row added · 1 sheet removed". */
640export function summaryOf(cmp: LinesComparison | GridComparison, changes: Change[]): string {
641  if (changes.length === 0) return 'No changes'
642  const parts = [n(changes.length, 'change')]
643  if (cmp.kind === 'lines') {
644    const c = cmp.counts
645    if (c.changed) parts.push(`${n(c.changed, cmp.unit)} changed`)
646    if (c.added) parts.push(`${n(c.added, cmp.unit)} added`)
647    if (c.removed) parts.push(`${n(c.removed, cmp.unit)} removed`)
648    if (c.pictures.added) parts.push(`${n(c.pictures.added, 'picture')} added`)
649    if (c.pictures.removed) parts.push(`${n(c.pictures.removed, 'picture')} removed`)
650    return parts.join(' · ')
651  }
652  let cells = 0
653  let rowsAdded = 0
654  let rowsRemoved = 0
655  let colsAdded = 0
656  let colsRemoved = 0
657  let formulas = 0
658  for (const s of cmp.sheets) {
659    if (s.status === 'added' || s.status === 'removed') continue
660    cells += s.counts.cells
661    formulas += s.counts.formulas
662    rowsAdded += s.counts.rowsAdded
663    rowsRemoved += s.counts.rowsRemoved
664    colsAdded += s.counts.colsAdded
665    colsRemoved += s.counts.colsRemoved
666  }
667  if (cells) parts.push(`${n(cells, 'cell')}${formulas ? ` (${n(formulas, 'formula')})` : ''}`)
668  if (rowsAdded) parts.push(`${n(rowsAdded, 'row')} added`)
669  if (rowsRemoved) parts.push(`${n(rowsRemoved, 'row')} removed`)
670  if (colsAdded) parts.push(`${n(colsAdded, 'column')} added`)
671  if (colsRemoved) parts.push(`${n(colsRemoved, 'column')} removed`)
672  const added = cmp.sheets.filter(s => s.status === 'added').length
673  const removed = cmp.sheets.filter(s => s.status === 'removed').length
674  const renamed = cmp.sheets.filter(s => s.status === 'renamed').length
675  if (added) parts.push(`${n(added, 'sheet')} added`)
676  if (removed) parts.push(`${n(removed, 'sheet')} removed`)
677  if (renamed) parts.push(`${n(renamed, 'sheet')} renamed`)
678  return parts.join(' · ')
679}
680

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { GridCell, GridSheet } from '../types'
6
7const MAX_ROWS = 5000
8const MAX_COLS = 60
9const MAX_CELL = 2000
10
11/** Column letters as Excel writes them: 1 is A, 27 is AA. */
12export function letters(n: number): string {
13  let s = ''
14  for (; n > 0; n = Math.floor((n - 1) / 26)) s = String.fromCharCode(65 + ((n - 1) % 26)) + s
15  return s
16}
17
18/** The delimiter a file uses: a tab for .tsv, else whichever of , ; | tab is most common on the first lines. */
19function delimiterOf(text: string, ext: string): string {
20  if (ext === 'tsv') return '\t'
21  const head = text.slice(0, 4000)
22  let best = ','
23  let most = -1
24  for (const d of [',', ';', '\t', '|']) {
25    const n = head.split(d).length
26    if (n > most) {
27      most = n
28      best = d
29    }
30  }
31  return best
32}
33
34/**
35 * A CSV or TSV file as one sheet, quotes handled the RFC 4180 way (a quoted
36 * field may hold the delimiter, a new line, or a doubled quote). Numbers keep
37 * their text as written, with `x` set so they line up on the right.
38 */
39export function readCsv(text: string, ext = 'csv'): { sheet: GridSheet; isCut: boolean } {
40  const d = delimiterOf(text, ext)
41  const rows: string[][] = []
42  let row: string[] = []
43  let field = ''
44  let isQuoted = false
45  let isCut = false
46  let i = 0
47  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
48  const endField = () => {
49    row.push(field.length > MAX_CELL ? `${field.slice(0, MAX_CELL)}…` : field)
50    field = ''
51  }
52  const endRow = () => {
53    endField()
54    rows.push(row)
55    row = []
56  }
57  for (; i < body.length; i += 1) {
58    const ch = body[i]!
59    if (isQuoted) {
60      if (ch === '"') {
61        if (body[i + 1] === '"') {
62          field += '"'
63          i += 1
64        } else isQuoted = false
65      } else field += ch
66    } else if (ch === '"' && field === '') isQuoted = true
67    else if (ch === d) endField()
68    else if (ch === '\n' || ch === '\r') {
69      if (ch === '\r' && body[i + 1] === '\n') i += 1
70      endRow()
71      if (rows.length >= MAX_ROWS) {
72        isCut = i + 1 < body.length
73        break
74      }
75    } else field += ch
76  }
77  if (field !== '' || row.length > 0) endRow()
78  const width = Math.min(MAX_COLS, rows.reduce((n, r) => Math.max(n, r.length), 0))
79  if (rows.some(r => r.length > MAX_COLS)) isCut = true
80  const cells: GridCell[][] = rows.map(r =>
81    Array.from({ length: width }, (_, c) => {
82      const v = (r[c] ?? '').replace(/\t/g, '  ')
83      const n = /^\s*-?\d[\d,]*(\.\d+)?\s*$/.test(v) ? Number(v.replace(/[,\s]/g, '')) : NaN
84      return Number.isFinite(n) ? { v, x: n } : { v }
85    }),
86  )
87  return { sheet: { name: ext === 'tsv' ? 'TSV' : 'CSV', cols: Array.from({ length: width }, (_, k) => letters(k + 1)), rows: cells, ...(isCut ? { isCut: true } : {}) }, isCut }
88}
89

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5/**
6 * One time limit for reading a file, shared by every reader. Each reader has
7 * its own caps too; this is the guard behind them, so a loop a hostile file
8 * drives too long ends in a note ("only part of it is shown") or a plain
9 * message, never in a hook that runs out of time and leaves the pane blank.
10 */
11
12export class TooSlow extends Error {
13  override message = 'it takes too long to read here'
14}
15
16let until = Infinity
17let calls = 0
18let late = false
19
20/** Starts the clock for one read: `ms` from now. */
21export function startReading(ms: number) {
22  until = Date.now() + ms
23  calls = 0
24  late = false
25}
26
27export function stopReading() {
28  until = Infinity
29  late = false
30}
31
32/** Whether the time is up; cheap enough for a hot loop (it looks at the clock once in 512 calls, and stays up once it is). */
33export function isLate(): boolean {
34  if (late) return true
35  calls += 1
36  if ((calls & 511) === 0 && Date.now() > until) late = true
37  return late
38}
39
40/** Throws TooSlow once the time is up. */
41export function checkTime() {
42  if (isLate()) throw new TooSlow()
43}
44

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5/**
6 * Reads a Word document (.docx) for the pane: headings, paragraphs with bold,
7 * italic, strike-through and links, bulleted and numbered lists, tables, and
8 * a placeholder for each picture. Tracked insertions are shown and tracked
9 * deletions are not, as Word shows the document with changes accepted.
10 */
11
12import type { DocRow, Picture, Span } from '../types'
13import { checkTime } from './deadline'
14import { decodePicture } from './picture'
15import { attr, child, descendants, elements, parseTree, textOf } from './xml'
16import type { XmlNode } from './xml'
17import { clean } from './xlsx'
18import { openZip } from './zip'
19
20const MAX_ROWS = 4000
21/** How much of the document's XML is unpacked: 4,000 rows fit well inside it, so a huge document opens as fast as a small one. */
22const DOCUMENT_START_BYTES = 24 * 1024 * 1024
23
24/** A row, or a table row with its cells, which the pane lays out as a table. */
25export type ReadRow = DocRow & { cells?: string[]; isHeader?: boolean }
26export type LinesResult = { kind: 'lines'; rows: ReadRow[]; isFormatted: true; note?: string; pictures?: Picture[] }
27
28/** A picture found in a paragraph: the relationship naming its file (none for a chart or diagram), and what to call it. */
29type Found = { rid?: string; label: string; kind?: string }
30
31/** The pictures in a paragraph, in order: drawings, old-style (VML) pictures, charts and diagrams. Deleted ones and fallback copies are left out. */
32function picturesIn(node: XmlNode, out: Found[] = []): Found[] {
33  for (const c of elements(node)) {
34    if (c.name === 'del' || c.name === 'moveFrom' || c.name === 'Fallback') continue
35    if (c.name === 'drawing') {
36      const doc = descendants(c, 'docPr')[0]
37      const label = (attr(doc?.attrs ?? '', 'descr') || attr(doc?.attrs ?? '', 'title') || '').trim()
38      const blip = descendants(c, 'blip')[0]
39      if (blip) out.push({ rid: attr(blip.attrs, 'embed') ?? '', label })
40      else if (descendants(c, 'chart').length > 0) out.push({ label, kind: 'a Word chart' })
41      else if (descendants(c, 'relIds').length > 0) out.push({ label, kind: 'a SmartArt diagram' })
42      continue
43    }
44    if (c.name === 'pict' || c.name === 'object') {
45      const image = descendants(c, 'imagedata')[0]
46      if (image) out.push({ rid: attr(image.attrs, 'id') ?? '', label: (attr(image.attrs, 'title') ?? '').trim() })
47      continue
48    }
49    picturesIn(c, out)
50  }
51  return out
52}
53
54/** Word's built-in style names as python-docx (and Word's own menus) show them. */
55const UI_NAMES: Record<string, string> = {
56  caption: 'Caption',
57  footer: 'Footer',
58  header: 'Header',
59  ...Object.fromEntries(Array.from({ length: 9 }, (_, k) => [`heading ${k + 1}`, `Heading ${k + 1}`])),
60}
61
62/** Whether a run property such as <w:b/> is on (it is, unless its val says 0 or false). */
63const isOn = (props: XmlNode | undefined, name: string) => {
64  const el = child(props, name)
65  if (!el) return false
66  const val = attr(el.attrs, 'val')
67  return val !== '0' && val !== 'false'
68}
69
70/** A paragraph's runs as spans; deleted text is left out, links marked. */
71function spansOf(paragraph: XmlNode): Span[] {
72  const spans: Span[] = []
73  const walk = (node: XmlNode, isLink: boolean) => {
74    for (const c of elements(node)) {
75      // Deleted text is not shown; of Word's two forms of a drawing (mc:Choice and mc:Fallback), only the first is read.
76      if (c.name === 'del' || c.name === 'moveFrom' || c.name === 'Fallback') continue
77      if (c.name === 'r') {
78        const text = textInRun(c)
79        if (!text) continue
80        const props = child(c, 'rPr')
81        const span: Span = { t: clean(text) }
82        if (isOn(props, 'b')) span.b = 1
83        if (isOn(props, 'i')) span.i = 1
84        if (isOn(props, 'strike')) span.s = 1
85        if (isLink) span.l = 1
86        spans.push(span)
87      } else if (c.name !== 'pPr') {
88        walk(c, isLink || c.name === 'hyperlink')
89      }
90    }
91  }
92  walk(paragraph, false)
93  return spans
94}
95
96/** A run's text, with any text box inside it read once (not its fallback copy). */
97function textInRun(node: XmlNode): string {
98  let out = ''
99  for (const c of elements(node)) {
100    if (c.name === 'Fallback' || c.name === 'delText') continue
101    out += c.name === 't' ? textOf(c) : textInRun(c)
102  }
103  return out
104}
105
106/** A table cell's text as python-docx gives it: its own paragraphs, words separated by single spaces. */
107function cellText(tc: XmlNode): string {
108  const parts: string[] = []
109  const runText = (r: XmlNode) => {
110    for (const c of elements(r)) {
111      if (c.name === 't') parts.push(textOf(c))
112      else if (c.name === 'tab' || c.name === 'ptab') parts.push('\t')
113      else if (c.name === 'br' || c.name === 'cr') parts.push('\n')
114      else if (c.name === 'noBreakHyphen') parts.push('-')
115    }
116  }
117  for (const p of elements(tc, 'p')) {
118    if (picturesIn(p).length > 0) parts.push(' [picture] ')
119    for (const c of elements(p)) {
120      if (c.name === 'r') runText(c)
121      else if (c.name === 'hyperlink' || c.name === 'ins') elements(c, 'r').forEach(runText)
122    }
123    parts.push('\n')
124  }
125  return clean(parts.join('').split(/\s+/).filter(Boolean).join(' '))
126}
127
128/** The body's paragraphs and tables in order, looking inside content controls. */
129function blocksOf(node: XmlNode, out: XmlNode[] = []): XmlNode[] {
130  for (const c of elements(node)) {
131    if (c.name === 'sdt') {
132      const content = child(c, 'sdtContent')
133      if (content) blocksOf(content, out)
134    } else if (c.name === 'p' || c.name === 'tbl') {
135      out.push(c)
136    }
137  }
138  return out
139}
140
141export function readDocx(bytes: Uint8Array): LinesResult {
142  const zip = openZip(bytes)
143  const start = zip.textStart('word/document.xml', DOCUMENT_START_BYTES)
144  if (start === null) throw new Error('it is not a Word document')
145  const body = child(child(parseTree(start.text), 'document'), 'body')
146  if (!body) throw new Error('it is not a Word document')
147  const blocks = blocksOf(body)
148
149  // Where each picture's file is: word/media/…, by relationship id.
150  const media = new Map<string, string>()
151  const relsXml = zip.side('word/_rels/document.xml.rels')
152  if (relsXml) {
153    for (const rel of descendants(parseTree(relsXml), 'Relationship')) {
154      const target = attr(rel.attrs, 'Target') ?? ''
155      if (attr(rel.attrs, 'TargetMode') === 'External') continue
156      media.set(attr(rel.attrs, 'Id') ?? '', target.startsWith('/') ? target.slice(1) : `word/${target}`.replace(/\/[^/]+\/\.\.\//g, '/'))
157    }
158  }
159  const pictures: Picture[] = []
160  const addPicture = (found: Found): number => {
161    const part = found.rid ? media.get(found.rid) : undefined
162    pictures.push({
163      label: clean(found.label).slice(0, 200),
164      load: () => {
165        if (found.kind) return `it is ${found.kind}, which the pane can’t draw`
166        const bytes = part ? zip.read(part) : null
167        return bytes ? decodePicture(bytes) : 'it is linked from outside the document, so it isn’t in the file'
168      },
169    })
170    return pictures.length - 1
171  }
172  // Read from its start only, the last block may be cut off part-way: it is left out.
173  if (start.isCut) blocks.pop()
174
175  // Style names by id, and the default paragraph style.
176  const styleNames = new Map<string, string>()
177  let defaultStyle = ''
178  const stylesXml = zip.side('word/styles.xml')
179  if (stylesXml) {
180    for (const style of descendants(parseTree(stylesXml), 'style')) {
181      if (attr(style.attrs, 'type') !== 'paragraph') continue
182      const raw = attr(child(style, 'name')?.attrs ?? '', 'val') ?? ''
183      const name = UI_NAMES[raw] ?? raw
184      const id = attr(style.attrs, 'styleId') ?? ''
185      styleNames.set(id, name)
186      if (['1', 'true'].includes(attr(style.attrs, 'default') ?? '')) defaultStyle = name
187    }
188  }
189
190  // List formats: numId → abstractNum → per level, whether it is numbered (not a bullet).
191  const numbered = new Map<string, Map<number, boolean>>()
192  const numberingXml = zip.side('word/numbering.xml')
193  if (numberingXml) {
194    const tree = parseTree(numberingXml)
195    const abstract = new Map<string, Map<number, boolean>>()
196    for (const a of descendants(tree, 'abstractNum')) {
197      const levels = new Map<number, boolean>()
198      for (const lvl of elements(a, 'lvl')) {
199        const fmt = attr(child(lvl, 'numFmt')?.attrs ?? '', 'val')
200        levels.set(Number(attr(lvl.attrs, 'ilvl') ?? 0), fmt !== undefined && fmt !== 'bullet' && fmt !== 'none')
201      }
202      abstract.set(attr(a.attrs, 'abstractNumId') ?? '', levels)
203    }
204    for (const num of descendants(tree, 'num')) {
205      const levels = abstract.get(attr(child(num, 'abstractNumId')?.attrs ?? '', 'val') ?? '')
206      if (levels) numbered.set(attr(num.attrs, 'numId') ?? '', levels)
207    }
208  }
209
210  const rows: ReadRow[] = []
211  let heading: string | null = null
212  let paragraphIndex = 0
213  let tableIndex = 0
214  let numbers = new Map<number, number>()
215  let hasTitle = false
216  let isCut = start.isCut
217  const space = () => {
218    const last = rows[rows.length - 1]
219    if (last && last.style !== 'space') rows.push({ text: '', anchor: last.anchor, style: 'space', unit: last.unit ?? 'paragraph' })
220  }
221
222  for (const block of blocks) {
223    checkTime()
224    if (rows.length >= MAX_ROWS) {
225      isCut = true
226      break
227    }
228    if (block.name === 'p') {
229      paragraphIndex += 1
230      const spans = spansOf(block)
231      const text = spans.map(s => s.t).join('').trim()
232      const found = picturesIn(block)
233      // Each picture gets a row of its own, after the paragraph's text: selecting it shows it.
234      const pictureRows = () => {
235        for (const one of found) {
236          const pic = addPicture(one)
237          const name = `Picture ${pic + 1}${one.label ? `: ${clean(one.label).slice(0, 200)}` : ''}`
238          const under = heading ? ` (under "${heading}")` : ''
239          space()
240          rows.push({ text: `[${name}]`, anchor: `paragraph ${paragraphIndex}, picture ${pic + 1}${under}`, unit: 'paragraph', style: 'p', pic, spans: [{ t: `▣ ${name}`, d: 1 }] })
241        }
242      }
243      if (!text) {
244        pictureRows()
245        continue
246      }
247      const pPr = child(block, 'pPr')
248      const styleId = attr(child(pPr, 'pStyle')?.attrs ?? '', 'val')
249      const style = (styleId !== undefined ? styleNames.get(styleId) : undefined) ?? defaultStyle
250      // A document with a Title uses it as the top level; its Heading 1s sit one below.
251      hasTitle ||= style === 'Title'
252      const digits = /(\d+)/.exec(style)
253      const level = style === 'Title' ? 1 : style.startsWith('Heading') ? Math.min(3, (digits ? Number(digits[1]) : 3) + (hasTitle ? 1 : 0)) : 0
254      const under = heading && !level ? ` (under "${heading}")` : ''
255      const row: DocRow = { text, anchor: `paragraph ${paragraphIndex}${under}`, unit: 'paragraph', spans }
256      let kind: [number, boolean] | null = null
257      const numPr = child(pPr, 'numPr')
258      if (numPr) {
259        const depth = Number(attr(child(numPr, 'ilvl')?.attrs ?? '', 'val') ?? 0) || 0
260        const numId = attr(child(numPr, 'numId')?.attrs ?? '', 'val') ?? ''
261        kind = [depth, numbered.get(numId)?.get(depth) ?? false]
262      } else if (style.includes('List')) {
263        const depthMatch = /(\d+)$/.exec(style)
264        kind = [depthMatch ? Math.max(0, Number(depthMatch[1]) - 1) : 0, style.includes('Number')]
265      }
266      if (level) {
267        heading = text
268        numbers = new Map()
269        space()
270        row.style = `h${level}` as DocRow['style']
271        rows.push(row)
272        if (level === 1) rows.push({ text: '', anchor: row.anchor, style: 'rule', unit: 'paragraph' })
273      } else if (kind) {
274        const [depth, isNumbered] = kind
275        for (const deeper of [...numbers.keys()].filter(d => d > depth)) numbers.delete(deeper)
276        const last = rows[rows.length - 1]
277        if (last && last.style !== 'li' && last.style !== 'space') space()
278        if (isNumbered) numbers.set(depth, (numbers.get(depth) ?? 0) + 1)
279        Object.assign(row, { style: 'li', indent: depth, marker: isNumbered ? `${numbers.get(depth)}.` : ['•', '◦', '▪'][depth % 3] })
280        rows.push(row)
281      } else {
282        numbers = new Map()
283        space()
284        row.style = style.includes('Quote') ? 'quote' : 'p'
285        rows.push(row)
286      }
287      pictureRows()
288    } else {
289      tableIndex += 1
290      numbers = new Map()
291      space()
292      // Each row's cells; a vertically merged cell repeats the text of the one above it, as python-docx gives it.
293      const above: (XmlNode | undefined)[] = []
294      elements(block, 'tr').forEach((tr, r) => {
295        const cells: string[] = []
296        let gridCol = 0
297        for (const tc of elements(tr, 'tc')) {
298          const props = child(tc, 'tcPr')
299          // Word's own limit is 63 columns: a larger span is a damaged (or hostile) file.
300          const span = Math.min(64, Math.max(1, Number(attr(child(props, 'gridSpan')?.attrs ?? '', 'val') ?? 1) || 1))
301          if (gridCol > 4096) break
302          const vMerge = child(props, 'vMerge')
303          const isContinue = vMerge !== undefined && (attr(vMerge.attrs, 'val') ?? 'continue') === 'continue'
304          const source = isContinue ? (above[gridCol] ?? tc) : tc
305          for (let k = 0; k < span; k += 1) above[gridCol + k] = source
306          gridCol += span
307          cells.push(cellText(source))
308        }
309        rows.push({ text: cells.join(' | '), cells, isHeader: r === 0, anchor: `table ${tableIndex}, row ${r + 1}`, unit: 'table row' })
310      })
311      space()
312    }
313  }
314  while (rows.length > 0 && rows[rows.length - 1]!.style === 'space') rows.pop()
315  const doc: LinesResult = { kind: 'lines', rows, isFormatted: true, ...(pictures.length > 0 ? { pictures } : {}) }
316  if (isCut) doc.note = rows.length >= MAX_ROWS ? `Only the first ${MAX_ROWS} rows of this document are shown.` : 'This document is very long: only its first part is shown.'
317  return doc
318}
319

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { Doc } from '../types'
6
7/**
8 * Document families, pure: budget.xlsx, budget_v2.xlsx, budget_final.xlsx
9 * and "budget (1).xlsx" are all one document. A new file is matched to the
10 * document it came from by its type, its folder, its name and what it holds.
11 */
12
13/** File types that are the same kind of document: a .htm can be a new version of a .html. */
14export const KINDS: Record<string, string> = {
15  xlsx: 'excel',
16  xlsm: 'excel',
17  docx: 'word',
18  pdf: 'pdf',
19  md: 'markdown',
20  markdown: 'markdown',
21  html: 'html',
22  htm: 'html',
23  csv: 'table',
24  tsv: 'table',
25  txt: 'text',
26  adf: 'confluence',
27}
28
29export const TRACKED = Object.keys(KINDS)
30
31export const extOf = (path: string) => (path.match(/\.([^./]+)$/)?.[1] ?? '').toLowerCase()
32export const kindOf = (path: string) => KINDS[extOf(path)]
33export const nameOf = (path: string) => path.split('/').pop() ?? path
34export const folderOf = (path: string) => path.slice(0, Math.max(0, path.lastIndexOf('/')))
35
36/** The words people and tools add to a copy's name: v2, final, updated, (1), copy, a date… */
37const SUFFIX =
38  /(?:[\s_.-]*(?:\(\d+\)|\[\d+\]|copy(?:\s*\d+)?|v\s?\d+(?:\.\d+)*|ver(?:sion)?\s?\d+|r(?:ev(?:ision)?)?\s?\d+|final|updated?|new|revised|rev|edited|edit|draft|latest|clean|fixed|amended|corrected|redline|proposed|claude|ai|\d{4}[-_.]?\d{2}[-_.]?\d{2}|\d{1,2}[-_.]\d{1,2}[-_.]\d{2,4}|\d+))+$/i
39const PREFIX = /^(?:copy of|new|updated|final|draft)[\s_.-]+/i
40
41/** A name with its type and its copy words taken off, lower case: "Budget_v2 (1).xlsx" is "budget". */
42export function stemOf(path: string): string {
43  let stem = nameOf(path).replace(/\.[^.]+$/, '').toLowerCase()
44  for (let k = 0; k < 4; k += 1) {
45    const next = stem.replace(SUFFIX, '').replace(PREFIX, '').trim()
46    if (next === stem || next === '') break
47    stem = next
48  }
49  return stem.replace(/[\s_.-]+/g, ' ').trim()
50}
51
52/** Edit distance, for names that are close but not the same stem (budget vs budgte). */
53function distance(a: string, b: string): number {
54  if (a === b) return 0
55  const prev = Array.from({ length: b.length + 1 }, (_, j) => j)
56  for (let i = 1; i <= a.length; i += 1) {
57    let diag = prev[0]!
58    prev[0] = i
59    for (let j = 1; j <= b.length; j += 1) {
60      const tmp = prev[j]!
61      prev[j] = Math.min(prev[j]! + 1, prev[j - 1]! + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1))
62      diag = tmp
63    }
64  }
65  return prev[b.length]!
66}
67
68/** How alike two file names are as names of one document, 0 to 1. */
69export function nameScore(a: string, b: string): number {
70  const x = stemOf(a)
71  const y = stemOf(b)
72  if (x === '' || y === '') return 0
73  if (x === y) return 1
74  // One name holds the other whole: "budget" and "budget for board".
75  if (x.length >= 4 && y.length >= 4 && (x.startsWith(y) || y.startsWith(x))) return 0.75
76  const d = distance(x, y)
77  return Math.max(0, 1 - d / Math.max(x.length, y.length))
78}
79
80/** What a version holds, in a few dozen words: sheet names and headings, then its first words. For telling which document a new file came from. */
81export function fingerprintOf(d: Doc): string[] {
82  const words = new Set<string>()
83  const add = (text: string, most: number) => {
84    for (const w of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
85      if (words.size >= most) return
86      if (w.length >= 3) words.add(w)
87    }
88  }
89  if (d.kind === 'grid') {
90    for (const s of d.sheets) add(`sheet ${s.name}`, 40)
91    for (const s of d.sheets.slice(0, 3)) for (const row of s.rows.slice(0, 12)) add(row.filter(c => c.x === undefined).map(c => c.v).join(' '), 80)
92  } else if (d.kind === 'lines') {
93    for (const r of d.rows) if (r.style === 'h1' || r.style === 'h2' || r.style === 'h3') add(r.text, 40)
94    for (const r of d.rows.slice(0, 200)) add(r.text, 80)
95  }
96  return [...words]
97}
98
99/** How alike two fingerprints are, 0 to 1. */
100export function contentScore(a: readonly string[] | undefined, b: readonly string[] | undefined): number {
101  if (!a || !b || a.length === 0 || b.length === 0) return 0
102  const set = new Set(a)
103  let common = 0
104  for (const w of b) if (set.has(w)) common += 1
105  return common / Math.min(a.length, b.length)
106}
107
108export type Candidate = { family: string; path: string; fingerprint?: string[] }
109export type Match = { family: string; path: string; score: number; isSameName: boolean }
110
111/**
112 * The document a new file most likely came from, and how sure that is:
113 * `sure` joins it, `unsure` asks the person once, `none` is a new document.
114 * Same kind of file only; the same folder counts for a little.
115 */
116export function matchParent(path: string, fingerprint: string[] | undefined, candidates: Candidate[]): { verdict: 'sure' | 'unsure' | 'none'; best?: Match; others: Match[] } {
117  const kind = kindOf(path)
118  const scored: Match[] = []
119  for (const c of candidates) {
120    if (c.path === path || kindOf(c.path) !== kind) continue
121    const name = nameScore(path, c.path)
122    const content = contentScore(fingerprint, c.fingerprint)
123    const folder = folderOf(c.path) === folderOf(path) ? 1 : 0
124    // A name that matches says the most; what it holds confirms it or makes up for a renamed copy.
125    const score = 0.55 * name + 0.35 * content + 0.1 * folder
126    if (score >= 0.35) scored.push({ family: c.family, path: c.path, score, isSameName: name === 1 && folder === 1 })
127  }
128  scored.sort((x, y) => y.score - x.score)
129  // One match per family: its closest file.
130  const seen = new Set<string>()
131  const ranked = scored.filter(m => (seen.has(m.family) ? false : (seen.add(m.family), true)))
132  const best = ranked[0]
133  const second = ranked[1]
134  if (!best) return { verdict: 'none', others: [] }
135  const margin = best.score - (second?.score ?? 0)
136  // The same name in the same folder is enough on its own, even when the file can't be read.
137  const isOnlySameName = best.isSameName && !ranked.slice(1).some(m => m.isSameName)
138  const sure = isOnlySameName || (best.score >= 0.72 && margin >= 0.12)
139  return { verdict: sure ? 'sure' : best.score >= 0.5 ? 'unsure' : 'none', best, others: ranked.slice(1, 4) }
140}
141

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { ClientModule } from 'claude-code'
6
7import { cutTo, strWidth } from './text'
8
9/**
10 * The top bar: the open file's name, a ▾ that drops down the list of every
11 * open file, a dim detail (how many changes, when, by whom), and a ‹ n/N ›
12 * stepper at the right. One line until the list is open.
13 *
14 * Click ▾ (or press ↓ / Enter on the bar) to open the list; click a file or
15 * use ↑ ↓ and Enter to jump to it. ← → step through the files in order.
16 */
17
18export type FileBarProps = {
19  files: { name: string; color: string }[]
20  active: number
21  colors: { accent: string; text: string; subtle: string; dim: string; band: string }
22  badge?: { label: string; bg: string; fg: string }
23  /** Dim words after the name: "13 changes · 6.54am → 7.11am by Claude". */
24  detail?: string
25  /** The pane's width in columns. */
26  width: number
27  /** Switches at the right; `short` is shown when the pane is too narrow for `label`. */
28  asides?: { id: string; label: string; short: string; color: string; isBold?: boolean }[]
29}
30
31type Local = { isOpen: boolean; hover: number }
32
33const FileBar: ClientModule<FileBarProps, Local> = (input, surface) => {
34  const { Box, Text } = surface.elements
35  const files = input.files
36  const active = Math.min(Math.max(0, input.active), Math.max(0, files.length - 1))
37  const c = input.colors
38  const width = Math.max(30, input.width)
39  const counter = files.length > 1 ? `‹ ${active + 1}/${files.length} ›` : ''
40  const badgeText = input.badge ? ` ${input.badge.label} ` : ''
41  // On a narrow pane the switches shrink to their icons before the name gives way.
42  const full = input.asides ?? []
43  const roomy = strWidth(badgeText) + 2 + 16 + 4 + counter.length + 2 + strWidth(full.map(a => a.label).join('   ')) <= width
44  const asides = full.map(a => ({ ...a, label: roomy ? a.label : a.short }))
45  const local = surface.state ?? { isOpen: false, hover: active }
46
47  const go = (index: number) => {
48    surface.setState({ isOpen: false, hover: index })
49    if (index !== active) surface.post({ type: 'tab', group: 'files', index })
50  }
51  const step = (delta: number) => {
52    if (files.length < 2) return
53    go((active + delta + files.length) % files.length)
54  }
55
56  // Layout of the bar line, for clicks: badge, name, ▾, the detail, then ‹ n/N › and any switches at the right.
57  const asideText = asides.map(a => a.label).join('   ')
58  const right = [counter, asideText].filter(Boolean).join('   ')
59  // The name gives way to the stepper; the detail gives way to the name.
60  const name = cutTo(files[active]?.name ?? '', Math.max(6, width - strWidth(badgeText) - 2 - 4 - strWidth(right) - 2))
61  const nameAt = badgeText.length + (badgeText ? 2 : 0)
62  const caretAt = nameAt + strWidth(name)
63  const detailAt = caretAt + (files.length > 1 ? 3 : 0) + 3
64  // The detail drops whole parts from the end ("by Claude", then the times) before it's cut.
65  const room = Math.max(0, width - detailAt - strWidth(right) - 2)
66  const parts = (input.detail ?? '').split(' · ')
67  while (parts.length > 1 && strWidth(parts.join(' · ')) > room) parts.pop()
68  const detail = cutTo(parts.join(' · '), room)
69  const counterAt = Math.max(detailAt + strWidth(detail) + 2, width - strWidth(right))
70  const asideAt = counterAt + counter.length + (counter ? 3 : 0)
71
72  surface.onPointer(event => {
73    if (event.type !== 'down') return
74    if (event.y === 0) {
75      if (event.x >= asideAt && asides.length > 0) {
76        let ax = asideAt
77        for (const aside of asides) {
78          if (event.x < ax + strWidth(aside.label) + 3) {
79            surface.post({ type: 'aside', id: aside.id })
80            return
81          }
82          ax += strWidth(aside.label) + 3
83        }
84        return
85      }
86      if (counter && event.x >= counterAt && event.x < counterAt + 2) return step(-1)
87      if (counter && event.x >= counterAt + counter.length - 2 && event.x < counterAt + counter.length) return step(1)
88      if (files.length > 1 && event.x >= nameAt && event.x < detailAt) {
89        surface.setState({ isOpen: !local.isOpen, hover: active })
90      }
91      return
92    }
93    // A click on the open list picks that file.
94    const index = event.y - 1
95    if (local.isOpen && index >= 0 && index < files.length) go(index)
96  })
97
98  surface.onKey(event => {
99    const k = event.key
100    if (k === 'left') return step(-1)
101    if (k === 'right') return step(1)
102    if (!local.isOpen) {
103      if ((k === 'down' || k === 'return') && files.length > 1) surface.setState({ isOpen: true, hover: active })
104      return
105    }
106    if (k === 'up') surface.setState({ ...local, hover: (local.hover - 1 + files.length) % files.length })
107    else if (k === 'down') surface.setState({ ...local, hover: (local.hover + 1) % files.length })
108    else if (k === 'return') go(local.hover)
109    else if (k === 'backspace' || k === 'delete') surface.setState({ ...local, isOpen: false })
110  })
111
112  const used = detailAt + strWidth(detail)
113  return (
114    <Box flexDirection="column">
115      <Box flexDirection="row">
116        {input.badge && (
117          <Text>
118            <Text backgroundColor={input.badge.bg} color={input.badge.fg} bold>
119              {badgeText}
120            </Text>
121            <Text>{'  '}</Text>
122          </Text>
123        )}
124        <Text bold color={c.text}>
125          {name}
126        </Text>
127        <Text color={c.subtle}>{files.length > 1 ? (local.isOpen ? ' ▴ ' : ' ▾ ') : ''}</Text>
128        <Text color={c.subtle}>{`   ${detail}`}</Text>
129        {right !== '' && <Text>{' '.repeat(Math.max(2, counterAt - used))}</Text>}
130        {counter !== '' && <Text color={c.subtle}>{counter}</Text>}
131        {asides.map((aside, i) => (
132          <Text key={`a${i}`} color={aside.color} bold={aside.isBold}>
133            {i === 0 && counter ? '   ' : ''}
134            {aside.label}
135            {i < asides.length - 1 ? '   ' : ''}
136          </Text>
137        ))}
138      </Box>
139      {local.isOpen &&
140        files.map((file, i) => {
141          const isHover = i === local.hover
142          const isActive = i === active
143          const shown = cutTo(file.name, Math.min(width, 60) - 14)
144          return (
145            <Box key={`f${i}`} flexDirection="row">
146              <Text backgroundColor={isHover ? c.band || undefined : undefined} inverse={isHover && !c.band}>
147                <Text color={c.accent} bold>{isHover ? ' ▸ ' : '   '}</Text>
148                <Text color={file.color}>▪ </Text>
149                <Text color={isActive ? c.text : c.subtle} bold={isActive}>
150                  {shown}
151                </Text>
152                <Text color={c.dim}>{isActive ? '  (open)' : ''}</Text>
153                <Text>{' '.repeat(Math.max(1, Math.min(width, 60) - strWidth(shown) - 13))}</Text>
154                <Text color={c.dim}>{String(i + 1).padStart(2)}</Text>
155                <Text>{' '}</Text>
156              </Text>
157            </Box>
158          )
159        })}
160      {local.isOpen && (
161        <Text color={c.dim}>   ↑↓ choose · Enter open · ← → previous / next · click ▴ to close</Text>
162      )}
163    </Box>
164  )
165}
166
167export default FileBar
168

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5/**
6 * A content key for a file: two independent 32-bit hashes of its base64 text
7 * and its length, so two files share a key only when they are the same bytes.
8 * Used to store each version's content once, never for security.
9 */
10export function contentKey(text: string): string {
11  let h1 = 0xdeadbeef ^ text.length
12  let h2 = 0x41c6ce57 ^ text.length
13  for (let i = 0; i < text.length; i += 1) {
14    const ch = text.charCodeAt(i)
15    h1 = Math.imul(h1 ^ ch, 2654435761)
16    h2 = Math.imul(h2 ^ ch, 1597334677)
17  }
18  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909)
19  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909)
20  const hex = (n: number) => (n >>> 0).toString(16).padStart(8, '0')
21  return `${hex(h1)}${hex(h2)}${text.length.toString(36)}`
22}
23
24/** A short key for a string (a folder, a row's text): 8 hex digits. */
25export function shortKey(text: string): string {
26  let h = 0x811c9dc5
27  for (let i = 0; i < text.length; i += 1) h = Math.imul(h ^ text.charCodeAt(i), 16777619)
28  return (h >>> 0).toString(16).padStart(8, '0')
29}
30

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { DocRow, Span, Tone } from '../types'
6import { gap, plain, squash, tableRows, trimSpaces } from './format'
7
8/**
9 * HTML read into formatted rows: what a reader of the page sees (headings,
10 * paragraphs, lists, tables, quotes, code), with styles, scripts and the
11 * head left out. Anchors name the element and its source line
12 * (`<h1> at line 15`, `<p> #2 at line 15` for the second on that line),
13 * which is what Claude edits.
14 */
15
16const ENTITIES: Record<string, string> = {
17  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', copy: '©', reg: '®', trade: '™',
18  rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“', laquo: '«', raquo: '»', bull: '•', middot: '·', deg: '°', plusmn: '±',
19  times: '×', divide: '÷', minus: '−', le: '≤', ge: '≥', ne: '≠', larr: '←', rarr: '→', uarr: '↑', darr: '↓', harr: '↔',
20  euro: '€', pound: '£', yen: '¥', cent: '¢', sect: '§', para: '¶', frac12: '½', frac14: '¼', frac34: '¾', check: '✓', hearts: '♥',
21}
22
23const REPLACEMENT = String.fromCharCode(0xfffd)
24const fromCode = (code: number) => {
25  try {
26    return String.fromCodePoint(code)
27  } catch {
28    return REPLACEMENT
29  }
30}
31const decode = (text: string) =>
32  text.replace(/&(#x[0-9a-f]{1,8}|#\d{1,9}|\w{1,32});/gi, (whole, code: string) =>
33    code[0] !== '#' ? (ENTITIES[code.toLowerCase()] ?? whole) : fromCode(code[1] === 'x' || code[1] === 'X' ? parseInt(code.slice(2), 16) : Number(code.slice(1))),
34  )
35
36const BLOCKS = new Set(['p', 'div', 'section', 'article', 'header', 'footer', 'main', 'nav', 'aside', 'li', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'tr', 'table', 'ul', 'ol', 'hr', 'figure', 'figcaption', 'dt', 'dd', 'form', 'label', 'button', 'details', 'summary'])
37const HIDDEN = /^(script|style|head|title|template|svg|noscript)$/
38
39/** A tag (its attributes may quote a ">"), a declaration, text, or a lone "<". */
40const TOKEN = /<(\/?)([a-zA-Z][\w-]*)((?:[^>"']|"[^"]{0,2000}"|'[^']{0,2000}'){0,400})\/?>|<[!?][^>]{0,2000}>|([^<]+)|(<)/g
41
42type Open = { tag: string; attrs: string }
43
44/**
45 * Pictures written into the page (src="data:image/…") can be megabytes
46 * long: each is set aside, in one pass, and its attribute holds a short
47 * name for it (its line breaks kept, so line numbers stay right).
48 */
49function setAsideData(source: string, out: string[]): string {
50  const parts: string[] = []
51  let at = 0
52  for (;;) {
53    const found = source.indexOf('data:image/', at)
54    if (found < 0) break
55    const quote = source[found - 1]
56    if (quote !== '"' && quote !== "'") {
57      parts.push(source.slice(at, found + 11))
58      at = found + 11
59      continue
60    }
61    const end = source.indexOf(quote, found)
62    if (end < 0) break
63    const value = source.slice(found, end)
64    parts.push(source.slice(at, found), `lpp-data:${out.push(value) - 1}`, '\n'.repeat((value.match(/\n/g) ?? []).length))
65    at = end
66  }
67  parts.push(source.slice(at))
68  return parts.join('')
69}
70
71export function htmlRows(source: string): DocRow[] {
72  const data: string[] = []
73  const html = setAsideData(source, data).replace(/<!--[\s\S]*?-->/g, m => m.replace(/[^\n]/g, ' '))
74  const lower = html.toLowerCase()
75  // Where each line starts, for a binary search from an offset to its line.
76  const starts = [0]
77  for (let at = html.indexOf('\n'); at >= 0; at = html.indexOf('\n', at + 1)) starts.push(at + 1)
78  const lineAt = (offset: number) => {
79    let lo = 0
80    let hi = starts.length - 1
81    while (lo < hi) {
82      const mid = (lo + hi + 1) >> 1
83      if ((starts[mid] ?? 0) <= offset) lo = mid
84      else hi = mid - 1
85    }
86    return lo + 1
87  }
88
89  const rows: DocRow[] = []
90  let heading: string | null = null
91  let spans: Span[] = []
92  let blockTag = 'p'
93  let blockLine = 1
94  let tone: Tone | undefined
95  const stack: Open[] = []
96  const lists: { ordered: boolean; n: number }[] = []
97  let table: { cells: Span[][][]; header: number; isFirstRowTh: boolean; line: number; rowLines: number[] } | null = null
98  let cell: Span[] | null = null
99  let span = 1
100  /** Elements of one tag already named on one line: the second is "#2". */
101  const named = new Map<string, number>()
102
103  const where = (tag: string, line: number) => {
104    const key = `${tag}@${line}`
105    const n = (named.get(key) ?? 0) + 1
106    named.set(key, n)
107    return `<${tag}>${n > 1 ? ` #${n}` : ''} at line ${line}${heading ? ` (under "${heading}")` : ''}`
108  }
109  const styleNow = (): Omit<Span, 't'> => {
110    const style: Omit<Span, 't'> = {}
111    for (const open of stack) {
112      if (/^(b|strong|th)$/.test(open.tag)) style.b = 1
113      if (/^(i|em|cite)$/.test(open.tag)) style.i = 1
114      if (/^(code|kbd|samp|pre)$/.test(open.tag)) style.c = 1
115      if (open.tag === 'a') style.l = 1
116      if (/^(s|del|strike)$/.test(open.tag)) style.s = 1
117    }
118    return style
119  }
120  let pictureCount = 0
121  const flush = () => {
122    const isPre = blockTag === 'pre'
123    const content = isPre ? spans : squash(spans)
124    spans = []
125    if (plain(content).trim() === '') return
126    if (isPre) {
127      gap(rows)
128      for (const [k, line] of plain(content).replace(/^\n/, '').split('\n').entries()) {
129        rows.push({ text: line, anchor: where('pre', blockLine + k), style: 'code', unit: 'element', spans: [{ t: line || ' ', c: 1 }] })
130      }
131      gap(rows)
132      return
133    }
134    const level = /^h[1-6]$/.test(blockTag) ? Number(blockTag[1]) : 0
135    if (level > 0) {
136      heading = plain(content).trim()
137      gap(rows)
138      const anchor = where(blockTag, blockLine)
139      rows.push({ text: heading, anchor, style: level === 1 ? 'h1' : level === 2 ? 'h2' : 'h3', unit: 'element', spans: content })
140      if (level === 1) rows.push({ text: '', anchor, style: 'rule', unit: 'element' })
141      return
142    }
143    if (blockTag === 'li') {
144      const list = lists[lists.length - 1]
145      const marker = list?.ordered ? `${list.n}.` : '•'
146      const previous = rows[rows.length - 1]
147      if (previous && previous.style !== 'li' && previous.style !== 'space') gap(rows)
148      rows.push({ text: plain(content), anchor: where('li', blockLine), style: 'li', unit: 'element', spans: content, indent: Math.max(0, lists.length - 1), marker })
149      return
150    }
151    gap(rows)
152    const anchor = where(blockTag, blockLine)
153    if (tone) rows.push({ text: plain(content), anchor, style: 'panel', unit: 'element', spans: content, tone })
154    else rows.push({ text: plain(content), anchor, style: blockTag === 'blockquote' ? 'quote' : 'p', unit: 'element', spans: content })
155  }
156
157  const body = /<body[\s>]/.exec(lower)
158  TOKEN.lastIndex = body ? body.index : 0
159  let skip: string | null = null
160
161  for (let match = TOKEN.exec(html); match; match = TOKEN.exec(html)) {
162    const [whole, closing, rawTag, attrs = '', text, lone] = match
163    if (text !== undefined || lone !== undefined) {
164      if (skip) continue
165      const piece = { ...styleNow(), t: decode(text ?? '<') }
166      if (cell) cell.push(piece)
167      else spans.push(piece)
168      continue
169    }
170    if (rawTag === undefined) continue
171    const tag = rawTag.toLowerCase()
172    if (skip) {
173      if (closing && tag === skip) skip = null
174      continue
175    }
176    // Hidden content: only when it is closed, so an unclosed <head> does not hide the page.
177    if (!closing && HIDDEN.test(tag) && !whole.endsWith('/>') && lower.indexOf(`</${tag}`, TOKEN.lastIndex) >= 0) {
178      skip = tag
179      continue
180    }
181    if (!closing && (tag === 'head' || tag === 'title')) continue
182    const line = lineAt(match.index)
183    if (tag === 'br') {
184      if (cell) cell.push({ t: ' ' })
185      else {
186        flush()
187        blockLine = line
188      }
189      continue
190    }
191    if (tag === 'img' && !closing) {
192      const alt = decode(attrs.match(/alt\s*=\s*"([^"]*)"/i)?.[1] ?? attrs.match(/alt\s*=\s*'([^']*)'/i)?.[1] ?? '').trim()
193      const written = (attrs.match(/src\s*=\s*"([^"]*)"/i)?.[1] ?? attrs.match(/src\s*=\s*'([^']*)'/i)?.[1] ?? '').trim()
194      const src = /^lpp-data:\d+$/.test(written) ? (data[Number(written.slice(9))] ?? '') : decode(written)
195      if (cell) {
196        cell.push({ t: `▣ ${alt || 'picture'}`, d: 1 })
197        continue
198      }
199      // A picture is a row of its own, where selecting it shows it: the text before it is its own row.
200      flush()
201      pictureCount += 1
202      const name = `Picture ${pictureCount}${alt ? `: ${alt.slice(0, 200)}` : ''}`
203      gap(rows)
204      rows.push({ text: `[${name}]`, anchor: `${where('img', line)}, picture ${pictureCount}`, style: 'p', unit: 'element', pic: pictureCount - 1, src, spans: [{ t: `▣ ${name}`, d: 1 }] })
205      continue
206    }
207    if (tag === 'hr' && !closing) {
208      flush()
209      gap(rows)
210      rows.push({ text: '', anchor: where('hr', line), style: 'rule', unit: 'element' })
211      continue
212    }
213
214    if (table && /^(td|th)$/.test(tag)) {
215      if (!closing) {
216        cell = []
217        span = Math.min(10, Math.max(1, Number(attrs.match(/colspan\s*=\s*["']?(\d+)/i)?.[1] ?? 1)))
218        if (tag === 'th' && table.cells.length === 1) table.isFirstRowTh = true
219        stack.push({ tag, attrs })
220      } else {
221        const last = table.cells[table.cells.length - 1]
222        if (last && cell) {
223          last.push(squash(cell))
224          // A cell across several columns: the ones it covers stay blank, so later cells keep their headers.
225          for (let k = 1; k < span; k += 1) last.push([])
226        }
227        cell = null
228        span = 1
229        if (stack[stack.length - 1]?.tag === tag) stack.pop()
230      }
231      continue
232    }
233    if (table && tag === 'tr') {
234      if (!closing) {
235        table.cells.push([])
236        table.rowLines.push(line)
237      }
238      continue
239    }
240    if (tag === 'thead' && table) {
241      if (closing) table.header = table.cells.length
242      continue
243    }
244    if (tag === 'table') {
245      if (!closing) {
246        flush()
247        table = { cells: [], header: 0, isFirstRowTh: false, line, rowLines: [] }
248      } else if (table) {
249        const t = table
250        const header = t.header || (t.isFirstRowTh ? 1 : 0)
251        gap(rows)
252        rows.push(...tableRows(t.cells.filter(row => row.length > 0), header, r => where('tr', t.rowLines[r] ?? t.line), 'element'))
253        gap(rows)
254        table = null
255      }
256      continue
257    }
258
259    if (BLOCKS.has(tag)) {
260      flush()
261      if (tag === 'ul' || tag === 'ol') {
262        if (!closing) lists.push({ ordered: tag === 'ol', n: 0 })
263        else lists.pop()
264      }
265      if (!closing && tag === 'li') {
266        const list = lists[lists.length - 1]
267        if (list) list.n += 1
268      }
269      if (!closing && /class\s*=\s*["'][^"']*\b(info|note|warning|error|success|tip|alert|callout)\b/i.test(attrs)) {
270        const kind = attrs.match(/\b(info|note|warning|error|success|tip)\b/i)?.[1]?.toLowerCase()
271        tone = (kind as Tone | undefined) ?? 'note'
272      } else if (closing && tone && /^(div|aside|section)$/.test(tag)) tone = undefined
273      blockTag = closing ? 'p' : tag
274      blockLine = line
275      continue
276    }
277
278    // Inline tags left open pile up on a broken page: only the newest hundred count.
279    if (!closing) stack.push({ tag, attrs }) > 100 && stack.shift()
280    else {
281      const at = stack.map(open => open.tag).lastIndexOf(tag)
282      if (at >= 0) stack.splice(at, 1)
283    }
284  }
285  flush()
286
287  return trimSpaces(rows)
288}
289

1// Copyright (c) 2026 Parag Pandya. MIT License, see LICENSE.
2// Claude Code Track Changes: https://github.com/paragpandyareal/claude-code-track-changes
3// Based on Lazy Panda Panel: https://github.com/paragpandyareal/lazy-panda-panel
4
5import type { DocRow, GridCell } from '../types'
6import type { Change, GridOp, LinesComparison, Piece, SheetComparison } from './compare'
7import { letters } from './csv'
8import { cutTo, strWidth } from './text'
9
10/**
11 * A comparison laid out as the lines the pane shows, at a width: inline
12 * (one column, removed above added) or side by side (before | after). Pure.
13 *
14 * Every change carries a mark as well as a colour, for people who can't tell
15 * red from green: removed is struck through with −, added is underlined with
16 * +, changed has ~.
17 */
18
19/** How a run of text is drawn. */
20export type SegKind = 'n' | 'del' | 'add' | 'mdel' | 'madd' | 'mmod' | 'dim' | 'h1' | 'h2' | 'h3' | 'quote' | 'code' | 'num' | 'head' | 'fold' | 'sep' | 'li' | 'th' | 'sel' | 'pic'
21
22export type Seg = { t: string; k?: SegKind }
23
24/** A cell's place on a grid line, for clicks: columns `x` to `x + w`. */
25export type CellSpot = { x: number; w: number; key: string }
26
27export type DRow = {
28  segs: Seg[]
29  /** The change this line belongs to, for the focus mark and the glow. */
30  change?: number
31  /** A fold of unchanged lines: its id, clicked to open. */
32  fold?: string
33  cells?: CellSpot[]
34}
35
36export type Laid = { rows: DRow[]; changeAt: number[] }
37
38const CONTEXT = 2
39
40const pad = (text: string, width: number) => {
41  const cut = cutTo(text, width)
42  return cut + ' '.repeat(Math.max(0, width - strWidth(cut)))
43}
44
45/** Wraps runs of text to `width` cells, breaking at spaces where it can; each line starts with `lead`. */
46export function wrapSegs(segs: Seg[], width: number, lead: Seg[] = [], cont: Seg[] = lead.map(s => ({ ...s, t: ' '.repeat(strWidth(s.t)) }))): Seg[][] {
47  const leadW = lead.reduce((n, s) => n + strWidth(s.t), 0)
48  const room = Math.max(4, width - leadW)
49  const lines: Seg[][] = []
50  let line: Seg[] = []
51  let used = 0
52  const push = (t: string, k: SegKind | undefined) => {
53    const last = line[line.length - 1]
54    if (last && last.k === k) last.t += t
55    else line.push(k ? { t, k } : { t })
56    used += strWidth(t)
57  }
58  const flush = () => {
59    lines.push([...(lines.length === 0 ? lead : cont), ...line])
60    line = []
61    used = 0
62  }
63  for (const seg of segs) {
64    const words = seg.t.match(/\s+|\S+/g) ?? []
65    for (let word of words) {
66      while (strWidth(word) > room) {
67        // A word longer than the line is broken.
68        if (used > 0) flush()
69        const head = cutTo(word, room)
70        push(head, seg.k)
71        flush()
72        word = word.slice(head.length)
73      }
74      if (used + strWidth(word) > room) {
75        if (/^\s+$/.test(word)) {
76          // A space at the end of a line still shows when it is a change.
77          if (seg.k === 'del' || seg.k === 'add') push(cutTo(word, Math.max(0, room - used)), seg.k)
78          flush()
79          continue
80        }
81        flush()
82      }
83      push(word, seg.k)
84    }
85  }
86  if (line.length > 0 || lines.length === 0) flush()
87  return lines
88}
89
90// ── Documents ──
91
92const STYLE_KIND: Partial<Record<string, SegKind>> = { h1: 'h1', h2: 'h2', h3: 'h3', quote: 'quote', code: 'code', th: 'th' }
93
94/** A row's own look, for its kept text. */
95function rowLead(row: DocRow): Seg[] {
96  if (row.style === 'li') return [{ t: `${'  '.repeat(row.indent ?? 0)}${row.marker ?? '•'} `, k: 'li' }]
97  if (row.style === 'quote') return [{ t: '▎ ', k: 'quote' }]
98  if (row.style === 'h2') return [{ t: '▍ ', k: 'h2' }]
99  return []
100}
101
102const keptKind = (row: DocRow): SegKind => STYLE_KIND[row.style ?? ''] ?? (row.pic !== undefined ? 'pic' : 'n')
103
104const pictureText = (row: DocRow) => (row.pic !== undefined ? `▣ ${row.text.replace(/^\[|\]$/g, '') || 'Picture'}` : row.text)
105
106/** One document row as runs, kept, removed or added as a whole. */
107function rowSegs(row: DocRow, as: 'n' | 'del' | 'add'): Seg[] {
108  const text = pictureText(row)
109  const lead = rowLead(row)
110  if (as === 'n') return [...lead, { t: text === '' ? ' ' : text, k: keptKind(row) }]
111  return [...lead.map(s => ({ ...s, k: as })), { t: text === '' ? ' ' : text, k: as }]
112}
113
114function pieceSegs(pieces: Piece[], side: 'both' | 'before' | 'after', base: SegKind): Seg[] {
115  const out: Seg[] = []
116  pieces.forEach((p, k) => {
117    if (p.op === 0) out.push({ t: p.t, k: base })
118    else if (p.op === -1 && side !== 'after') {
119      out.push({ t: p.t, k: 'del' })
120      // A space between the old words and the new, so "3" then "10" never reads as "310".
121      if (side === 'both' && pieces[k + 1]?.op === 1) out.push({ t: ' ' })
122    } else if (p.op === 1 && side !== 'before') out.push({ t: p.t, k: 'add' })
123  })
124  return out.length > 0 ? out : [{ t: ' ' }]
125}
126
127const MARK: Record<'del' | 'add' | 'mod' | 'same', Seg> = {
128  del: { t: '− ', k: 'mdel' },
129  add: { t: '+ ', k: 'madd' },
130  mod: { t: '~ ', k: 'mmod' },
131  same: { t: '  ' },
132}
133
134const isQuiet = (row: DocRow | undefined) => !row || row.style === 'space' || (row.text.trim() === '' && row.pic === undefined)
135
136/** The ops shown, with long runs of kept rows folded into one line unless opened. */
137function foldRuns<T extends { kind: string }>(ops: T[], open: ReadonlySet<string>, prefix: string, isQuietOp: (op: T) => boolean = () => false): ({ op: T; at: number } | { fold: string; count: number; at: number })[] {
138  const out: ({ op: T; at: number } | { fold: string; count: number; at: number })[] = []
139  let k = 0
140  const hasChanges = ops.some(o => o.kind !== 'same')
141  while (k < ops.length) {
142    if (ops[k]!.kind !== 'same') {
143      out.push({ op: ops[k]!, at: k })
144      k += 1
145      continue
146    }
147    let end = k
148    while (end < ops.length && ops[end]!.kind === 'same') end += 1
149    const first = k === 0
150    const last = end === ops.length
151    const keepHead = first ? 0 : CONTEXT
152    const keepTail = last ? 0 : CONTEXT
153    const id = `${prefix}${k}`
154    const hidden = end - k - keepHead - keepTail
155    // Blank lines between paragraphs aren't counted as paragraphs.
156    let count = 0
157    for (let j = k + keepHead; j < end - keepTail; j += 1) if (!isQuietOp(ops[j]!)) count += 1
158    if (!hasChanges || hidden < 3 || count < 2 || open.has(id)) {
159      for (let j = k; j < end; j += 1) out.push({ op: ops[j]!, at: j })
160    } else {
161      for (let j = k; j < k + keepHead; j += 1) out.push({ op: ops[j]!, at: j })
162      out.push({ fold: id, count, at: k + keepHead })
163      for (let j = end - keepTail; j < end; j += 1) out.push({ op: ops[j]!, at: j })
164    }
165    k = end
166  }
167  return out
168}
169
170const plural = (n: number, one: string) => `${n.toLocaleString('en')} ${one}${n === 1 ? '' : 's'}`
171
172function foldRow(id: string, count: number, unit: string, width: number): DRow {
173  const text = `··· ${plural(count, `unchanged ${unit}`)} · click to show ···`
174  return { segs: [{ t: pad(`  ${text}`, width), k: 'fold' }], fold: id }
175}
176
177export function layoutLines(cmp: LinesComparison, changes: Change[], opts: { width: number; mode: 'inline' | 'side'; open: ReadonlySet<string> }): Laid {
178  const width = Math.max(20, opts.width)
179  const rows: DRow[] = []
180  const changeOfOp = new Map<number, number>()
181  changes.forEach((c, i) => changeOfOp.set(c.op, i))
182  const changeAt: number[] = changes.map(() => 0)
183  // A run of added or removed rows is one change: each row of it carries that change.
184  let current: number | undefined
185  const shown = foldRuns(cmp.ops, opts.open, 'L', op => op.kind === 'same' && isQuiet(cmp.after[op.b]))
186  for (const item of shown) {
187    if ('fold' in item) {
188      current = undefined
189      rows.push(foldRow(item.fold, item.count, cmp.unit, width))
190      continue
191    }
192    const { op, at } = item
193    const starts = changeOfOp.get(at)
194    if (starts !== undefined) {
195      current = starts
196      changeAt[starts] = rows.length
197    } else if (op.kind === 'same' || op.kind === 'mod') current = undefined
198    const change = op.kind === 'same' ? undefined : current
199    if (opts.mode === 'inline') {
200      let lines: Seg[][]
201      if (op.kind === 'same') {
202        const row = cmp.after[op.b]!
203        lines = wrapSegs(rowSegs(row, 'n'), width, [MARK.same])
204      } else if (op.kind === 'del') lines = wrapSegs(rowSegs(cmp.before[op.a]!, 'del'), width, [MARK.del])
205      else if (op.kind === 'add') lines = wrapSegs(rowSegs(cmp.after[op.b]!, 'add'), width, [MARK.add])
206      else {
207        const row = cmp.after[op.b]!
208        lines = wrapSegs([...rowLead(row), ...pieceSegs(op.pieces, 'both', keptKind(row))], width, [MARK.mod])
209        if (op.restyled) lines.push([{ t: '  ' }, { t: `(${op.restyled})`, k: 'dim' }])
210      }
211      // A blank line between paragraphs is just a gap, kept or not, never a change of its own.
212      if ((op.kind === 'same' && isQuiet(cmp.after[op.b])) || (op.kind === 'del' && isQuiet(cmp.before[op.a])) || (op.kind === 'add' && isQuiet(cmp.after[op.b]))) {
213        if (op.kind !== 'del' && !rows[rows.length - 1]?.segs.every(s => s.t.trim() === '')) rows.push({ segs: [{ t: ' ' }] })
214        continue
215      }
216      for (const segs of lines) rows.push({ segs, ...(change !== undefined ? { change } : {}) })
217      continue
218    }
219    // Side by side: before on the left, after on the right, line for line.
220    const half = Math.max(8, Math.floor((width - 3) / 2))
221    let left: Seg[][]
222    let right: Seg[][]
223    if (op.kind === 'same') {
224      left = wrapSegs(rowSegs(cmp.before[op.a]!, 'n'), half, [MARK.same])
225      right = wrapSegs(rowSegs(cmp.after[op.b]!, 'n'), half, [MARK.same])
226    } else if (op.kind === 'del') {
227      left = wrapSegs(rowSegs(cmp.before[op.a]!, 'del'), half, [MARK.del])
228      right = [[]]
229    } else if (op.kind === 'add') {
230      left = [[]]
231      right = wrapSegs(rowSegs(cmp.after[op.b]!, 'add'), half, [MARK.add])
232    } else {
233      left = wrapSegs([...rowLead(cmp.before[op.a]!), ...pieceSegs(op.pieces, 'before', keptKind(cmp.before[op.a]!))], half, [MARK.mod])
234      right = wrapSegs([...rowLead(cmp.after[op.b]!), ...pieceSegs(op.pieces, 'after', keptKind(cmp.after[op.b]!))], half, [MARK.mod])
235    }
236    const height = Math.max(left.length, right.length)
237    for (let k = 0; k < height; k += 1) {
238      const l = left[k] ?? []
239      const used = l.reduce((n, s) => n + strWidth(s.t), 0)
240      rows.push({ segs: [...l, { t: ' '.repeat(Math.max(0, half - used)) }, { t: ' │ ', k: 'sep' }, ...(right[k] ?? [])], ...(change !== undefined ? { change } : {}) })
241    }
242  }
243  return { rows, changeAt }
244}
245
246// ── Spreadsheets ──
247
248const EMPTY: GridCell = { v: '' }
249const MAX_CELL = 22
250const MIN_CELL = 3
251
252type Col = { op: GridOp; letter: string; index: number }
253
254/** The columns as shown: every column of either version, in order, each with its letter. */
255function columnsOf(sheet: SheetComparison): Col[] {
256  return sheet.cols.map((op, index) => ({ op, index, letter: letters((op.kind === 'del' ? op.a : op.b) + 1) }))
257}
258
259function cellOf(sheet: SheetComparison, side: 'a' | 'b', row: number | undefined, col: GridOp): GridCell {
260  if (row === undefined) return EMPTY
261  if (side === 'a') return col.kind === 'add' ? EMPTY : (sheet.before?.rows[row]?.[col.a] ?? EMPTY)
262  return col.kind === 'del' ? EMPTY : (sheet.after?.rows[row]?.[col.b] ?? EMPTY)
263}
264
265/** A cell's look in a row: kept, removed, added, or changed (old struck through, then new). */
266function cellSegs(sheet: SheetComparison, rowOp: GridOp, rowIndex: number, col: Col, side: 'both' | 'before' | 'after'): { segs: Seg[]; changed: boolean } {
267  const a = 'a' in rowOp ? rowOp.a : undefined
268  const b = 'b' in rowOp ? rowOp.b : undefined
269  const before = cellOf(sheet, 'a', rowOp.kind === 'add' ? undefined : a, col.op)
270  const after = cellOf(sheet, 'b', rowOp.kind === 'del' ? undefined : b, col.op)
271  if (rowOp.kind === 'del' || col.op.kind === 'del') return { segs: side === 'after' ? [] : before.v ? [{ t: before.v, k: 'del' }] : [], changed: before.v !== '' }
272  if (rowOp.kind === 'add' || col.op.kind === 'add') return { segs: side === 'before' ? [] : after.v ? [{ t: after.v, k: 'add' }] : [], changed: after.v !== '' }
273  const change = sheet.cells.get(`${rowIndex}:${col.index}`)
274  if (!change) {
275    const shown = side === 'before' ? before : after
276    return { segs: shown.v ? [{ t: shown.v, k: 'n' }] : [], changed: false }
277  }
278  if (!change.value) {
279    // The value is the same but its formula changed: marked, so it isn't missed.
280    const shown = side === 'before' ? before : after
281    return { segs: [{ t: 'ƒ', k: 'mmod' }, { t: shown.v || ' ', k: 'n' }], changed: true }
282  }
283  if (side === 'before') return { segs: [{ t: before.v || '(empty)', k: 'del' }], changed: true }
284  if (side === 'after') return { segs: [{ t: after.v || '(empty)', k: 'add' }], changed: true }
285  // Inline, the cell holds the new value only, so the columns stay readable; the old one is in the change line.
286  return { segs: [{ t: after.v || '(empty)', k: 'add' }], changed: true }
287}
288
289const segWidth = (segs: Seg[]) => segs.reduce((n, s) => n + strWidth(s.t), 0)
290
291/** Cuts a cell's runs to `width`, the old value first, so the new one stays readable. */
292function fitCell(segs: Seg[], width: number, isNumber: boolean): Seg[] {
293  const total = segWidth(segs)
294  if (total <= width) {
295    const gap = { t: ' '.repeat(width - total) }
296    return isNumber ? [gap, ...segs] : [...segs, gap]
297  }
298  const out = segs.map(s => ({ ...s }))
299  let over = total - width
300  for (const s of out) {
301    if (over <= 0) break
302    if (s.k !== 'del' && out.length > 1) continue
303    const keep = Math.max(1, strWidth(s.t) - over - 1)
304    const cut = `${cutTo(s.t, keep)}…`
305    over -= strWidth(s.t) - strWidth(cut)
306    s.t = cut
307  }
308  if (over > 0) {
309    const flat: Seg[] = []
310    let room = width
311    for (const s of out) {
312      if (room <= 0) break
313      const t = strWidth(s.t) > room ? `${cutTo(s.t, Math.max(0, room - 1))}…` : s.t
314      flat.push({ ...s, t })
315      room -= strWidth(t)
316    }
317    return flat
318  }
319  return [...out, { t: ' '.repeat(Math.max(0, width - segWidth(out))) }]
320}
321
322export type GridLaid = Laid & { moreLeft: number; moreRight: number; shownCols: number[] }
323
324export function layoutGrid(sheet: SheetComparison, sheetIndex: number, changes: Change[], opts: { width: number; mode: 'inline' | 'side'; open: ReadonlySet<string>; left: number; picked: string | null }): GridLaid {
325  const cols = columnsOf(sheet)
326  const rowsShown = foldRuns(sheet.rows, opts.open, `G${sheetIndex}:`)
327  const side = opts.mode === 'side'
328  const lastRow = Math.max(sheet.before?.rows.length ?? 0, sheet.after?.rows.length ?? 0)
329  const gutter = Math.max(3, String(lastRow).length)
330  const lead = gutter + 3
331  // Column widths from what they show, within limits.
332  const widths = cols.map(col => {
333    let w = Math.max(MIN_CELL, col.letter.length)
334    for (const item of rowsShown.slice(0, 400)) {
335      if ('fold' in item) continue
336      const segs = side
337        ? [cellSegs(sheet, item.op, item.at, col, 'before').segs, cellSegs(sheet, item.op, item.at, col, 'after').segs]
338        : [cellSegs(sheet, item.op, item.at, col, 'both').segs]
339      for (const s of segs) w = Math.max(w, segWidth(s))
340    }
341    return Math.min(side ? 14 : MAX_CELL, w)
342  })
343  const halfWidth = side ? Math.floor((opts.width - 3) / 2) : opts.width
344  // As many columns as fit, from the first one in view; the first column (the row labels) stays, as a frozen column in Excel.
345  const left = Math.max(0, Math.min(opts.left, cols.length - 1))
346  const shownCols: number[] = []
347  let used = lead
348  if (left > 0 && cols.length > 1) {
349    shownCols.push(0)
350    used += (widths[0] ?? MIN_CELL) + 2
351  }
352  for (let c = left === 0 ? 0 : Math.max(1, left); c < cols.length; c += 1) {
353    const need = (widths[c] ?? MIN_CELL) + 2
354    if (used + need > halfWidth && shownCols.length > 0) break
355    shownCols.push(c)
356    used += need
357  }
358  const moreLeft = left > 1 ? left - 1 : 0
359  const moreRight = Math.max(0, cols.length - 1 - (shownCols[shownCols.length - 1] ?? 0))
360  const changeAt: number[] = changes.map(() => 0)
361  const rows: DRow[] = []
362  // Column letters: a removed column's letter struck through, an added one's underlined.
363  const header = (which: 'both' | 'before' | 'after'): { segs: Seg[]; cells: CellSpot[] } => {
364    const segs: Seg[] = [{ t: pad(moreLeft > 0 ? `◀${moreLeft}` : '', gutter + 1), k: 'head' }, { t: '  ', k: 'head' }]
365    for (const c of shownCols) {
366      const col = cols[c]!
367      const w = widths[c]!
368      const isGone = col.op.kind === 'del'
369      const isNew = col.op.kind === 'add'
370      const hide = (which === 'after' && isGone) || (which === 'before' && isNew)
371      const mark = hide ? '' : isGone ? '−' : isNew ? '+' : ''
372      segs.push({ t: pad(hide ? '' : `${mark}${col.letter}`, w), k: hide ? 'head' : isGone ? 'del' : isNew ? 'add' : 'head' }, { t: '  ', k: 'head' })
373    }
374    return { segs, cells: [] }
375  }
376  const sheetChanges = changes.map((c, i) => ({ c, i })).filter(x => x.c.sheet === sheetIndex)
377  for (const { c, i } of sheetChanges) if (c.op === 0 && c.col === undefined) changeAt[i] = 0
378  if (side) {
379    const l = header('before')
380    const r = header('after')
381    rows.push({ segs: [...l.segs.map(s => ({ ...s, t: s.t })), { t: ' '.repeat(Math.max(0, halfWidth - segWidth(l.segs))), k: 'head' }, { t: ' │ ', k: 'sep' }, ...r.segs] })
382  } else rows.push({ segs: header('both').segs })
383  for (const { c, i } of sheetChanges) if (c.col !== undefined && sheet.cols[c.col]?.kind !== 'same') changeAt[i] = 0
384  const changeOfCell = new Map<string, number>()
385  const cellChangesOfRow = new Map<number, number[]>()
386  const changeOfRow = new Map<number, number>()
387  for (const { c, i } of sheetChanges) {
388    if (c.col !== undefined && sheet.cols[c.col]?.kind === 'same') {
389      changeOfCell.set(`${c.op}:${c.col}`, i)
390      cellChangesOfRow.set(c.op, [...(cellChangesOfRow.get(c.op) ?? []), i])
391    }
392    else if (c.col === undefined && (sheet.rows[c.op]?.kind === 'add' || sheet.rows[c.op]?.kind === 'del')) changeOfRow.set(c.op, i)
393  }
394  let runChange: number | undefined
395  for (const item of rowsShown) {
396    if ('fold' in item) {
397      runChange = undefined
398      rows.push(foldRow(item.fold, item.count, 'row', Math.min(opts.width, used + (side ? halfWidth + 3 : 0))))
399      continue
400    }
401    const { op, at } = item
402    if (changeOfRow.has(at)) runChange = changeOfRow.get(at)
403    else if (op.kind !== 'add' && op.kind !== 'del') runChange = undefined
404    const drawSide = (which: 'both' | 'before' | 'after'): { segs: Seg[]; cells: CellSpot[]; change?: number } => {
405      const number = which === 'before' ? (op.kind === 'add' ? '' : op.a + 1) : op.kind === 'del' ? op.a + 1 : op.b + 1
406      const showNumber = (which === 'before' && op.kind === 'add') || (which === 'after' && op.kind === 'del') ? '' : String(number)
407      const isAbsent = (which === 'before' && op.kind === 'add') || (which === 'after' && op.kind === 'del')
408      const mark = isAbsent ? MARK.same : op.kind === 'del' ? MARK.del : op.kind === 'add' ? MARK.add : op.kind === 'mod' ? MARK.mod : MARK.same
409      const segs: Seg[] = [{ t: showNumber.padStart(gutter), k: 'num' }, { t: ' ' }, mark]
410      const cells: CellSpot[] = []
411      let x = lead
412      let change: number | undefined = op.kind === 'add' || op.kind === 'del' ? runChange : undefined
413      for (const ci of shownCols) {
414        const col = cols[ci]!
415        const w = widths[ci]!
416        const hide = (which === 'after' && (op.kind === 'del' || col.op.kind === 'del')) || (which === 'before' && (op.kind === 'add' || col.op.kind === 'add'))
417        const { segs: cs } = hide ? { segs: [] } : cellSegs(sheet, op, at, col, which)
418        const value = op.kind !== 'del' && col.op.kind !== 'del' ? sheet.after?.rows[op.b]?.[col.op.b]?.x : undefined
419        const key = `${at}:${ci}`
420        const isPicked = opts.picked === key
421        const fitted = fitCell(cs, w, value !== undefined && cs.length === 1 && cs[0]?.k === 'n')
422        segs.push(...(isPicked ? fitted.map(s => ({ ...s, k: 'sel' as const })) : fitted), { t: '  ' })
423        cells.push({ x, w, key })
424        x += w + 2
425      }
426      // Changed cells off to the side still belong to this line.
427      for (const own of cellChangesOfRow.get(at) ?? []) {
428        changeAt[own] = rows.length
429        change ??= own
430      }
431      return { segs, cells, ...(change !== undefined ? { change } : {}) }
432    }
433    if (runChange !== undefined && changeOfRow.get(at) === runChange) changeAt[runChange] = rows.length
434    if (side) {
435      const l = drawSide('before')
436      const r = drawSide('after')
437      const lw = segWidth(l.segs)
438      const change = l.change ?? r.change
439      rows.push({
440        segs: [...l.segs, { t: ' '.repeat(Math.max(0, halfWidth - lw)) }, { t: ' │ ', k: 'sep' }, ...r.segs],
441        cells: [...l.cells, ...r.cells.map(c => ({ ...c, x: c.x + Math.max(halfWidth, lw) + 3 }))],
442        ...(change !== undefined ? { change } : {}),
443      })
444    } else {
445      const one = drawSide('both')
446      rows.push({ segs: one.segs, cells: one.cells, ...(one.change !== undefined ? { change: one.change } : {}) })
447    }
448  }
449  return { rows, changeAt, moreLeft, moreRight, shownCols }
450}
451
452/** The display column a change's cell is in, so the view can scroll sideways to it. */
453export function columnOf(change: Change): number | undefined {
454  return change.col
455}
456