twinshot 1.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61129562a7595873fe7d577f08d2d98b5a7d608a4c021c1b76eb3b66533deca8
+  data.tar.gz: 1c78a3f84ad0edcffe46144084a959d7db5eadd0886baa9d348f72d8d89fb2d7
+SHA512:
+  metadata.gz: f71390ff6a0309a3d7f2008cb44cb96a902494275bbfc0993f0f3ff2cc492cf3f75fddffb6eecaf7b11fdc6ea23a892a892ed0324a364d2bd2f412bc96a21d07
+  data.tar.gz: 3984e3f511e04341b7ddaaf3089c9281c415988fa73590a248ca2d12a38ef080ffd934439b0a3d63a835eadb8965851833c379aeba88c77c5d9aaa4bc9e8c4ce

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Oleg Orlov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PLAN.md

@@ -0,0 +1,107 @@
+# Twinshot — план реализации
+
+Гем для 1:1-парити двух деревьев артефактов: оракул (verified) vs текущее
+состояние. Структура папок свободная, но должна совпасть. Любой файл без
+адаптера — фейл. Отчёт — самодостаточный HTML с 1:1-галереей (как текущий
+`artifacts/compare/report.html` в capybara-tests) + поиск, фильтры, режимы
+сравнения картинок. В хорошем случае команды генерации не нужны — compare
+берёт две готовые папки.
+
+## Конфиг (`twinshot.yml`, минимальный)
+
+```yaml
+oracle:
+  path: artifacts/rails
+  generate: bin/record          # опционально
+current:
+  path: artifacts/crails
+  generate: bin/record --crails # опционально
+png:
+  max_diff_ratio: 0.002         # опционально, дефолт 0.002
+```
+
+Отчёт всегда пишется в `<dirname(config)>/twinshot-report/`
+(`report_for_human.html` + `report_for_agent.md` + `summary.json` +
+`diffs/*`). Не настраивается.
+
+## Структура кода
+
+```
+lib/twinshot.rb               — точка входа, requires
+lib/twinshot/cli.rb           — OptionParser: help / generate / compare
+lib/twinshot/config.rb        — загрузка + валидация twinshot.yml
+lib/twinshot/tree.rb          — скан дерева, сверка структуры
+lib/twinshot/adapters.rb      — реестр адаптеров по расширению
+lib/twinshot/adapters/binary.rb — sha256, побайтово
+lib/twinshot/adapters/txt.rb    — построчный diff (diff-lcs)
+lib/twinshot/adapters/html.rb   — по структуре: nokogiri-канонизация → построчный diff
+lib/twinshot/adapters/png.rb    — байты fast-path → попиксельно (chunky_png) + diff-картинка
+lib/twinshot/compare.rb       — оркестратор: структура → файлы в пуле форк-воркеров
+lib/twinshot/report.rb        — HTML-отчёт (инлайн CSS/JS, без зависимостей)
+exe/twinshot
+```
+
+## Правила сравнения
+
+1. **Структура**: дерево файлов `current` обязано совпадать с `oracle` 1:1.
+   Лишний файл / недостающий / пустая папка в стороне — фейл-запись в отчёт.
+2. **Файлы**: адаптер по расширению. Нет адаптера → фейл («no adapter for .xyz»).
+3. PNG: байты равны → pass; иначе попиксельно, pass если diff-доля ≤
+   `max_diff_ratio`; при несовпадении размеров — фейл с указанием размеров.
+   Для провала генерится `diffs/<rel>.diff.png` (изменённые пиксели красным).
+4. HTML: канонизация DOM (nokogiri: убрать комментарии, схлопнуть пробелы в
+   текст-нодах, отсортировать атрибуты, сериализовать построчно) → построчный
+   diff. Pass = 0 расхождений.
+5. TXT: построчный diff (diff-lcs). Pass = 0 расхождений.
+6. Бинарные (зарегистрированные как binary): sha256.
+
+## Параллелизм
+
+Структура — синхронно (дёшево). Файлы — пул форк-воркеров (`--jobs N`,
+дефолт = число ядер, кап 8): round-robin срезы, результаты пишутся воркерами
+в tmpdir как JSON, родитель мёржит и сортирует. `--jobs 1` — последовательно.
+Форки вместо Ractors: совместимо с 3.2+ и без GVL-проблем chunky_png.
+
+## CLI
+
+```
+twinshot help [COMMAND]                — справка
+twinshot generate oracle|current       — запускает generate-команду из конфига (chdir = dirname конфига)
+twinshot compare                       — сравнивает две папки, пишет отчёт
+  -c, --config PATH   (default: twinshot.yml)
+  -j, --jobs N
+      --json           — machine-итог в stdout
+  -V, --version
+```
+
+Exit-коды: 0 — всё сошлось; 1 — есть расхождения; 2 — ошибка конфига/usage.
+
+## Отчёт
+
+- Группировка по папкам (заголовок группы + счётчик), внутри провалы первыми.
+- Sticky-шапка: итоги, поиск по подстроке имени, фильтры все/провалы/прошедшие,
+  режимы картинок: рядом / слайдер / мигание.
+- Sticky-имя файла над каждой парой (как в текущем отчёте capybara-tests).
+- Клавиши n/p — прыжок к следующему/предыдущему видимому шоту.
+- Текстовые диффы инлайном (`+/-` строки, кап 400 строк).
+- Всё инлайн (CSS/JS), внешних ассетов нет; картинки — относительные пути.
+
+## Тесты (minitest)
+
+- config: загрузка, дефолты, ошибки валидации
+- tree: совпадение/лишний/недостающий файл
+- adapters: binary/txt/png (мини-PNG генерим chunky_png)/html-канонизация/unknown ext
+- compare: e2e на tmp-деревьях, включая fork-пул (jobs 1 и 2)
+- cli: help, unknown command, exit-коды
+- report: генерится, содержит маркеры групп/шотов
+
+## Интеграция
+
+`capybara-tests/twinshot.yml` → `oracle: artifacts/rails`, `current: artifacts/crails`,
+запуск `twinshot compare`, проверка exit-кода, отчёта и summary.json на живых данных
+(127 файлов rails, 129 crails — есть реальный лишний файл для проверки структуры).
+
+## Готовность
+
+rake test зелёный, rake build собирается, на capybara-артефактах compare
+возвращает ненулевой exit (лишний файл), отчёт открывается и работает.

data/README.md

@@ -0,0 +1,179 @@
+<p align="center">
+  <img src="logo.svg" alt="Twinshot logo" width="256">
+</p>
+
+# Twinshot — Make "clean room" implementation of every program in the earth!
+
+Save and compare screenshots of the functionality of other applications you
+want to copy end to end: a proven **oracle** tree against the **current**
+state, 1:1 parity between two folders of snapshots (screenshots, HTML, text).
+
+## Use cases
+
+- **Pixel-perfect design from mockups** — export every screen from Figma or a
+  sketch into `oracle/`, screenshot your implementation into `current/`, and
+  twinshot verifies it pixel-by-pixel: a tolerance (`png.max_diff_ratio`) for
+  antialiasing, a red diff image and a heat-zone overlay showing exactly where
+  you drifted. "Matches the design" stops being an opinion.
+- **Clean-room reimplementation** — rebuilding an app on a new stack
+  (the gem's origin: a Rails app rewritten in crails): snapshot both versions
+  and drive to 1:1 parity, screen by screen.
+- **Upgrade/refactor safety net** — before a framework or Ruby major upgrade,
+  snapshot pages before and after; zero diff proves the UI didn't move.
+- **AI agent feedback loop** — an agent implements, `twinshot compare` writes
+  `report_for_agent.md` designed to be fed back to the model; exit codes
+  fit CI and `git bisect run`.
+- **Golden-master testing** — not just pixels: rendered HTML compared by
+  canonicalized DOM structure, JSON/CSV/logs by line diff — catch structural
+  regressions with no flaky selectors.
+- **Cross-browser parity** — the same pages screenshotted in different
+  browsers/OSes, compared as trees.
+
+## How it works
+
+1. **Structure**: the `current` file tree must match `oracle` 1:1. An extra
+   or missing file is a failure.
+2. **Files**: every file is compared by its extension's adapter. No adapter —
+   failure (no fallbacks).
+3. **Report**: a self-contained HTML gallery (`report_for_human.html`) +
+   a markdown report for LLM agents (`report_for_agent.md`) + `summary.json`.
+
+Adapters:
+
+| Type  | How it compares                                                       |
+|-------|-----------------------------------------------------------------------|
+| `png` | bytes fast-path → pixel-by-pixel; threshold `png.max_diff_ratio`; diff image (red) + purple heat-zone overlay |
+| `html`| by DOM structure: canonicalization (nokogiri: no comments, whitespace collapsed, attributes sorted) → line diff |
+| `xml` | by structure like html, via the XML parser (case-sensitive names): canonicalization → line diff (`xml`, `svg`) |
+| `txt` | line diff (`txt`, `md`, `log`, `json`, `csv`)                          |
+| `bin` | byte-wise SHA-256 (`bin`, `dat`)                                       |
+
+## Config — `twinshot.yml`
+
+```yaml
+oracle:
+  path: artifacts/rails
+  generate: bin/record            # optional
+
+current:
+  path: artifacts/crails
+  generate: bin/record --crails   # optional
+
+png:
+  max_diff_ratio: 0.002           # optional, default 0.002 (applies to all groups)
+
+soft_check:                       # optional: exact tree-relative paths or globs
+  - dashboard/header.png          # diffs tolerated (clocks, dates…); missing/
+  - code/capybara-tests/*         # extra files on one side — all warnings,
+                                   # exit code stays 0
+
+# optional: named groups — additional tree pairs with the same fields
+# (path + generate per side). Any names work.
+groups:
+  dogs:
+    oracle:
+      path: artifacts/dogs-rails
+      generate: bin/record --dogs
+    current:
+      path: artifacts/dogs-crails
+```
+
+The top-level `oracle`/`current` pair is the unnamed **default group**;
+`compare` runs every group in order (or just one — `compare dogs`), and
+`groups` in the yaml adds named ones (the name `default` is reserved).
+There is nothing special about an "API-style" group: if you need to compare
+not just the output but the input too, simply put the input artifacts into
+the group's trees — they are compared by the same adapters.
+
+Every group writes its report into its own folder:
+`<config dir>/twinshot-report/<group>/` — the default group reports into
+`twinshot-report/default/`. Each folder holds the same layout as before:
+`report_for_human.html`, `report_for_agent.md`, `summary.json`, `diffs/`.
+Not configurable.
+
+Entries in `soft_check` (the same list for every group) are exact
+tree-relative paths or glob patterns. They are snapshots whose content is
+allowed to differ — typically screenshots with a clock or other dynamic
+content — and files that may legitimately exist on only one side of the
+trees. Globs match nested files and dotfiles (`*` crosses `/`):
+`code/capybara-tests/*` covers the entire subtree. Everything a listed path
+produces is a **warning** (`!` in yellow in the run output): a content diff
+when it exists on both sides, or a missing/extra structure result when it
+exists on only one. Warnings are fully visible in both reports and counted
+separately, but they never change the exit code.
+
+## Commands
+
+```
+twinshot compare [GROUP|all] [-c PATH] [-j N] [--json] [--[no-]open]  # compare, write reports
+twinshot generate [GROUP|all|SIDE][:oracle|current]  # run generate commands
+twinshot review [GROUP|all] [compare flags]        # regenerate, then compare
+twinshot help [COMMAND]                      # help
+```
+
+- `compare` in the happy case needs no generation — it takes the folders as
+  they are. `GROUP` (a group name, `all` by default) selects what runs:
+  `compare dogs` compares only that group and writes only its report;
+  `compare all` — every configured group.
+- `-j N` — worker pool (forks, default: core count, capped at 8): the
+  structure is checked synchronously, files in parallel.
+- After `compare`, the first compared group's report opens in a browser: on
+  a tty — automatically, `--open` — force it (even with `--json`),
+  `--no-open` — disable. Cross-platform "open" (`Twinshot::Opener`): darwin
+  — `open`, windows — `start` via `cmd /c`, linux/BSD — `xdg-open`; a failed
+  launch does not affect the exit code.
+- `generate` takes a `GROUP:SIDE` selector: `generate dogs:oracle` — one
+  tree of a named group; a bare side (`generate oracle`, same as
+  `default:oracle`) — the default group's tree (no namespace means
+  default); `generate dogs` — both trees of one group; `generate all` /
+  `all:oracle` / no selector — every configured tree of every group (one
+  side or both), announced as a `Generate:` list first. A failing command
+  doesn't stop the rest, but the exit code reports it. The words `all`,
+  `oracle` and `current` are reserved and cannot be group names.
+- `review` is generate + compare in one run: both sides of the selected
+  groups (`review dogs`, `all` by default) regenerate first — a tree
+  without a generate command is taken as it is — then the compare runs and
+  writes the same reports, with the same options as `compare`. A failed
+  generate command fails the run (exit 1) without comparing.
+- Exit codes: `0` — everything matched, `1` — differences found (fits
+  `git bisect run` and CI), `2` — config/usage error. `soft_check` warnings
+  never affect the exit code.
+
+## Report
+
+Two files per group folder:
+
+- `report_for_human.html` — the visual report (opened in a browser after
+  `compare`):
+  - flat gallery ordered by folder (one card per file, no folder headings);
+  - substring search, filters all/failed/warned/passed;
+  - image modes: **side-by-side** (50/50), **slider** (overlay with a handle),
+    **blink** (oracle/current alternating);
+  - **zones** — a purple overlay over images: the picture is split into 32×32 px
+    squares, a square's opacity grows with the share of differing pixels (`heat`
+    metadata in `summary.json`, a toolbar toggle);
+  - inline text diffs (`+/-` lines);
+  - `n`/`p` keys — navigate shots, `Esc` — reset search.
+- `report_for_agent.md` — the same results as markdown to feed to a model:
+  every failed file gets a section with its metadata (absolute oracle/current
+  paths, kind, detail, ratio, diff-image path) plus the divergence snippet as a
+  unified-style `diff` fence — the same line diffs the human report renders
+  inline (for `html` that is the canonicalized DOM line diff, so the snippet
+  shows what structurally differs, not raw source noise). Passed files are a
+  plain list at the bottom.
+
+## Install and development
+
+```sh
+bundle exec rake test && bundle exec rake build   # pkg/twinshot-X.Y.Z.gem
+```
+
+Ruby >= 3.2 (developed on 4.0). Dependencies: `ruby-vips` (native `libvips`),
+`colorize`, `diff-lcs`, `nokogiri`.
+
+A run prints live progress: a banner, a colored per-file verdict (✓ pass /
+`!` warn / ✗ fail) in worker arrival order, and a final stats block by type.
+When anything failed, a copyable `FAILS:` list of every failed file follows
+the stats block; on an otherwise green run with warnings, a `WARNS:` list of
+the `soft_check` files instead. Colors on a tty only; `--json` disables
+progress.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/exe/twinshot

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "twinshot"
+
+exit(Twinshot::CLI.new(ARGV).call)

data/lib/twinshot/adapters/binary.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Twinshot
+  # Adapter implementations (the contract lives in adapters.rb).
+  module Adapters
+    # Byte-for-byte comparison via SHA-256.
+    module Binary
+      module_function
+
+      def call(_rel, oracle_file, current_file, _ctx)
+        same = Digest::SHA256.file(oracle_file).hexdigest == Digest::SHA256.file(current_file).hexdigest
+        { "kind" => "binary", "status" => same ? "pass" : "fail",
+          "detail" => same ? "bytes equal" : "bytes differ" }
+      end
+    end
+
+    register(Binary, "bin", "dat")
+  end
+end

data/lib/twinshot/adapters/html.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Twinshot
+  # Adapter implementations (the contract lives in adapters.rb).
+  module Adapters
+    # HTML compares by DOM structure, not raw text: canonical serialization
+    # (comments dropped, whitespace-only text nodes dropped, runs of whitespace
+    # in text squashed to one space, attributes sorted by name) followed by a
+    # line diff over that canonical form. Pass when structures are identical.
+    module Html
+      module_function
+
+      def call(_rel, oracle_file, current_file, _ctx)
+        Adapters.structural_result("html", canonical_lines(oracle_file), canonical_lines(current_file))
+      end
+
+      def canonical_lines(path)
+        doc = Nokogiri::HTML4(File.read(path, encoding: "UTF-8"))
+        Adapters.canonical_dom_lines(doc, downcase_names: true)
+      end
+    end
+
+    register(Html, "html", "htm")
+  end
+end

data/lib/twinshot/adapters/png.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "vips"
+
+# twinshot parallelizes across files with its own worker pool, so keep each
+# libvips call single-threaded — otherwise every forked worker would spin up
+# its own nproc-sized libvips threadpool and oversubscribe the machine.
+Vips.vips_concurrency_set(1)
+
+module Twinshot
+  # Adapter implementations (the contract lives in adapters.rb).
+  module Adapters
+    # PNG: bytes fast-path, then pixel-by-pixel via libvips (decode, diff mask
+    # and diff image are all native C — a pure-ruby pixel walk was the old
+    # bottleneck). Pass when the share of differing pixels is within
+    # ctx.max_diff_ratio. On fail writes a diff image (differing pixels painted
+    # red over the current snapshot) into the report dir. Whenever any pixel
+    # differs, also emits "heat" — a grid metadata for the report's purple
+    # overlay (see #heat_grid).
+    module Png
+      module_function
+
+      HEAT_CELL = 32
+      RED = [255, 0, 0, 255].freeze
+
+      def call(rel, oracle_file, current_file, ctx)
+        if Digest::SHA256.file(oracle_file).hexdigest == Digest::SHA256.file(current_file).hexdigest
+          return { "kind" => "png", "image" => true, "status" => "pass", "detail" => "bytes equal" }
+        end
+
+        a = decode(oracle_file)
+        b = decode(current_file)
+        return a if a.is_a?(Hash)
+        return b if b.is_a?(Hash)
+        if a.width != b.width || a.height != b.height
+          return { "kind" => "png", "image" => true, "status" => "fail",
+                   "detail" => "size mismatch #{a.width}x#{a.height} vs #{b.width}x#{b.height}" }
+        end
+
+        mask = diff_mask(a, b).copy_memory
+        total = a.width * a.height
+        diff_count = (mask.avg * total / 255.0).round
+        ratio = diff_count.fdiv(total)
+        result = { "kind" => "png", "image" => true,
+                   "status" => ratio <= ctx.max_diff_ratio ? "pass" : "fail",
+                   "detail" => format("%.3f%% px differ (%d/%d)", ratio * 100, diff_count, total),
+                   "ratio" => ratio }
+        if diff_count.positive?
+          result["heat"] = heat_grid(a, mask)
+          result["diff_image"] = write_diff_image(rel, b, mask, ctx) if result["status"] == "fail"
+        end
+        result
+      end
+
+      def decode(path)
+        Vips::Image.new_from_file(path, access: :random)
+      rescue Vips::Error => e
+        { "kind" => "png", "image" => true, "status" => "fail", "detail" => "decode error: #{e.message}" }
+      end
+
+      # Single-band 0/255 mask: 255 where any band of the two images differs.
+      # Both sides are normalized to rgba first so an rgb/rgba (or grey/rgba)
+      # pair still compares pixel-wise.
+      def diff_mask(oracle, current)
+        (rgba(oracle) != rgba(current)).bandor
+      end
+
+      def rgba(img)
+        case img.bands
+        when 1 then g = img.extract_band(0)
+                    g.bandjoin([g, g]).bandjoin_const([255])
+        when 2 then g = img.extract_band(0)
+                    g.bandjoin([g, g, img.extract_band(1)])
+        when 3 then img.bandjoin_const([255])
+        else img
+        end
+      end
+
+      # Splits the image into HEAT_CELL squares and returns, for every cell
+      # with at least one differing pixel, its share of differing pixels:
+      #
+      #   { "cell" => 32, "w" => 1280, "h" => 800,
+      #     "cells" => [[col, row, intensity], ...] }  # intensity in 0..1
+      #
+      # Per-cell differing-pixel counts come from a libvips shrink (average
+      # over each cell) so the counting stays native. Edge cells on the
+      # right/bottom cover the remainder, so their area (the intensity
+      # denominator) is smaller than HEAT_CELL^2.
+      def heat_grid(image, mask)
+        width = image.width
+        height = image.height
+        cols = (width + HEAT_CELL - 1) / HEAT_CELL
+        rows = (height + HEAT_CELL - 1) / HEAT_CELL
+        # pad to a HEAT_CELL multiple so shrink keeps whole cells (and works
+        # at all when the image is smaller than one cell); the zero padding
+        # leaves each cell's differing-pixel count untouched.
+        padded = mask.embed(0, 0, cols * HEAT_CELL, rows * HEAT_CELL)
+        avgs = padded.cast(:float).shrink(HEAT_CELL, HEAT_CELL).write_to_memory.unpack("e*")
+        cells = avgs.each_with_index.filter_map do |avg, idx|
+          col = idx % cols
+          row = idx / cols
+          cell_w = [width - col * HEAT_CELL, HEAT_CELL].min
+          cell_h = [height - row * HEAT_CELL, HEAT_CELL].min
+          # avg is over the padded HEAT_CELL^2 cell, so the count denominator
+          # is the padded area, not the cell's actual (edge-trimmed) area.
+          count = (avg * HEAT_CELL * HEAT_CELL / 255.0).round
+          next if count.zero?
+
+          [col, row, (count.fdiv(cell_w * cell_h) * 100).round / 100.0]
+        end
+        { "cell" => HEAT_CELL, "w" => width, "h" => height, "cells" => cells }
+      end
+
+      def write_diff_image(rel, base, mask, ctx)
+        diff = mask.ifthenelse(RED, rgba(base))
+        rel_path = File.join("diffs", "#{rel}.diff.png")
+        abs = File.join(ctx.report_dir, rel_path)
+        FileUtils.mkdir_p(File.dirname(abs))
+        diff.pngsave(abs)
+        rel_path
+      end
+    end
+
+    register(Png, "png")
+  end
+end

data/lib/twinshot/adapters/txt.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Twinshot
+  # Adapter implementations (the contract lives in adapters.rb).
+  module Adapters
+    # Plain text: line-by-line diff. Pass when every line matches.
+    module Txt
+      module_function
+
+      def call(_rel, oracle_file, current_file, _ctx)
+        a_lines = read_lines(oracle_file)
+        b_lines = read_lines(current_file)
+        return { "kind" => "txt", "status" => "pass", "detail" => "lines identical" } if a_lines == b_lines
+
+        changed, entries = Adapters.line_diff(a_lines, b_lines)
+        { "kind" => "txt", "status" => "fail", "detail" => "#{changed} line(s) differ",
+          "diff_lines" => changed, "diff" => entries }
+      end
+
+      def read_lines(path)
+        File.read(path, encoding: "UTF-8").gsub(/\r\n?/, "\n").lines.map(&:chomp)
+      end
+    end
+
+    register(Txt, "txt", "md", "log", "json", "csv")
+  end
+end

data/lib/twinshot/adapters/xml.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Twinshot
+  # Adapter implementations (the contract lives in adapters.rb).
+  module Adapters
+    # XML compares by structure like html, but through the XML parser:
+    # element names stay case-sensitive and no html/body structure is
+    # implied. Canonical serialization → line diff; pass when structures are
+    # identical. svg is XML, so it lands here too (compared as markup, not
+    # rendered pixels).
+    module Xml
+      module_function
+
+      def call(_rel, oracle_file, current_file, _ctx)
+        Adapters.structural_result("xml", canonical_lines(oracle_file), canonical_lines(current_file))
+      end
+
+      def canonical_lines(path)
+        doc = Nokogiri::XML(File.read(path, encoding: "UTF-8"))
+        Adapters.canonical_dom_lines(doc, downcase_names: false)
+      end
+    end
+
+    register(Xml, "xml", "svg")
+  end
+end