Repository navigation
User Guide
DiffLens has four screens: the Compare wizard (home), the Diff view, the Downloads manager, and Settings. No screenshot exists yet (the GUI needs a display; see Home), so every screen is described in words — with an ASCII sketch of the main diff layout below.
The home route is where every comparison starts:
- Two file slots (old document, new document). Each slot has a Browse button that opens the native file picker — the app never asks you to type paths. Dropped files are accepted too: DiffLens registers Tauri's drag-and-drop, and dropping onto the window fills the empty slots in order (first drop → old slot, second → new slot; two at once fill both).
- Format badge per slot: the format (PDF/DOCX/XLSX/PPTX/TXT) is auto-detected from the extension and shown as a badge next to the file name, so you notice a wrong pick before running.
- Same-file validation: choosing the identical file in both slots disables Compare and shows a hint — comparing a file with itself is rejected.
- Comparison options: the OCR fallback toggle (default: auto — see OCR-experimental). Semantic alignment is always on; it is the product.
-
Progress card: once you press Compare, a live card tracks the job via the
diff://progressevent — stage name and percent. Stages in order:extract→ocr(only when the OCR path engages) →align→diff→enrich→done(failed/cancelledare terminal states too). A Cancel button flags the job; the pipeline checks the flag at stage boundaries and stops cleanly. - Recent comparisons: past sessions (from the local SQLite store) are listed with format, stats and date; clicking one re-opens its full report; entries can be deleted.
┌─ Home ────────────────────────────────────────────────────────┐
│ Old document New document │
│ ┌───────────────────────────┐ ┌───────────────────────────┐ │
│ │ contract-v1.pdf [PDF] ✕ │ │ contract-v2.pdf [PDF] ✕ │ │
│ └───────────────────────────┘ └───────────────────────────┘ │
│ (browse…) or drag files anywhere onto the window │
│ │
│ [x] OCR fallback (auto; needs local Tesseract + vie) │
│ │
│ ▶ Compare │
│ │
│ ┌ Job: job-abc123 ── running ──────────────────────────────┐ │
│ │ extract ████████░░░░ 62% (extract→ocr→align→diff→…) │ │
│ │ [Cancel]│ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ Recent: contract-v2.pdf [PDF] +1 −2 ~4 2 min ago ⌫ │
└────────────────────────────────────────────────────────────────┘
The result workspace at /diff/{jobId}, laid out in three regions:
-
Stats chips — the header row shows added / removed / modified / equal counts and an embeddings indicator (whether the real e5 model produced the alignment or the build fell back to the deterministic fake embedder — the same flag
embeddings_usedthat the audit trail records). OCR usage is flagged when it contributed blocks. -
Change list (left) — every change with its severity band (info → critical), kind glyph (added/removed/modified/moved), and the rule tags the heuristic layer attached (e.g.
MONEY_CHANGED −50%). Chips at the top filter by kind and by severity, each showing live counts. - Side-by-side view (right) — the documents rendered as aligned rows, virtualized with TanStack Virtual so thousand-block documents scroll smoothly. Inline spans color added text and removed text within a modified row; moved rows get an arrow glyph (⇄) with the positional delta; long runs of unchanged rows are collapsed into a "N unchanged" expander that opens and scrolls to the relevant change.
Clicking a change in the list reveals it in the view and opens the detail drawer:
┌─ Diff report: contract-v2.pdf ────────────────────────────────┐
│ [added 2] [removed 1] [modified 4] [equal 31] e5 ✓ embeddings│
│──────────────┬────────────────────────────────┬───────────────┤
│ FILTERS │ OLD (v1) │ NEW (v2) │ CHANGE LIST │
│ kind: Δ ○ ✕ ⇄│ Payment within │ Payment w │ ● HIGH MONEY │
│ sev: ●▲■□○ │ 30 days │ 15 days │ −50% ~c3 │
│ │ (unchanged rows… │ │ ● MED DATE │
│ │ collapsed) │ │ ○ LOW entity│
│ │────────────────────────────────│ … │
│ │ inline: [30]{15} spans colored│ │
│──────────────┴────────────────────────────────┴───────────────┤
│ DETAIL DRAWER (opens over the right side) │
│ Change ~c3 — Modified · severity HIGH │
│ Flag: Money changed 5,000,000 VND → 2,500,000 VND (−50.0%) │
│ Why HIGH: rule MONEY_CHANGED = 35 pts (max) + keyword uplift │
│ Audit: aligned by anchor (Điều 5) · extracted from PDF p.3 │
│ [Explain with AI ▸ streaming… ▐ stop] [Export ▾ HTML / MD] │
└────────────────────────────────────────────────────────────────┘
Drawer contents, top to bottom:
-
Flags with old → new values — each heuristic flag shows the matched entities verbatim (e.g.
5.000.000 VND → 2.500.000 VND), the computed delta and the label key (flag.moneyChanged). - The audit trail — "why this severity" — which rule fired, its point contribution, the risk-lexicon keyword uplift, and the alignment decision (anchor / semantic / move-repair, with cosine similarity). Severity is fully explained, never asserted.
-
Explain with AI (visible once a model is installed) — requests a streaming explanation for this one change; tokens appear live, and a Stop button cancels mid-stream (the
llm://token/llm://doneevents drive it). Without a model the panel shows an honest setup hint pointing at Downloads. - Export menu — writes the whole report as standalone HTML or Markdown via a native save dialog; the backend validates the target path (absolute, matching extension) before writing.
The only screen that ever touches the network. It shows a status snapshot for each manifest-pinned component:
-
llama-server install card — the pinned llama.cpp build (
b12503) for your OS, with size and a Install button; state (running/done/failed/cancelled) streams in onllm://downloadwith byte counts and percent. If allama-serveris already found on yourPATH, that is detected and shown as a fallback. -
Model cards — one per GGUF in the manifest (Qwen3-4B primary, Qwen2.5-3B fallback) with file size, license, minimum-RAM guidance, and a SHA-256 verified badge (the checksum is enforced before the file is moved into place — an unverified entry would show a warning badge instead). Download progress is resumable; Cancel really aborts the transfer (fixed in v1.0.1) and keeps the
.partfile for resume. -
OCR availability card — whether Tesseract + the
vielanguage pack were detected on this machine, with the resolved binary path (see OCR-experimental).
- Theme — light / dark / system.
-
Language — English or Tiếng Việt (persisted in
localStorage; both locales are parity-tested against the backend's label keys, so every rule tag has a translated string). -
OCR preference — the switch controls the
run_diffOCR flag: on = auto mode (OCR runs only when a PDF is suspected-scanned and Tesseract+vieare detectable); off = the OCR path is disabled entirely, no detection, no warnings. See OCR-experimental. - About — app version and license summary.
Every finished comparison is persisted (fire-and-forget) to a local SQLite database (difflens.sqlite3 inside your OS app-data directory). History rows keep both file paths, format, stats, the embeddings/OCR flags and the full result JSON, so a re-opened session shows the identical report — including the audit trail. Deleting an entry removes it permanently; nothing is synced anywhere.
- Dropped files fill empty slots in order — no dialog round-trip needed.
- Event listeners are re-registered per route and cleaned up on unmount (no ghost progress updates).
- Export always goes through the native save dialog; the typed file extension must match the chosen format.