qrcode-ai-scanner 0.3.0__tar.gz

qrcode_ai_scanner-0.3.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: qrcode-ai-scanner
+Version: 0.3.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: jsonschema ; extra == 'test'
+Requires-Dist: pillow ; extra == 'test'
+Provides-Extra: test
+Summary: QR decoding + scannability scoring for artistic, AI-generated, and photo-captured QR codes — Rust core via PyO3.
+Keywords: qrcode,qr,scanner,decoder,barcode,validation
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://github.com/supernovae-st/qrcode-ai-scanner/tree/main/docs
+Project-URL: Repository, https://github.com/supernovae-st/qrcode-ai-scanner
+
+# qrcode-ai-scanner (Python)
+
+QR decoding + scannability scoring for **artistic / AI-generated / photo-captured** QR
+codes — the Rust [`qrcode-ai-scanner`](https://crates.io/crates/qrcode-ai-scanner) engine,
+via PyO3. Same versioned `ScanReport` contract as the Rust, Node and WASM surfaces.
+
+```python
+import qrcode_ai_scanner as qr
+
+with open("image.png", "rb") as f:
+    report = qr.scan(f.read(), profile="full")   # "full" | "fast" | "frame"
+
+if report["detections"]:
+    d = report["detections"][0]
+    print(d["content"]["text"])
+    print(report["score"]["value"], report["score"]["grade"])  # 0-100 + ISO band
+    print(report["hints"])                                      # machine-actionable
+```
+
+- `scan(image: bytes, profile="full") -> dict` — decode encoded bytes (PNG/JPEG/WebP/GIF).
+- `scan_frame(rgba: bytes, width: int, height: int, profile="frame") -> dict` — raw RGBA
+  frame, no image-format roundtrip.
+- "No QR found" returns a `dict` with empty `detections`; `ValueError` is raised only for
+  invalid input.
+
+The returned `dict` is the same `ScanReport` documented in the
+[spec](https://github.com/supernovae-st/qrcode-ai-scanner/tree/main/spec).
+
+License: AGPL-3.0-or-later · © SuperNovae Studio.
+

qrcode_ai_scanner-0.3.0/README.md

@@ -0,0 +1,29 @@
+# qrcode-ai-scanner (Python)
+
+QR decoding + scannability scoring for **artistic / AI-generated / photo-captured** QR
+codes — the Rust [`qrcode-ai-scanner`](https://crates.io/crates/qrcode-ai-scanner) engine,
+via PyO3. Same versioned `ScanReport` contract as the Rust, Node and WASM surfaces.
+
+```python
+import qrcode_ai_scanner as qr
+
+with open("image.png", "rb") as f:
+    report = qr.scan(f.read(), profile="full")   # "full" | "fast" | "frame"
+
+if report["detections"]:
+    d = report["detections"][0]
+    print(d["content"]["text"])
+    print(report["score"]["value"], report["score"]["grade"])  # 0-100 + ISO band
+    print(report["hints"])                                      # machine-actionable
+```
+
+- `scan(image: bytes, profile="full") -> dict` — decode encoded bytes (PNG/JPEG/WebP/GIF).
+- `scan_frame(rgba: bytes, width: int, height: int, profile="frame") -> dict` — raw RGBA
+  frame, no image-format roundtrip.
+- "No QR found" returns a `dict` with empty `detections`; `ValueError` is raised only for
+  invalid input.
+
+The returned `dict` is the same `ScanReport` documented in the
+[spec](https://github.com/supernovae-st/qrcode-ai-scanner/tree/main/spec).
+
+License: AGPL-3.0-or-later · © SuperNovae Studio.

qrcode_ai_scanner-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "qrcode-ai-scanner"
+description = "QR decoding + scannability scoring for artistic, AI-generated, and photo-captured QR codes — Rust core via PyO3."
+requires-python = ">=3.8"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+keywords = ["qrcode", "qr", "scanner", "decoder", "barcode", "validation"]
+classifiers = [
+  "Programming Language :: Rust",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+test = ["pytest", "jsonschema", "pillow"]
+
+[project.urls]
+Repository = "https://github.com/supernovae-st/qrcode-ai-scanner"
+Documentation = "https://github.com/supernovae-st/qrcode-ai-scanner/tree/main/docs"
+
+[tool.maturin]
+module-name = "qrcode_ai_scanner"
+manifest-path = "qrcode-ai-scanner-py/Cargo.toml"
+
+[tool.maturin.generate-ci.github]
+trusted-publishing = true

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/Cargo.toml

@@ -0,0 +1,57 @@
+[package]
+name = "qrcode-ai-scanner"
+description = "QR code decoding and scannability scoring for artistic, AI-generated, and photo-captured QR codes"
+keywords = ["qrcode", "qr", "scanner", "validation", "decoder"]
+categories = ["multimedia::images", "encoding", "computer-vision"]
+readme = "README.md"
+version = "0.3.0"
+edition = "2024"
+rust-version = "1.87.0"
+license = "AGPL-3.0-or-later"
+repository = "https://github.com/supernovae-st/qrcode-ai-scanner"
+authors = ["Thibaut MÉLEN <thibaut@supernovae.studio>", "SuperNovae <contact@supernovae.studio>"]
+
+[features]
+default = ["engine-rxing", "engine-rqrr", "parallel", "serde"]
+# decode engines — at least one is required (compile_error! otherwise)
+engine-rxing = ["dep:rxing"]
+engine-rqrr = ["dep:rqrr"]
+# rayon parallelism — native targets only, keep OFF for wasm
+parallel = ["dep:rayon"]
+# ScanReport (de)serialization — the cross-boundary contract
+serde = ["dep:serde", "dep:base64"]
+
+[dependencies]
+rxing = { version = "^0.9.1", default-features = false, optional = true, features = ["decoders", "multi_barcode_readers", "full_barcode_format_support", "encoding_rs"] }
+rqrr = { version = "^0.10.1", optional = true }
+image = { version = "^0.25", default-features = false, features = ["png", "jpeg", "webp", "gif"] }
+encoding_rs = "^0.8"
+serde = { version = "^1", optional = true, features = ["derive"] }
+base64 = { version = "^0.22", optional = true }
+thiserror = "^2"
+miette = "^7"
+web-time = "^1.1"
+rayon = { version = "^1.10", optional = true }
+
+[dev-dependencies]
+jsonschema = { version = "0.33", default-features = false }
+criterion = { version = "^0.8", features = ["html_reports"] }
+qrcode = "^0.14"
+insta = { version = "^1", features = ["json", "redactions"] }
+proptest = "^1"
+pretty_assertions = "^1"
+serde_json = "^1"
+
+[lints.rust]
+missing_docs = "warn"
+# cargo-fuzz builds the graph with --cfg fuzzing (fuzz-only pub surface)
+unexpected_cfgs = { level = "warn", check-cfg = ["cfg(fuzzing)"] }
+
+[lints.clippy]
+unwrap_used = "deny"
+expect_used = "deny"
+pedantic = { level = "warn", priority = -1 }
+
+[[bench]]
+name = "decode"
+harness = false

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/README.md

@@ -0,0 +1,25 @@
+# qrcode-ai-scanner
+
+QR decoding + scannability scoring for **artistic, AI-generated, and
+photo-captured** QR codes. Deterministic multi-engine ladder (rxing + rqrr),
+score contract v3 (six survival-ramp stress axes incl. perspective/rotation/
+lighting, finder-integrity + quiet-zone caps), and the **synthetic UEC** —
+the ISO 15415 unused-error-correction margin computed from the engine's own
+sampled bitstream. Machine-actionable hints close the generate → scan →
+regenerate loop.
+
+```rust
+use qrcode_ai_scanner::{ImageInput, ScanProfile, Scanner};
+
+let scanner = Scanner::builder().profile(ScanProfile::Full).build();
+let report = scanner.scan(ImageInput::encoded(&bytes))?;
+// report.detections · report.score (value/grade/axes/uec) · report.hints
+```
+
+"No QR found" is `Ok` with empty detections — `Err` is reserved for invalid
+input and cancellation (`QRS-001..005`). Camera frames skip the PNG roundtrip
+via `ImageInput::rgba8`. Full docs: the
+[repository](https://github.com/supernovae-st/qrcode-ai-scanner) —
+`docs/ARCHITECTURE.md` + `docs/SCORING.md`.
+
+License: AGPL-3.0-or-later · © SuperNovae Studio.

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/benches/decode.rs

@@ -0,0 +1,46 @@
+//! Decode + score benchmarks over the committed corpus images.
+//! Local wall-clock reference (criterion); CI regression gating runs the
+//! corpus-report timings on fixed runners instead — see ci.yml.
+
+#![allow(clippy::unwrap_used, clippy::expect_used, missing_docs)]
+
+use criterion::{Criterion, criterion_group, criterion_main};
+use qrcode_ai_scanner::{ImageInput, ScanProfile, Scanner};
+use std::hint::black_box;
+
+fn fixture(rel: &str) -> Vec<u8> {
+    std::fs::read(format!(
+        "{}/../../fixtures/{rel}",
+        env!("CARGO_MANIFEST_DIR")
+    ))
+    .unwrap()
+}
+
+fn bench_decode(c: &mut Criterion) {
+    let clean = fixture("clean/gen_v5_q.png");
+    let artistic = fixture("artistic/OK_1069ms_85_8b6a54b3.png");
+
+    let frame = Scanner::builder().profile(ScanProfile::Frame).build();
+    let fast = Scanner::builder().profile(ScanProfile::Fast).build();
+    let full = Scanner::builder().profile(ScanProfile::Full).build();
+
+    c.bench_function("frame_clean", |b| {
+        b.iter(|| frame.scan(black_box(ImageInput::encoded(&clean))).unwrap());
+    });
+    c.bench_function("fast_clean_scored", |b| {
+        b.iter(|| fast.scan(black_box(ImageInput::encoded(&clean))).unwrap());
+    });
+    c.bench_function("full_artistic", |b| {
+        b.iter(|| {
+            full.scan(black_box(ImageInput::encoded(&artistic)))
+                .unwrap()
+        });
+    });
+}
+
+criterion_group! {
+    name = benches;
+    config = Criterion::default().sample_size(10);
+    targets = bench_decode
+}
+criterion_main!(benches);

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/proptest-regressions/gs1.txt

@@ -0,0 +1,7 @@
+# Seeds for failure cases proptest has generated in the past. It is
+# automatically read and these particular cases re-run before any
+# novel cases are generated.
+#
+# It is recommended to check this file in to source control so that
+# everyone who runs the test benefits from these saved cases.
+cc 409e7ccab8e1538e12bb47ec375084a6fd12bb59ee5a2aec26beb0837dd92157 # shrinks to s = "ࠀ"

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/proptest-regressions/rescue/ee.txt

@@ -0,0 +1,7 @@
+# Seeds for failure cases proptest has generated in the past. It is
+# automatically read and these particular cases re-run before any
+# novel cases are generated.
+#
+# It is recommended to check this file in to source control so that
+# everyone who runs the test benefits from these saved cases.
+cc 5ad5a32402feb81f1d65b31c3cba983189e8c3a56aa42f559b9c4f7e676e48c4 # shrinks to seed = 1, npar = 4

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/src/engine/charset.rs

@@ -0,0 +1,96 @@
+//! Charset resolution for raw decoded bytes — done ONCE here, never per-engine.
+//!
+//! Order: strict UTF-8 → isolated-byte Latin-1 short-circuit → Shift-JIS
+//! (error-free decode) → windows-1252 (never fails).
+//!
+//! The short-circuit is the load-bearing part: most Latin-1 accented bytes
+//! (0x81-0x9F · 0xE0-0xFC) followed by an ASCII letter form a VALID
+//! Shift-JIS kanji pair, so "SJIS decodes error-free" alone garbles the
+//! dominant legacy European class ("Québec" → "Qu饕ec", review-proven).
+//! Real Shift-JIS text has RUNS of non-ASCII bytes (kanji pairs, katakana
+//! sequences); Latin-1 European text has accented bytes ISOLATED between
+//! ASCII. Known residual ambiguity: a single isolated half-width katakana
+//! between ASCII letters now reads as Latin-1 — inherent, documented.
+
+use crate::report::Charset;
+
+/// Every non-ASCII byte sits alone between ASCII neighbours (or string
+/// edges) — the Latin-1-not-SJIS signature.
+fn all_non_ascii_isolated(raw: &[u8]) -> bool {
+    raw.iter().enumerate().all(|(i, b)| {
+        b.is_ascii()
+            || ((i == 0 || raw[i - 1].is_ascii()) && (i + 1 == raw.len() || raw[i + 1].is_ascii()))
+    })
+}
+
+/// Resolve raw payload bytes into text + the charset that produced it.
+pub(crate) fn resolve(raw: &[u8]) -> (String, Charset) {
+    if let Ok(s) = std::str::from_utf8(raw) {
+        return (s.to_owned(), Charset::Utf8);
+    }
+    if all_non_ascii_isolated(raw) {
+        let (text, _, _) = encoding_rs::WINDOWS_1252.decode(raw);
+        return (text.into_owned(), Charset::Latin1);
+    }
+    let (text, _, had_errors) = encoding_rs::SHIFT_JIS.decode(raw);
+    if !had_errors {
+        return (text.into_owned(), Charset::ShiftJis);
+    }
+    let (text, _, _) = encoding_rs::WINDOWS_1252.decode(raw);
+    (text.into_owned(), Charset::Latin1)
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used)]
+
+    use super::*;
+
+    fn windows_1252(s: &str) -> Vec<u8> {
+        let (bytes, _, had_errors) = encoding_rs::WINDOWS_1252.encode(s);
+        assert!(!had_errors);
+        bytes.into_owned()
+    }
+
+    #[test]
+    fn latin1_accented_words_resolve_as_latin1_not_garbled_sjis() {
+        // review-proven garble class: accented byte + ASCII letter forms a
+        // valid SJIS kanji pair ("Québec" read "Qu饕ec" pre-fix)
+        for truth in ["Québec", "señor", "crème brûlée", "café au lait", "Éé"] {
+            let raw = windows_1252(truth);
+            let (text, charset) = resolve(&raw);
+            assert_eq!(text, truth);
+            assert_eq!(charset, Charset::Latin1, "{truth}");
+        }
+    }
+
+    #[test]
+    fn real_shift_jis_runs_still_resolve_as_sjis() {
+        // kanji pairs = consecutive non-ASCII bytes — not isolated
+        let (raw, _, had_errors) = encoding_rs::SHIFT_JIS.encode("日本語テスト");
+        assert!(!had_errors);
+        let (text, charset) = resolve(&raw);
+        assert_eq!(text, "日本語テスト");
+        assert_eq!(charset, Charset::ShiftJis);
+        // mixed ASCII + kanji run keeps the SJIS reading too
+        let (raw, _, _) = encoding_rs::SHIFT_JIS.encode("QR: 漢字");
+        let (text, charset) = resolve(&raw);
+        assert_eq!(text, "QR: 漢字");
+        assert_eq!(charset, Charset::ShiftJis);
+    }
+
+    #[test]
+    fn utf8_always_wins() {
+        let (text, charset) = resolve("déjà 日本".as_bytes());
+        assert_eq!(text, "déjà 日本");
+        assert_eq!(charset, Charset::Utf8);
+    }
+
+    #[test]
+    fn invalid_everywhere_falls_back_to_latin1_lossy() {
+        // 0xFF is outside the SJIS lead ranges → SJIS errors; consecutive
+        // non-ASCII → not isolated → the final lossy Latin-1 fallback
+        let (_, charset) = resolve(&[0xFF, 0xFF]);
+        assert_eq!(charset, Charset::Latin1);
+    }
+}

qrcode_ai_scanner-0.3.0/qrcode-ai-scanner/src/engine/mod.rs

@@ -0,0 +1,278 @@
+//! Decode engines — isolated wrappers around third-party decoders.
+//!
+//! Contract: engines NEVER panic outward (`catch_unwind` boundary), never
+//! decide charset (raw bytes are the truth, resolution happens once here in
+//! `charset`), and only report what they actually measured — no stubs.
+
+pub(crate) mod charset;
+#[cfg(feature = "engine-rqrr")]
+mod rqrr_engine;
+#[cfg(feature = "engine-rxing")]
+mod rxing_engine;
+
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+use crate::input::LumaImage;
+use crate::report::{EcLevel, EngineKind, Point, Symbology};
+
+/// Still-masked codeword bitstream as the engine sampled it (rqrr only) —
+/// feeds the synthetic UEC.
+#[derive(Debug, Clone)]
+pub(crate) struct MaskedStream {
+    /// Packed bits, MSB-first per byte.
+    pub bits: Vec<u8>,
+    /// Stream length in bits.
+    pub bit_len: usize,
+}
+
+/// What an engine actually measured — no stubs, `None` means "not provided".
+#[derive(Debug, Clone)]
+pub(crate) struct RawDetection {
+    /// Symbology the engine read this as.
+    pub symbology: Symbology,
+    /// Decoded payload bytes (charset-independent truth).
+    pub raw: Vec<u8>,
+    /// Raw sampled bitstream when the engine exposes it (rqrr).
+    pub masked_stream: Option<MaskedStream>,
+    /// Symbol corners when the engine provides true bounds (rqrr).
+    pub corners: Option<[Point; 4]>,
+    /// Symbol version 1-40 when measured.
+    pub version: Option<u8>,
+    /// Error-correction level when measured.
+    pub ec: Option<EcLevel>,
+    /// Mask pattern 0-7 when measured.
+    pub mask: Option<u8>,
+    /// FNC1-in-first-position symbol (GS1 formatted data — symbology
+    /// `]Q3`/`]Q4`). Only rxing surfaces this; rqrr cannot decode FNC1
+    /// symbols at all (its mode dispatch rejects indicators 0x5/0x9).
+    pub fnc1: bool,
+    /// Producing engine.
+    pub engine: EngineKind,
+}
+
+/// Aggregated result of one pass over all enabled engines.
+#[derive(Debug, Clone, Default)]
+pub(crate) struct EngineOutcome {
+    /// Every detection from every engine (deduplication is the ladder's job).
+    pub detections: Vec<RawDetection>,
+    /// Grids detected but NOT decoded (rqrr `get_raw_data` ok, RS failed) —
+    /// the S5 rescue inputs. Corners are in ATTEMPT space here.
+    pub rescue: Vec<crate::rescue::RescueCandidate>,
+    /// Engine panics caught and isolated during this pass. NOTE: isolation
+    /// stops the unwind, but the process-global panic HOOK still runs first
+    /// — server embedders see a backtrace on stderr per caught panic
+    /// (suppress via `std::panic::set_hook` in the application if needed;
+    /// a library must not touch the global hook).
+    pub panics: u8,
+}
+
+/// Run a closure with a panic boundary. `None` = the closure panicked.
+fn run_isolated<T>(f: impl FnOnce() -> T) -> Option<T> {
+    catch_unwind(AssertUnwindSafe(f)).ok()
+}
+
+/// Which symbologies a decode pass tries — the cost lever: every extra
+/// format family is another detector walking the image.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum FormatFilter {
+    /// Everything rxing supports + rqrr.
+    All,
+    /// QR · Micro QR · rMQR (+ rqrr) — the artistic-recovery stages are
+    /// QR-calibrated; paying the 1D/PDF417/DataMatrix detectors on every
+    /// deep rung starves the budget for nothing.
+    QrFamily,
+    /// Exactly one symbology — the scoring fast path (30 stress cells ×
+    /// every decoder is 1× vs ~5× scan cost, and a cross-symbology text
+    /// match would be a false survival signal anyway).
+    Only(Symbology),
+}
+
+/// One decode pass: every enabled engine, all symbologies.
+#[cfg(test)]
+pub(crate) fn decode_all(luma: &LumaImage) -> EngineOutcome {
+    decode_filtered(luma, FormatFilter::All)
+}
+
+/// Decode under a format filter.
+pub(crate) fn decode_filtered(luma: &LumaImage, filter: FormatFilter) -> EngineOutcome {
+    let mut outcome = EngineOutcome::default();
+
+    #[cfg(feature = "engine-rxing")]
+    match run_isolated(|| rxing_engine::decode(luma, filter)) {
+        Some(found) => outcome.detections.extend(found),
+        None => outcome.panics += 1,
+    }
+
+    #[cfg(feature = "engine-rqrr")]
+    if matches!(
+        filter,
+        FormatFilter::All | FormatFilter::QrFamily | FormatFilter::Only(Symbology::QrCode)
+    ) {
+        match run_isolated(|| rqrr_engine::decode(luma)) {
+            Some((found, rescue)) => {
+                outcome.detections.extend(found);
+                outcome.rescue.extend(rescue);
+            }
+            None => outcome.panics += 1,
+        }
+    }
+
+    outcome
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::cast_precision_loss)]
+
+    use super::*;
+    use crate::input::LumaImage;
+    use crate::report::{Charset, EcLevel, EngineKind};
+
+    /// Render a QR to luma bytes module-by-module (no image-crate coupling):
+    /// `scale` px per module + 4-module quiet zone. Returns the symbol version.
+    fn qr_luma(content: &[u8], ec: qrcode::EcLevel, scale: u32) -> (LumaImage, u8) {
+        let code = qrcode::QrCode::with_error_correction_level(content, ec).unwrap();
+        let modules = code.width();
+        let colors = code.to_colors();
+        let qz = 4u32;
+        let side = (u32::try_from(modules).unwrap() + 2 * qz) * scale;
+        let mut data = vec![255u8; (side * side) as usize];
+        for my in 0..modules {
+            for mx in 0..modules {
+                if colors[my * modules + mx] == qrcode::Color::Dark {
+                    for dy in 0..scale {
+                        for dx in 0..scale {
+                            let x = (u32::try_from(mx).unwrap() + qz) * scale + dx;
+                            let y = (u32::try_from(my).unwrap() + qz) * scale + dy;
+                            data[(y * side + x) as usize] = 0;
+                        }
+                    }
+                }
+            }
+        }
+        let version = match code.version() {
+            qrcode::Version::Normal(v) => u8::try_from(v).unwrap(),
+            qrcode::Version::Micro(_) => 0,
+        };
+        (LumaImage::new(data, side, side), version)
+    }
+
+    #[cfg(feature = "engine-rxing")]
+    #[test]
+    fn rxing_decodes_utf8_qr_with_text_and_ec() {
+        let payload = "héllo → 🦋";
+        let (luma, _) = qr_luma(payload.as_bytes(), qrcode::EcLevel::Q, 4);
+        let outcome = decode_all(&luma);
+        let d = outcome
+            .detections
+            .iter()
+            .find(|d| d.engine == EngineKind::Rxing)
+            .expect("rxing must decode a clean generated QR");
+        let (text, _) = charset::resolve(&d.raw);
+        assert_eq!(text, payload);
+        assert_eq!(d.raw, payload.as_bytes());
+        assert_eq!(d.ec, Some(EcLevel::Q));
+        assert_eq!(outcome.panics, 0);
+    }
+
+    #[cfg(feature = "engine-rqrr")]
+    #[test]
+    fn rqrr_provides_geometry_version_ec_mask() {
+        let (luma, version) = qr_luma(b"https://qrcode-ai.com/scan", qrcode::EcLevel::Q, 4);
+        let outcome = decode_all(&luma);
+        let d = outcome
+            .detections
+            .iter()
+            .find(|d| d.engine == EngineKind::Rqrr)
+            .expect("rqrr must decode a clean generated QR");
+        assert_eq!(d.version, Some(version));
+        assert_eq!(d.ec, Some(EcLevel::Q), "rqrr ecc_level 0-3 mapping");
+        let mask = d.mask.expect("rqrr reports the mask");
+        assert!(mask <= 7, "mask {mask}");
+        let corners = d.corners.expect("rqrr reports bounds");
+        let side = luma.width() as f32;
+        for p in corners {
+            assert!(
+                p.x >= 0.0 && p.x < side && p.y >= 0.0 && p.y < side,
+                "{p:?}"
+            );
+        }
+    }
+
+    #[cfg(feature = "engine-rqrr")]
+    #[test]
+    fn rqrr_ec_mapping_pinned_on_l_too() {
+        let (luma, _) = qr_luma(b"ec level L pin", qrcode::EcLevel::L, 4);
+        let outcome = decode_all(&luma);
+        let d = outcome
+            .detections
+            .iter()
+            .find(|d| d.engine == EngineKind::Rqrr)
+            .expect("decode");
+        assert_eq!(d.ec, Some(EcLevel::L));
+    }
+
+    #[cfg(all(feature = "engine-rxing", feature = "engine-rqrr"))]
+    #[test]
+    fn engines_agree_on_raw_payload_bytes() {
+        let payload = "parity check 1234";
+        let (luma, _) = qr_luma(payload.as_bytes(), qrcode::EcLevel::M, 4);
+        let outcome = decode_all(&luma);
+        let rxing_raw = outcome
+            .detections
+            .iter()
+            .find(|d| d.engine == EngineKind::Rxing)
+            .map(|d| d.raw.clone())
+            .expect("rxing");
+        let rqrr_raw = outcome
+            .detections
+            .iter()
+            .find(|d| d.engine == EngineKind::Rqrr)
+            .map(|d| d.raw.clone())
+            .expect("rqrr");
+        assert_eq!(rxing_raw, rqrr_raw);
+        assert_eq!(rxing_raw, payload.as_bytes());
+    }
+
+    #[cfg(feature = "engine-rqrr")]
+    #[test]
+    fn latin1_byte_mode_payload_resolves_via_raw_path() {
+        // "Éé" in windows-1252 — invalid UTF-8, the rqrr decode() trap case.
+        let (luma, _) = qr_luma(&[0xC9, 0xE9], qrcode::EcLevel::M, 4);
+        let outcome = decode_all(&luma);
+        let d = outcome
+            .detections
+            .iter()
+            .find(|d| d.engine == EngineKind::Rqrr)
+            .expect("rqrr must decode byte-mode latin1");
+        assert_eq!(d.raw, vec![0xC9, 0xE9]);
+        let (text, cs) = charset::resolve(&d.raw);
+        assert_eq!(text, "Éé");
+        assert_eq!(cs, Charset::Latin1);
+    }
+
+    #[test]
+    fn charset_resolution_order_utf8_sjis_latin1() {
+        let (t, c) = charset::resolve("plain ascii".as_bytes());
+        assert_eq!((t.as_str(), c), ("plain ascii", Charset::Utf8));
+
+        let (t, c) = charset::resolve("héllo🦋".as_bytes());
+        assert_eq!((t.as_str(), c), ("héllo🦋", Charset::Utf8));
+
+        // こんにちは in Shift-JIS
+        let sjis: &[u8] = &[0x82, 0xB1, 0x82, 0xF1, 0x82, 0xC9, 0x82, 0xBF, 0x82, 0xCD];
+        let (t, c) = charset::resolve(sjis);
+        assert_eq!((t.as_str(), c), ("こんにちは", Charset::ShiftJis));
+
+        let (t, c) = charset::resolve(&[0xC9, 0xE9]);
+        assert_eq!((t.as_str(), c), ("Éé", Charset::Latin1));
+    }
+
+    #[test]
+    fn panics_are_isolated_not_propagated() {
+        let caught: Option<u8> = run_isolated(|| panic!("engine exploded"));
+        assert!(caught.is_none());
+        let fine = run_isolated(|| 7u8);
+        assert_eq!(fine, Some(7));
+    }
+}