Skip to content

User Guide

vibecoder880 edited this page Nov 19, 2026 · 1 revision

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.

1. Compare wizard (Home)

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://progress event — stage name and percent. Stages in order: extract → ocr (only when the OCR path engages) → align → diff → enrich → done (failed / cancelled are 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   ⌫     │
└────────────────────────────────────────────────────────────────┘

2. Diff view

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_used that 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:

  1. 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).
  2. 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.
  3. 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://done events drive it). Without a model the panel shows an honest setup hint pointing at Downloads.
  4. 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.

3. Downloads

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 on llm://download with byte counts and percent. If a llama-server is already found on your PATH, 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 .part file for resume.
  • OCR availability card — whether Tesseract + the vie language pack were detected on this machine, with the resolved binary path (see OCR-experimental).

4. Settings

  • 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_diff OCR flag: on = auto mode (OCR runs only when a PDF is suspected-scanned and Tesseract+vie are detectable); off = the OCR path is disabled entirely, no detection, no warnings. See OCR-experimental.
  • About — app version and license summary.

Sessions and history

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.

Keyboard & small behaviors worth knowing

  • 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.

Clone this wiki locally