Building a Text Comparer

We will use Claude Code as our only development tool to go from requirements to a working app. We won't use scaffolding tools like superpowers or gstack — just Claude Code and VS code.

You can try the finished app here: Text Comparer

Before writing any code, let's step back and think about what we're building and why.

What is Text Comparison?#

Text comparison (also called diffing) is the process of analyzing two pieces of text to find what's different between them. The result — commonly called a diff — highlights exactly which parts were added, removed, or modified.

You encounter text comparison constantly in software development, even if you don't always realize it:

  • Version control: When you run git diff, Git compares two versions of a file and shows you what changed between them
  • Code review: Pull request views on GitHub highlight added lines in green and removed lines in red — that's a diff
  • Debugging: When a configuration file "used to work" but now doesn't, comparing the current version to a known-good version instantly reveals what changed
  • Content editing: Writers and editors compare document drafts to see what was revised between iterations

At its core, a diff algorithm takes two inputs (often called the original and modified texts) and produces a list of changes. Each change is classified as one of four types: added (present only in the modified text), removed (present only in the original text), modified (present in both but different), or unchanged (identical in both).

Here's a simple example. Given these two texts:

The quick brown fox
jumps over the lazy dog

The quick red fox
leaps over the lazy cat

A line-level diff would report that both lines were modified — it knows that each line is different between the two versions, but it treats each line as a single unit. It can tell you which lines changed, but not what within those lines changed.

This is where granularity comes in. Different granularity levels reveal different kinds of detail:

  • A line-level diff identifies which lines changed. It's the broadest view — great for quickly scanning which parts of a file were touched. In the example above, it would report: "line 1 was modified, line 2 was modified."
  • A word-level diff goes deeper. It compares word by word within each line, so it can pinpoint that "brown" changed to "red" on line 1, and "jumps" changed to "leaps" and "dog" changed to "cat" on line 2 — while "The", "quick", "fox", "over", "the", and "lazy" remained the same.
  • A character-level diff is the finest granularity. It compares individual characters, which is useful for catching typos or subtle edits like color vs. colour.

Why Do We Need a Text Comparer?#

Comparing two short texts by eye is easy enough. But in practice, the texts you need to compare are often long — hundreds or thousands of lines — and the differences can be subtle. Consider these real-world scenarios:

  • A configuration file was changed, and your application stopped working. The file is 200 lines long, and the problem turns out to be a single mistyped value buried on line 147. Scanning the entire file manually could take a long time and you might still miss it; a diff tool finds it instantly.
  • Two teammates edited the same document, and you need to merge their changes. Without a comparison tool, you'd have to read both versions side by side, line by line, hoping you don't miss anything — a process that's both slow and unreliable.
  • An API response changed between versions. The response is a 500-line JSON document, and you need to know exactly which fields were added, removed, or modified before you can update your code to handle the new format.

In all of these cases, manually comparing the texts is slow, error-prone, and frustrating. A text comparison tool automates this work — it takes two pieces of text, computes the differences using a diff algorithm, and presents them in a clear, visual format so you can understand the changes at a glance.

That's what we're building: a Text Comparer that lets you paste (or upload) two texts, see their differences highlighted with color coding, navigate between changes, and export the results in multiple formats.

Key Features#

  1. Dual-Panel Input — Two side-by-side code editors (original on the left, modified on the right) with line numbers, line wrapping, and placeholder guidance
  2. Real-Time Diffing — Differences update automatically as you type or paste — no "Compare" button needed
  3. Multiple Diff Granularities — Switch between line, word, and character diff modes for different levels of detail
  4. Side-by-Side Diff View — Color-coded results (green = added, red = removed, yellow = modified) with synced scrolling between both panes
  5. Change Navigation — Previous/next buttons with a change counter (e.g., "3 / 7") to jump between differences
  6. Swap & Clear — Swap left and right texts with one click, or clear both editors for a fresh start
  7. File Upload — Load files via upload button or drag-and-drop; supports .txt, .json, .xml, .csv, .md, .log, and more
  8. Copy & Export — Copy diff to clipboard; download as .diff, .txt, or .html formats
  9. Settings — Ignore case, whitespace, or empty lines; show whitespace characters; all settings persist across sessions via localStorage
  10. Statistics — Change counts (additions, deletions, modifications), line counts, and plain-language status messages

Quality Goals#

  • Performance — Instant diff for typical inputs; UI stays responsive even with thousands of lines
  • Usability — Self-explanatory dual-panel layout, clear labels and tooltips, familiar Git-style color coding
  • Responsiveness — Resizable panels that adapt to different screen sizes
  • Reliability — Handles edge cases (empty input, mixed line endings, huge files) and falls back to defaults if localStorage is unavailable

What's Next?#

With these requirements as our guide, we'll use Claude Code to build the Text Comparer step by step — starting with writing a product requirements document (PRD).

NextProduct Requirements Document (PRD)