chore(release): v0.18.0

New engines, each calibrated on its TC260 USCC cohort and validated by a
full-corpus sweep (42009 files):
- runninghub: top-left corner (new corner="tl"), faint mid-gray text via
  the new raw-grayscale "gray" detection front-end, anchor-position gate
- baidu: text-run-only template (pill is a bright-blob magnet), load-bearing
  Doubao+Qwen rival margins, corner-extended footprint for the white tag
- liblib: bottom-center (new corner="bc"), Arial silhouette (font is the
  discriminative lever against latin UI text), logo-extended footprint

Qingyan parked (no clean-arm separation at any render/box), MiniMax/Hailuo
parked (1 visible frame, the xinghui rule); silhouettes kept as starting
points.

CLAUDE.md

@@ -4,7 +4,7 @@ You are a **principal Python engineer** maintaining a CLI tool and library for r
 
 ## Scope and non-goals
 
-The mission is removing **AI-provenance watermarks** that a platform stamps onto content the user generated themselves — SynthID, the Gemini / Nano Banana sparkle, the Doubao / Jimeng / Samsung visible AI labels, the Chinese TC260 "由…AI生成" label, and C2PA / IPTC / EXIF "Made with AI" metadata. The point is user autonomy over their own generated output.
+The mission is removing **AI-provenance watermarks** that a platform stamps onto content the user generated themselves — SynthID, the Gemini / Nano Banana sparkle, the Doubao / Jimeng / Qwen / Samsung visible AI labels, the Chinese TC260 "由…AI生成" label, and C2PA / IPTC / EXIF "Made with AI" metadata. The point is user autonomy over their own generated output.
 
 It deliberately does **not** remove watermarks that protect someone else's paid or copyrighted content — stock-agency overlays (Shutterstock, Getty, iStock, Adobe Stock), classifieds-site marks, or any tiled / diagonal "preview" watermark whose job is to gate a purchase. Stripping those makes a paid resource free off someone else's work; out of scope **by principle, not by technical difficulty**. The line: a visible mark is in scope when it labels the user's **own** AI generation, and out of scope when it protects a **third party's paid asset**.
 
@@ -17,16 +17,16 @@ Consequences for contributors (do not drift back into the stock niche just becau
 
 ## How to run
 
-Per-command exit-code semantics (the no-signal / GPU-missing skip branches), test traps, and regression-guard paths live in `docs/module-internals.md` (section "CLI commands (`cli.py`)") — read it before changing any command's skip/exit behavior.
+Per-command exit-code semantics (the no-signal / GPU-missing skip branches), test traps, and regression-guard paths live in `docs/module-internals.md` (section "CLI commands (`cli.py`)") — read it before changing any command's skip/exit behavior. Every single-image command's `source` argument declares `dir_okay=False`: without it `click.Path(exists=True)` accepts a directory, which then reached `open()` and raised `IsADirectoryError` (Tier E, 2026-07-20; `batch`'s `directory` already declared `file_okay=False`). Regression: `tests/test_cli_robustness.py::TestDirectoryInputIsRejected`.
 
-- `uv run remove-ai-watermarks all <image.png> -o <output.png>` — full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible`, plus the visible-pass `--inpaint/--no-inpaint`/`--inpaint-method`. Skips step 2 (invisible/SynthID) when the `[gpu]` extra is absent or no invisible signal is detectable; see the module doc for the distinct exit codes.
-- `uv run remove-ai-watermarks invisible <image.png> -o <out.png>` — diffusion SynthID removal. **Full knob set** (kept identical across `invisible`/`all`/`batch`): `--strength` (vendor-adaptive default), `--steps`, `--guidance-scale` (CFG, default 7.5), `--pipeline sdxl|controlnet|qwen` (default `controlnet`; `qwen` is a manual opt-in only — see the qwen note in the module map), `--controlnet-scale`, `--model` (HF model id, default SDXL base), `--device`, `--seed`, `--hf-token`, `--max-resolution`/`--min-resolution`, `--upscaler lanczos|esrgan`, `--humanize` (Analog Humanizer grain), `--unsharp` (final sharpen), `--adaptive-polish/--no-adaptive-polish` (**ON by default**), `--tile/--no-tile` + `--tile-size`/`--tile-overlap` (**OFF by default**), `--force/--no-force` (default skip = ON, runs the scrub even with no detected signal). `--auto` is deprecated and a no-op that only warns. Skips the diffusion when no invisible signal is detectable (the no-signal gate); see the module doc.
-- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — known-visible-mark removal. `--method auto` (default) uses reverse-alpha for the capture marks (recovers exact pixels, CPU, no GPU -- measured cleaner + lighter than inpaint on them) and inpaint only for the capture-less pill; `--method reverse-alpha|inpaint` forces one (inpaint uses MI-GAN with the `migan` extra, else cv2). `--mark auto` (default) removes EVERY detected mark in one pass (a Jimeng-basic image carries the top-left "AI生成" pill AND the bottom-right "★ 即梦AI" wordmark) from: Gemini sparkle, Doubao "豆包AI生成", Jimeng "★ 即梦AI", Samsung Galaxy AI "✦ Contenuti generati dall'AI", and the capture-less Jimeng "AI生成" pill (top-left, metadata-gated); `--mark gemini|doubao|jimeng|samsung|jimeng_pill` forces one. For arbitrary logos/objects use `erase`. When no known mark is detected the command writes no output and exits with the no-visible-mark code instead of re-serving the input; `--no-detect` forces the gemini fallback and proceeds. See the module doc for the routing/exit detail. `--method` is shared across `visible`/`all`/`batch`.
+- `uv run remove-ai-watermarks all <image.png> -o <output.png>` — full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible`, plus the visible-pass `--backend auto|cv2|migan|lama` (default `auto`) and `--sensitivity auto|strict` (default `auto`) for the localize -> fill visible removal (see the `visible` bullet). Skips step 2 (invisible/SynthID) when the `[gpu]` extra is absent or no invisible signal is detectable; see the module doc for the distinct exit codes.
+- `uv run remove-ai-watermarks invisible <image.png> -o <out.png>` — diffusion SynthID removal. **Full knob set** (kept identical across `invisible`/`all`/`batch`): `--strength` (vendor-adaptive default), `--steps` (**interacts with `--strength`**: diffusers derives its timesteps as `int(steps * strength)`, so a low `--steps` used to crash inside torch with `cannot reshape tensor of 0 elements` -- at the default 0.15 that was every value below 7. `noai/watermark_profiles.viable_steps` now raises the count to the minimum that denoises and logs the adjustment; keep the guard where it is, above `_generate_one`, so all three pipelines and the tiled path inherit it), `--guidance-scale` (CFG, default 7.5), `--pipeline sdxl|controlnet|qwen` (default `controlnet`; `qwen` is a manual opt-in only — see the qwen note in the module map), `--controlnet-scale`, `--model` (HF model id, default SDXL base), `--device`, `--seed`, `--hf-token`, `--max-resolution`/`--min-resolution`, `--upscaler lanczos|esrgan`, `--humanize` (Analog Humanizer grain), `--unsharp` (final sharpen), `--adaptive-polish/--no-adaptive-polish` (**ON by default**), `--tile/--no-tile` + `--tile-size`/`--tile-overlap` (**OFF by default**), `--force/--no-force` (default skip = ON, runs the scrub even with no detected signal). `--auto` is deprecated and a no-op that only warns. Skips the diffusion when no invisible signal is detectable (the no-signal gate); see the module doc.
+- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — known-visible-mark removal by **localize -> fill**: each detected mark is localized to a binary full-frame footprint mask, then one shared, swappable fill inpaints that mask. `--backend auto|cv2|migan|lama` (default `auto`) picks the fill: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, light, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available. `--mark auto` (default) removes EVERY detected mark in one pass (a Jimeng-basic image carries the top-left "AI生成" pill AND the bottom-right "★ 即梦AI" wordmark) from: Gemini sparkle, Doubao "豆包AI生成", Jimeng "★ 即梦AI", Qwen "千问AI生成", Samsung Galaxy AI "✦ Contenuti generati dall'AI", Baidu "百度 AI生成", LibLibAI wordmark (bottom-center), RunningHub "RunningHub AI生成" (top-left), and the capture-less Jimeng "AI生成" pill (top-left, metadata-gated); `--mark gemini|doubao|jimeng|qwen|kling|samsung|baidu|liblib|runninghub|jimeng_pill` forces one. `--sensitivity auto|strict` (default `auto`) sets how hard a borderline mark is trusted: `auto` relaxes a mark's gate only on same-product evidence (metadata provenance for that vendor, or a confidently detected sibling mark of the same product — clean images stay untouched); `strict` never relaxes. Metadata provenance is read automatically and feeds `auto`. (`assume-ai` was REMOVED in 0.16 — see the registry bullet; a user who can SEE a missed mark should point at it with `erase --region`, or name it with `--mark <text-mark> --no-detect`.) For arbitrary logos/objects use `erase`. When no known mark is detected the command writes no output and exits with the no-visible-mark code instead of re-serving the input; `--no-detect` forces the gemini fallback and proceeds. See the module doc for the routing/exit detail. `--backend` and `--sensitivity` are shared across `visible`/`all`/`batch`.
 - `uv run remove-ai-watermarks erase <image.png> --region x,y,w,h -o <out.png>` — universal region eraser (any logo/object, any position). `--backend cv2` (default, no deps), `--backend migan` (MI-GAN via onnxruntime, extra `migan`; ~28 MB, ~1 GB RAM, near-LaMa), or `--backend lama` (big-LaMa, extra `lama`; best quality but ~4.7 GB RAM); `--region` is repeatable.
 - `uv run remove-ai-watermarks identify <image>` — provenance verdict (platform + watermark inventory + confidence); `--json` for machine output, `--no-visible` to skip the cv2 sparkle detector
 - `uv run remove-ai-watermarks metadata <image.png> --check` — inspect AI metadata (C2PA, EXIF, PNG chunks)
 - `uv run remove-ai-watermarks metadata <image.png> --remove -o <out.png>` — strip all AI metadata
-- `uv run remove-ai-watermarks batch <directory>` — process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the full `invisible` knob set above, plus `--inpaint/--no-inpaint` for the visible pass. Applies the same no-signal skip per image; see the module doc.
+- `uv run remove-ai-watermarks batch <directory>` — process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the full `invisible` knob set above, plus `--backend` and `--sensitivity` for the visible localize -> fill pass. Applies the same no-signal skip per image; see the module doc. **Exit code:** non-zero when any image errored OR (mirroring single `all`) a `--mode invisible`/`all` image carried an invisible signal but the GPU extra was absent, so its SynthID scrub was skipped — it emits a loud warning and copies the input through (invisible mode) so the output dir stays complete; a wrapping service can then detect the incomplete run instead of trusting a silent exit 0.
 
 ## Test and lint
 
@@ -53,22 +53,28 @@ Per-command exit-code semantics (the no-signal / GPU-missing skip branches), tes
 Compact map. The full per-module detail (design decisions, tuned thresholds, calibration history, incident records, and the regression-guard map) lives in `docs/module-internals.md` — **read the relevant section there before changing any module below.**
 
 - `noai/c2pa.py` — C2PA reading. `extract_c2pa_info(path)` uses the official **c2pa-python `Reader`** first (core dep, any container; `read_manifest_store_json` returns the WHOLE store JSON — active + ingredient manifests — so an AI marker on a parent manifest is seen), and falls back to the hand-rolled caBX/CBOR parser (`has_c2pa_metadata` / `extract_c2pa_chunk` / `_extract_c2pa_info_png`) for synthetic/partial blobs the validator rejects or a broken/absent wheel. The registry scan (issuer / source-type / SynthID / soft-binding) is shared by both paths via `_populate_registry_fields`, so the return-dict shape is identical. Do not reimplement chunk parsing; chunk reads are clamped to the remaining file size by design. `extract_c2pa_chunk`/`inject_c2pa_chunk` stay PNG-only (raw caBX bytes, test/extractor use).
-- `noai/constants.py` — the single `C2PA_AI_VENDORS` registry (+ `C2PA_SOFT_BINDINGS`) from which `C2PA_ISSUERS` / `SYNTHID_C2PA_ISSUERS` / `identify._ISSUER_PLATFORM` are all derived. Add a new vendor as one registry entry; never edit the derived dicts and never add inline.
-- `metadata.py` — `scan_head(path)` is the shared (memoized) input for every C2PA/AIGC/IPTC byte scan; use it instead of `open().read(1MB)` for any new marker scan. Also home to `synthid_source`, `xai_signature`, `iptc_ai_system`, `aigc_label`, `huggingface_job`, `samsung_genai`, and `remove_ai_metadata` (fail-safe `strip_c2pa_boxes`). `exif_generator` matches a VALUE against `AI_GENERATOR_TOKENS` across EXIF `Software`/`Make`/`Artist`/`ImageDescription`, XMP `CreatorTool`, AND PNG `tEXt` chunks (`Software`/`Source`/`Title`/`Description` — NovelAI stamps there, not EXIF). **Detection and removal must stay in parity:** a generator that stamps an AI-shaped VALUE under a non-AI KEY (NovelAI's `Title`/`Source`) is dropped on removal by `_is_ai_value` (value-token match, mirrors `exif_generator`), NOT by `_is_ai_key` alone — else the cleaned file still reads as that generator. Add a new no-C2PA generator = one `AI_GENERATOR_TOKENS` entry (use a distinctive token, e.g. `reve.com` not bare `reve`); detection and removal then both follow. Regression: `tests/test_metadata.py::TestExifGenerator::{test_novelai_png_text_chunk_detected,test_novelai_removal_parity}`.
-- `identify.py` — aggregates every locally-readable signal into one `ProvenanceReport`; `is_ai_generated` is True or None, never asserted False. `ProvenanceReport.ai_source_kind` exposes the C2PA digital-source-type split — `"generated"` (trainedAlgorithmicMedia, fully AI) vs `"enhanced"` (compositeWithTrainedAlgorithmicMedia, a real photo with an AI-composited region), else None — so a caller branches full-frame scrub vs region-targeted clean (see `noai/tiling.feather_region_composite` + `WatermarkRemover.remove_watermark(region=...)`). The sparkle provenance threshold is the SHARED `watermark_registry.GEMINI_SPARKLE_TRUST_CONF` (imported, not a private copy) so the provenance "is there a sparkle" verdict and the removal "take the sparkle" decision can never drift. `import identify` is deliberately light (lazy `noai/__init__`, fits a 512 MB host) — keep heavy imports out (the `watermark_registry` constant import stays light: engines are lazy there). Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM` only when verified against a real C2PA file; editing-app/AI-device signer tokens go to `_SIGNER_C2PA_PLATFORM`; generator/issuer platforms to `C2PA_AI_VENDORS` in `constants.py`. Integrity-clash detection is high-precision by design (only hard generator stamps feed it, source-grouped independence).
-- `watermark_registry.py` — the single catalog of known visible watermarks (gemini / doubao / jimeng / samsung / jimeng_pill). **`--mark auto` removes EVERY detected mark in one pass** via `remove_auto_marks` (marks coexist -- a Jimeng-basic image has the top-left pill AND the bottom-right wordmark; `best_auto_mark` single-strongest would leave one). **The `jimeng_pill` is CAPTURE-LESS** (`has_capture=False`, `pill_engine.py`): the top-left "AI生成" label has no alpha map, so it is detect-by-synthetic-silhouette + inpaint-only (every method resolves to inpaint). Its weak edge-NCC detector (~7% raw false-fire) is gated in `remove_auto_marks` via **`_keep_pill`** (32k real-upload corpus validation 2026-07): the pill never rides on a **Doubao** detection, and has **two confirmation arms** because metadata confirms the platform, not pill presence. **(1) Bottom-right "★ 即梦AI" wordmark fired** — ~94% precise and survives **metadata-STRIPPED uploads** (screenshots / re-saves, ~61% of pills carry a detectable wordmark): remove **unrestricted**. **(2) TC260 metadata only** (CLI `_aigc_metadata_present` → `pill_metadata`, no wordmark) — only ~27% precise, its false fires are **textured ceilings/walls that inpaint visibly SMEARS**, so remove **only when the top-left footprint is flat enough for an invisible inpaint** (`pill_engine.footprint_is_flat`, median-Sobel texture ≤ `_FLAT_TEXTURE_MAX`). This keeps real flat-scene pills (incl. metadata-only ones the wordmark misses) plus harmless flat false fires, and leaves the damaging textured false fires untouched. Do NOT drop the wordmark arm or loosen the metadata arm back to a bare metadata-OR gate. **Two removal methods, selected by `KnownMark.remove(method=...)` / CLI `--method`:** `reverse-alpha` recovers exact pixels from the captured alpha map (lighter, better on structured backgrounds), `inpaint` erases the mark footprint (`footprint_mask` → MI-GAN, or cv2 without the `migan` extra). `auto` (default) = `resolve_removal_method`: **reverse-alpha for capture marks, inpaint for capture-less** (deterministic, model-independent). Reverse-alpha is the default where a capture exists because it recovers the true pixels and is measured CLEANER than MI-GAN inpaint on the capture marks (doubao/gemini/jimeng — MI-GAN adds a rainbow/smudge artifact on structure) AND lighter (no model/RAM); inpaint is reserved for the capture-less pill. The inpaint backend is chosen by `preferred_inpaint_backend`: **MI-GAN when its extra is installed, else cv2** — big-LaMa is NOT auto-selected (both run on onnxruntime, so availability cannot express intent; big-LaMa stays an explicit `erase --backend lama` opt-in). The inpaint mask MUST be the full NCC-aligned alpha silhouette (`footprint_mask`), NOT the per-image `extract_mask` signature — the signature under-segments and leaves glyph residue (corpus-validated 2026-07). Add a new **reverse-alpha** text mark = one `_text_mark(...)` row + a `TextMarkConfig` with a captured alpha map; do not re-add per-mark `if` branches. A **capture-less inpaint mark** (no alpha map, like `jimeng_pill`) is instead a `has_capture=False` `KnownMark` + a small engine exposing `detect`/`footprint_mask` (geometry + synthetic silhouette) + a metadata/cross-mark gate for its detector -- this path does NOT need a flat capture (removal quality comes from the inpaint backend, so a font-rendered silhouette is data-safe and sufficient). `cli._write_bgr_with_alpha` must NOT zero alpha in the watermark bbox (issue #30 white-box regression). **A new REVERSE-ALPHA visible mark is HARD-BLOCKED on real controlled flat captures** — the alpha map is solved by `scripts/visible_alpha_solve.py` from solid black + gray (+white) captures of the mark produced by the actual app/device at native resolution, committed under `data/<engine>_capture/captures/`. Do NOT synthesize the alpha by font-rendering the wordmark — the user rejected synthetic reconstruction as below the quality bar (2026-06-22), and per-image alpha falloff/variation needs the real capture. Corpus images are NOT a substitute (data-safety: no corpus-derived committed assets; and reverse-alpha needs the flat capture, not real content). So if no flat capture exists for a mark, the work is parked — do not propose synthetic, do not derive from user uploads. (Meta AI, more Samsung locales, and any Grok visible mark are all parked on this; Grok additionally needs confirming it even HAS a visible mark — its known signal is EXIF-only `xai_signature`.)
-- `gemini_engine.py` — visible Gemini-sparkle remover/detector (cv2/numpy, no GPU): top-K size-weighted fusion candidate selection (`_SELECT_TOPK`), corner-promote, over/under-subtraction guards, false-positive gate, self-verify repair. Detection scores the top-K size-weighted matches by full fusion (spatial+gradient+variance) and keeps the highest — NOT the raw-NCC argmax, which re-admits the tiny-patch FPs the size weight suppresses (the osachub 2026-06-12 sub-0.85 corner-sparkle regression; see `docs/module-internals.md`). Keep the 0.85 corner-promote NCC gate; a margin/chroma-gated lower promote was measured and REJECTED 2026-06-11 (~33% FP on non-Google content). Gate any removal candidate on a physical brightness check, not the detector alone.
-- `_text_mark_engine.py` — shared base for the three reverse-alpha text-mark engines (extracted 2026-06-09); the per-engine modules are config-only subclasses. New text mark = a `TextMarkConfig` + a thin subclass + one registry row. Gemini stays a separate engine (different model).
-- `pill_engine.py` — the CAPTURE-LESS Jimeng-basic "AI生成" pill (top-left, issue #54). No alpha map: `detect` is edge-NCC of a synthetic font-rendered silhouette (`assets/jimeng_pill.png`, regenerate via `scripts/render_pill_silhouette.py`; committed, data-safe -- corpus stays out of the repo) in the top-left ROI, calibrated on 61 local real positives to threshold 0.22; `footprint_mask` is a generous FIXED top-left geometry box (NOT the NCC match position -- the synthetic silhouette localizes only approximately, the corner is negative space, so a geometry box removes cleanly while a match box leaves outline residue). `footprint_texture`/`footprint_is_flat` (median-Sobel over that box, `_FLAT_TEXTURE_MAX`) back the metadata-only safe-inpaint gate. Removal is inpaint-only (MI-GAN/cv2). Detector precision is weak (~7% raw false-fire), so it is registry-gated in `remove_auto_marks` via `_keep_pill`: never on Doubao; the bottom-right wordmark removes it unrestricted (~94% precise, survives metadata-STRIPPED uploads); TC260-metadata-only removes it ONLY on a flat footprint (its textured false fires -- ceilings/walls -- are what inpaint smears). Do NOT loosen those gates.
-- `doubao_engine.py` / `jimeng_engine.py` / `samsung_engine.py` — thin `TextMarkEngine` subclasses: Doubao "豆包AI生成" (bottom-right), Jimeng "★ 即梦AI" (bottom-right), Samsung Galaxy AI "✦ Contenuti generati dall'AI" (bottom-LEFT, locale-specific — Italian variant calibrated). Removal = reverse-alpha (always-align) + thin residual inpaint, **with an over-subtraction guard ported from `gemini_engine` (2026-06-20)**: `_reverse_alpha_oversubtracts` predicts the reverse-alpha output PER PIXEL over the glyph body from the INPUT, and when the recovered body lands more than `_OVERSUB_DARK_MARGIN` (25) gray levels below the local ring it abandons the reverse-alpha pixels and inpaints the footprint from the original surroundings (`_inpaint_footprint`) — fixing the dark-pit ghost on dark/mid-tone backgrounds (roadmap P0#8). Predicting per-pixel from the input (not the produced output) keeps a clean full-strength mark byte-identical (no false trip). A detector-only removal test is insufficient — assert visual residual (the textured-shift tests + `tests/test_text_mark_oversubtraction.py`).
-- `region_eraser.py` — universal region eraser (`erase` CLI) and the inpaint backend for the visible-mark fallback. Three backends: `cv2` (default, no deps), `migan` (MI-GAN ONNX, extra `migan`, MIT, ~28 MB / ~0.95 GB peak / ~0.19 s — the droplet-friendly tier, **the preferred backend for the auto inpaint fallback** via `watermark_registry.preferred_inpaint_backend`), `lama` (big-LaMa ONNX, extra `lama`, ~200 MB / ~4.7 GB peak — best quality, does not fit a minimal droplet, explicit opt-in only). **MI-GAN mask polarity is INVERTED** (0=hole/255=known) vs this package's 255-erase convention; `erase_migan` inverts before feeding the model (feeding 255=hole regenerates the whole frame into stripes — corpus-validated). Both ONNX models download on first use, never bundled.
+- `noai/constants.py` — the single `C2PA_AI_VENDORS` registry (+ `C2PA_SOFT_BINDINGS`) from which `C2PA_ISSUERS` / `SYNTHID_C2PA_ISSUERS` / `C2PA_IDENTITY_AI_ORGS` / `identify._ISSUER_PLATFORM` are all derived. Add a new vendor as one registry entry; never edit the derived dicts and never add inline. A vendor's `asserts_ai=True` flag means its mere presence asserts AI generation even without a `trainedAlgorithmicMedia` digital-source-type (a pure-generator brand with a distinctive issuer/generator string, e.g. **Dreamina** — ByteDance's international Jimeng brand, signed as "Bytedance Pte. Ltd." with a "Dreamina/x.y" claim generator and no source-type); NEVER set it for common-word issuers (Adobe/Google/OpenAI/Microsoft) that appear incidentally in unrelated bytes — those stay source-type-gated in `identify._attribute_platform`.
+- `metadata.py` — `scan_head(path)` is the shared (memoized) input for every C2PA/AIGC/IPTC byte scan; use it instead of `open().read(1MB)` for any new marker scan. Also home to `synthid_source`, `xai_signature`, `iptc_ai_system`, `aigc_label`, `huggingface_job`, `samsung_genai`, and `remove_ai_metadata` (fail-safe `strip_c2pa_boxes`). **A caller that REPORTS an outcome must use `strip_and_verify`, not `remove_ai_metadata` directly** -- the stripper is deliberately fail-safe (a file PIL cannot decode is copied through UNCHANGED rather than crashing), so its return value cannot distinguish a no-op from a real strip. `metadata --remove` and `batch --mode metadata|all` both re-scan the OUTPUT through it and fail loudly; corpus-observed on real Samsung Galaxy S22 C2PA PNGs, where the command printed "stripped" and exited 0 while the output still read as AI (2026-07-19). **`remove_ai_metadata` is the SINGLE metadata stripper** (the legacy PIL-re-encoding `noai/cleaner` was deleted; the diffusion core and the public `noai.remove_ai_metadata` re-export now point here). It strips **losslessly** per container: ISOBMFF (HEIC/AVIF/MP4) blanks tokens / strips boxes in place; **JPEG uses `_strip_jpeg_metadata_lossless`** — a marker-segment walk that drops the AI-bearing APP segments (C2PA APP11; XMP APP1 carrying C2PA, a China-AIGC token, OR an IPTC `digitalSourceType` / 2025.1 AI-disclosure marker; IPTC-IIM APP13) and scrubs AI EXIF tags via piexif, copying the entropy-coded scan verbatim so **the pixels are bit-identical** (no DCT re-encode). **Detection<->removal parity across every marker placement is load-bearing** — anything a scanner flags, the strip must reach, or a re-served file still reads as AI: (a) the APP1-XMP branch of `_jpeg_app_carries_ai` checks the IPTC marker sets too, not only C2PA/AIGC (the Instagram/MidJourney/Meta "Made with AI" `digitalSourceType` lives in XMP, not the APP13 IIM record); (b) a bare `AIGC{...}` / `{"AIGC":{...}}` block in ANY JPEG APP segment — the specific C2PA(APP11)/XMP(APP1)/IPTC(APP13) checks FALL THROUGH to a generic `_is_aigc_exif_value` drop, so a bare AIGC in APP11 (the common real-corpus placement, NOT a C2PA manifest) is caught, not swallowed by the C2PA-only 0xEB branch — plus the same AIGC block in a STANDARD **PNG text chunk** value (e.g. `Description`, which `_is_ai_key` keeps) is dropped on the value; (c) the China TC260 `{"AIGC":{...}}` block in EXIF `UserComment`/`ImageDescription` is scrubbed by `_scrub_ai_exif` (Doubao producer + Tencent service-provider schemas); (d) the Samsung Galaxy AI `PhotoEditor_Re_Edit_Data` trailer past the JPEG EOI is truncated by `_strip_samsung_trailer` (and `samsung_genai` reads the file tail so a multi-MB photo's trailer past the 512 KB quick-scan window is still DETECTED). Pixels stay bit-identical throughout, so a `--strip-metadata` on a q100 removal output does NOT crush it back to q75; PNG/WebP re-saves are pixel-lossless (WebP written at cv2 lossless mode, quality 101 — quality 1-100 is lossy). **The PIL-fallback save format is chosen by the source's CONTENT, not its file extension** (`_sniff_image_format`, and the JPEG-lossless gate is content-gated too): ~2% of real uploads are misnamed (a PNG served as `.jpg` is the common one), and routing on the extension re-encoded a lossless PNG/WebP into a real JPEG — a silent degradation that broke "work with originals" (corpus-measured ~0.9% of files). A **misnamed** lossless source (source-extension format != content) is preserved in its true format; a **correctly-named** source still honors a deliberate output-extension conversion (e.g. `source.png -> output.jpg`). Not yet handled: a 16-bit PNG is downconverted to 8-bit on the PIL re-save (rare; would need a byte-level PNG chunk stripper). Regression: `tests/test_metadata.py::TestHasAiMetadata::test_strip_preserves_lossless_content_with_mismatched_extension`. **`remove_ai_metadata` is fail-safe on an undecodable image:** a truncated/corrupt file (PIL raises `OSError` decoding it; ~0.2% of real uploads) is copied through UNCHANGED rather than crashing a direct library caller (a web worker would 500 on a partial upload), mirroring `strip_c2pa_boxes` — we cannot strip what we cannot parse, but we never raise. Regression: `tests/test_metadata.py::TestHasAiMetadata::test_remove_ai_metadata_failsafe_on_truncated_png`. Regression: `tests/test_metadata.py::TestHasAiMetadata::{test_jpeg_metadata_strip_is_pixel_lossless, test_jpeg_strip_removes_iptc_marker_in_xmp}`, `TestSamsungGenai::{test_remove_strips_post_eoi_trailer, test_detects_trailer_past_scan_window}`, the AIGC-EXIF/bare-APP removal tests, and `tests/test_noai.py::TestISOBMFF::{test_blank_aigc_block_in_exif, test_blank_xai_signature_pair_in_exif}`. `exif_generator` matches a VALUE against `AI_GENERATOR_TOKENS` across EXIF `Software`/`Make`/`Artist`/`ImageDescription`, XMP `CreatorTool`, AND PNG `tEXt` chunks (`Software`/`Source`/`Title`/`Description` — NovelAI Line truncated
+- `identify.py` — aggregates every locally-readable signal into one `ProvenanceReport`; `is_ai_generated` is True or None, never asserted False. `ProvenanceReport.ai_source_kind` exposes the C2PA digital-source-type split — `"generated"` (trainedAlgorithmicMedia, fully AI) vs `"enhanced"` (compositeWithTrainedAlgorithmicMedia, a real photo with an AI-composited region), else None — so a caller branches full-frame scrub vs region-targeted clean (see `noai/tiling.feather_region_composite` + `WatermarkRemover.remove_watermark(region=...)`). The sparkle provenance threshold is the SHARED `watermark_registry.GEMINI_SPARKLE_TRUST_CONF` (imported, not a private copy) so the provenance "is there a sparkle" verdict and the removal "take the sparkle" decision can never drift. `import identify` is deliberately light (lazy `noai/__init__`, fits a 512 MB host) — keep heavy imports out (the `watermark_registry` constant import stays light: engines are lazy there). Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM` only when verified against a real C2PA file; editing-app/AI-device signer tokens go to `_SIGNER_C2PA_PLATFORM`; generator/issuer platforms to `C2PA_AI_VENDORS` in `constants.py`. The IPTC `digitalSourceType` **`algorithmicMedia`** (bare) is PROCEDURAL (an algorithm not trained on sampled data), NOT AI/ML generation, so it is deliberately absent from `IPTC_AI_MARKERS` — flagging it made `identify` assert AI + `has_invisible_target` True, scrubbing clean procedural content (it is a distinct token from `trainedAlgorithmicMedia`, so real "Made with AI" labels are unaffected; regression `test_metadata.py::...test_bare_algorithmic_media_not_flagged_ai`). Integrity-clash detection is high-precision by design (only hard generator stamps feed it, source-grouped independence). `_vendor_of` normalizes ByteDance/Canva/ElevenLabs/Black Forest Labs (as well as OpenAI/Google/... ) so their C2PA claims participate in the clash check; the generic **China TC260 AIGC label names no specific vendor**, so when a TC260-applying vendor (ByteDance, `_TC260_VENDORS`) is co-attributed the label is attributed to it (a legit Doubao image carrying its own TC260 label must NOT clash), while a NON-TC260 vendor next to a TC260 label still clashes as a laundering tell. Corpus-validated: adding the vendors introduced 0 new clashes on 5000 carriers.
+- `watermark_registry.py` — the single catalog of known visible watermarks (gemini / doubao / jimeng / qwen / kling / samsung / runninghub / baidu / liblib / jimeng_pill). **Removal is LOCALIZE -> FILL for every mark:** each mark is localized to a binary full-frame footprint mask (a `Localization`), then ONE shared, swappable fill inpaints that mask via `fill(image, mask, backend=...)` (delegates to `region_eraser.erase`). Reverse-alpha (the old `original = (wm - a*logo)/(1-a)` inversion of a captured alpha map + thin residual inpaint) is GONE for ALL marks; why it was dropped is recorded in `docs/module-internals.md`. Backends: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, light, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available. The captured alpha maps (`scripts/visible_alpha_solve.py`) are still used to DETECT the marks and to shape the mask, but NOT for pixel recovery. **`--mark auto` removes EVERY detected mark in one pass** via `remove_auto_marks(image, *, sensitivity="auto", provenance=frozenset(), backend="auto")` (marks coexist -- a Jimeng-basic image has the top-left pill AND the bottom-right wordmark; a single-strongest pick would leave one). **Three orthogonal axes:** `backend` (the fill), `sensitivity` (how hard to trust a borderline mark: `auto`/`strict`, see the `Sensitivity` literal), and `provenance` (vendor keys metadata confirms -- the evidence that drives `auto`). **Perception / decision / action are separated:** `_build_candidates(image)` runs every detector at BOTH trust levels (strict + relaxed) and packages raw verdicts + features into `Candidate`s (no policy); the pure arbiter `decide(candidates, Context(sensitivity, provenance)) -> [Decision]` makes every keep/drop call (per-mark `resolve_trust` + the assumed-trust floor + the pill gate) with no image/IO, so it is unit-testable in isolation; then each winner is localized -> filled. Do NOT put policy back into the engines (the one exception, the Gemini FP gate, stays in `gemini_engine` because `identify` shares that confidence). `detect_marks(..., provenance=frozenset())` stays strict (identify verdict, precision over recall); `KnownMark.remove/detect/localize(..., provenance: bool)` take the already-resolved boolean. **How `auto` decides (this is metadata-INDEPENDENT for recall):** the visual detectors are pixel-based and need no metadata; the recall gain comes from RELAXING the false-positive gate, not from metadata. `strict` never relaxes (clean images untouched); `auto` relaxes a mark only on same-product evidence -- metadata provenance for that vendor OR a confidently detected sibling mark of the SAME product (`_PRODUCT_OF`; Doubao and Jimeng are both bottom-right ByteDance but distinct products, so they do NOT cross-relax). **`resolve_trust` resolves TWO levels:** `confirmed` bypasses the engine's false-positive gate, and only `confirmed` has evidence naming THAT vendor, which is exactly what the bypass is contracted to require (`GeminiEngine.detect_watermark`'s `trust_provenance` docstring: "external metadata already proves this is a Google generation"). **Historical, kept as the reason the third level is gone:** a removed `assumed` level let `assume_ai` bypass the gate on the bare assertion an image is AI. On its first form that left only the raw 0.35 detector threshold and it fired on **59.8% of 256 genuine camera captures**, filling a phantom sparkle on ~6 of every 10 CLEAN photos; a confidence floor made it tolerable, and the mode was removed outright in 0.16. Corpus-measured 2026-07-16 before removal (400 Google-C2PA positives with metadata hidden; 256 camera-capture negatives): recall strict 55.0% / auto 55.2% / assume_ai 62.8%, false fire 0.0% / 0.0% / 2.3% -- the extra recall was never free. A wrong relaxation only fills a small corner near-losslessly (the localize -> fill benign failure mode), which is what made a SMALL false-fire rate arguable; it was never a licence for a 60% one. Metadata provenance mapping (feeds `auto`, read by `cli._visible_provenance`): Google/Gemini C2PA issuer -> gemini; China-AIGC (TC260) label -> doubao/jimeng; `samsung_genai` -> samsung. **The `jimeng_pill` is CAPTURE-LESS** (`pill_engine.py`): the top-left "AI生成" label has no captured alpha map, so it is detect-by-synthetic-silhouette; its footprint is a fixed top-left geometry box. Its weak edge-NCC detector (~7% raw false-fire) is gated in `remove_auto_marks` via **`_keep_pill`** (32k real-upload corpus validation 2026-07): the pill never rides on a **Doubao**, **Qwen**, **Kling**, **RunningHub** or **Baidu** detection (each of those marks names its own product, and none is Jimeng-basic), and has confirmation arms because metadata/intent confirms the platform, not pill presence. **(1) Bottom-right "★ 即梦AI" wordmark fired** — ~94% precise and survives **metadaLine truncated
+- `gemini_engine.py` — visible Gemini-sparkle detector + localizer (cv2/numpy, no GPU): top-K size-weighted fusion candidate selection (`_SELECT_TOPK`), corner-promote, false-positive gate (the provenance prior relaxes the gate + lowers the trust threshold when a Google/Gemini C2PA issuer confirms the vendor). **White-core rescue:** the FP gate demotes a low-gradient match (soft edges), but a real FAINT sparkle also has soft edges -- so the gate keeps a low-grad match that is a strong (conf ≥ `_SPARKLE_KEEP_CONF` 0.52), bright (margin), near-WHITE-core sparkle (`_core_saturation` ≤ `_SPARKLE_WHITE_SAT` 0.20): a real sparkle core is white, a clean bright corner that shape-matches (sky/sun) is colored. This recovers ~14/20 metadata-stripped faint sparkles under the DEFAULT strict/auto (no flag, no metadata) at ~1.25% clean false-fire (baseline 0.55%); the ~0.51-scoring bright-bg FPs stay demoted (below 0.52). A learned classifier on the SAME features was measured WORSE than the tuned gate (2026-07 tier-1: MLP 86.7% recall vs 90.8% at equal FP), so the heuristic stays; a patch-CNN with richer features is the only lever left (roadmapped P2, low expected value -- the wall is fundamental). Detection scores the top-K size-weighted matches by full fusion (spatial+gradient+variance) and keeps the highest — NOT the raw-NCC argmax, which re-admits the tiny-patch FPs the size weight suppresses (the osachub 2026-06-12 sub-0.85 corner-sparkle regression; see `docs/module-internals.md`). Keep the 0.85 corner-promote NCC gate; a margin/chroma-gated lower promote was measured and REJECTED 2026-06-11 (~33% FP on non-Google content). Removal is localize -> fill: `footprint_mask` returns the sparkle footprint (the captured alpha thresholded LOW so the faint halo is included, then dilated by a sparkle-relative margin), and the shared `watermark_registry.fill` inpaints it. The captured alpha maps are used only to detect and to shape the mask, not for pixel recovery. `detect_sparkle_confidence` reuses a process-wide `_shared_engine()` singleton (lru_cache) — the engine holds only constant assets (captures, alpha maps, a precomputed 16..118 template ladder) and takes the image as an arg, so do NOT reconstruct `GeminiEngine()` per call: that reloaded assets + recomputed alpha maps + rebuilt the template cache on every one of ~34k `identify` calls (−24% on the sparkle path once made a singleton, output byte-identical). `detect_watermark`/`footprint_mask` guard `image.size == 0` before `to_bgr`, and return an empty (detected=False) result when no template scale fits (short side < 16 px), rather than dereferencing an empty candidate list.
+- `_text_mark_engine.py` — shared base for the text-mark engines (extracted 2026-06-09); the per-engine modules are config-only subclasses. Detection still matches the glyph silhouette (NCC, keys on glyph shape). The removal mask is TEMPLATE-FREE: it is the bounding box of the top-hat glyph blob (`extract_mask`), filled solid + dilated, so the shared fill inpaints the whole wordmark rectangle. This drops the fixed alpha-template placement, so a re-rendered or differently-placed mark is still masked; the captured alpha maps are now used only for the detection silhouette, not for removal. New text mark = a `TextMarkConfig` + a thin subclass + one registry row. Gemini stays a separate engine (different model). The corner anchor is `corner` = `br`/`bl`/`tl`/`bc` (tl added 2026-07-22 for runninghub, bc for liblib's centered wordmark); `detect_frontend` is `binary`/`tophat`/`gray` (`gray` = raw-grayscale NCC for the faint mid-gray runninghub mark, added 2026-07-22; contrast-DEPENDENT, so its gates never port). The detection scale ladder is per-mark (`TextMarkConfig.ladder`, default `(0.8, 1.0, 1.25)` -- added 2026-07-21 for qwen's two size modes; the shared default is unchanged for every other mark, and densifying the SHARED ladder was measured and rejected, see `docs/verification-plan.md` B2).
+- `pill_engine.py` — the CAPTURE-LESS Jimeng-basic "AI生成" pill (top-left, issue #54). No alpha map: `detect` is edge-NCC of a synthetic font-rendered silhouette (`assets/jimeng_pill.png`, regenerate via `scripts/render_pill_silhouette.py`; committed, data-safe -- corpus stays out of the repo) in the top-left ROI, calibrated on 61 local real positives to threshold 0.22; `footprint_mask` is a generous FIXED top-left geometry box (NOT the NCC match position -- the synthetic silhouette localizes only approximately, the corner is negative space, so a geometry box fills cleanly while a match box leaves outline residue). `footprint_texture`/`footprint_is_flat` (median-Sobel over that box, `_FLAT_TEXTURE_MAX`) back the metadata-only safe-fill gate. Removal is the shared localize -> fill (MI-GAN/cv2). Detector precision is weak (~7% raw false-fire), so it is registry-gated in `remove_auto_marks` via `_keep_pill`: never on Doubao; the bottom-right wordmark removes it unrestricted (~94% precise, survives metadata-STRIPPED uploads); TC260-metadata-only removes it ONLY on a flat footprint (its textured false fires -- ceilings/walls -- are what the fill smears). Do NOT loosen those gates.
+- `doubao_engine.py` / `jimeng_engine.py` / `samsung_engine.py` — thin `TextMarkEngine` subclasses: Doubao "豆包AI生成" (bottom-right), Jimeng "★ 即梦AI" (bottom-right), Samsung Galaxy AI "✦ Contenuti generati dall'AI" (bottom-LEFT, locale-specific — Italian variant calibrated). Detection matches the glyph silhouette (NCC); removal localizes the glyph blob to a solid dilated box (`extract_mask`) and hands it to the shared fill. Corpus validation: doubao and jimeng localize + remove at ~100% with clean footprints (the filled region blends into its surroundings within a few LAB levels, no color shift, no dark pit); clean images with no vendor signature had 0% false removal. **Samsung detection is calibrated only for the Italian "Contenuti generati dall'AI" string** (a pre-existing limit, unchanged by the localize -> fill refactor but now surfaced because detection gates removal): non-Italian Samsung locales are not detected, and thus not removed, even though the fill mask itself is locale-independent; other locales need their own detection silhouette (the locale string font-rendered + calibrated on real positives), NOT an app capture.
+- `qwen_engine.py` — the Qwen (Alibaba Tongyi Qianwen) "千问AI生成" text mark (bottom-right), registered 2026-07-21 off the 117-frame TC260-producer cohort (`scripts/vendor_cohort_harvest.py` + `scripts/vendor_mark_calibrate.py`; the full calibration record is in `docs/module-internals.md`). Same `TextMarkEngine` subclass shape, but EVERY tuned number is measured on the cohort, not inherited from doubao: `scale_basis=short`, a **per-mark 2-rung `ladder=(0.78, 1.27)`** (the mark sits in two size modes ~0.124/~0.203 of the short side, ratio 1.64 -- wider than the shared ladder's 1.5625 span, so the best single fraction covers only 74.5% and the small mode falls into the comb's collapse zone; `TextMarkConfig.ladder` was added for this, default `(0.8, 1.0, 1.25)` unchanged for every other mark), a fitted locate box (the real mark sits ~0.025 of short off the right edge and doubao's 0.004-margin box clipped the first glyph, 0.73 -> 0.26 NCC), `alpha_height_frac` from the measured 0.260 aspect (not the silhouette's, not doubao's), gate **0.45** (clean p99 0.301; 83 of ~96 eyeballed visible marks fire = 86% recall of visible marks). **STRICT ONLY** (`provenance_ncc_factor` 1.0, no provenance mapping): the sub-gate band is dominated by non-Qwen banners (夸克 strip 0.274, 造点 mark 0.253), so a relaxed arm would be mostly false fills. **No rival margin** (0 cross-fires on 400 doubao / 298 jimeng / 286 clean frames at the gate; a 0.10 margin would cost ~10% of genuine qwen detections). A confident qwen detection suppresses the jimeng pill like doubao's does. Parity: 83/83 real marks detector-clean after cv2 fill. **Calibration trap for the next vendor:** the 2026-07-18 `present: []` clean labels are in the vocabulary of the REGISTERED marks only -- qwen-cohort frames visibly carrying 千问AI生成 sat in the "clean" arm and were its whole top tail (p99 0.69); `vendor_mark_calibrate.load_sets` now excludes every frame in ANY TC260 cohort.
+- `kling_engine.py` — the Kling (Kuaishou 可灵) "可灵AI 3.0" text mark (bottom-right), registered 2026-07-21 off the 30-frame TC260-producer cohort, same playbook as qwen. UNIMODAL at 0.12 of the short side, so it keeps the shared 3-rung ladder and gets a fitted locate box (margins ~0.03/0.023); gate **0.35** (clean p99 0.304 / max 0.320), STRICT ONLY (the faint "Omni"-suffix / latin "KlingAI" / version-less variants score 0.17-0.25, inside the clean arm's top tail -- unreachable, capping recall at ~47% of visible marks, precision 9/9), no rival margin (crossfire 1/400 doubao below gate, 0 jimeng, 0 clean). Parity 9/9. Suppresses the jimeng pill like doubao/qwen. **元宝 (Tencent Yuanbao) was attempted the same day and PARKED as a measured negative** -- its two-line italic-slanted block does not separate from clean corners on either front-end at any render/box setting (full record in `docs/verification-plan.md`); the fitted render recipe stays in `render_vendor_silhouettes.py` `MARK_OPTS` as the starting point for a future structural/learned lever. The **cat-logo** cohort was also probed and parked: 19 frames but only 2 unique carriers, so nothing to calibrate recall against; the `draw_catlogo` silhouette already separates (mark 0.50 vs clean max 0.333) and registration is a gate pick (~0.42) once more unique carriers arrive.
+- `runninghub_engine.py` — the RunningHub "RunningHub AI生成" mark (**top-left**, the first `corner="tl"`), registered 2026-07-22 off the 73-frame TC260 cohort. Faint mid-gray text that the top-hat suppresses to clean-arm levels, so it introduced the **third detection front-end `gray`** (raw-grayscale silhouette NCC, contrast-DEPENDENT, one `_gray_best` method serving detection and mask): positives 0.38-0.54 vs clean max 0.295, gate **0.34**, STRICT ONLY. Two measured traps: the tight ladder `(0.95, 1.0, 1.05)` sits exactly on the measured 0.32-of-width (the comb is razor-sharp: 0.537 on-size vs 0.223 at +5.6%), and an **anchor gate** in `detect` (match must sit at x<=0.025 / y<=0.015 of the frame) kills the 37/42009 full-corpus false fires (hair, shelves, CJK banners) that no NCC threshold separates from the 0.381 positives. Footprint is always the detector's match box (the binary blob under-segments the faint head glyphs and left "Runni" unremoved on the first try).
+- `baidu_engine.py` — the Baidu "百度 AI生成" mark (bottom-right), registered 2026-07-22 off the 16-frame cohort (USCC names Baidu). Detection keys on the 百度 **text run ONLY** (a text+pill template was a measured bright-blob magnet with no separation); the white "AI生成" tag is still removed because the custom `footprint_mask` extends the match box right to the corner (the tag's flat white interior gives no top-hat response, so a blob bbox left it as a ghost). Gate settled at **0.48** after three measured steps (0.37 clean-arm; the 741-eval set fired on 12 Qwen marks + one 抖音 mark, so `rivals=("doubao_alpha.png","qwen_alpha.png")` with load-bearing margins; the full-corpus sweep put true outside-cohort carriers at 0.50-0.66 vs the false arm max 0.47). Cohort 7/16, all true, plus 6 metadata-stripped true carriers the cohort cannot see. STRICT ONLY.
+- `liblib_engine.py` — the LibLibAI (哩布哩布AI) "LibLibAI" wordmark (**bottom-center**, the first `corner="bc"`), registered 2026-07-22 off the 15-frame cohort. The discriminative lever is the silhouette **font**: STHeiti scored the cohort at the false arm's level (latin UI text bands); measured across 7 fonts, **Arial** lifts the cohort to 0.42-0.73 and drops the false arm to max 0.398. Gate **0.42**, STRICT ONLY, plus a per-mark size floor (`_MIN_SHORT_SIDE=480`: the one remaining false fire was a 200x200 icon on a 20px template). Custom footprint = match box extended left ~1.3 glyph heights for the triangle logo (the blob bbox bled into background structure and never owned the logo). **Zhipu Qingyan (清言·AI生成) and MiniMax/Hailuo were attempted the same day and PARKED** as measured negatives (qingyan: cohort 0.34-0.39 vs clean max 0.34-0.37, no separation at any render/box; minimax: 1 of 6 frames visibly marked, the xinghui rule) -- record in `docs/verification-plan.md` ("The 2026-07-22 vendor round").
+- `region_eraser.py` — universal region eraser (`erase` CLI) and the shared fill backend behind `watermark_registry.fill` for the visible localize -> fill removal. Three backends: `cv2` (default, no deps, the floor), `migan` (MI-GAN ONNX, extra `migan`, MIT, ~28 MB / ~0.19 s — the droplet-friendly tier, **the preferred default fill** when the extra is installed), `lama` (big-LaMa ONNX, extra `lama`, ~200 MB / ~4.7 GB peak — best quality, does not fit a minimal droplet, explicit opt-in only). Both `migan` and `lama` **crop a padded region around the mask** before inference and paste only masked pixels back, so peak RAM is bounded by the MARK size, not the image (`migan` ~0.6-0.9 GB regardless of upload size — feeding the whole frame scaled it to ~2.4 GB at 25 MP; `migan` feeds the crop at native resolution, `lama` resizes to its fixed 512²). **Measured end to end 2026-07-20** (`scripts/resource_ceilings.py`, fresh process per cell, 1 MP → 25 MP): `migan` 603 → 775 MB and `lama` 4679 → 4779 MB, both **flat in input size** — the crop-around-the-mask design holds and both documented figures reproduce. **`cv2` is the only backend that GROWS with the input** (74 → 440 MB, 5.9x) because it inpaints the full frame rather than a crop; still the cheapest tier, but size it for the largest upload accepted. Cold wall time 0.02-0.12 s (cv2) / ~0.6 s (migan) / ~3.8 s (lama), model load included. (The harness's own no-op check originally allocated a full-frame temp before reading peak RSS and inflated these by up to 17% at 25 MP; it now compares only the mask box. The conclusion survived re-measurement, the digits moved.) **MI-GAN mask polarity is INVERTED** (0=hole/255=known) vs this package's 255-erase convention; `erase_migan` inverts before feeding the model (feeding 255=hole regenerates the whole frame into stripes — corpus-validated). Both ONNX models download on first use, never bundled. The `erase` command keeps its own `--backend`/`--inpaint-method` (unchanged).
 - `invisible_watermark.py` — decodes the OPEN DWT-DCT watermarks (SD / SDXL / FLUX) via `imwatermark` (extra `detect`, pulls torch). Fragile two ways: (1) does not survive JPEG re-encode/resize; (2) **carrier-fragile on a broad class of pristine images** -- a clean encode->decode round-trip recovers 48/48 on chatgpt/firefly/random but FAILS (28-39/48, below the `_MATCH_48`=44 gate) on the FLUX fox, doubao, a flat FLUX generation, AND a clean synthetic flat fill with no watermark. The failure does NOT track texture; it goes with a degenerate **all-ones decode that is a CARRIER ARTIFACT, not a watermark** (synthetic clean image reproduces it). So `detect_invisible_watermark` is **positive-only**: trust a hit; a `None` is inconclusive unless a same-carrier positive-control embed first recovers >=44. Verified 2026-06-19; full caveat in `docs/watermarking-landscape.md`.
 - `trustmark_detector.py` — Adobe TrustMark open decoder (extra `trustmark`). Do NOT remove the JPEG re-encode false-positive gate — a lone TrustMark hit without it is almost always content noise.
-- `noai/watermark_remover.py` — `WatermarkRemover` with three diffusion pipelines selected by the explicit `pipeline` ctor arg, never inferred from `model_id`: `sdxl` (plain SDXL img2img), `controlnet` (SDXL + canny ControlNet, **the DEFAULT since 2026-06-09**), and `qwen` (Qwen-Image 20B MMDiT img2img, Apache-2.0, CUDA/cloud-class — best **text** preservation (incl. CJK); `_load_qwen_pipeline`/`_run_qwen`, bf16, no MPS fallback; call shape in the pure `_build_qwen_kwargs` using `true_cfg_scale`). Removal comes from the img2img `strength`; ControlNet only preserves text/face STRUCTURE — SynthID CAN survive controlnet on photoreal content at low strength. Qwen CERTIFIED oracle floors (2026-06-20): OpenAI **0.10** (seed-robust, clean on seeds 0-4), Gemini **0.25** (seed 0 verified, pin a seed — Gemini oracle rate-limits volume; higher than the controlnet Gemini floor 0.15). `resolve_strength(..., pipeline="qwen")` carries the Qwen ladder (`_QWEN_VENDOR_STRENGTH`), so `--pipeline qwen` gets the 0.25 Gemini floor automatically (the old manual `--strength 0.25` workaround is retired). `_build_qwen_kwargs` passes an explicit `height`/`width` from the input (floored to /16 via `_qwen_target_size`) — without it the pipeline defaults to a 1024x1024 SQUARE and silently squishes non-square inputs (fixed 2026-06-20). **`qwen` is a MANUAL opt-in only — there is NO auto-router.** Measured (`scripts/fidelity_metrics.py`, OCR-CER / ArcFace / LPIPS / Laplacian-var, NOT eyeball): qwen beats controlnet on ONE niche only — **clean body text on a plain background, no faces** (openai_1/2 CER 0.241 vs 0.385). controlnet wins FACES (it always has) AND **display/decorative text in a scene** (abba poster: controlnet CER 0.114 vs qwen 0.379 — canny holds letter shapes, qwen re-renders and garbles them). So a content `--pipeline auto` router and a faces+text **mixed dual-pass** were prototyped and **DROPPED** (2026-06-20): on the canonical faces+text case controlnet wins every metric incl. text, so mixed loses; and "text→qwen" can't be auto-decided (it is body-vs-display text that matters, undetectable cheaply). qwen stays for callers who KNOW their content is clean-text-heavy and face-free. No face-restore extra ships, by validated decision (every restore approach looked MORE AI-generated). `remove_watermark(region=(x,y,w,h), region_feather=...)` runs the regeneration but feather-composites only the AI box back over the original (via `noai/tiling.feather_region_composite`), preserving the real photo elsewhere — the **AI-enhanced composite** path (`identify` `ai_source_kind == "enhanced"`); the box is supplied by the caller (a C2PA composite manifest carries no reliable machine-readable region, so we do not fabricate one).
+- `noai/watermark_remover.py` — `WatermarkRemover` with three diffusion pipelines selected by the explicit `pipeline` ctor arg, never inferred from `model_id`: `sdxl` (plain SDXL img2img), `controlnet` (SDXL + canny ControlNet, **the DEFAULT since 2026-06-09**), and `qwen` (Qwen-Image 20B MMDiT img2img, Apache-2.0, CUDA/cloud-class — best **text** preservation (incl. CJK); `_load_qwen_pipeline`/`_run_qwen`, bf16, no MPS fallback; call shape in the pure `_build_qwen_kwargs` using `true_cfg_scale`). Removal comes from the img2img `strength`; ControlNet only preserves text/face STRUCTURE — SynthID CAN survive controlnet on photoreal content at low strength. **Both SDXL loaders (`_load_pipeline`, `_load_controlnet_pipeline`) pass `add_watermarker=False`** — diffusers otherwise embeds an open "Stable Diffusion XL" DWT-DCT invisible watermark on EVERY SDXL output whenever `invisible-watermark` is installed (the `detect` extra), so a watermark REMOVER would re-stamp a detectable AI watermark and the cleaned output re-reads as AI (`identify` → "Open invisible watermark: Stable Diffusion XL"; corpus-observed on the SynthID sample before the fix). Only the pipeline accepts the kwarg, not the `ControlNetModel` sub-model; qwen is not SDXL and has no such watermarker. Regression: `tests/test_platform.py::TestNoReembeddedWatermark`. Qwen CERTIFIED oracle floors (2026-06-20): OpenAI **0.10** (seed-robust, clean on seeds 0-4), Gemini **0.25** (seed 0 verified, pin a seed — Gemini oracle rate-limits volume; higher than the controlnet Gemini floor 0.15). `resolve_strength(..., pipeline="qwen")` carries the Qwen ladder (`_QWEN_VENDOR_STRENGTH`), so `--pipeline qwen` gets the 0.25 Gemini floor automatically (the old manual `--strength 0.25` workaround is retired). `_build_qwen_kwargs` passes an explicit `height`/`width` from the input (floored to /16 via `_qwen_target_size`) — without it the pipeline defaults to a 1024x1024 SQUARE and silently squishes non-square inputs (fixed 2026-06-20). **`qwen` is a MANUAL opt-in only — there is NO auto-router.** Measured (`scripts/fidelity_metrics.py`, OCR-CER / ArcFace / LPIPS / Laplacian-var, NOT eyeball): qwen beats controlnet on ONE niche only — **clean body text on a plain background, no faces** (openai_1/2 CER 0.241 vs 0.385). controlnet wins FACES (it always has) AND **display/decorative text in a scene** (abba poster: controlnet CER 0.114 vs qwen 0.379 — canny holds letter shapes, qwen re-renders and garbles them). So a content `--pipeline auto` router and a faces+text **mixed dual-pass** were prototyped and **DROPPED** (2026-06-20): on the canonical faces+text case controlnet wins every metric incl. text, so mixed loses; and "text→qwen" can't be auto-decided (it is body-vs-display text that matters, undetectable cheaply). qwen stays for callers who KNOW their content is clean-text-heavy and face-free. No face-restore extra ships, by validated decision (every restore approach looked MORE AI-generated). `remove_watermark(region=(x,y,w,h), region_feather=...)` runs the regeneration but feather-composites only the AI box back over the original (via `noai/tiling.feather_region_composite`), preserving the real photo elsewhere — the **AI-enhanced composite** path (`identify` `ai_source_kind == "enhanced"`); the box is supplied by the caller (a C2PA composite manifest carries no reliable machine-readable region, so we do not fabricate one).
 - `noai/tiling.py` — sliding-window tiled diffusion for large inputs (CLI `--tile`). `WatermarkRemover.remove_watermark` branches to `run_tiled` when `tile` is set AND the long side exceeds `tile_size`, refactoring the single-pass `_generate` into a per-tile `_generate_one` (the ControlNet edge map is rebuilt per tile inside it). Pure helpers `plan_tiles` (uniform-size tiles, last one flush to the edge) and `feather_weights` (strictly-positive separable taper -> partition-of-unity blend) are unit-tested without the model. Also home to `feather_region_composite(base, regenerated, box, *, feather)` — the pure region-targeted compositor for **AI-enhanced composites** (`ai_source_kind == "enhanced"`): blends the regenerated AI box back over the original with a feathered seam, leaving the real photo OUTSIDE the box pixel-exact. It backs `WatermarkRemover.remove_watermark(region=...)` (regenerate ONLY the AI region, not the whole frame); the no-model lossless region path stays `region_eraser.erase`. New tile/region-blend tuning goes in these pure helpers; do not inline blend math into the runner.
 - `auto_config.py` + the content-detection layer were REMOVED 2026-06-09; `--auto` is a deprecated no-op (controlnet is the default pipeline and the adaptive polish is ON by default and self-gates to a no-op where there is no detail deficit).
 - `upscaler.py` — optional Real-ESRGAN pre-diffusion super-resolution for small inputs (extra `esrgan`, spandrel only). Manual opt-in; the default `--upscaler` stays `lanczos` and the engine always falls back to Lanczos on absence/error. ESRGAN can degrade faces and thin text.
-- `image_io.py` — Unicode-safe cv2 IO (issue #17). Every cv2 file read/write in the package routes through `imread`/`imwrite`; do not call `cv2.imread`/`cv2.imwrite` directly. `to_bgr(image)` is the shared channel normalizer — use it instead of inlining `cvtColor` branches.
+- `image_io.py` — Unicode-safe cv2 IO (issue #17). Every cv2 file read/write in the package routes through `imread`/`imwrite`; do not call `cv2.imread`/`cv2.imwrite` directly. `to_bgr(image)` is the shared channel normalizer — use it instead of inlining `cvtColor` branches. `read_bgr_and_alpha`/`write_bgr_with_alpha` (+ `ALPHA_FORMATS`) are the alpha-preserving IO helpers shared by the CLI and the library `api` (moved here from cli so both use ONE implementation; the write MUST NOT zero alpha in the mark bbox — issue #30 white box). **`write_bgr_with_alpha` RETURNS `imwrite`'s success flag and every caller must check it** — `imwrite` is contractually non-raising, so that bool is the ONLY signal the file was not created. The wrapper used to return `None` and swallow it, so a write that a read-only directory silently prevented ran on to `output.stat()` and died with a bare `FileNotFoundError` traceback pointing at the stat rather than the write (Tier E, 2026-07-20). **Three different layers each needed their own handling, and the right one is NOT the same everywhere:** the single-image commands (`visible --mark <name>`, `erase`, `all`) write through the shared `cli._write_output_or_exit`, which exits; `api._write_visible_result` (behind `visible --mark auto`) RAISES `OSError` so a library caller gets an accurate error instead of a confusing `FileNotFoundError` from the downstream metadata strip; and the **batch** sites raise too, never `SystemExit` — the batch loop catches per-image exceptions, counts them and exits non-zero, so aborting there would kill the whole run. Discarding the flag in batch made a read-only output directory produce **zero files and still exit 0** — silent data loss contradicting the documented batch contract. Regression: `tests/test_cli_robustness.py`. cv2/numpy import lazily, so importing `image_io` is cheap. **`imread` has a Pillow fallback (`_pil_read`) for HEIC/AVIF**: cv2 can't decode those containers, so when its decode returns None it opens via Pillow (AVIF native; HEIC via the core `pillow-heif` dep, whose libheif also covers AVIF) and converts to the same BGR/BGRA layout the flags imply — so the pixel/removal path reads iPhone HEIC and AVIF, not just the metadata path. Normal PNG/JPEG/WebP never reach the fallback. Corpus-verified: 54/55 HEIC+AVIF now decode (the 1 miss is a truncated upload). **`imwrite` PRESERVES the input format at max quality** ("work with originals"): the removal only touches the mark footprint (cv2 AND MI-GAN fills composite over the original — untouched pixels are bit-exact), so the container re-encode must not degrade the rest. JPEG is written at quality 100 / 4:4:4 (no chroma subsampling) — PSNR ~55 dB vs the old default-95's ~48; HEIC/AVIF write via Pillow (`_pil_write`) since cv2 has NO encoder for them (writing `.heic` via cv2 RAISES — a HEIC input used to crash on save). `imwrite` never raises (catches `cv2.error`). **`api.remove_visible` copies the original bytes verbatim on a no-op** (nothing removed + same output format) rather than a lossy re-encode, so a clean image round-trips byte-identical. `noai/constants.SUPPORTED_FORMATS` now includes `.heic`/`.heif`/`.avif` alongside png/jpg/jpeg/webp (pillow-heif is core, so read+write both work), so `batch` discovers them and the CLI no longer warns on an iPhone HEIC; JPEG-XL stays OUT (metadata/strip-only, no pixel decoder without pillow-jxl). **The invisible/SynthID path is inherently a full-frame diffusion regeneration (every pixel changes by design — you cannot "work with originals" there), but it no longer piles gratuitous re-encodes on top:** `watermark_remover` saves the regenerated output through `image_io.imwrite` (not raw `PIL.save`, which defaults to JPEG q75), `invisible_engine` writes its pre-diffusion temp as lossless PNG (not a re-compressed copy of a JPEG input), and the output metadata strip goes through the byte-level `metadata.remove_ai_metadata` (see its bullet) which for JPEG does NOT re-encode the DCT at all — pixels stay bit-identical.
+- `api.py` — the high-level convenience API, re-exported lazily at the package top level via `__init__.__getattr__` (PEP 562, so `import remove_ai_watermarks` stays cheap): `remove_visible(source, output=None, *, sensitivity="auto", backend="auto", strip_metadata=True, write_noop=True) -> (result_bgr, [labels])` (source = path OR BGR ndarray; a PATH auto-reads metadata provenance and preserves alpha, an ARRAY does neither; `write_noop=True` writes a clean passthrough copy when nothing is removed, `False` leaves `output` untouched so a "no mark = produce nothing" caller like the CLI `visible` command does not clobber a pre-existing file there) and `visible_provenance(path) -> frozenset[str]` (the single metadata→vendor-keys mapper; `cli._visible_provenance` is a thin None-guarded wrapper over it). **`remove_visible` is the ONE path the CLI and library share** — `cli.cmd_visible`'s `--mark auto` branch delegates entirely to it (read → provenance → `remove_auto_marks` → write → `strip_metadata`), so there is no CLI-vs-library drift; `strip_metadata` defaults True to match `visible --strip-metadata`. This is where a library caller should start — NOT the engines directly (`GeminiEngine`/`TextMarkEngine` have no `remove_watermark` any more; removal is registry `remove_auto_marks`/`KnownMark.remove`; the old single-strongest `best_auto_mark` is gone — removal takes EVERY mark). `identify` is NOT top-level re-exported (it collides with the `identify` submodule); use `from remove_ai_watermarks.identify import identify`.
 
 For the Doubao alpha-distillation history (why content-image reverse-alpha distillation fails by physics and controlled captures were required), see `docs/research-doubao-distillation.md`.
 
@@ -80,14 +86,15 @@ Who embeds what (C2PA / IPTC / EXIF / TC260 AIGC / xAI signature / open and prop
 
 Compact list. Full measurements, incident history, and oracle-validation runs live in `docs/known-limitations.md` — **read the relevant section there before changing the diffusion pipelines, strength defaults, resolution handling, or metadata coverage.**
 
+- **Visible-mark fill quality is background/backend-dependent.** The fill only touches the mark footprint (no outside-box damage) and whether the mark is removed is fill-independent — cv2/MI-GAN/LaMa all strip the shape; only the recovered region's *quality* differs. Flat backgrounds: all clean (cv2 often crispest). Textured/regular-structured (fabric, grid): cv2 smears, MI-GAN can ghost/hallucinate, LaMa best. The old reverse-alpha recovered true pixels so it was sometimes cleaner on structure, but localize -> fill trades that for robustness (moved/re-rendered marks, no per-mark capture); `auto` = LaMa > MI-GAN > cv2 with a one-time cv2-fallback warning. Head-to-head vs v0.12.1 on the full visible set: doubao/jimeng identical (100%/100%), gemini strict coverage a few points lower (the metadata-stripped faint ones now mostly recovered by the default white-core rescue in the gemini FP gate), clearance ~98% both. Detail in `docs/known-limitations.md`.
 - `invisible` processes at native resolution for inputs >= 1024px long side and auto-upscales smaller inputs to a 1024px floor (`--min-resolution 0` disables; `--max-resolution N` is an opt-in cap to bound GPU/MPS memory). MPS OOM is memory-tier dependent, not a hard limit: ~24 GB unified memory falls back to CPU (slow but weight-identical output), 32 GB runs native on MPS. The native-vs-cap-vs-floor decision lives in the pure helper `invisible_engine._target_size` — keep the logic there, unit-tested without the model. For large inputs that OOM, `--tile` is the **lossless** alternative to `--max-resolution`: sliding-window diffusion at native resolution, each tile near SDXL's 1024 training size, feather-blended over the overlap (`noai/tiling.py`). It only engages when the long side exceeds `--tile-size`; the geometry (`plan_tiles`) and the blend window (`feather_weights`) are pure and unit-tested (`tests/test_tiling.py`). Caveat: each tile is an independent low-strength regeneration, so at the certified removal strengths (0.20-0.30) tile drift is minimal but not zero; tiling is a memory workaround, not a quality upgrade over a single native pass.
 - fp16 VAE black-output (issues #29/#41): the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix`) is swapped in for the default SDXL checkpoint on cuda/xpu fp16, plus a model-agnostic backstop that detects a degenerate (all-black) fp16 output and re-runs once in fp32. cpu/mps run fp32 and never reproduce the bug.
 - Pyright first run is slow (2-3 min) due to ML deps (torch/diffusers/transformers stubs); full-project `uv run pyright` can stall for many minutes — scope it to changed files.
 - A third-party PIL plugin autoload (e.g. an HEIF/AVIF plugin) can raise a non-OSError (`ModuleNotFoundError`), not `UnidentifiedImageError`, when opening a file. Code that opens user-supplied or unknown-format files should `except Exception`, not just `OSError`/`UnidentifiedImageError`.
 - rich was dropped: the CLI + analysis scripts print plain text (`click.echo` / the `scripts/_plain_console.py` shim). `rich` is NOT a dependency — importing it breaks the core+dev CI sync; new scripts must use the shim. No Unicode glyphs / colors / progress bars in CLI output by design.
-- AVIF/HEIF/JPEG-XL metadata detection is a binary scan; C2PA removal in those containers (and MP4/MOV/M4V) is `noai/isobmff.py`; non-ISOBMFF audio/video (WebM/MP3/WAV/FLAC/OGG) strips losslessly via ffmpeg on PATH. An AI-generator token in an `Exif` meta-box *item* (bytes in `mdat`/`idat`) is now blanked **in place** by `isobmff.blank_ai_exif_tokens` (same-length space overwrite, piexif-validated so a coincidental II/MM run in pixels is ignored — no `iinf`/`iloc` surgery, mirrors `blank_ai_xmp_packets`); it scrubs the AI-token value only, leaving camera/editor EXIF intact. Still NOT built: Resemble PerTh audio detection (no presence/confidence flag exists).
+- HEIC/AVIF are decodable on BOTH paths now: the pixel/removal path via the `image_io.imread` Pillow fallback (+ core `pillow-heif`), and metadata detection via a plugin-free binary scan. C2PA removal in those containers (and MP4/MOV/M4V) is `noai/isobmff.py`; JPEG-XL stays metadata/strip-only (Pillow can't decode it without `pillow-jxl`, not a dep). Non-ISOBMFF audio/video (WebM/MP3/WAV/FLAC/OGG) strips losslessly via ffmpeg on PATH. On the ISOBMFF path `remove_ai_metadata` routes to the container branch and never runs the JPEG `_scrub_ai_exif`, so `isobmff.blank_ai_exif_tokens` is the ONLY EXIF scrubber there and must stay in PARITY with it: it blanks **in place** (same-length space overwrite, piexif-validated so a coincidental II/MM run in pixels is ignored — no `iinf`/`iloc` surgery, mirrors `blank_ai_xmp_packets`) an AI-generator token in `Software`/`Make`/`Artist`/`ImageDescription`, the China TC260 `{"AIGC":{...}}` block in `ImageDescription`/`UserComment` (via `_is_aigc_exif_value`), AND the xAI/Grok `Signature:` + UUID-`Artist` pair — leaving camera/editor EXIF intact. Still NOT built: Resemble PerTh audio detection (no presence/confidence flag exists).
 - **SynthID technical reference: `docs/synthid.md`** — primary-source-cited doc covering mechanism (post-hoc encoder/decoder pair, 136-bit payload at 512x512, pixel-space, model weights NOT modified), robustness numbers (arXiv:2510.09263: ~99.98% TPR@0.1%FPR across 30 transforms including JPEG/crop/resize/color/noise), removal attacks and forensic detectability (arXiv:2605.09203: all 6 attacks detectable at >98% TPR@1%FPR), detectability limits (no public decoder, metadata-proxy only), oracle scope, and adoption landscape. Read that doc first before adding notes here.
 - **SynthID detection is metadata-only.** No local pixel detector is possible by design (Google's decoder is proprietary, trusted-testers only); we read the C2PA companion proxy, which goes quiet once metadata is stripped — a quiet proxy is not proof the pixel watermark is gone. Each vendor has its OWN oracle and it detects only that vendor's content: the Gemini app "Verify with SynthID" for Google, `openai.com/verify` for OpenAI. **Validate the OpenAI arm FIRST** — `openai.com/verify` is more accessible (fewer per-check restrictions) and the strongest automation candidate (Playwright / Chrome MCP); the Gemini flow is more manual. Ordering/throughput choice, not a substitution (see `docs/synthid.md`). SynthID survives JPEG re-encode, so GitHub issue attachments remain valid pixel-watermark test subjects. Every spectral/phase detection approach evaluated (reverse-SynthID, our own probes) works only on controlled solid fills, never on real content.
 - **External AI-vs-real classifier models are out of scope** (decided 2026-05-24): per-generator, degrade off-distribution, and our own light SDXL pass would likely defeat them. Detection stays local + signal-based.
-- **Default strength is VENDOR-ADAPTIVE, one ladder for BOTH pipelines** (since 2026-06-09): `resolve_strength(strength, vendor)` picks OpenAI **0.20** / Gemini **0.30** / unknown **0.30** when `--strength` is unset; explicit `--strength` always wins. Removal at low strength is content x pipeline dependent, and near-threshold removal is SEED-NON-DETERMINISTIC — pick a strength with margin and oracle-revalidate per content type. Certified controlnet floors (Modal cert 2026-06-04): OpenAI 0.20 (resolution-independent), Gemini 0.30 (only <= 1536px; native large Gemini needs ~0.35+ or a cap).
+- **Default strength is VENDOR-ADAPTIVE, one ladder for BOTH pipelines** (since 2026-06-09): `resolve_strength(strength, vendor)` picks OpenAI **0.10** / Gemini **0.15** / unknown **0.15** when `--strength` is unset (the 2026-06-14 lowering from the 2026-06-04 cert floors of 0.20/0.30 — the single source of truth is `watermark_profiles.py`, and the full cert/lowering history is in `docs/known-limitations.md`); explicit `--strength` always wins. Removal at low strength is content x pipeline dependent, and near-threshold removal is SEED-NON-DETERMINISTIC — pick a strength with margin and oracle-revalidate per content type.
 - **`controlnet` is the default pipeline**; `--pipeline sdxl` is the lighter opt-down. Neither pipeline clears all content at low strength (photoreal survives controlnet, flat graphics survive sdxl — the lever is higher strength). A removal-priority caller MUST oracle-validate strength across content types; prod recipe: controlnet + per-vendor floor + FIXED seed. Forensic-stealth caveat (arXiv:2605.09203): defeating the SynthID verifier is NOT forensic invisibility — removal-processed images are flaggable at >98% TPR@1%FPR.

README.md

@@ -21,14 +21,14 @@ If this tool saves you time, consider [sponsoring its development](https://githu
 
 ## Scope
 
-This tool removes **AI-provenance watermarks** that a platform stamps onto content **you generated yourself** — SynthID, the Gemini / Nano Banana sparkle, the Doubao / Jimeng / Samsung visible AI labels, the Chinese TC260 "由…AI生成" label, and C2PA / IPTC / EXIF "Made with AI" metadata. The point is your autonomy over your own output.
+This tool removes **AI-provenance watermarks** that a platform stamps onto content **you generated yourself** — SynthID, the Gemini / Nano Banana sparkle, the Doubao / Jimeng / Qwen / Kling / Baidu / LibLibAI / RunningHub / Samsung visible AI labels, the Chinese TC260 "由…AI生成" label, and C2PA / IPTC / EXIF "Made with AI" metadata. The point is your autonomy over your own output.
 
 It does **not** target watermarks that protect someone else's paid or copyrighted content — stock-agency overlays (Shutterstock, Getty, iStock, Adobe Stock), classifieds-site marks, or any tiled "preview" watermark whose job is to gate a purchase. Removing those is out of scope by design. `erase` is a generic, user-driven region tool for your own objects, not an automatic stock-watermark remover.
 
 ## Features
 
-- **Visible watermark removal** — a registry of known marks in their usual places: the Gemini / Nano Banana sparkle, the Doubao "豆包AI生成" text strip, the Jimeng "★ 即梦AI" wordmark, and the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-left, locale-specific). Each is removed by **reverse-alpha blending** against a captured alpha map (`original = (wm − α·logo)/(1−α)`), recovering the true pixels rather than inpainting a guess. The Gemini sparkle recovers cleanly on its own on bright backgrounds; it adapts the alpha to each image's sparkle opacity, so a more-opaque-than-captured sparkle is still fully removed (and on a dark background, where the fixed alpha would over-subtract and leave a dark spot, it automatically inpaints the small sparkle footprint instead); the Doubao, Jimeng, and Samsung text marks re-rasterize slightly per image, so a thin residual inpaint over the glyph footprint clears the leftover edges (the alpha maps are reproducibly rebuilt from controlled captures by `scripts/visible_alpha_solve.py`). Fast, offline, no GPU. `visible --mark auto` finds and removes the strongest detected mark. (For arbitrary logos/objects, see `erase`.)
-- **Universal region eraser (`erase`)** — remove any logo / watermark / object inside boxes you specify, regardless of position or colour. Default cv2 inpainting (CPU, instant); optional big-LaMa via onnxruntime (`lama` extra) for higher quality
+- **Visible watermark removal** — a registry of known marks in their usual places: the Gemini / Nano Banana sparkle, the Doubao "豆包AI生成" text strip, the Jimeng "★ 即梦AI" wordmark, the Qwen "千问AI生成" and Kling "可灵AI 3.0" text strips, the Baidu "百度 AI生成" text + tag, the LibLibAI wordmark (bottom-center), the RunningHub "RunningHub AI生成" text (top-left), and the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-left, locale-specific). Each mark is **localized to a footprint mask, then filled**: the engine finds the mark, builds a binary mask over its footprint, and one shared, swappable fill inpaints that region. Choose the fill with `--backend`: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN, light, the memory-tight pick where LaMa will not fit), or `lama` (big-LaMa, best quality, heavier, auto-preferred when a learned backend is available); the default `auto` uses LaMa > MI-GAN > cv2, best available. The localizer is cheap CPU (cv2/numpy), so it runs anywhere; the heavier MI-GAN/LaMa fill is opt-in. Detection keys on each mark's own shape (NCC against a captured silhouette; the alpha captures rebuilt by `scripts/visible_alpha_solve.py` are used to detect and to shape the mask, not for pixel recovery). The visual detector needs no metadata, but a borderline (faint or moved) mark is only trusted with corroboration: `--sensitivity` (default `auto`) relaxes a mark's gate when local metadata confirms the vendor or a same-product sibling mark is found; `strict` never relaxes. There is deliberately no "assume this is AI" mode: asserting that an image is AI says nothing about *which* vendor made it or *where* the mark is, which is exactly what a gate bypass needs. If you can SEE a mark the detector missed, point at it with `erase --region x,y,w,h`, or force a known text mark by name with `--mark <name> --no-detect` -- both act on what you actually see instead of relaxing every detector at once. `visible --mark auto` finds and removes every detected mark in one pass. Fast, offline, no GPU. (For arbitrary logos/objects, see `erase`.)
+- **Universal region eraser (`erase`)** — remove any logo / watermark / object inside boxes you specify, regardless of position or color. Default cv2 inpainting (CPU, instant); optional big-LaMa via onnxruntime (`lama` extra) for higher quality
 - **Invisible watermark removal** — SynthID, StableSignature, TreeRing via diffusion-based regeneration (needs a local GPU, or run it with no setup on [raiw.cc](https://raiw.cc))
 - **AI metadata stripping** — EXIF, PNG text chunks, C2PA provenance manifests (PNG / JPEG / AVIF / HEIF / JPEG-XL, **MP4 / MOV / M4V / M4A** at the container level, and **WebM / MP3 / WAV / FLAC / OGG** losslessly via ffmpeg), XMP DigitalSourceType
 - **"Made with AI" label removal** — removes the AI-disclosure metadata that platforms read to apply automatic labels (useful for clearing a false-positive label from a human-edited photograph)
@@ -36,7 +36,7 @@ It does **not** target watermarks that protect someone else's paid or copyrighte
 - **Text and face preservation (default)** — the default pipeline is a canny ControlNet that keeps text and face structure sharp through the removal pass (without copying original pixels, so SynthID is still removed). Use `--pipeline sdxl` for plain SDXL img2img (lighter, no extra model download) on inputs without text or faces. An experimental `--pipeline qwen` runs Qwen-Image (20B, Apache-2.0) img2img, which preserves **text** (including CJK and small text) better than SDXL at equal strength; it is CUDA/cloud-class (does not fit MPS), and its strength floors are not yet certified (pass an explicit `--strength`, especially for Gemini content). Note: measured fidelity (`scripts/fidelity_metrics.py`) shows Qwen wins on text but controlnet preserves **faces** better (Qwen smooths skin more), so Qwen is not a universal upgrade. Canny preserves face *structure*, not *identity* (the regenerated face drifts in likeness). The library does not ship a face-restore extra: every approach evaluated (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned) regenerated the face via SDXL and made the output look more AI-generated than the cleaned image. The cleaned controlnet output is the least-AI face state achievable without re-introducing SynthID.
 - **Batch processing** — process entire directories
 - **Detection** — three-stage NCC watermark detection with confidence scoring
-- **Provenance detection (`identify`)** — aggregate C2PA issuer, the C2PA soft-binding forensic-watermark vendor (Adobe TrustMark, Digimarc, Imatag, ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, embedded SD/ComfyUI params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the China TC260 AIGC label (XMP, PNG chunk, EXIF, or JPEG segment), the HuggingFace `hf-job-id` job marker, the SynthID metadata proxy, the C2PA cloud-manifest reference (Adobe Durable Content Credentials, when the embedded manifest is stripped), the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), the open SD/SDXL/FLUX invisible watermark, and (with the `trustmark` extra) the open Adobe TrustMark watermark into one origin-platform + watermark-inventory verdict (`--json` for machine output)
+- **Provenance detection (`identify`)** — aggregate C2PA issuer, the C2PA soft-binding forensic-watermark vendor (Adobe TrustMark, Digimarc, Imatag, ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, embedded SD/ComfyUI params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the China TC260 AIGC label (XMP, PNG chunk, EXIF, or JPEG segment), the HuggingFace `hf-job-id` job marker, the SynthID metadata proxy, the C2PA cloud-manifest reference (Adobe Durable Content Credentials, when the embedded manifest is stripped), the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Qwen "千问AI生成" / Kling "可灵AI 3.0" / Baidu "百度 AI生成" / LibLibAI / RunningHub "RunningHub AI生成" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), the open SD/SDXL/FLUX invisible watermark, and (with the `trustmark` extra) the open Adobe TrustMark watermark into one origin-platform + watermark-inventory verdict (`--json` for machine output)
 
 ## Examples
 
@@ -48,7 +48,7 @@ It does **not** target watermarks that protect someone else's paid or copyrighte
 
 | AI model | Visible watermark | Invisible watermark | Metadata | Our approach |
 | --- | --- | --- | --- | --- |
-| **Google Gemini / Nano Banana / Gemini 3 Pro** | ✅ Sparkle logo | ✅ SynthID v1 + v2 (default SDXL pipeline, native resolution) | ✅ C2PA + EXIF | Alpha reversal + diffusion + metadata strip |
+| **Google Gemini / Nano Banana / Gemini 3 Pro** | ✅ Sparkle logo | ✅ SynthID v1 + v2 (default SDXL pipeline, native resolution) | ✅ C2PA + EXIF | Localize + fill + diffusion + metadata strip |
 | **OpenAI DALL-E 3 / ChatGPT** | — | — | ✅ C2PA manifest | Metadata strip |
 | **OpenAI ChatGPT Images 2.0** (gpt-image-2) | — | ✅ SynthID + content-specific pixel watermark (since May 2026; no local decoder, openai.com/verify oracle) | ✅ C2PA manifest (verified) | Diffusion regeneration + metadata strip |
 | **Stable Diffusion / SDXL (AUTOMATIC1111, ComfyUI)** | — | ✅ DWT-DCT (imwatermark — locally detectable) | ✅ PNG text chunks | Diffusion regeneration + metadata strip |
@@ -59,16 +59,21 @@ It does **not** target watermarks that protect someone else's paid or copyrighte
 | **xAI Grok (Aurora)** | — | — | ✅ EXIF signature scheme (no C2PA): `Signature:` blob + UUID `Artist` | Detected (`identify`); metadata strip |
 | **Midjourney** | — | — | ✅ EXIF + XMP (prompt, model, seed) | Metadata strip |
 | **Meta AI** | — | — | ✅ IPTC "Made with AI" (digitalSourceType) | Metadata strip (removes the label) |
-| **Doubao** (ByteDance) / China AIGC generators | ✅ "豆包AI生成" text strip (bottom-right) | — | ✅ TC260 AIGC label (`<TC260:AIGC>` XMP, `AIGC` PNG chunk, or EXIF JSON) **+ C2PA** signed by ByteDance Volcano Engine (`volcengine`) | Reverse-alpha (captured α map) + thin residual inpaint, NCC-aligned across resolutions, + metadata strip |
-| **Jimeng / Dreamina** (即梦AI, ByteDance) | ✅ "★ 即梦AI" wordmark (bottom-right) | — | ✅ TC260 AIGC label + C2PA (Volcano Engine) | Reverse-alpha (captured α map) + residual inpaint over the glyph footprint, NCC-aligned across resolutions, + metadata strip |
-| **Samsung Galaxy AI** (Generative Edit, Sketch to Image, ...) | ✅ "✦ Contenuti generati dall'AI" strip (bottom-left, locale-specific) | — | ✅ C2PA (signer "Samsung Galaxy") + `trainedAlgorithmicMedia` / proprietary `genAIType` marker | Reverse-alpha (captured α map) + thin residual inpaint, NCC-aligned across resolutions, + metadata strip |
+| **Doubao** (ByteDance) / China AIGC generators | ✅ "豆包AI生成" text strip (bottom-right) | — | ✅ TC260 AIGC label (`<TC260:AIGC>` XMP, `AIGC` PNG chunk, or EXIF JSON) **+ C2PA** signed by ByteDance Volcano Engine (`volcengine`) | Localize glyph footprint + fill + metadata strip |
+| **Jimeng / Dreamina** (即梦AI, ByteDance) | ✅ "★ 即梦AI" wordmark (bottom-right) | — | ✅ TC260 AIGC label + C2PA (Volcano Engine) | Localize glyph footprint + fill + metadata strip |
+| **Qwen / Tongyi Qianwen** (千问, Alibaba) | ✅ "千问AI生成" text strip (bottom-right) | — | ✅ TC260 AIGC label | Localize glyph footprint + fill + metadata strip |
+| **Kling** (可灵, Kuaishou) | ✅ "可灵AI 3.0" text strip (bottom-right) | — | ✅ TC260 AIGC label | Localize glyph footprint + fill + metadata strip |
+| **Baidu** | ✅ "百度 AI生成" text + tag (bottom-right) | — | ✅ TC260 AIGC label | Localize glyph footprint + fill + metadata strip |
+| **LibLibAI** (哩布哩布AI) | ✅ "LibLibAI" wordmark (bottom-center) | — | ✅ TC260 AIGC label | Localize glyph footprint + fill + metadata strip |
+| **RunningHub** | ✅ "RunningHub AI生成" text (top-left) | — | ✅ TC260 AIGC label | Localize glyph footprint + fill + metadata strip |
+| **Samsung Galaxy AI** (Generative Edit, Sketch to Image, ...) | ✅ "✦ Contenuti generati dall'AI" strip (bottom-left, Italian-locale detection) | — | ✅ C2PA (signer "Samsung Galaxy") + `trainedAlgorithmicMedia` / proprietary `genAIType` marker | Localize glyph footprint + fill + metadata strip |
 | **Black Forest Labs** (FLUX API) | — | — | ✅ C2PA (`Black Forest Labs API` + `c2pa.ai_generated_content` + `trainedAlgorithmicMedia`) | Metadata strip |
 | **StableSignature** (Meta) | — | ✅ In-model watermark | — | Diffusion regeneration |
 | **TreeRing** | — | ✅ Latent space watermark | — | Diffusion regeneration |
 
-> Visible overlays are used by Google Gemini / Nano Banana (sparkle logo), by ByteDance's Doubao ("豆包AI生成" corner text) and Jimeng / Dreamina ("★ 即梦AI" wordmark), and by Samsung Galaxy AI ("✦ Contenuti generati dall'AI" strip, bottom-left, locale-specific). All are removed on CPU by reverse-alpha against a captured alpha map (Jimeng and Samsung add a thin residual inpaint over the glyph footprint, since their marks re-rasterize per image). Other services rely on invisible watermarks and/or metadata; our diffusion-based regeneration works against any invisible watermark in pixel or frequency domain. For a visible mark from any other source (any position, any colour), use the universal `erase --region` command.
+> Visible overlays are used by Google Gemini / Nano Banana (sparkle logo), by ByteDance's Doubao ("豆包AI生成" corner text) and Jimeng / Dreamina ("★ 即梦AI" wordmark), by Alibaba's Qwen / Tongyi Qianwen ("千问AI生成" corner text), by Kuaishou's Kling ("可灵AI 3.0" corner text), by Baidu ("百度 AI生成" text + tag), by LibLibAI ("LibLibAI" wordmark, bottom-center), by RunningHub ("RunningHub AI生成", top-left), and by Samsung Galaxy AI ("✦ Contenuti generati dall'AI" strip, bottom-left, locale-specific). All are removed by localizing the mark to a footprint mask and inpainting it with one shared fill (cv2 by default, MI-GAN or big-LaMa via `--backend`); the localizer is CPU-cheap and the heavier fills are opt-in. Other services rely on invisible watermarks and/or metadata; our diffusion-based regeneration works against any invisible watermark in pixel or frequency domain. For a visible mark from any other source (any position, any color), use the universal `erase --region` command.
 
-> **Detection:** `remove-ai-watermarks identify <image>` reports the origin platform and watermark inventory for all the signals above — C2PA issuer, the C2PA soft-binding forensic-watermark vendor (TrustMark / Digimarc / Imatag / ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, the China TC260 AIGC label (XMP, PNG chunk, EXIF, or JPEG segment), the HuggingFace `hf-job-id` job marker, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, the C2PA cloud-manifest reference (Adobe Durable Content Credentials, when the embedded manifest is stripped), the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), and (with the `[detect]` / `[trustmark]` extras) the open SD/SDXL/FLUX and Adobe TrustMark invisible watermarks. SynthID and the proprietary soft-binding watermarks (Digimarc etc.) have no local decoder, so they are reported by metadata proxy / vendor name only.
+> **Detection:** `remove-ai-watermarks identify <image>` reports the origin platform and watermark inventory for all the signals above — C2PA issuer, the C2PA soft-binding forensic-watermark vendor (TrustMark / Digimarc / Imatag / ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, the China TC260 AIGC label (XMP, PNG chunk, EXIF, or JPEG segment), the HuggingFace `hf-job-id` job marker, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, the C2PA cloud-manifest reference (Adobe Durable Content Credentials, when the embedded manifest is stripped), the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Qwen "千问AI生成" / Kling "可灵AI 3.0" / Baidu "百度 AI生成" / LibLibAI / RunningHub "RunningHub AI生成" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), and (with the `[detect]` / `[trustmark]` extras) the open SD/SDXL/FLUX and Adobe TrustMark invisible watermarks. SynthID and the proprietary soft-binding watermarks (Digimarc etc.) have no local decoder, so they are reported by metadata proxy / vendor name only.
 
 ## How it works
 
@@ -80,25 +85,19 @@ Google Gemini (internally codenamed **Nano Banana**) adds a visible sparkle logo
 watermarked = α × logo + (1 − α) × original
 ```
 
-We reverse this with a known alpha map (extracted from Gemini / Nano Banana output on a pure-black background):
+A multi-scale NCC (Normalized Cross-Correlation) detector finds the sparkle position and scale dynamically in the bottom-right region (with a false-positive gate), so it works even if the image was resized or cropped. Removal is **localize then fill**: the sparkle footprint is built from the captured alpha thresholded low (so the faint halo is included) and dilated by a sparkle-relative margin, and that mask is inpainted by the shared fill. The captured alpha maps are used only to detect the sparkle and to shape the mask, not to recover pixels. If local metadata already confirms Google (a Google / Gemini C2PA issuer), the detection trust gate is relaxed so a moved or re-rendered sparkle is still caught. Pick the fill with `--backend` (cv2 default, MI-GAN or big-LaMa opt-in).
 
-```text
-original = (watermarked − α × logo) / (1 − α)
-```
-
-A three-stage NCC (Normalized Cross-Correlation) detector finds the watermark position and scale dynamically, so it works even if the image was resized or cropped. After removal, residual sparkle-edge artifacts are cleaned via gradient-masked inpainting.
-
-**Speed**: ~0.05s per image. No GPU needed.
+**Speed**: fast on CPU with the default cv2 fill. No GPU needed.
 
 ### Removing the Doubao "豆包AI生成" text watermark
 
-Doubao (ByteDance) stamps every output with a light, semi-transparent "豆包AI生成" text strip in the bottom-right corner — the visible AIGC label mandated by China's TC260 standard. It is a fixed semi-transparent white overlay, so it is removed by **reverse-alpha blending**: `original = (watermarked - α·logo) / (1 - α)`, recovering the true pixels instead of hallucinating them. The α map is solved from controlled black/gray captures (rebuildable with `scripts/visible_alpha_solve.py`). Like the Jimeng mark, Doubao re-rasterizes its text slightly per image, so reverse-alpha is followed by a thin residual inpaint over the glyph footprint to clear the leftover edges, and the α template is NCC-aligned to the actual mark (handling per-image scale/position jitter). Detection matches the same glyph silhouette against the corner (normalized correlation), so it keys on the "豆包AI生成" shape, not on textured corners.
+Doubao (ByteDance) stamps every output with a light, semi-transparent "豆包AI生成" text strip in the bottom-right corner — the visible AIGC label mandated by China's TC260 standard. Detection matches the glyph silhouette against the corner (normalized correlation), so it keys on the "豆包AI生成" shape, not on textured corners. Removal is **localize then fill**: the light glyph blob is localized to a solid, dilated footprint mask (template-free, so a re-rendered or differently-placed mark is still masked) and the shared fill inpaints it. On corpus images the filled region blends into its surroundings within a few LAB levels, with no color shift and no dark pit. Pick the fill with `--backend` (cv2 default, MI-GAN or big-LaMa opt-in).
 
-**Speed**: ~0.05s, no GPU needed.
+**Speed**: fast on CPU with the default cv2 fill, no GPU needed.
 
 ### Removing the Jimeng "★ 即梦AI" wordmark
 
-Jimeng / Dreamina (即梦AI, also ByteDance, distinct from Doubao) stamps a "★ 即梦AI" wordmark — a four-point sparkle followed by the 即梦AI characters — in the bottom-right corner. It is a fixed semi-transparent **pure-white** overlay, solved from controlled black / gray / white captures the same way as Doubao. `visible --mark auto` detects and removes it (or force it with `--mark jimeng`). One difference from Doubao: Jimeng re-rasterizes its mark slightly differently per image, so a single alpha map does not cancel it pixel-for-pixel — reverse-alpha knocks the mark down and a residual inpaint over the glyph footprint clears the remaining outline. The two ByteDance marks do not confuse `auto`: detection keys on each mark's own glyph shape (the Jimeng detector scores far below its threshold on a Doubao strip, and vice versa).
+Jimeng / Dreamina (即梦AI, also ByteDance, distinct from Doubao) stamps a "★ 即梦AI" wordmark — a four-point sparkle followed by the 即梦AI characters — in the bottom-right corner. Detection keys on the wordmark's glyph shape (NCC against a captured silhouette). `visible --mark auto` detects and removes it (or force it with `--mark jimeng`). Removal is **localize then fill**: the glyph blob is localized to a solid, dilated footprint mask and the shared fill inpaints it, so a re-rendered or differently-placed mark is still cleared. On corpus images the filled region blends into its surroundings within a few LAB levels, no color shift. The two ByteDance marks do not confuse `auto`: detection keys on each mark's own glyph shape (the Jimeng detector scores far below its threshold on a Doubao strip, and vice versa).
 
 ```bash
 remove-ai-watermarks visible jimeng.png -o clean.png            # --mark auto picks Jimeng
@@ -107,7 +106,7 @@ remove-ai-watermarks visible jimeng.png --mark jimeng -o clean.png
 
 ### Removing the Samsung Galaxy AI "✦ Contenuti generati dall'AI" mark
 
-Samsung's on-device Generative AI edits (Generative Edit, Sketch to Image, Portrait Studio) burn a visible sparkle + "generated with AI" string into the **bottom-left** corner — a faint, low-opacity semi-transparent white overlay. It is solved from controlled black / gray / white captures the same way as Jimeng and removed by reverse-alpha plus a thin residual inpaint over the glyph footprint (the mark re-rasterizes per image, and the flat captures are smaller than real photos, so the alpha template is NCC-aligned and width-scaled to the actual mark). `visible --mark auto` detects and removes it (or force it with `--mark samsung`); being bottom-left it never confuses the bottom-right Gemini/Doubao/Jimeng marks. The string is **locale-specific** — this build is calibrated for the Italian "Contenuti generati dall'AI" variant; other locales need their own captured template (open a sample on issue #37).
+Samsung's on-device Generative AI edits (Generative Edit, Sketch to Image, Portrait Studio) burn a visible sparkle + "generated with AI" string into the **bottom-left** corner — a faint, low-opacity semi-transparent white overlay. Detection matches the glyph silhouette (NCC), and removal is **localize then fill**: the glyph blob is localized to a solid, dilated footprint mask and the shared fill inpaints it. `visible --mark auto` detects and removes it (or force it with `--mark samsung`); being bottom-left it never confuses the bottom-right Gemini/Doubao/Jimeng marks. **Detection is locale-specific** — this build detects only the Italian "Contenuti generati dall'AI" variant, so other Samsung locales are not detected (and thus not removed) and need their own captured detection template (open a sample on issue #37). The fill mask itself is locale-independent.
 
 ```bash
 remove-ai-watermarks visible samsung.jpg -o clean.jpg            # --mark auto picks Samsung
@@ -116,7 +115,7 @@ remove-ai-watermarks visible samsung.jpg --mark samsung -o clean.jpg
 
 ### Universal region eraser
 
-For any visible mark the dedicated engines do not cover — a logo anywhere, any colour — `erase --region x,y,w,h` inpaints the box you specify. The default `cv2` backend is instant and dependency-free; the optional `lama` backend (big-LaMa via onnxruntime, `lama` extra, ~200 MB model downloaded on first use) gives much cleaner fills on textured regions at the cost of ~3-4 GB RAM per call.
+For any visible mark the dedicated engines do not cover — a logo anywhere, any color — `erase --region x,y,w,h` inpaints the box you specify. The default `cv2` backend is instant and dependency-free; the optional `lama` backend (big-LaMa via onnxruntime, `lama` extra, ~200 MB model downloaded on first use) gives much cleaner fills on textured regions at the cost of ~3-4 GB RAM per call.
 
 ### Removing SynthID and other invisible watermarks
 
@@ -335,15 +334,26 @@ remove-ai-watermarks batch ./images/ --mode all
 # of a clean origin. Add --json for machine-readable output.
 remove-ai-watermarks identify image.png
 
-# Visible watermark only — fast, offline, CPU. --mark auto (default) finds the
-# strongest known mark (Gemini sparkle / Doubao "豆包AI生成" / Jimeng "即梦AI" /
-# Samsung Galaxy AI "Contenuti generati dall'AI"); force one with
-# --mark gemini / doubao / jimeng / samsung. Removed by reverse-alpha (true-pixel recovery).
+# Visible watermark only — fast, offline, CPU. --mark auto (default) removes every
+# detected known mark (Gemini sparkle / Doubao "豆包AI生成" / Jimeng "即梦AI" /
+# Qwen "千问AI生成" / Kling "可灵AI 3.0" / Baidu "百度 AI生成" / LibLibAI /
+# RunningHub "RunningHub AI生成" / Samsung Galaxy AI "Contenuti generati dall'AI");
+# force one with --mark gemini / doubao / jimeng / qwen / kling / baidu / liblib /
+# runninghub / samsung. Removal localizes each mark to a
+# footprint mask and inpaints it with a shared fill; --backend auto|cv2|migan|lama
+# (default auto) picks the fill (auto = LaMa > MI-GAN > cv2, best available).
+# --sensitivity auto|strict (default auto) sets how hard a borderline mark is
+# trusted; there is no "assume this is AI" mode -- to act on a mark you can see
+# but the detector missed, point at it with `erase --region` (below).
 # If no known visible mark is found, it writes no output and exits 2 (not 0),
 # pointing you to `all` (for an invisible/metadata mark) or `erase` (for an
 # arbitrary logo) instead of handing back the unchanged image.
 remove-ai-watermarks visible image.png -o clean.png
 
+# Metadata-stripped screenshot where you can SEE the mark but detection missed it:
+# point at it. This executes what you see instead of relaxing every detector at once.
+remove-ai-watermarks erase screenshot.png --region 812,1180,190,44 -o clean.png
+
 # Erase arbitrary region(s) — universal, any logo/watermark/object, any position.
 # Default cv2 inpainting (CPU). --backend lama uses big-LaMa (extra 'lama').
 remove-ai-watermarks erase image.png --region 1640,1930,400,100 -o clean.png
@@ -390,20 +400,30 @@ remove-ai-watermarks batch ./images/ --mode all
 
 ### Python API
 
+One high-level call removes every detected visible mark (Gemini sparkle, Doubao / Jimeng / Qwen / Samsung text, the Jimeng pill) by localize then fill. For a file it reads metadata provenance automatically and preserves the alpha channel; `import remove_ai_watermarks` stays cheap (the heavy deps load lazily on first use).
+
 ```python
-from remove_ai_watermarks.gemini_engine import GeminiEngine
+import remove_ai_watermarks as raiw
+
+# Clean a file -> writes clean.png, returns the array and what was removed.
+result, removed = raiw.remove_visible("watermarked.png", "clean.png")
+print("removed:", removed)          # e.g. ['Google Gemini sparkle']
+# An empty list means nothing known was found (route to `all` or `erase` instead).
+
+# Array in, array out (BGR numpy). Pick the fill backend: cv2 (default), migan, lama.
 import cv2
+clean, removed = raiw.remove_visible(cv2.imread("in.png"), backend="cv2")
 
-engine = GeminiEngine()
-image = cv2.imread("watermarked.png")
+# Metadata-stripped screenshot you know is AI-generated: relax detection to recover a
+# moved or faint mark (a wrong guess just fills a small corner near-losslessly).
+raiw.remove_visible("screenshot.png", "clean.png", sensitivity="strict")
 
-# Detect
-result = engine.detect_watermark(image)
-print(f"Detected: {result.detected} (confidence: {result.confidence:.1%})")
+# What the file's metadata confirms (drives the default `auto` sensitivity):
+raiw.visible_provenance("in.png")   # e.g. frozenset({'gemini'})
 
-# Remove
-clean = engine.remove_watermark(image)
-cv2.imwrite("clean.png", clean)
+# Full provenance verdict (platform + watermark inventory + confidence):
+from remove_ai_watermarks.identify import identify
+report = identify("in.png")
 ```
 
 #### Invisible removal (diffusion)
@@ -487,7 +507,7 @@ Won't fix:
 
 ## Limitations
 
-- **Visible-mark and metadata removal is lossless.** Reverse-alpha recovers the original pixels under the mark; metadata stripping never touches image data.
+- **Visible-mark removal is localized inpainting; metadata removal is lossless.** Each visible mark is localized to a footprint mask and filled by inpainting (cv2, MI-GAN, or big-LaMa), so only the small masked region is reconstructed and it blends into its surroundings within a few LAB levels; a slightly-off localization just fills a small region near-losslessly rather than leaving a color-shifted smear. Metadata stripping never touches image data.
 - **The invisible (SynthID) path is lossy and not guaranteed.** It runs a low-strength SDXL img2img regeneration, so it softens fine detail and is content-dependent. There is no public SynthID decoder, so the tool cannot verify removal locally; confirm with the Gemini app's "Verify with SynthID" oracle and raise `--strength` if it still detects. A vendor can change the scheme at any time, so treat this as an arms race, not a permanent fix.
 - **Large images: native by default, opt-in tiling for OOM.** The SynthID path runs at the diffusion model's native resolution; on a memory-constrained GPU/MPS you can either cap the long side with `--max-resolution` (lossy downscale) or pass `--tile` to regenerate in overlapping, feather-blended tiles at native resolution (lossless, no seam). Tiling is a memory workaround, not a quality upgrade over a single native pass: each tile is an independent low-strength regeneration. (Nano Banana 2 is natively 1024px; GPT Image 2 supports 4K experimentally.)
 - **Out of scope:** defeating trained AI-vs-real classifiers like Hive (see [Threat model](#threat-model)), visible-logo removal from video, and any guarantee that a stripped copy is untraceable server-side.

docs/known-limitations.md

@@ -9,6 +9,30 @@ measurements, incident history, oracle runs, and the reasoning behind each
 decision. Read the relevant section here before changing the diffusion
 pipelines, strength defaults, or metadata coverage.
 
+## Visible-mark fill quality is background- and backend-dependent
+
+Visible-mark removal is localize -> fill (the reverse-alpha pixel recovery was
+dropped; see `docs/module-internals.md`). The fill only touches the mark's
+footprint, so there is never collateral damage outside it, and whether the mark
+is *removed* is fill-independent -- cv2, MI-GAN and LaMa all strip the mark's
+shape. What varies is the *quality of the recovered region*, and it depends on
+the background:
+
+- **Flat backgrounds:** every backend is clean; cv2 is often the crispest.
+- **Textured / regular-structured backgrounds** (fabric, foliage, a lattice or
+  grid): an inpaint can only guess the hidden pixels. `cv2` (the classical
+  no-deps floor) visibly smears; `migan` (light, learned) can leave a ghost or
+  hallucinate structure; `lama` (heavy, learned) is the most reliable and
+  recovers structure best.
+
+The old reverse-alpha recovered the *true* pixels under a well-captured, static
+mark, so on structured backgrounds it was sometimes cleaner than any inpaint.
+The trade for localize -> fill is robustness (it also handles moved / re-rendered
+marks and needs no per-mark alpha capture) and a simpler, swappable pipeline.
+`auto` resolves best-first (`LaMa > MI-GAN > cv2`) and warns once when it falls
+back to cv2 because no learned backend is installed; a memory-tight deployment
+that cannot afford LaMa's ~4.7 GB peak pins `--backend migan` explicitly.
+
 ## Invisible-pipeline resolution handling (native / 1024 floor / `--max-resolution`; MPS memory tiers)
 
 `invisible` pipeline processes at **native resolution for inputs whose long side is >= 1024px**, and **auto-upscales smaller inputs UP to a 1024px floor** (`min_resolution=1024`, the default; `--min-resolution 0` disables) before diffusion -- SDXL img2img distorts badly on a tiny latent (a 381x512 portrait wrecks at native, the #36 follow-up), and the output is restored to the original input size so the floor is a transparent quality boost (it adds time/memory on small inputs). The floor upscale uses Lanczos by default; **`--upscaler esrgan`** (opt-in, the `esrgan` extra) runs Real-ESRGAN first for better detail before the Lanczos resize to the exact target (`upscaler.py` / `InvisibleEngine._esrgan_upscale`, falls back to Lanczos if the extra is absent). `max_resolution=0` (default) means no downscale cap, matching the hosted raiw.cc backend (fal fast-sdxl, no pre-downscale). The old forced downscale-to-1024 -> upscale-back round-trip for LARGE images was the main quality loss (issue #10) and is gone; at strength ~0.05 SDXL img2img does not need a downscale.
@@ -20,7 +44,7 @@ pipelines, strength defaults, or metadata coverage.
 `--tile` (OFF by default; `--tile-size` default 1024, `--tile-overlap` default 128) processes the diffusion pass in overlapping sliding-window tiles instead of one forward pass, so a large image is regenerated at **native resolution** without the OOM and without the lossy `--max-resolution` downscale round-trip. It engages only when the long side exceeds `--tile-size`; a sub-tile image runs a single pass unchanged. `WatermarkRemover.remove_watermark` refactors the single-image `_generate` into a per-tile `_generate_one` (the ControlNet canny edge map is rebuilt per tile, so structure preservation works tile-local) and routes it through `noai.tiling.run_tiled` when tiling is active. The geometry and blend math are pure helpers, unit-tested without the model (`tests/test_tiling.py`):
 
 - `plan_tiles(w, h, tile_size, overlap)` lays out a row-major grid where every tile is exactly `tile_size` (the last tile on each axis is pulled back flush to the far edge, simply overlapping its predecessor more). Uniform tile size keeps each diffusion pass at SDXL's preferred dimension.
-- `feather_weights(w, h, overlap)` is a separable linear taper, ~1 in the interior and ramping toward each edge, kept **strictly positive** so the normalised accumulate-and-divide blend (`accum / weight_sum`) is a partition of unity: a region covered by one feathered edge (an image corner) still divides cleanly. Identical (unchanged) tiles therefore reconstruct the input exactly -- the seam-free guarantee, asserted in `test_identity_generate_reconstructs_image`.
+- `feather_weights(w, h, overlap)` is a separable linear taper, ~1 in the interior and ramping toward each edge, kept **strictly positive** so the normalized accumulate-and-divide blend (`accum / weight_sum`) is a partition of unity: a region covered by one feathered edge (an image corner) still divides cleanly. Identical (unchanged) tiles therefore reconstruct the input exactly -- the seam-free guarantee, asserted in `test_identity_generate_reconstructs_image`.
 
 CAVEAT: each tile is an **independent** low-strength regeneration. At the certified removal strengths (0.20-0.30) the per-tile drift is small and the feather blend hides the seams, but tiling is a memory workaround, not a quality upgrade over a single native pass -- a 32 GB MPS box that clears the native UNet peak should prefer no tiling. The MPS->CPU fallback still applies per tile; if the first tile falls back to CPU, the device stays CPU for the rest of the image.
 
@@ -50,7 +74,7 @@ Metadata detection for AVIF/HEIF/JPEG-XL relies on a binary scan for `C2PA_UUID`
 
 **Meta-box XMP now handled (`isobmff.blank_ai_xmp_packets`, v0.6.9):** an AI-label XMP packet stored as a meta-box `mime` item (AVIF/HEIF) is blanked in place (overwritten with spaces of the same length, so `iloc` offsets and the coded image stay valid).
 
-**`Exif` item inside the `meta` box (AVIF/HEIF), now handled in place (2026-06-19):** an AI-generator token in an EXIF item (its TIFF bytes live in `mdat`/`idat`) is blanked by `isobmff.blank_ai_exif_tokens` — it finds EXIF TIFF blocks by their II/MM byte-order header, validates each with **piexif** (a coincidental II/MM run in pixel data won't parse as a TIFF IFD, so it is ignored), and overwrites any `Software`/`Make`/`Artist`/`ImageDescription` value carrying an `AI_GENERATOR_TOKENS` token with spaces of the **same length**. Same-length means every box size and `iloc` offset stays valid and the coded image is untouched — so it avoids the full `iinf`/`iloc` surgery (offset rewrite) that exiftool would need (exiftool is a non-installed binary dep, deliberately not used). It scrubs only the AI-token value; camera/editor EXIF is preserved. Wired into `remove_ai_metadata`'s ISOBMFF path after `blank_ai_xmp_packets`. Limitation: covers the AI-generator-token case (the realistic one); a future xAI-signature-in-meta-box-EXIF (Grok is JPEG-only today) is not separately handled. **Still NOT built:** Resemble PerTh audio detection (no presence/confidence flag exists).
+**`Exif` item inside the `meta` box (AVIF/HEIF), now handled in place (2026-06-19):** an AI-generator token in an EXIF item (its TIFF bytes live in `mdat`/`idat`) is blanked by `isobmff.blank_ai_exif_tokens` — it finds EXIF TIFF blocks by their II/MM byte-order header, validates each with **piexif** (a coincidental II/MM run in pixel data won't parse as a TIFF IFD, so it is ignored), and overwrites any `Software`/`Make`/`Artist`/`ImageDescription` value carrying an `AI_GENERATOR_TOKENS` token with spaces of the **same length**. Same-length means every box size and `iloc` offset stays valid and the coded image is untouched — so it avoids the full `iinf`/`iloc` surgery (offset rewrite) that exiftool would need (exiftool is a non-installed binary dep, deliberately not used). It scrubs only the AI value; camera/editor EXIF is preserved. Wired into `remove_ai_metadata`'s ISOBMFF path after `blank_ai_xmp_packets`. Because the ISOBMFF branch never runs the JPEG `_scrub_ai_exif`, this is the ONLY EXIF scrubber on that path and must stay in PARITY with it: it now also blanks the China TC260 `{"AIGC":{...}}` block in `ImageDescription`/`UserComment` (via `_is_aigc_exif_value` — Doubao producer + Tencent service-provider schemas) and the xAI/Grok `Signature:` + UUID-`Artist` pair, not just `AI_GENERATOR_TOKENS` in `Software`/`Make`/`Artist`/`ImageDescription` (regression `test_noai.py::TestISOBMFF::{test_blank_aigc_block_in_exif, test_blank_xai_signature_pair_in_exif}`). **Still NOT built:** Resemble PerTh audio detection (no presence/confidence flag exists).
 
 **Audio watermark DETECTION (Resemble PerTh) was evaluated and NOT built (2026-05-26):** `resemble-perth`'s `PerthImplicitWatermarker.get_watermark()` returns a raw bit-array with **no presence/confidence flag** (clean audio decodes to arbitrary bits too), so reliably distinguishing watermarked-from-clean needs either Resemble's fixed payload or a confidence API -- neither is public, and there's no real Resemble sample to calibrate against. Same wall-class as the SynthID pixel detector: the decode exists, reliable presence-detection does not. (perth's top-level `PerthImplicitWatermarker` is also gated to None unless `librosa` is importable.)
 

docs/module-internals.md

@@ -15,7 +15,7 @@ module.
 
 ## `noai/constants.py`
 
-`noai/constants.py` — PNG_SIGNATURE, C2PA_CHUNK_TYPE, C2PA_SIGNATURES, and `C2PA_AI_VENDORS` — the single `C2paAiVendor` registry of C2PA-signing vendors (issuer byte, resolved org name, the `identify` platform label, and a `synthid` flag), from which `C2PA_ISSUERS`, `SYNTHID_C2PA_ISSUERS` (issuers that pair SynthID with C2PA: Google, OpenAI), and `identify._ISSUER_PLATFORM` are all **derived** — plus `C2PA_SOFT_BINDINGS` (soft-binding `alg` prefix → forensic-watermark vendor: Adobe TrustMark, Digimarc, Imatag, Steg.AI, Microsoft, ...). Add a new C2PA vendor as one `C2PA_AI_VENDORS` entry (never edit the derived dicts), a new soft-binding to `C2PA_SOFT_BINDINGS`; not inline. A vendor that signs under multiple legal names needs one entry PER distinctive issuer byte string: e.g. ByteDance's Volcano Engine is registered both as latin `volcengine` AND the Chinese legal entity `北京火山引擎科技有限公司` (UTF-8; the latin needle misses the Chinese-named certs entirely) — both normalize to the same "ByteDance" needle/platform. ElevenLabs ("Eleven Labs Inc.", pure generative-AI) is registered as a generator. Deliberately EXCLUDED (mined-corpus candidates 2026-06-20, documented in the file): TikTok Inc. (a content-provenance / AI-labeling signer on uploads, not a generator) and PixelBin.io / "Fynd" (an image transform / CDN signer) — registering either as a generator would mis-label human uploads as AI; the `is_ai` verdict keys off the digitalSourceType, which is already honored.
+`noai/constants.py` — PNG_SIGNATURE, C2PA_CHUNK_TYPE, C2PA_SIGNATURES, and `C2PA_AI_VENDORS` — the single `C2paAiVendor` registry of C2PA-signing vendors (issuer byte, resolved org name, the `identify` platform label, and a `synthid` flag), from which `C2PA_ISSUERS`, `SYNTHID_C2PA_ISSUERS` (issuers that pair SynthID with C2PA: Google, OpenAI), and `identify._ISSUER_PLATFORM` are all **derived** — plus `C2PA_SOFT_BINDINGS` (soft-binding `alg` prefix → forensic-watermark vendor: Adobe TrustMark, Digimarc, Imatag, Steg.AI, Microsoft, ...). Add a new C2PA vendor as one `C2PA_AI_VENDORS` entry (never edit the derived dicts), a new soft-binding to `C2PA_SOFT_BINDINGS`; not inline. A vendor that signs under multiple legal names needs one entry PER distinctive issuer byte string: e.g. ByteDance's Volcano Engine is registered both as latin `volcengine` AND the Chinese legal entity `北京火山引擎科技有限公司` (UTF-8; the latin needle misses the Chinese-named certs entirely) — both normalize to the same "ByteDance" needle/platform. ElevenLabs ("Eleven Labs Inc.", pure generative-AI) is registered as a generator. A vendor may also set **`asserts_ai=True`** — its presence asserts AI generation even without a `trainedAlgorithmicMedia` digital-source-type; the derived `C2PA_IDENTITY_AI_ORGS` frozenset feeds `identify`, which lifts the AI verdict for such an issuer. Set it ONLY for a pure-generator brand with a distinctive issuer/generator string: **Dreamina** (ByteDance's international Jimeng brand, signed as "Bytedance Pte. Ltd." with a `Dreamina/x.y` claim generator and NO source-type — the caBX / store-JSON byte-scan sees the `Dreamina` token across active + ingredient manifests, where the active one is often a plain `c2pa-tool` transcode; verified on the retained corpus 2026-07; normalizes to the shared "ByteDance" needle/platform). Do NOT set `asserts_ai` on common-word issuers (Adobe/Google/OpenAI/Microsoft) — they appear incidentally in unrelated XMP/trust-chain bytes, so they must stay source-type-gated. Deliberately EXCLUDED (mined-corpus candidates 2026-06-20, documented in the file): TikTok Inc. (a content-provenance / AI-labeling signer on uploads, not a generator) and PixelBin.io / "Fynd" (an image transform / CDN signer) — registering either as a generator would mis-label human uploads as AI; the `is_ai` verdict keys off the digitalSourceType, which is already honored.
 
 ## `metadata.py`
 
@@ -29,7 +29,7 @@ module.
 
 **AI-generated vs AI-enhanced** (`ProvenanceReport.ai_source_kind`, roadmap item): the C2PA digital-source-type is split into `"generated"` (trainedAlgorithmicMedia, fully synthetic) vs `"enhanced"` (compositeWithTrainedAlgorithmicMedia, a real photo with an AI-composited region) — the two byte strings are unambiguous (`compositeWithTrainedAlgorithmicMedia` capitalizes the inner "Trained", so a lowercase `trainedAlgorithmicMedia` match is standalone full generation; full generation wins when both appear). `ai_source_kind` is set only when the AI verdict actually came from the C2PA source type (a non-C2PA AI signal — IPTC/AIGC/local gen/xAI — leaves it None). It lets a caller branch a full-frame scrub (`generated`) from a region-targeted clean that preserves the real photo (`enhanced`; see `noai/tiling.feather_region_composite`). The CLI verdict line reads "AI-generated (fully synthetic)" vs "AI-enhanced (real content with an AI-composited region)".
 
-**Visible-mark detection** (`check_visible`, signals `visible_sparkle` / `visible_doubao` / `visible_jimeng` / `visible_samsung`): the Gemini sparkle keeps its own file-level path (`_visible_sparkle` → `gemini_engine.detect_sparkle_confidence`, promoted only at confidence ≥ `_SPARKLE_THRESHOLD`, which is the SHARED `watermark_registry.GEMINI_SPARKLE_TRUST_CONF` (0.5) — imported, not a private copy, so the provenance detect threshold and the removal `best_auto_mark` / `_gemini_detect` arbitration gate can never drift (the detect-vs-remove desync from roadmap P0#7; regression-guarded by `tests/test_identify.py::TestSparkleDetectRemoveAlignment`, which composites the real demo sparkle at borderline opacities and asserts identify and `best_auto_mark` AGREE on either side of the line). Lowering the gate to recover faint sub-0.5 sparkles was evaluated 2026-06-20 and REJECTED: a real Doubao text mark scores ~0.40-0.42 as a gemini match with a HIGHER core-ring brightness margin than a genuine faint sparkle, so neither confidence nor the brightness gate separates them in the [0.35, 0.5) band — lowering trades a rare miss for false-positive removals on clean images. Corpus-tuned to separate Gemini sparkles ≥0.56 from non-sparkle ≤0.49), while Doubao/Jimeng/Samsung reuse the registry detectors (`_visible_text_marks` → `watermark_registry`, iterating `_VISIBLE_MARK_PLATFORM`), each gated by its own engine NCC threshold via `MarkDetection.detected` (Doubao 0.4, Jimeng 0.45, Samsung 0.4). Doubao/Jimeng are normally also caught by the TC260 AIGC metadata label and Samsung by its C2PA + `genAIType` marker, so the visible path is their stripped-metadata fallback. Visible marks set `platform` only when no harder signal already did, and (like the sparkle) are excluded from integrity-clash vendor claims. The cv2 dependency lives in the engines, not here.
+**Visible-mark detection** (`check_visible`, signals `visible_sparkle` / `visible_doubao` / `visible_jimeng` / `visible_qwen` / `visible_samsung`): the Gemini sparkle keeps its own file-level path (`_visible_sparkle` → `gemini_engine.detect_sparkle_confidence`, promoted only at confidence ≥ `_SPARKLE_THRESHOLD`, which is the SHARED `watermark_registry.GEMINI_SPARKLE_TRUST_CONF` (0.5) — imported, not a private copy, so the provenance detect threshold and the removal `detect_marks` / `_gemini_detect` arbitration gate can never drift (the detect-vs-remove desync from roadmap P0#7; regression-guarded by `tests/test_identify.py::TestSparkleDetectRemoveAlignment`, which composites the real demo sparkle at borderline opacities and asserts identify and `detect_marks` AGREE on either side of the line). Lowering the gate to recover faint sub-0.5 sparkles was evaluated 2026-06-20 and REJECTED: a real Doubao text mark scores ~0.40-0.42 as a gemini match with a HIGHER core-ring brightness margin than a genuine faint sparkle, so neither confidence nor the brightness gate separates them in the [0.35, 0.5) band — lowering trades a rare miss for false-positive removals on clean images. Corpus-tuned to separate Gemini sparkles ≥0.56 from non-sparkle ≤0.49), while Doubao/Jimeng/Qwen/Samsung reuse the registry detectors (`_visible_text_marks` → `watermark_registry`, iterating `_VISIBLE_MARK_PLATFORM`), each gated by its own engine NCC threshold via `MarkDetection.detected` (Doubao 0.50, Jimeng 0.45, Qwen 0.45, Samsung 0.40). Doubao/Jimeng are normally also caught by the TC260 AIGC metadata label and Samsung by its C2PA + `genAIType` marker, so the visible path is their stripped-metadata fallback. Visible marks set `platform` only when no harder signal already did, and (like the sparkle) are excluded from integrity-clash vendor claims. The cv2 dependency lives in the engines, not here.
 
 **`import identify` is deliberately light** (~26 MB; ~36 MB with cv2 loaded by a visible-mark run, ~106 MB for a full `check_visible` run): it imports the `noai.c2pa`/`noai.constants` submodules, and `noai/__init__` is lazy (see "Test and lint"), so torch/diffusers are NOT pulled at import even in a full `gpu`/`detect` install — fits a 512 MB host. `noai.c2pa` does eagerly import the **c2pa-python** binary (Rust + cryptography, ~+5 MB RSS, no torch) for the primary `Reader` path — light enough to stay on the dependency-light host; a broken/absent wheel degrades to the byte-scan parser (`reader_available()` False). The heavy paths are opt-in: `check_invisible=True` needs the `detect`/`trustmark` extras (each pulls **torch**; TrustMark also **downloads weights**), so on a core-only deploy leave `check_invisible` off (it is a no-op there anyway). Before the lazy `__init__`, the mere presence of torch in the env inflated `import identify` to ~420 MB.
 
@@ -41,9 +41,9 @@ module.
 
 **Samsung Galaxy + ASUS Gallery live in a separate `_SIGNER_C2PA_PLATFORM` (scanned after `_device_platform`, before the issuer fallback), NOT in `_DEVICE_C2PA_PLATFORM`** — verified on real signed files 2026-05-29. Reason: a Galaxy phone stamps BOTH its device cert AND a `trainedAlgorithmicMedia`/genAIType AI marker on a Generative-Edit image, so treating it as a "genuine camera capture" would false-fire integrity-clash rule 2 on every Galaxy AI edit. The signer tokens (`b"Samsung Galaxy"` cert org — distinct from the EXIF `SM-xxxx` model string on ordinary Samsung photos; `b"com.asus.gallery"` claim generator) only resolve the platform label; the AI verdict still comes from the source-type / genAIType. ASUS Gallery is a C2PA-signed edit with no AI marker, so it attributes the platform without asserting `is_ai`.
 
-**Samsung's `genAIType` (in the proprietary `PhotoEditor_Re_Edit_Data` JSON) is an undocumented Galaxy-AI editing marker** (`metadata.samsung_genai`, gated on the `PhotoEditor_Re_Edit_Data` container; non-zero value = AI tool used, values {1,5} observed): medium-confidence because the field has no public spec (verified 2026-05-29: absent from C2PA spec + Samsung docs), but it co-occurred with `trainedAlgorithmicMedia` in 3/3 verified files that record a source-type and was the SOLE AI marker on a Galaxy S24 file that omits the source type. Camera C2PA marks capture authenticity, not AI (Pixel carries `computationalCapture`, not `trainedAlgorithmicMedia`), so these never set `is_ai` -- that stays driven by digital-source-type. `c2pa.cbor_text_after` (now public) is best-effort for the `generator` detail string only and can be None when the manifest keys it `claim_generator_info` (Pixel).
+**Samsung's `genAIType` (in the proprietary `PhotoEditor_Re_Edit_Data` JSON) is an undocumented Galaxy-AI editing marker** (`metadata.samsung_genai`, gated on the `PhotoEditor_Re_Edit_Data` container; non-zero value = AI tool used, values {1,5} observed; Galaxy AI appends it as a trailer AFTER the JPEG EOI, so `samsung_genai` reads the file TAIL when the 512 KB quick-scan head misses it — else a multi-MB photo's trailer past the window went undetected while removal, which reads the whole file, would still strip it; removal truncates the post-EOI Samsung trailer via `metadata._strip_samsung_trailer`, pixels bit-identical): medium-confidence because the field has no public spec (verified 2026-05-29: absent from C2PA spec + Samsung docs), but it co-occurred with `trainedAlgorithmicMedia` in 3/3 verified files that record a source-type and was the SOLE AI marker on a Galaxy S24 file that omits the source type. Camera C2PA marks capture authenticity, not AI (Pixel carries `computationalCapture`, not `trainedAlgorithmicMedia`), so these never set `is_ai` -- that stays driven by digital-source-type. `c2pa.cbor_text_after` (now public) is best-effort for the `generator` detail string only and can be None when the manifest keys it `claim_generator_info` (Pixel).
 
-**Issuer→generator mapping is `is_ai`-gated** (`_attribute_platform(issuers, is_ai=c2pa_is_ai)`): a specific AI-generator platform is named only when the digital-source-type is `trainedAlgorithmicMedia`; on a non-AI source an issuer substring is treated as incidental (an "Adobe XMP" toolkit string in an *unmapped* Canon/Sony capture would otherwise mislabel it "Adobe Firefly"), so it degrades to the neutral "C2PA signer: X" label. Real Firefly/OpenAI/Google output carries the AI source-type, so it is unaffected (verified: chatgpt-1.png→OpenAI, firefly-1.png→Adobe Firefly still attribute). `_attribute_platform` defaults `is_ai=True` so the mapping stays unit-testable in isolation. Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM`, editing-app/AI-device signer tokens to `_SIGNER_C2PA_PLATFORM`, generator/issuer platforms to the `C2PA_AI_VENDORS` registry in `constants.py` (which derives `_ISSUER_PLATFORM`), not inline. For non-PNG containers (JPEG/WebP/AVIF/HEIF/JXL) the caBX parser returns nothing, so issuer (`_issuers_in`) and generator (`_ai_tools_in`, reusing `C2PA_AI_TOOLS`) are recovered by binary-scanning the first MB. EXIF `Software` / `Make` / `Artist` / `ImageDescription`, XMP `CreatorTool`, and PNG `tEXt` chunks (`Software`/`Source`/`Title`/`Description` — NovelAI stamps its generator there, not EXIF) are read by `metadata.exif_generator` (PIL+piexif for any format PIL opens incl. AVIF, plus a container-agnostic XMP raw-byte scan that also covers HEIF/JXL), matched against `AI_GENERATOR_TOKENS` so ordinary editors (plain "Adobe Photoshop") and real-camera `Make` ("Apple"/"Canon") are not flagged. Tokens mined from the retained corpus 2026-06-22: `novelai`, `reve.com` (full token, not bare `reve`), `aphrodite ai` — all no-C2PA generator stamps that previously read as no-signal (and under the P0#5 no-signal skip would have skipped the scrub).
+**Issuer→generator mapping is `is_ai`-gated** (`_attribute_platform(issuers, is_ai=c2pa_is_ai)`): a specific AI-generator platform is named only when the digital-source-type is `trainedAlgorithmicMedia`; on a non-AI source an issuer substring is treated as incidental (an "Adobe XMP" toolkit string in an *unmapped* Canon/Sony capture would otherwise mislabel it "Adobe Firefly"), so it degrades to the neutral "C2PA signer: X" label. **The one exception is an identity-AI issuer** (`c2pa_is_ai = c2pa_source_kind is not None or c2pa_identity_ai`, where `c2pa_identity_ai` is any resolved issuer org in `C2PA_IDENTITY_AI_ORGS`): a vendor flagged `asserts_ai` (today only Dreamina) sets `c2pa_is_ai` True on its own, so its platform resolves even though the manifest carries no `trainedAlgorithmicMedia`. This is safe precisely because the flag is restricted to distinctive brand strings, not the incidental-mention-prone common words. Real Firefly/OpenAI/Google output carries the AI source-type, so it is unaffected (verified: chatgpt-1.png→OpenAI, firefly-1.png→Adobe Firefly still attribute). `_attribute_platform` defaults `is_ai=True` so the mapping stays unit-testable in isolation. Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM`, editing-app/AI-device signer tokens to `_SIGNER_C2PA_PLATFORM`, generator/issuer platforms to the `C2PA_AI_VENDORS` registry in `constants.py` (which derives `_ISSUER_PLATFORM`), not inline. For non-PNG containers (JPEG/WebP/AVIF/HEIF/JXL) the caBX parser returns nothing, so issuer (`_issuers_in`) and generator (`_ai_tools_in`, reusing `C2PA_AI_TOOLS`) are recovered by binary-scanning the first MB. EXIF `Software` / `Make` / `Artist` / `ImageDescription`, XMP `CreatorTool`, and PNG `tEXt` chunks (`Software`/`Source`/`Title`/`Description` — NovelAI stamps its generator there, not EXIF) are read by `metadata.exif_generator` (PIL+piexif for any format PIL opens incl. AVIF, plus a container-agnostic XMP raw-byte scan that also covers HEIF/JXL), matched against `AI_GENERATOR_TOKENS` so ordinary editors (plain "Adobe Photoshop") and real-camera `Make` ("Apple"/"Canon") are not flagged. Tokens mined from the retained corpus 2026-06-22: `novelai`, `reve.com` (full token, not bare `reve`), `aphrodite ai` — all no-C2PA generator stamps that previously read as no-signal (and under the P0#5 no-signal skip would have skipped the scrub).
 
 **Ideogram tags its output with EXIF `Make="Ideogram AI"`** (verified on a real download 2026-05-24) — that's why `Make` is read.
 
@@ -51,9 +51,9 @@ module.
 
 **Rule 2's independence gate (added 2026-06-11):** a device that both captures and runs on-device generative AI (Google Pixel Magic Editor / Pixel Studio) records the capture AND the AI edit in ONE C2PA manifest — so the AI vendor is named only from that same manifest (`c2pa` issuer + `synthid` proxy, both `c2pa_manifest` source) — a legitimate edit chain, NOT a clash. Rule 2 therefore fires only when some `ai_vendor_claims` family has a source `!= "c2pa_manifest"` (EXIF/XMP generator, IPTC, TC260 AIGC, a second manifest naming AI on a camera capture — the real laundering tell). This killed a false-positive class on the corpus: 2 real Pixel generative-edit PNGs (`computationalCapture` + `trainedAlgorithmicMedia` + "Applied imperceptible SynthID watermark" in one Google manifest) read as camera-vs-AI clashes before the gate. Pure cameras (Leica/Sony/Nikon/Truepic) that do NOT generate AI still clash on any within-manifest AI marker only if it is independent — they never legitimately carry one, so the gate is behavior-neutral for them while fixing Pixel (regression-guarded by `test_identify.py::TestIntegrityClashesHelper::{test_pixel_generative_edit_same_manifest_no_clash,test_camera_plus_independent_ai_marker_still_clashes}` + `TestIntegrityClashEndToEnd::test_pixel_generative_edit_no_clash`).
 
-**Independence is source-grouped (`_CLASH_SOURCE`, added 2026-06-02):** the C2PA issuer attribution (`c2pa`) and the SynthID proxy (`synthid`) are NOT independent — the proxy is inferred from the *same* manifest — so they share one source and two vendors named within a single manifest do not clash. This killed a false-positive class found on the spaces corpus: legitimate multi-actor manifests where a product wraps another vendor's engine (Microsoft Designer on OpenAI → `OpenAI, Microsoft`; Microsoft on Google → `Microsoft, Google LLC, Google C2PA Core Generator Library`) or an edit chain re-signs (Adobe over a Gemini original → Adobe c2pa + Google synthid) — 19 such files across the 2026-06-01/02 batches read as clashes before the fix. Rule 1 still fires when a manifest vendor disagrees with a genuinely independent stamp (EXIF/XMP generator, IPTC `AISystemUsed`, AIGC, xAI); each non-`c2pa`/`synthid` family is its own source (`test_identify.py::TestIntegrityClashes::{test_multi_actor_manifest_no_clash,test_manifest_vendor_vs_independent_signal_clashes}`). Vendor normalization is `_vendor_of` over `_AI_VENDOR_TOKENS` (so a C2PA "Google (Gemini)" issuer and a SynthID-Google proxy agree, while different vendors clash).
+**Independence is source-grouped (`_CLASH_SOURCE`, added 2026-06-02):** the C2PA issuer attribution (`c2pa`) and the SynthID proxy (`synthid`) are NOT independent — the proxy is inferred from the *same* manifest — so they share one source and two vendors named within a single manifest do not clash. This killed a false-positive class found on the spaces corpus: legitimate multi-actor manifests where a product wraps another vendor's engine (Microsoft Designer on OpenAI → `OpenAI, Microsoft`; Microsoft on Google → `Microsoft, Google LLC, Google C2PA Core Generator Library`) or an edit chain re-signs (Adobe over a Gemini original → Adobe c2pa + Google synthid) — 19 such files across the 2026-06-01/02 batches read as clashes before the fix. Rule 1 still fires when a manifest vendor disagrees with a genuinely independent stamp (EXIF/XMP generator, IPTC `AISystemUsed`, AIGC, xAI); each non-`c2pa`/`synthid` family is its own source (`test_identify.py::TestIntegrityClashes::{test_multi_actor_manifest_no_clash,test_manifest_vendor_vs_independent_signal_clashes}`). Vendor normalization is `_vendor_of` over `_AI_VENDOR_TOKENS` (so a C2PA "Google (Gemini)" issuer and a SynthID-Google proxy agree, while different vendors clash). `_AI_VENDOR_TOKENS` covers ByteDance (all brands: bytedance/doubao/jimeng/dreamina/volcengine), Canva, ElevenLabs, and Black Forest Labs in addition to the OpenAI/Google/Adobe/... set — without them a transplanted ByteDance/Canva/BFL C2PA manifest next to an independent conflicting stamp was silently missed. **The generic `China AIGC (TC260)` label names no SPECIFIC vendor** (any Chinese generator applies it), so it cannot vendor-conflict in the spoofing sense: when a Chinese TC260-applying vendor (`_TC260_VENDORS`, today `{ByteDance}`) is co-attributed, Rule 1 attributes the label to that vendor (a legit Doubao image carries BOTH a ByteDance C2PA manifest and its own TC260 label and must not clash); against a NON-TC260 vendor (OpenAI etc.) the label stays generic and still clashes as a laundering tell (`test_bytedance_c2pa_plus_own_aigc_no_clash`, `test_foreign_vendor_plus_aigc_still_clashes`, `test_bytedance_c2pa_plus_foreign_generator_clashes`). Corpus-validated: 0 new clashes on 5000 ByteDance/AIGC/Canva/FLUX carriers.
 
-**High-precision by design:** only hard generator stamps feed it (C2PA-issuer when source is AI, SynthID, EXIF/XMP generator, IPTC `AISystemUsed`, xAI, AIGC); the fuzzy visible sparkle and the open invisible watermark are **excluded** (the latter can be a by-product of our own SDXL removal pass). The c2pa vendor is classified from the issuer attribution / generator, NOT the resolved `platform` (a camera label like "Google Pixel" would mis-normalize to "Google"). All real single-origin fixtures (chatgpt/firefly/doubao/grok/mj) verified to produce **zero** clashes (false-positive guard in `test_identify.py::TestRealSamplesHaveNoClash`).
+**High-precision by design:** only hard generator stamps feed it (C2PA-issuer when source is AI, SynthID, EXIF/XMP generator, IPTC `AISystemUsed`, xAI, AIGC); the fuzzy visible sparkle and the open invisible watermark are **excluded** (both are low-precision/positive-only signals; the open watermark was also historically a by-product of our own SDXL removal pass, until `watermark_remover` was fixed to load the SDXL pipelines with `add_watermarker=False` — it stays excluded as a fuzzy signal regardless). The c2pa vendor is classified from the issuer attribution / generator, NOT the resolved `platform` (a camera label like "Google Pixel" would mis-normalize to "Google"). All real single-origin fixtures (chatgpt/firefly/doubao/grok/mj) verified to produce **zero** clashes (false-positive guard in `test_identify.py::TestRealSamplesHaveNoClash`).
 
 **`ai_from_metadata` field + `has_invisible_target` helper (P0#5, 2026-06-22):** the high-confidence union (everything that sets `confidence == "high"`: C2PA AI-issuer / SynthID proxy, IPTC, AIGC, local gen params, EXIF/xAI, open DWT-DCT / TrustMark — the medium-confidence `hf_only`/`visible_only`/`samsung_only` are excluded) is now surfaced as the public `ProvenanceReport.ai_from_metadata` boolean, so callers gate on intent rather than on the `confidence` string. `has_invisible_target(path)` wraps `identify(path, check_visible=False, check_invisible=True)` and returns that field — it is the decision gate for the diffusion scrub (the CLI `invisible`/`all`/`batch` no-signal skip, `cli._no_invisible_signal_exit`): a visible-only or no-signal image has it False, so regeneration (which would only degrade a clean image) does not run. It fails SAFE — any detector exception returns True so the removal still runs (leaving a watermark on a paid removal is worse than over-regenerating). It does NOT prove a pixel SynthID is absent (SynthID is detectable only via its metadata proxy, gone once stripped), so a False means "no locally-detectable target", never "clean". Guarded by `test_identify.py::{TestIdentifyRealSamples::test_has_invisible_target_*,TestHasInvisibleTargetFailSafe}`.
 
@@ -61,13 +61,135 @@ module.
 
 `watermark_registry.py` — **single catalog of known visible watermarks**, the unified "find known marks in their usual places, recognize, remove" entry.
 
-**Reverse-alpha based by policy**: a mark is listed only once a real alpha map has been captured for it, and removal inverts that map (`original = (wm - a*logo)/(1-a)`) — Gemini recovers cleanly with no inpaint (its sparkle alpha comes from a pure-black capture, so it is near-exact), while **Doubao, Jimeng, and Samsung all add an always-on THIN residual inpaint** over the glyph footprint (their text marks re-rasterize + jitter a few px per image, so a single capture cannot pixel-cancel them; the inpaint blends into the reverse-alpha-recovered pixels). Arbitrary-region inpainting still lives in `region_eraser`/`erase`. Each `KnownMark` ties a key to {usual `location`, `in_auto` flag, `recovery` (="reverse-alpha"), a `detect` adapter → uniform `MarkDetection`, a `remove` adapter}. Entries today: `gemini` (bottom-right sparkle), `doubao` (bottom-right "豆包AI生成"), `jimeng` (bottom-right "★ 即梦AI"), and `samsung` (bottom-**LEFT** "✦ Contenuti generati dall'AI", Samsung Galaxy AI, Italian locale). `detect_marks` scans all; `best_auto_mark` picks the highest-confidence detection.
+**Localize -> fill by policy (replaced reverse-alpha):** each mark is localized to a binary full-frame footprint mask (a `Localization`), and one shared, swappable fill inpaints that mask via `fill(image, mask, backend=...)` (delegates to `region_eraser.erase`). This replaced the old reverse-alpha removal (invert a captured alpha map, `original = (wm - a*logo)/(1-a)`, plus a thin residual inpaint) for ALL marks — gemini, doubao, jimeng, samsung, and jimeng_pill. **Why it changed:** reverse-alpha depended on a fixed captured alpha map at a fixed position, so it broke whenever a vendor moved or re-rendered its mark; and it was not color-lossless even with the right map (it amplifies 8-bit quantization and JPEG-chroma error by `1/(1-a)`), which showed up as "the color just changed, not removed" reports. Localize -> fill has a benign failure mode: a slightly-off localization just inpaints a small region near-losslessly instead of leaving a color-shifted smear. The captured alpha maps are still used to DETECT the marks and to shape the mask (gemini's footprint), but NOT for pixel recovery. Fill backends: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, light, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available. Each `KnownMark` ties a key to {usual `location`, `in_auto` flag, a `_detect` callable → uniform `MarkDetection`, a `_mask` callable → full-frame footprint mask}; `KnownMark.remove(image, *, backend="auto", provenance=False, force=False)`. Entries today: `gemini` (bottom-right sparkle), `doubao` (bottom-right "豆包AI生成"), `jimeng` (bottom-right "★ 即梦AI"), `qwen` (bottom-right "千问AI生成", Alibaba Tongyi Qianwen), `samsung` (bottom-**LEFT** "✦ Contenuti generati dall'AI", Samsung Galaxy AI, Italian locale), and the capture-less `jimeng_pill` (top-left "AI生成"). `detect_marks(image, *, provenance=frozenset())` scans all (strict, for the identify verdict); `remove_auto_marks(image, *, sensitivity="auto", provenance=frozenset(), backend="auto")` removes every detected mark in one pass. **Sensitivity (`auto`/`strict`/`assume_ai`)** decides how hard a borderline mark is trusted: the visual detectors are pixel-based (no metadata needed) and the recall gain comes from relaxing the false-positive gate, not from metadata. `resolve_trust` turns the policy + evidence into the per-mark trust level the engines consume as `provenance = level != "strict"` — `strict` never relaxes; `auto` relaxes only on same-product evidence (metadata provenance for that vendor, or a confidently strict-detected sibling of the same `_PRODUCT_OF` — Doubao and Jimeng are both bottom-right ByteDance but distinct products, so they do NOT cross-relax); `assume_ai` relaxes every mark (the caller asserts AI, e.g. a metadata-stripped screenshot). **Three levels, not two: `strict` / `assumed` / `confirmed`.** Relaxing bypasses the engine's false-positive gate outright, and that bypass is contracted to mean the vendor is CONFIRMED (`GeminiEngine.detect_watermark`'s `trust_provenance`: "external metadata already proves this is a Google generation"). An `assume_ai` caller asserts the image is AI, which says nothing about WHICH vendor, so a mark relaxed on assumption alone must also clear `_ASSUMED_CONF_FLOOR` (`assumed_floor_ok`; gemini 0.50) — see "Assumed-trust confidence floor" below. **Perception / decision / action are separated three ways** (the removal path only; `identify` keeps calling `KnownMark.detect` directly, so its verdict is untouched): `_build_candidates(image)` is PERCEPTION — it runs each detector at both trust levels and packages raw verdicts + the pill's flatness feature into `Candidate`s, no policy; `decide(candidates, Context(sensitivity, provenance)) -> [Decision]` is the pure DECISION arbiter — all keep/drop policy (`resolve_trust` cross-mark corroboration + the assumed-trust floor + the pill gate) in one image-free, unit-testable function (`tests/test_watermark_registry.py::TestArbiter`); then `remove_auto_marks` does the ACTION, localizing -> filling each winner. The Gemini FP gate deliberately stays inside `gemini_engine` (not the arbiter) because `identify` reads that same gated confidence — pulling it out would drift the provenance verdict. Behavior was byte-identical to the pre-arbiter two-pass when the arbiter landed; `assume_ai` has since gained the assumed-trust confidence floor (see below), which deliberately changes its verdict on weak gate-bypassed matches.
 
-**Cross-engine confidences aren't directly comparable**, so the gemini adapter applies the corpus-validated 0.5 sparkle threshold (`_GEMINI_AUTO_MIN_CONF`) for its `detected` flag — otherwise the gemini engine's loose internal threshold weakly fires (~0.36) on the Doubao text and hijacks `auto`. The shape-keyed Doubao/Jimeng/Samsung NCC detectors don't cross-fire (jimeng scores ~0.22 on the Doubao strip, well under its 0.45 threshold; Samsung is bottom-left so it shares no corner with the others, and scored 0.0 on Doubao/Jimeng captures and they 0.0 on a real Samsung photo), so `auto` picks the right one. `cli.cmd_visible` is registry-driven: `--mark auto` → `best_auto_mark`, `--mark <key>` → that mark; `--mark` choices come from `mark_keys()`.
+**Head-to-head validation (v0.12.1 reverse-alpha vs the current localize -> fill):** run over the full labelled visible-mark set, with the cv2 / MI-GAN / LaMa fills each compared against the old reverse-alpha. **doubao and jimeng are identical** across every backend -- 100% coverage and 100% clearance either way. **gemini** strict coverage is a few points below reverse-alpha's (the deliberate false-positive tightening), but the metadata-stripped faint ones are now mostly recovered by the DEFAULT white-core rescue in the FP gate (`gemini_engine`: a bright near-WHITE core distinguishes a real faint sparkle from a colored bright corner -- ~14/20 recovered at ~1.25% clean false-fire; a learned classifier on the same features measured worse, 2026-07 tier-1), the residual under `assume_ai`; clearance is equal (~98% both), and neither version touches pixels outside the mark box (outside-box PSNR ~99). **Clearance is fill-independent** -- cv2, MI-GAN and LaMa all strip the mark's shape equally, so the re-detect metric does not separate them; the difference is purely the *visual fill quality* on the recovered region, and it is background-dependent. reverse-alpha recovered textured and especially regular/structured backgrounds (a lattice, a grid) more cleanly than any inpaint; **LaMa closes most of that gap** (the best learned backend), **MI-GAN can ghost or hallucinate structure**, and **cv2 smears** (the last-resort floor). This is why `auto` resolves `LaMa > MI-GAN > cv2` (`preferred_inpaint_backend`) and warns once on the cv2 fallback; on flat backgrounds every backend is clean.
 
-**`cli._remove_visible_auto` is the shared visible-removal helper used by `cmd_all`/`cmd_batch` too** (they no longer hardcode `GeminiEngine`), so `all`/`batch` remove Doubao/Jimeng/Samsung text marks, not just the Gemini sparkle (regression-guarded by `test_all_visible_step_uses_registry`). The three text-mark adapters were consolidated 2026-06-09: a single `_text_mark(key, label, location)` builds the registry row from one parameterized `_text_mark_detect`/`_text_mark_remove` pair (reverse-alpha only when detected/forced AND `reverse_alpha_available`, else skipped — no inpaint); the gemini adapters stay bespoke. Add a new visible mark = one `_text_mark(...)` row + its `TextMarkConfig` (with a captured alpha map); do not re-add per-mark `if` branches or copy-paste adapters.
+**`assume_ai` removed (2026-07-19).** It relaxed EVERY mark's false-positive gate on the caller's bare assertion that an image is AI. That assertion says nothing about WHICH vendor or WHERE the mark is, which is exactly what a gate bypass is contracted to require -- before it carried a confidence floor it filled a phantom sparkle on 59.8% of genuine camera photos, and even with the floor it was a statistical gamble rather than an instruction. It also had no place in the product's model: detector finds a mark -> remove it; detector finds nothing -> leave the image alone; the USER sees a mark and says so -> act on that.
 
-**Alpha-on-save policy (issue #30):** `cli._write_bgr_with_alpha` rejoins the input's alpha plane **unchanged** — it must NOT zero alpha in the watermark bbox. Reverse-alpha (and `erase` inpaint) recover real pixels there, so zeroing alpha punched a transparent hole that renders as a solid **white box** on any non-transparent viewer (Gemini app exports are opaque RGBA, so every user hit it; regression-guarded by `test_visible_keeps_alpha_opaque_in_watermark_region`). The registry `remove()` still returns its region (used for `inpaint_residual` positioning), but the CLI no longer uses it to clear alpha.
+Removing it collapsed the trust ladder from three levels to two (`strict` / `confirmed`) and took `_ASSUMED_CONF_FLOOR`, `assumed_floor_ok` and the `assumed` level with it. `_keep_pill` lost its `sensitivity` parameter (its assume-arm is gone; the metadata arm and its flatness guard are unchanged). Verified on the 240-image unbiased recall sample: doubao 92%/99%, gemini 96%/80%, jimeng 71%/71%, pill 50%/60% -- identical before and after, so nothing on the default path moved.
+
+**The replacement advice is PER MARK, because the forced paths are not equally reliable** (measured 2026-07-19):
+
+| path | reliability |
+|---|---|
+| `erase --region x,y,w,h` | sound by construction -- the user supplies the coordinates |
+| `--mark <text-mark> --no-detect` | reasonable: the forced mask is the real glyph blob, non-empty on 13/13 missed doubao marks |
+| `--mark gemini --no-detect` | **NOT recommended** -- falls back to a fixed default sparkle slot, which covered the true sparkle on only **31% of 97** sparkles the strict gate missed (median offset 63px up-and-left). The other 69% fill a clean corner AND report a removal that did not happen. |
+
+`cli._no_visible_mark_exit` therefore recommends `erase --region` first and a named text mark second, and never suggests forcing gemini. It previously recommended `--sensitivity assume-ai`, i.e. the product's own hint contradicted its model.
+
+**Migration is LOUD, not silent.** `Sensitivity` is a `Literal` and unenforced at runtime, so a 0.15 caller passing `sensitivity="assume_ai"` would otherwise get `auto` behaviour in silence -- a quiet semantic change on exactly the release where they need telling. `validate_sensitivity` (called by `api.remove_visible` and by `Context.__post_init__`) raises a `ValueError` naming the replacement. Regression: `tests/test_watermark_registry.py::TestNoBlanketRelaxation`.
+
+**Continuous top-hat detection front-end (`detect_frontend` / `tophat_response`, 2026-07-18).** `extract_mask` thresholds the white top-hat into a 0/255 glyph blob and correlates a binary silhouette against it. That is fine for a mark stamped bold and opaque, and destructive for a faint one: a thin translucent overlay shatters into specks under the threshold, and no template can match a blob that is not there (千问 measured 0.170 mean NCC, **0%** over its gate, against doubao's 0.723 / 82% -- same pipeline, each with its own template). The `tophat` front-end never binarizes: the saturation and absolute-luma gates become WEIGHTS instead of hard cuts, so a faint stroke contributes in proportion to its strength, and the response is max-normalized, which makes the score contrast-invariant.
+
+Doubao is switched to it; jimeng and samsung stay `binary` until measured, because a front-end change must be measured per mark before it ships. Corpus effect on the 240-image unbiased recall sample:
+
+| mark | recall before | recall after | precision before | precision after |
+|---|---|---|---|---|
+| doubao | 89% | **92%** | 99% | **99%** |
+| jimeng / gemini / pill | unchanged | unchanged | unchanged | unchanged |
+
+**The gate is FRONT-END SPECIFIC and must be re-calibrated, not ported.** The continuous response scores higher overall (mean 0.809 vs 0.723 on the same 90 positives), so the binary-era 0.40 left the provenance-relaxed gate (x0.7) far too low: at 0.40 the arm ran 96% recall / 91% precision (8 false fires), at 0.50 it runs 92% / 99% (1 false fire). 0.50 was chosen because it beats the binary front-end on recall at IDENTICAL precision -- a front-end that only trades one for the other would not have been worth shipping. A first pass at 0.40 also silently depressed the PILL (recall 50% -> 33%), because `_keep_pill` suppresses the pill whenever doubao fires; a coupling worth remembering when tuning any bottom-right mark.
+
+**The removal MASK must ride the same front-end, and how it does so was fixed twice.** `tophat` detection does not binarize, but `extract_mask` (which bounds the fill) still does, so a mark faint enough to be found only by the continuous response produced an EMPTY binary blob: `localize` returned `mask=None`, `remove()` was a silent no-op, and `identify` reported `visible_doubao` while `visible` said "no visible mark" on the same file (corpus-measured 2026-07-20: 57 of 60 sampled still-detected Doubao marks untouched, ~8% of its detections). The FIRST fallback (2026-07-19) thresholded the continuous response and took the bounding box of everything above the level -- but the level was `0.5` compared against the max-normalized **uint8 0..255** response, so it selected every non-zero pixel and filled ~120% of the corner box on textured frames (a padded whole-ROI box). It passed parity (a mask that fills everything is trivially detector-clean) and its regression test (a FLAT fixture, where the response is non-zero only on the glyph, so every threshold yields the same box). The SECOND fallback (2026-07-20) uses the detector's OWN best-match box instead: `_tophat_score` was split into **`_tophat_best(image, loc) -> (score, box)`**, the single method whose score gates detection and whose argmax box bounds the mask -- so the two cannot drift by construction, which is how the mismatch arose in the first place. Measured over 14 real faint-path frames (cv2 fill, detector re-run after): the match box fills a **58.7%**-median corner box vs the threshold's **120.9%**, both 100% detector-clean. The largest-connected-component alternative was tighter (10.5%) but removed the mark on only 21% of frames, so it does not cover it and was rejected. Regression: `tests/test_text_mark_faint_mask.py`, whose fixture now carries texture (the flatness of the old one is exactly why it could not see the threshold bug -- mutating the constant to 99.0 left it green). **Any future front-end change must move both the detection and the mask path, or re-check this.**
+
+**Vendor ATTRIBUTION for the shared-suffix marks -- solved for 千问 by exact sizing, not by a generic template.** The 2026-07-18 worry was that "千问AI生成" and "豆包AI生成" share the `AI生成` tail (four of six glyph cells), so their templates would cross-fire. That held while Qwen was scored at the WRONG SIZE (AUC 0.41-0.59, a coin flip). Re-measured 2026-07-21 at the fitted geometry on real pools (`scripts/vendor_mark_calibrate.py --crossfire`): Qwen's template scores p50 0.224 / p90 0.242 on 400 Doubao-marked frames against a 0.45 gate -- **0 cross-fires**, and 0 on 298 Jimeng-marked frames and 286 clean frames -- because an exact-size 6-glyph template is specific enough that the 2-glyph prefix mismatch dominates the shared tail. Qwen was therefore registered WITHOUT a rival margin (a 0.10 margin would have suppressed ~10% of genuine Qwen detections, whose margin p10 sits at 0.00). A GENERIC shared-tail template remains a harvesting aid, not a detector (measured: 0.407 on a bold positive vs clean p99 0.298).
+
+**千问 is registered since 2026-07-21; 星绘 is NOT (still one confirmed example).** The 2026-07-18 measurement below is why 千问 was originally held out -- it is kept because it records the failure CLASS that the registration then had to solve. Measured back then on 14 hand-verified corpus positives, same pipeline, each mark scored with its OWN template:
+
+| mark | n | mean NCC | median | above the 0.40 gate |
+|---|---|---|---|---|
+| doubao | 40 | 0.723 | 0.835 | **82%** |
+| qwen | 14 | 0.170 | 0.179 | **0%** |
+
+Three candidate explanations were ruled out in order, each by measurement:
+1. **Not the synthetic render.** A template cut from an ACTUAL Qwen mark scores the same as the font-rendered one (real-vs-real 0.307 vs synthetic 0.308), and real masks do not match EACH OTHER.
+2. **Not the morphology kernel.** `MORPH_OPEN`/`MORPH_CLOSE` use fixed 5px kernels regardless of mark size (~9% of a 57px-tall box, ~2.7% of a 188px one). Scaling them with the box height gained +0.014 mean and moved nothing across the gate.
+3. **Not the appearance thresholds.** Sweeping `tophat_delta` / `logo_min_luma` / kernel size peaked at mean 0.35 with 4/14 over the gate.
+
+The blocker was named as SEGMENTATION on a faint mark -- and the `tophat` front-end (built for Doubao the same week) removed exactly that blocker, yet 千问 still did not register, because the real residual was never segmentation alone: it was **mis-sized geometry** (two size modes the shared 3-rung ladder cannot straddle, plus a locate box that clipped the first glyph). The 2026-07-21 cohort harvest (117 labelled frames) and the full calibration chain are in the `qwen_engine.py` section below and `docs/verification-plan.md`. 星绘 remains where it was: ONE confirmed corpus example, so nothing to calibrate a gate against -- do not register it off a single frame. The synthetic renderer and the evidence chain are kept in `scripts/render_vendor_silhouettes.py`; researched vendor specs are in `docs/watermarking-landscape.md`.
+
+**RECALL, measured at last (unbiased random sample, 2026-07-18).** Every earlier round sampled where detectors FIRED, so recall was structurally unmeasurable. This round draws 240 images at RANDOM within each provenance class (160 TC260, 80 Google-C2PA) and labels them EXHAUSTIVELY -- both corners shown at native scale, so a missed mark is visible as a miss rather than absent from the data. Build it with `scripts/visible_recall_sample.py`; labels live in the gitignored research dir.
+
+| mark | present | recall | 95% CI | precision | 95% CI |
+|---|---|---|---|---|---|
+| doubao | 90 | **89%** | 81-94% | **99%** | 93-100% |
+| gemini | 46 | **96%** | 85-99% | **80%** | 68-88% |
+| jimeng | 14 | 71% | 45-88% | 71% | 45-88% |
+| jimeng_pill | 6 | 50% | 19-81% | 60% | 23-88% |
+
+Effect of the `scale_basis` fix on the same sample (strict verdicts recorded before it): **doubao recall 71% -> 89%**, gemini 91% -> 96%, jimeng 64% -> 71%. Part of the doubao gain is the provenance relaxation rather than the basis alone, since the after-numbers run the full `auto` path.
+
+**Three corrections this forced to earlier numbers:**
+* **Gemini precision is 80% on an unbiased sample, not the 41% the addition-sampled harness reports.** The 41% is precision restricted to relaxation ADDITIONS, which are by construction the marginal cases; production sees mostly strict fires, which are near-perfect. Quote 80% for the product and 41% only when discussing the relaxation arm.
+* Doubao is in excellent shape (89/99) and is no longer the problem it looked like before the basis fix.
+* Landscape is improved but NOT solved: doubao recall by aspect is portrait 92% / square 92% / **landscape 79%**, so a residual geometry gap remains beyond the basis.
+
+**Where the remaining loss actually is:** jimeng and the pill, both at small n with intervals too wide to tune against (a 14-positive and a 6-positive sample), plus **uncovered vendors at 6% of all sampled images** (千问/百度/星绘/抖音-class marks that no registered detector can ever fire on). Adding those vendors is now a larger win than any further tuning of the covered four, and `docs/watermarking-landscape.md` carries their researched specs.
+
+**Per-mark geometry scaling (`scale_basis` / `scale_base`, 2026-07-18) -- the largest single recall defect found so far.** Every tuned fraction in `TextMarkConfig` was calibrated on PORTRAIT captures, where the width and the short side coincide, so the scaling basis was never exercised until landscape inputs were measured. Corpus-measured on 2572 unique TC260 carriers, BEFORE the fix:
+
+| aspect ratio | detected | missed | miss rate |
+|---|---|---|---|
+| tall portrait <0.70 | 323 | 212 | 40% |
+| portrait 0.70-0.95 | 607 | 533 | 47% |
+| square ~1.0 | 190 | 272 | 59% |
+| landscape 1.15-1.6 | 0 | 143 | **100%** |
+| wide >1.6 | 0 | 292 | **100%** |
+
+**Not one landscape image in the corpus ever produced a detection** -- 435 of them, zero. A width-scaled box is inflated by the aspect ratio on a wide image, so the glyph never lands inside it and the blob never gets scored: of the 1452 no-detection TC260 images the median doubao NCC was **0.057**, with 49% at ~zero. This is a LOCALIZATION failure, not a threshold one -- only 2.7% of those images sat in the band a threshold change could reach, which is why a day of threshold tuning could never have found it. Re-running the previously-undetected set with a short-side basis recovers **56% of landscape** (12% square, 4% portrait; 20% overall).
+
+**The basis is PER MARK because the vendors genuinely differ.** The same switch took jimeng's labelled landscape positives from 13/13 to **0/13**: the Jimeng wordmark tracks the WIDTH while the Doubao strip tracks the short side, even though both are ByteDance and share a corner. So doubao is `short`, jimeng is `width`, and samsung stays `width` because there is no corpus evidence either way (1 addition corpus-wide) and an unmeasured change is not an improvement. China's GB 45438-2025 clause 5.2(e) mandates glyph height >= 5% of "the shortest side", which is why short-side is the natural prior -- but jimeng's measured behaviour overrides the prior. Regression: `tests/test_text_mark_engine.py::TestScaleBasis`.
+
+**How this was missed for so long:** precision was measured repeatedly and recall never was. The eval harness now reports a `missed` column for exactly this reason, and it is what caught the jimeng regression the short-side switch introduced.
+
+**Competitive detection among same-corner marks (`rivals` / `_rival_margin_ok`, 2026-07-18).** Detection was purely ABSOLUTE -- every engine scored its own template against its own threshold, so nothing ever asked the discriminative question "does this blob match the NEIGHBOUR's mark better than mine?". Doubao "豆包AI生成" and Jimeng "★ 即梦AI" both sit bottom-right in near-white CJK and survive the top-hat binarization as very similar blobs, so no absolute gate can separate them. Measured on hand-labelled examples, scoring BOTH templates against the SAME glyph blob (n=40 jimeng / 75 doubao / 20 other-vendor labels / 89 clean):
+
+| feature | separability (0.5 = useless, 1.0 = perfect) |
+|---|---|
+| absolute `ncc_jimeng` | 0.96 |
+| `ncc_jimeng` MINUS `ncc_doubao` | **0.99** |
+
+At a 0.10 margin: real Jimeng wordmarks pass **100%**, Doubao strips 8%, other vendors' AI labels (千问/百度/星绘/抖音) 55%, no-mark corners 12%. Corpus effect (`scripts/visible_eval.py`, 741 labelled images): **jimeng precision 38% -> 63%, genuine detections unchanged at 40, false fires 65 -> 23.** Because real marks pass at 100% this is a pure precision gain, unlike raising a threshold -- so the earlier 0.85 relaxation patch was REVERTED to 0.70 and the recall it had sacrificed came back. **The gate is deliberately asymmetric:** doubao declares no rival, because the symmetric gate cost it 7 genuine detections to prevent 5 false ones (1.4:1 against) while jimeng gained 25pp for free -- doubao's absolute detector is already 86% precise and has nothing to buy. A rival's config is looked up lazily by asset name (`_rival_config`) so its template is scored at ITS own geometry; scoring it at the host mark's geometry would compare a correctly-sized template against a mis-sized one and hand the margin a free win. Regression: `tests/test_text_mark_engine.py::TestRivalMargin`.
+
+**Evaluation harness (`scripts/visible_eval.py` + `scripts/visible_groundtruth.py`, 2026-07-18).** Run before AND after any detector change; `--save NAME` snapshots, `--vs NAME` diffs. Ground truth is 741 blind-labelled corpus images (779 cells across two rounds, two-sided control each). Three properties of the harness are load-bearing and were each added after the naive version produced a wrong number:
+
+* **Adjudication scope.** A crop centred on one mark only lets the labeller rule on marks visible IN THAT CROP. Scoring jimeng against a pill-round image (top-left crop) books real bottom-right detections as false fires -- ~61% of pills carry a wordmark. Each image records which marks its crop could rule on; bottom-right marks co-adjudicate each other.
+* **Provenance must come from METADATA, never from the labels.** A relaxation arm only fires when provenance names the vendor, so label-derived provenance hands the detector the answer: it scored gemini at 99% instead of the true 41%.
+* **Recall is NOT reported.** The labelled set was sampled where detectors fired, so images every detector missed are absent by construction; a recall computed here would divide by a denominator that excludes exactly the failures recall exists to expose. The `missed` column catches a change LOSING marks it used to find, nothing more. True recall needs a random corpus sample labelled exhaustively -- not yet done.
+
+Baseline at the time of writing (sensitivity `auto`, provenance from metadata): gemini 41% (321 fires), doubao 86% (77), jimeng 63% (63), jimeng_pill 64% (83), samsung unmeasurable (1 addition corpus-wide).
+
+**Per-mark provenance NCC relaxation + the corroboration gate (2026-07-18).** Two defects, both on the DEFAULT `auto` path (no flag, driven by TC260 metadata), found by blind hand-labelling the ADDITIONS (accepted with provenance, rejected without) over 4417 unique TC260 carriers. Two-sided control: labeller sensitivity 100% (doubao) / 96% (jimeng), specificity 100% / 100% — the controls are what make the low numbers trustworthy, and the "clean" stratum is structural (another vendor's C2PA image, where a ByteDance mark cannot exist) rather than detector-defined, so it is not circular.
+
+(1) **One shared `_PROVENANCE_NCC_FACTOR = 0.7` meant two different things per mark:**
+
+| mark | band | precision | 95% CI | n |
+|---|---|---|---|---|
+| doubao | whole arm | 76% | 61-87% | 42 |
+| | [0.280,0.340) | 58% | 36-77% | 19 |
+| | [0.340,0.400) | 91% | 73-98% | 23 |
+| jimeng | whole arm | 17% | 10-27% | 82 |
+| | [0.315,0.383) | 12% | 6-22% | 68 |
+| | [0.383,0.450) | 43% | 21-67% | 14 |
+
+The factor is now a per-mark `TextMarkConfig.provenance_ncc_factor`. Doubao stays 0.70 — both bands return more true marks than false fills, so tightening would cost 11 genuine recoveries to prevent 8. Jimeng moves to 0.85 (gate 0.3825), dropping the 12% band: −8 genuine recoveries, −60 false fills (7.5:1), arm precision 17% → 43%. **Why jimeng fails is a detector problem, not a threshold one:** of its 68 false additions, 33 were DOUBAO marks and 17 were other vendors' AI labels (千问 / 百度 / 星绘 / 抖音) — relaxed, the silhouette keys on "some text in the bottom-right corner", not on "★ 即梦AI". Damage was scored separately because doubao and jimeng share a corner: 45 of the 68 fill a corner nothing else would touch, the other 23 are harmless (doubao fires strictly there and fills the same box anyway). A better silhouette, not a lower factor, is the real fix.
+
+(2) **A weak detector must not corroborate a sibling (`_CANNOT_CORROBORATE`).** `resolve_trust` grants `confirmed` on a strict-detected sibling of the same `_PRODUCT_OF`, and `confirmed` bypasses the sibling's FP gate outright. The pill (~7% documented raw false-fire; 5.5% on 578 vendor negatives) maps to product "jimeng", so it could hand that bypass to the wordmark — a closed loop: pill false-fires on clean non-ByteDance content → jimeng relaxes 0.45 → 0.3825 and false-fires → `_keep_pill` sees "jimeng" in keys and takes the WORDMARK arm, removing the pill **unrestricted**, skipping the flatness guard written to stop exactly that smear. 3 of 578 negatives ran the full loop, one with `footprint_flat=0`. The fix costs nothing: negatives 3 → 0, TC260 carriers unchanged (jimeng 398 → 398, pill 117 → 117). `_keep_pill` already encoded this distrust for the pill's ACTION; the gap was that its TESTIMONY was ungated.
+
+**Pill arms, re-measured on the same corpus** (149 blind-labelled TC260-arm fires, 35 wordmark, 33 unconfirmed): wordmark **94%** (CI 81-98%, confirming the original claim), TC260-metadata-only **21%** raw (CI 16-29%, consistent with the original ~27%) — **29%** (CI 20-40%) among the flat footprints the guard PASSES vs 14% among those it blocks. The guard works directionally but weakly: the shipped arm still runs at ~2.4 false fills per genuine one. Whether an arm that inaccurate belongs on the default path is a product call, not a tuning one.
+
+**Samsung's relaxation is UNMEASURED and not measurable here:** the corpus holds 14 `samsung_genai` carriers and 3 visible Samsung detections total. Any precision estimate would carry a Wilson interval spanning most of [0,1]. Likely structural — detection is calibrated to the Italian locale string only.
+
+
+**Provenance prior:** when local metadata already confirms the vendor, the mark's detection trust gate is relaxed (a confirmed vendor means the mark is present with high prior, so a mark the conservative detector would demote as a content false positive is trusted). `detect_marks` / `remove_auto_marks` take a `provenance` frozenset and `KnownMark.remove` a `provenance` flag. Mapping: a Google/Gemini C2PA issuer relaxes gemini (skips its false-positive gate and lowers the trust threshold from 0.5 to 0.35); a China-AIGC (TC260) label relaxes doubao/jimeng; `samsung_genai` relaxes samsung. Corpus finding: on Google-C2PA images, Gemini sparkle recall rose from ~46% (plain detector) to ~90% with the provenance prior (recovering marks the vendor moved or re-rendered). That gain is why the bypass exists, and it is conditional on the metadata actually naming the vendor — a caller merely ASSUMING the image is AI does not get it unconditionally (see the assumed-trust confidence floor above). The localizer is cheap CPU (cv2/numpy), so a memory-tight caller runs it anywhere; the heavy MI-GAN/LaMa fill is opt-in and chosen by the caller.
+
+**Cross-engine confidences aren't directly comparable**, so the gemini adapter applies the corpus-validated 0.5 sparkle threshold (`_GEMINI_AUTO_MIN_CONF`) for its `detected` flag (lowered to 0.35 under the Google/Gemini provenance prior) — otherwise the gemini engine's loose internal threshold weakly fires (~0.36) on the Doubao text and hijacks `auto`. The shape-keyed Doubao/Jimeng/Samsung NCC detectors don't cross-fire (jimeng scores ~0.22 on the Doubao strip, well under its 0.45 threshold; Samsung is bottom-left so it shares no corner with the others, and scored 0.0 on Doubao/Jimeng captures and they 0.0 on a real Samsung photo), so `auto` picks the right one. `cli.cmd_visible` is registry-driven: `--mark auto` → `remove_auto_marks` (removes every detected mark), `--mark <key>` → that mark; `--mark` choices come from `mark_keys()`.
+
+**`cli._remove_visible_auto` is the shared visible-removal helper used by `cmd_all`/`cmd_batch` too** (they no longer hardcode `GeminiEngine`), so `all`/`batch` remove Doubao/Jimeng/Qwen/Samsung text marks, not just the Gemini sparkle (regression-guarded by `test_all_visible_step_uses_registry`). The three text-mark adapters were consolidated 2026-06-09: a single `_text_mark(key, label, location)` builds the registry row from one parameterized `_text_mark_detect`/`_text_mark_remove` pair (the remove adapter localizes the glyph footprint and hands it to the shared `fill` only when detected/forced, else skipped); the gemini adapters stay bespoke. Add a new visible mark = one `_text_mark(...)` row + its `TextMarkConfig` (with a captured alpha map for the detection silhouette); do not re-add per-mark `if` branches or copy-paste adapters.
+
+**Alpha-on-save policy (issue #30):** `image_io.write_bgr_with_alpha` (it lives in `image_io`, not `cli` — moved so the CLI and the library `api` share ONE implementation) rejoins the input's alpha plane **unchanged** — it must NOT zero alpha in the watermark bbox. The fill reconstructs real pixels there, so zeroing alpha punched a transparent hole that renders as a solid **white box** on any non-transparent viewer (Gemini app exports are opaque RGBA, so every user hit it; regression-guarded by `test_visible_keeps_alpha_opaque_in_watermark_region`). The registry `remove()` still returns its region, but the CLI no longer uses it to clear alpha. **It returns `imwrite`'s success flag and callers must check it** (2026-07-20): `imwrite` is contractually non-raising, so that bool is the only signal the file was not created. The wrapper previously returned `None` and swallowed it, so every CLI write site ran `output.stat()` to report the size and a read-only destination died with a bare `FileNotFoundError` traceback pointing at the stat instead of the write. The CLI now writes through the shared `cli._write_output_or_exit`. Regression: `tests/test_cli_robustness.py::TestFailedWriteIsReported`.
 
 ## `gemini_engine.py`
 
@@ -83,93 +205,105 @@ module.
 
 The cost (mislabel ~8-33% of non-Gemini content as Gemini) outweighs the benefit -- the visible sparkle is a medium-confidence stripped-metadata fallback, and intact Gemini is caught by C2PA in `identify` regardless. Remaining square misses are an accepted known limitation; a real fix would need a sparkle-specific discriminator (template match on a background-subtracted image, or a hard fixed-margin position prior), which is open research, not a threshold tweak.
 
-**Removal is reverse-alpha with an over-subtraction guard** (`remove_watermark` → `_reverse_alpha_blend`, else `_inpaint_footprint`): the sparkle alpha is computed (`alpha = max(R,G,B)/255`) from the bundled sparkle-on-black captures `assets/gemini_bg_{96,48}.png` (the capture max is ~130, NOT 255 — the sparkle is a ~51%-opaque white overlay, so `alpha` maxes at ~0.51, which is CORRECT for the capture, not under-exposed). The alpha is near-exact only when the real mark's effective opacity matches the capture, which holds on bright/flat backgrounds — re-verified clean on `demo_banana_before.png` 2026-05-31.
+**Removal is localize -> fill** (`footprint_mask` → `watermark_registry.fill`): `footprint_mask` returns the sparkle footprint = the captured alpha (computed `alpha = max(R,G,B)/255` from the bundled sparkle-on-black captures `assets/gemini_bg_{96,48}.png`, capture max ~130 for the ~51%-opaque overlay) thresholded LOW so the faint halo is included, then dilated by a sparkle-relative margin. That binary mask is inpainted by the shared fill (cv2 / MI-GAN / big-LaMa). The captured alpha maps are used only to detect and to shape the mask, not for pixel recovery. This replaced the old reverse-alpha removal path; because the fill only reconstructs the masked footprint from its surroundings (rather than dividing by `1-a`), the whole reverse-alpha removal tail — the over-subtraction guard (`_reverse_alpha_oversubtracts`, the dark-background black-pit fix), the under-subtraction alpha-gain estimate (`_estimate_alpha_gain`), and the self-verify repair — is GONE, along with the near-white `1/(1-a)` ill-conditioning and the "color changed, not removed" failure mode those guards patched around. A slightly-off localization now just fills a small region near-losslessly instead of leaving a color-shifted smear.
 
-**Issue #30 (dark-background black pit):** on a dark/textured background (e.g. grass, ~73) the real sparkle's effective opacity is LOWER than the captured 0.51, so the fixed-alpha reverse blend OVER-subtracts (`watermarked - a*logo` goes negative) and drives the footprint to black — the white sparkle becomes a black diamond. `remove_watermark` now detects this via `_reverse_alpha_oversubtracts` (fraction of footprint pixels with `alpha >= _FOOTPRINT_ALPHA` 0.1 whose numerator < 0 exceeds `_OVERSUB_FOOTPRINT_FRAC` 0.05) and **inpaints the footprint** (`_inpaint_footprint`, cv2 NS over the dilated alpha mask) from the surrounding pixels instead.
+**False-positive gate (added 2026-06-03):** `detect_watermark`'s shape-only NCC (`spatial*0.5 + gradient*0.3 + var*0.2`) fires on ornate/flat content (text strips, banners, hatching) that coincidentally matches the diamond shape — a real Gemini sparkle is a bright WHITE overlay, so its core sits above the local background, but the NCC is contrast-invariant and cannot see that. The fusion now **demotes** (caps confidence to 0.30) any low-confidence (`< _SPARKLE_FP_CONF` 0.65) match that shows NEITHER real-sparkle signature: a bright core (`_core_ring_margin >= _SPARKLE_FP_MARGIN` 5) OR a crisp star silhouette (`gradient_score >= _SPARKLE_FP_GRAD` 0.55). I.e. demote when `low_margin OR low_grad`. Real sparkles escape via high confidence (white-bg sparkles score ≥0.79 despite a low margin — the NCC shape match is strong), high margin (dark/mid backgrounds, incl. the #36 faint-corner case, lift well clear), OR high gradient (a real sparkle is grad ~0.97–1.0). **The gradient condition (added 2026-06-26) closes the bright-background FP class** the margin check alone missed: a snow+sky photo and a white-background product render both scored ~0.51 at `identify`, because a bright background gives the match a HIGH core-ring margin (it genuinely IS brighter than its surroundings), so the brightness gate read it as a real overlay — but a smooth luminance blob that shape-NCC-matches the rough diamond has low gradient fidelity (the two FPs measured grad 0.105 and 0.463 vs ≥0.8 for real sparkles), so the gradient floor demotes them. The OR is **strictly a superset** of the old margin-only demotion (it only ADDS demotions on bright backgrounds, where a real sparkle keeps grad ~0.97), so it cannot regress a dark/mid sparkle (kept by margin) or a white-bg one (kept by confidence ≥ 0.65). The gate is **monotonic** (only ever removes detections, never adds), so it cannot regress the verified-negative corpus (already 0 FPs); the 2026-06-26 corpus re-sweep flipped only OpenAI/ChatGPT content (no Gemini sparkle exists there) and already-`cleaned/` outputs, all sub-0.5 (below the `identify` threshold), so no provenance verdict changed. The original gate demoted 16/495 flagged sparkles on the validation corpus (13 carried no AI metadata = content FPs; the 3 AI-meta were visually FPs / a near-invisible white-on-white sparkle whose AI verdict is held by metadata anyway). `_core_ring_margin` uses the `_core_and_bg` helper (core 75th-pct brightness vs background-ring median). This gate is detection-side and unchanged by the localize -> fill refactor; the provenance prior skips it when a Google/Gemini C2PA issuer confirms the vendor. Regression-guarded by `test_gemini_engine.py::TestSparkleFalsePositiveGate` (incl. `test_bright_background_low_gradient_match_demoted`).
 
-**Behavior-neutral on the working case:** a bright background over-subtracts at ~0% so reverse-alpha is used and the output is byte-identical to before (verified: demo_banana 0.0 frac vs issue-#30 grass 0.61 frac; regression-guarded by `test_gemini_engine.py::TestOverSubtractionGuard`, which composites the sparkle at a reduced effective alpha to reproduce the mismatch).
+**The reverse-alpha removal tail is retired.** The self-verify repair (`_verify_and_repair`), the offset+scale alignment search, and the near-white `1/(1-a)` ill-conditioning survivors were all artifacts of solving the sparkle by inverting the alpha map. Under localize -> fill the footprint is reconstructed from its surroundings by the shared fill, so those failure classes and their guards no longer exist. The lesson from that era still holds and generalizes: a re-detect-confidence audit metric is gameable by reshaping the residual, so judge a visible removal by physical inspection of the footprint, not the detector alone.
 
-**Under-subtraction (the symmetric case, fixed 2026-06-03):** some real Gemini sparkles are rendered MORE opaque than the captured ~0.51, so the fixed-alpha reverse blend UNDER-subtracts and leaves a bright sparkle residual the detector still fires on (measured on the spaces corpus: a visible-removal audit through the registry path left a detectable sparkle on a meaningful fraction of marks, all under-removals, NOT a background-brightness class — failures and successes had the same input confidence and the same background-luma distribution; the discriminator was the removal delta itself). `remove_watermark` now estimates a per-image alpha gain (`_estimate_alpha_gain`: effective sparkle opacity at the bright core vs the local background ring, `a_eff/a_cap`, clamped `[1.0, _ALPHA_GAIN_MAX` 1.94`]`) and scales the alpha to match before the over-sub/blend branch. The gain cleanly separates on the corpus (under-removed marks ~1.47, cleanly-removed ~1.00), and a deadband (`_ALPHA_GAIN_DEADBAND` 1.05) keeps a matching sparkle **byte-identical** to the pre-fix output, so the fix is purely additive (0 regressions on the audit set; the over-sub guard still runs on the scaled alpha as the safety net for an over-shooting estimate). Regression-guarded by `test_gemini_engine.py::TestUnderSubtractionGain` (composites a more-opaque-than-capture sparkle; **asserts on footprint pixels, NOT the detector** — the detector's NCC is degenerate on a flat synthetic background, so a re-detect conf is meaningless there; the real corpus removal drops the detector from ~0.80 to ~0.27).
-
-**False-positive gate (added 2026-06-03):** `detect_watermark`'s shape-only NCC (`spatial*0.5 + gradient*0.3 + var*0.2`) fires on ornate/flat content (text strips, banners, hatching) that coincidentally matches the diamond shape — a real Gemini sparkle is a bright WHITE overlay, so its core sits above the local background, but the NCC is contrast-invariant and cannot see that. The fusion now **demotes** (caps confidence to 0.30) any low-confidence (`< _SPARKLE_FP_CONF` 0.65) match that shows NEITHER real-sparkle signature: a bright core (`_core_ring_margin >= _SPARKLE_FP_MARGIN` 5) OR a crisp star silhouette (`gradient_score >= _SPARKLE_FP_GRAD` 0.55). I.e. demote when `low_margin OR low_grad`. Real sparkles escape via high confidence (white-bg sparkles score ≥0.79 despite a low margin — the NCC shape match is strong), high margin (dark/mid backgrounds, incl. the #36 faint-corner case, lift well clear), OR high gradient (a real sparkle is grad ~0.97–1.0). **The gradient condition (added 2026-06-26) closes the bright-background FP class** the margin check alone missed: a snow+sky photo and a white-background product render both scored ~0.51 at `identify`, because a bright background gives the match a HIGH core-ring margin (it genuinely IS brighter than its surroundings), so the brightness gate read it as a real overlay — but a smooth luminance blob that shape-NCC-matches the rough diamond has low gradient fidelity (the two FPs measured grad 0.105 and 0.463 vs ≥0.8 for real sparkles), so the gradient floor demotes them. The OR is **strictly a superset** of the old margin-only demotion (it only ADDS demotions on bright backgrounds, where a real sparkle keeps grad ~0.97), so it cannot regress a dark/mid sparkle (kept by margin) or a white-bg one (kept by confidence ≥ 0.65). The gate is **monotonic** (only ever removes detections, never adds), so it cannot regress the verified-negative corpus (already 0 FPs); the 2026-06-26 corpus re-sweep flipped only OpenAI/ChatGPT content (no Gemini sparkle exists there) and already-`cleaned/` outputs, all sub-0.5 (below the `identify` threshold), so no provenance verdict changed. On the spaces corpus the original gate demoted 16/495 flagged sparkles (13 carried no AI metadata = content FPs; the 3 AI-meta were visually FPs / a near-invisible white-on-white sparkle whose AI verdict is held by metadata anyway), and dropped the removal-audit failures 20→15 (post-removal flat footprints the NCC re-fired on). `_core_ring_margin` and `_estimate_alpha_gain` share the `_core_and_bg` helper (core 75th-pct brightness vs background-ring median). Regression-guarded by `test_gemini_engine.py::TestSparkleFalsePositiveGate` (incl. `test_bright_background_low_gradient_match_demoted`).
-
-**Self-verify repair (added 2026-06-04):** the gain estimate corrects most under-subtractions, but a tail of strong sparkles still survived reverse-alpha (position jitter, or a gain the `[1.0, 1.94]` clamp could not fully reach). After the reverse blend, `remove_watermark` re-detects via `_verify_and_repair`; when a sparkle at or above `_VERIFY_FALLBACK_CONF` 0.5 (the registry's real fail line) remains, it inpaints the footprint and **keeps that only when it lowers the re-detect confidence** — purely additive (the common clean removal re-detects below 0.5 and is returned untouched, so it can never regress). On the spaces corpus this rescued **4 of the 15 remaining gemini removal-audit failures** (15→11, doubao/jimeng still 0), verified through the registry/CLI path. Costs one extra `detect_watermark` per removal (two when the fallback fires). Regression-guarded by `test_gemini_engine.py::TestVerifyAndRepair` (stubs `detect_watermark` to drive the keep-best control flow, since the NCC is degenerate on flat synthetics).
-
-**An offset+scale alignment search was prototyped on the remaining 11 fails and REJECTED (2026-06-04):** an audit "ceiling" test suggested it could rescue 4 more (e.g. a5a9 0.577→0.417), but direct inspection showed those were NCC-gaming, not removal — the lower-scoring placement left the sparkle as bright or BRIGHTER (a5a9: first-pass slot 99.5th-pct ~76 at background level, the "aligned win" slot ~164), it just reshaped the residual so the contrast-invariant shape-NCC scored lower. A slot-brightness sanity gate rejected every one, so alignment contributed 0 genuine rescues and was removed (the footprint inpaint stays because it physically reconstructs the slot from its darker surroundings, so its rescues are real).
-
-**Lesson: the visible-audit pass/fail metric (re-detect conf < 0.5) is gameable by reshaping the residual — optimizing it directly finds NCC-gaming placements, not clean removals; gate any removal candidate on a physical brightness check, not the detector alone.**
-
-The 11 survivors are near-white ill-conditioning (reverse-alpha divides by `1-a`≈0.02) or detector false positives (before≈after≈0.51) that no reverse-alpha placement fixes. The registry's optional `inpaint_residual` (edge cleanup) is a no-op on a clean reverse-alpha removal (and on the same corpus it lowered the re-detect conf on 3 marks, raised it on 10, no-op on 466 — net-neutral on pass/fail, so the self-verify repair, not it, drives the removal tail); an earlier "Gemini smears" read was a misjudged soft-fur original, not an artifact.
-
-**The bg assets are now rebuilt from OUR OWN controlled captures** (`data/gemini_capture/captures/`, committed) by `scripts/visible_alpha_solve.py gemini`, which locates the 96px sparkle on the black capture and crops it to the two logo sizes; our capture matched the previously third-party-sourced `gemini_bg_96.png` to **NCC 0.9998**, validating the asset and making it reproducible. Gemini's multi-size fixed-slot model is genuinely different from the Doubao/Jimeng text-strip engines (so it stays a separate engine, not part of the shared-base refactor).
+**The bg assets are rebuilt from OUR OWN controlled captures** (`data/gemini_capture/captures/`, committed) by `scripts/visible_alpha_solve.py gemini`, which locates the 96px sparkle on the black capture and crops it to the two logo sizes; our capture matched the previously third-party-sourced `gemini_bg_96.png` to **NCC 0.9998**, validating the asset and making it reproducible. Gemini's multi-size fixed-slot model is genuinely different from the Doubao/Jimeng text-strip engines (so it stays a separate engine, not part of the shared-base refactor).
 
 ## `_text_mark_engine.py`
 
-`_text_mark_engine.py` — **shared base for the three reverse-alpha text-mark engines (Doubao/Jimeng/Samsung), extracted 2026-06-09** (they were ~90% byte-identical clones). `TextMarkEngine(config: TextMarkConfig)` owns the whole `locate → extract_mask → detect → _fixed/_aligned_alpha_map → _apply_reverse_alpha → remove_watermark_reverse_alpha` pipeline (+ the asset-keyed `load_alpha_template`/`glyph_silhouette`/`template_match_score` caches). Each engine module is now a thin subclass: it supplies only its `TextMarkConfig` (the tuned constants, the bundled asset, and the bounded structural deltas — `corner` br/bl, `margin_floor` 4/2, `morph_open_size` 5/3, `min_gw` 8/16) plus the test-facing module shims (`_alpha_template`/`_glyph_silhouette`/`_template_match_score` + the constants). Behavior is byte-exact vs the old per-engine code (the three engine test suites pass unchanged). Gemini stays a SEPARATE engine (its multi-size fixed-slot sparkle model is genuinely different). Add a new text mark = a new `TextMarkConfig` + a thin subclass + one registry `_text_mark(...)` row. The engine bullets below describe each mark's calibration history; the LOGIC lives here. **Small-image detection guard (`_MIN_DETECT_SHORT_SIDE` 200, added 2026-06-26):** `detect` returns not-detected when the image short side is below 200px. Below that the glyph template degrades to the `min_gw` floor (~8px) and `TM_CCOEFF_NORMED` on a few pixels is noise, so an unrelated small geometric shape can spuriously correlate with the CJK silhouette — a 48×48 app-icon chevron scored Doubao 0.41 / Jimeng 0.47 (both above their thresholds), a pure small-size artifact (the same icon upscaled collapses to ~0.06–0.10 NCC at ≥256px). A real AI-generation label is stamped on a full-resolution render (the captured samples are 1086–2048px wide, the smallest positive test image is 1086px), so the floor sits far below any genuine mark while killing the icon/thumbnail band (≤96px); `identify` falls back to "unknown" (the safe default) and removal, gated on detection, is suppressed too. Regression-guarded by `test_{doubao,jimeng,samsung}_engine.py::TestDetect::test_small_image_guarded_from_false_positive`.
+`_text_mark_engine.py` — **shared base for the three text-mark engines (Doubao/Jimeng/Samsung), extracted 2026-06-09** (they were ~90% byte-identical clones). `TextMarkEngine(config: TextMarkConfig)` owns the `locate → extract_mask → detect` detection pipeline plus the removal that localizes the glyph blob to a footprint mask and hands it to the shared `watermark_registry.fill` (+ the asset-keyed `load_alpha_template`/`glyph_silhouette`/`template_match_score` caches). Detection still matches the glyph silhouette (NCC against the captured template); the removal MASK is TEMPLATE-FREE — it is the bounding box of the top-hat glyph blob from `extract_mask`, filled solid + dilated, so a re-rendered or differently-placed mark is still masked. This dropped the fixed alpha-template placement; the captured alpha maps are now used only for the detection silhouette, not for removal. Each engine module is a thin subclass supplying only its `TextMarkConfig` (the tuned constants, the bundled asset, and the bounded structural deltas — `corner` br/bl, `margin_floor` 4/2, `morph_open_size` 5/3, `min_gw` 8/16, and since 2026-07-21 `ladder` — the scale rungs `_tophat_best` sweeps, per-mark because 千问's two size modes do not fit the shared 3-rung comb (default `(0.8, 1.0, 1.25)`, unchanged for every other mark; densifying the SHARED ladder was measured and rejected -- see the verification plan's B2). plus the test-facing module shims (`_alpha_template`/`_glyph_silhouette`/`_template_match_score` + the constants). Gemini stays a SEPARATE engine (its multi-size fixed-slot sparkle model is genuinely different). Add a new text mark = a new `TextMarkConfig` + a thin subclass + one registry `_text_mark(...)` row. The engine bullets below describe each mark's calibration history; the LOGIC lives here. **Small-image detection guard (`_MIN_DETECT_SHORT_SIDE` 200, added 2026-06-26):** `detect` returns not-detected when the image short side is below 200px. Below that the glyph template degrades to the `min_gw` floor (~8px) and `TM_CCOEFF_NORMED` on a few pixels is noise, so an unrelated small geometric shape can spuriously correlate with the CJK silhouette — a 48×48 app-icon chevron scored Doubao 0.41 / Jimeng 0.47 (both above their thresholds), a pure small-size artifact (the same icon upscaled collapses to ~0.06–0.10 NCC at ≥256px). A real AI-generation label is stamped on a full-resolution render (the captured samples are 1086–2048px wide, the smallest positive test image is 1086px), so the floor sits far below any genuine mark while killing the icon/thumbnail band (≤96px); `identify` falls back to "unknown" (the safe default) and removal, gated on detection, is suppressed too. Regression-guarded by `test_{doubao,jimeng,samsung}_engine.py::TestDetect::test_small_image_guarded_from_false_positive`.
 
-**`_apply_reverse_alpha` runs on the glyph crop only:** the blend is a no-op outside the glyph `region` (x, y, w, h) (`(wm - 0)/(1 - 0) == wm`, and a uint8→float32→uint8 round-trip is exact). It copies the frame through and computes the reverse-alpha math on the `region` crop only — byte-identical to the old full-frame pass (verified: Doubao 130 + Jimeng 22 placements, 0 mismatches) but O(glyph) not O(image). The full-frame pass cost ~275 ms on a 12 MP frame for a glyph that is <0.1% of it, once per candidate placement (fixed + aligned ≈ 2×/removal); the crop drops that to ~2 ms. Mirror of the Gemini `_core_and_bg` crop.
+**Removal is localize -> fill.** The engine localizes the glyph blob (`extract_mask` over the located box) into a solid, dilated footprint mask and hands it to the shared `watermark_registry.fill` (cv2 / MI-GAN / big-LaMa). The template-free mask (bounding box of the glyph blob, not the fixed alpha template) means a re-rendered or moved mark is still covered, and the fill reconstructs the box from its surroundings. On corpus images doubao and jimeng localize + remove at ~100% with clean footprints (the filled region blends into its surroundings within a few LAB levels, no color shift, no dark pit); clean images with no vendor signature had 0% false removal.
 
-**Over-subtraction guard (`_reverse_alpha_oversubtracts` → `_inpaint_footprint`, ported from `gemini_engine` 2026-06-20, roadmap P0#8):** on a dark or mid-tone background the captured alpha can over-estimate THIS image's mark opacity, and reverse-alpha leaves a darker-than-background glyph ghost (a "dark pit") instead of recovering the true pixels — the sparkle-only fix (commit 41f6797) left the text marks unhandled. After `remove_watermark_reverse_alpha` selects the winning placement, the guard PREDICTS the reverse-alpha output PER PIXEL over the glyph body from the INPUT (`(obs - a*logo)/(1-a)`, exactly the remover's math) and, when the predicted body lands more than `_OVERSUB_DARK_MARGIN` (25) gray levels below the local background ring, abandons the reverse-alpha output for the footprint and inpaints it from the ORIGINAL surroundings (`_inpaint_footprint`, a wider dilate/radius than the thin residual pass). Predicting per-pixel from the INPUT (not the produced output, which depends on which placement the remover picked) is what keeps a cleanly captured full-strength mark byte-identical — it predicts back to the background everywhere, so the guard never trips on it (verified across Doubao/Jimeng/Samsung on white/mid/dark/midgray backgrounds). A faint mark predicts a body far below the ring and diverts to the inpaint. Regression-guarded by `tests/test_text_mark_oversubtraction.py` (predicate True on faint / False on clean, end-to-end no-dark-pit acceptance, clean-mark byte-identity, textured-background recovery). A flat synthetic background cannot exhibit the residual-inpaint failure (inpaint-from-flat is perfect regardless), so the value shows on textured/real content where the footprint inpaint samples un-darkened original pixels instead of the darkened reverse-alpha halo.
-
-**`_fixed/_aligned_alpha_map` and `extract_mask` return footprint-sized arrays, not full frames (memory):** the alpha-map helpers return the glyph-sized alpha **block** (`(gh, gw)` float32) plus its placement `(ax, ay, gw, gh)`, and `extract_mask` returns the box-sized glyph mask (`(loc.h, loc.w)` uint8) — both used to allocate a full `(h, w)` array that is read only inside the small glyph/box. A full-frame float32 alpha map is ~48 MB on a 12 MP frame and two were held at once during removal (fixed + aligned ≈ 96 MB of mostly-zeros); the box mask was a ~12 MB uint8 allocation rebuilt per text-mark `detect` on the memory-tight `identify` path. `_apply_reverse_alpha` consumes the block directly; the residual inpaint embeds it into one full-frame uint8 mask only at `cv2.inpaint` time (which needs a full-frame mask). Byte-identical to the old full-frame path — the block equals the old map's `[ay:ay+gh, ax:ax+gw]` slice and the box equals the old mask cropped to `loc.bbox` (regression-guarded by `tests/test_text_mark_memory.py`, which reconstructs the old full-frame path inline and asserts equality, so the proof survives a cv2/asset bump). `remove_watermark_reverse_alpha` tracks the winning `region` alongside `best_amap` to place that mask.
+**The reverse-alpha removal machinery is retired.** The old per-glyph reverse-alpha blend (`_apply_reverse_alpha`), the fixed/aligned alpha-map helpers, the over-subtraction guard (`_reverse_alpha_oversubtracts` → `_inpaint_footprint`, the dark-pit fix on dark/mid-tone backgrounds), and the always-align placement search are all gone — the fill reconstructs the footprint from its surroundings rather than inverting the captured alpha, so the dark-pit and color-shift failure modes those guards patched around no longer arise. `extract_mask` still returns a box-sized (`(loc.h, loc.w)`) mask rather than a full frame, which keeps the memory-tight `identify` detect path cheap.
 
 ## `doubao_engine.py`
 
-`doubao_engine.py` — **a thin `_text_mark_engine.TextMarkEngine` subclass (config only) since 2026-06-09.** visible Doubao "豆包AI生成" remover/detector (cv2/numpy, no GPU). `DoubaoEngine.locate` anchors a bottom-right box by **geometry** (mark scales with image WIDTH), `extract_mask` pulls the light, low-chroma glyphs (the detection candidate) using a per-pixel channel-spread proxy `sat = roi.max(axis=2) - roi.min(axis=2)` (no HSV conversion). `detect` is **shape-consistent**: it matches the bundled alpha glyph silhouette (`assets/doubao_alpha.png`) against the candidate via zero-mean normalized correlation (`_template_match_score`, cv2 `TM_CCOEFF_NORMED`), gated at `DETECT_NCC_THRESHOLD` 0.4 over a small `DETECT_MIN_COVERAGE` floor. Keying on glyph SHAPE (not coverage heuristics) fixed #23 (corpus FP 7/1243).
+`doubao_engine.py` — **a thin `_text_mark_engine.TextMarkEngine` subclass (config only) since 2026-06-09.** visible Doubao "豆包AI生成" detector + localizer (cv2/numpy, no GPU). `DoubaoEngine.locate` anchors a bottom-right box by **geometry** (mark scales with image WIDTH), `extract_mask` pulls the light, low-chroma glyphs (the detection candidate) using a per-pixel channel-spread proxy `sat = roi.max(axis=2) - roi.min(axis=2)` (no HSV conversion). `detect` is **shape-consistent**: it matches the bundled glyph silhouette (`assets/doubao_alpha.png`) against the candidate via zero-mean normalized correlation (`_template_match_score`, cv2 `TM_CCOEFF_NORMED`), gated at `DETECT_NCC_THRESHOLD` 0.4 over a small `DETECT_MIN_COVERAGE` floor. Keying on glyph SHAPE (not coverage heuristics) fixed #23 (corpus FP 7/1243).
 
-**Removal = reverse-alpha + thin residual inpaint** (`remove_watermark_reverse_alpha`): `original = (wm - a*logo)/(1-a)` from the bundled alpha map + `_ALPHA_LOGO_BGR` (pure white) + `_ALPHA_*_FRAC` geometry, then a deliberately THIN inpaint (`_RESIDUAL_*`, `INPAINT_NS`) over the glyph footprint clears leftover edges without smearing.
+**Removal is localize -> fill:** the glyph blob is localized to a solid, dilated footprint mask (`extract_mask` over the located box) and the shared `watermark_registry.fill` inpaints it. On corpus images this removes at ~100% with clean footprints (the filled region blends into its surroundings within a few LAB levels, no color shift, no dark pit).
 
-**Alpha is rebuilt by `scripts/visible_alpha_solve.py` (the careful gray-self solve: cubic background fit, mean over channels, full halo, unblurred), same recipe as Jimeng** — the captures are committed in `data/doubao_capture/captures/`.
+**The detection template (`assets/doubao_alpha.png`) is rebuilt by `scripts/visible_alpha_solve.py`** (the careful gray-self solve: cubic background fit, mean over channels, full halo, unblurred), same recipe as Jimeng — the captures are committed in `data/doubao_capture/captures/`. It is used only as the detection silhouette, not for pixel recovery.
 
-**Removal aligns ALWAYS** (no `_ALPHA_NATIVE_BAND` fast-path): it tries fixed geometry AND `_aligned_alpha_map`'s `TM_CCOEFF_NORMED` scale+position search and keeps the lower-residual one — the mark is re-rasterized and a few px off per image, so fixed geometry alone leaves a visible outline even at 2048.
-
-**The locate box (`WM_*`) is generous (0.22 wide, margins 0.004) and reaches close to the corner** — a tight box (the old 0.185 / margin 0.012) let a corner-ward shift fall OUTSIDE the alignment search, so the align missed and a readable outline survived; regression-guarded by `test_recovers_shifted_mark_on_texture` (composes the alpha shifted on a known texture; old box ~29 vs new ~1 mean residual).
-
-**Issue #13 follow-up defect (found 2026-05-31): the SHIPPED Doubao removal left a clearly READABLE "豆包AI生成" outline on the real `doubao-1.png` sample, while `detect` returned conf 0.0 (it is fooled by a thin outline) so `test_reverse_alpha_removes_mark` passed and the old "56/56 clean" claim was detector-measured, not visual.**
-
-Root cause: bad alpha (under-estimated, max ~0.65) + fixed-no-inpaint + tight box; the careful rebuild + always-align + thin inpaint + wide box takes it from a readable outline to faint texture-level traces (parity with Jimeng — a single capture cannot pixel-cancel a per-image re-rasterized mark).
-
-**Lesson: a detector-only removal test is insufficient; assert visual residual (the textured-shift test).** **`extract_mask` guards a degenerate ROI (`bh < 16 or bw < 16` -> empty mask, skips cv2):** the always-align removal scores each placement with a residual `detect(out)`, and on an extremely wide/short image (e.g. 2048x1, `test_wide_short_does_not_raise`) that fed cv2's GaussianBlur a ~1-px-tall ROI and **faulted natively on Windows py3.12 (access violation, non-deterministic — one CI cell went red while a re-run passed)**; the old at-native path never ran `detect` on degenerate sizes. Real images always clear the guard (the `WM_*` box floors are `max(16, …)` height / `max(40, …)` width), so it only short-circuits slivers. `reverse_alpha_available` is just "asset present"; the registry gates removal on `detect`. The shipped third-party `_refs/zhengsuanfa_doubao_alpha_120x20.png` is NOT a usable alpha (verified 2026-05-29). Arbitrary-region inpainting is `region_eraser`/`erase`.
+**The locate box (`WM_*`) is generous (0.22 wide, margins 0.004) and reaches close to the corner** so a re-rasterized, corner-ward-shifted mark still falls inside the localized box; regression-guarded by `test_recovers_shifted_mark_on_texture` (composes the mark shifted on a known texture). **`extract_mask` guards a degenerate ROI (`bh < 16 or bw < 16` -> empty mask, skips cv2)** — an extremely wide/short image (e.g. 2048x1, `test_wide_short_does_not_raise`) once fed cv2's GaussianBlur a ~1-px-tall ROI and **faulted natively on Windows py3.12**; real images always clear the guard (the `WM_*` box floors are `max(16, …)` height / `max(40, …)` width), so it only short-circuits slivers. The registry gates removal on `detect`. The shipped third-party `_refs/zhengsuanfa_doubao_alpha_120x20.png` is NOT a usable template (verified 2026-05-29). Arbitrary-region inpainting is `region_eraser`/`erase`. **Lesson from the reverse-alpha era (still holds): a detector-only removal test is insufficient; assert visual residual (the textured-shift test).**
 
 ## `jimeng_engine.py`
 
-`jimeng_engine.py` — **a thin `TextMarkEngine` subclass (config only) since 2026-06-09.** visible Jimeng / Dreamina "★ 即梦AI" remover/detector (cv2/numpy, no GPU), built 2026-05-30 from issue #13's solid captures (@powersee). Shares the base with `doubao_engine`: `locate` anchors a bottom-right box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma), `detect` matches the bundled "即梦AI" glyph silhouette (`assets/jimeng_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.45** cleanly separates real Jimeng marks (>=0.81) from the Doubao strip (0.21) and other AI output (0.0), so the two ByteDance marks don't cross-fire in `--mark auto`.
+`jimeng_engine.py` — **a thin `TextMarkEngine` subclass (config only) since 2026-06-09.** visible Jimeng / Dreamina "★ 即梦AI" detector + localizer (cv2/numpy, no GPU), built 2026-05-30 from issue #13's solid captures (@powersee). Shares the base with `doubao_engine`: `locate` anchors a bottom-right box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma), `detect` matches the bundled "即梦AI" glyph silhouette (`assets/jimeng_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.45** cleanly separates real Jimeng marks (>=0.81) from the Doubao strip (0.21) and other AI output (0.0), so the two ByteDance marks don't cross-fire in `--mark auto`.
 
-**Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; the white capture + an L-pair-solve confirm ~254.6); compositing is **sRGB, not linear** (a linear-light solve tripled the cross-residual).
+**The detection template (`assets/jimeng_alpha.png`) is rebuilt by `scripts/visible_alpha_solve.py` from the GRAY capture** (`data/jimeng_capture/captures/`, the solid captures committed): `a = (I - B)/(255 - B)`, B a per-capture **cubic** background fit over the non-glyph pixels, **averaged over channels, full halo extent (down to a~0.02), unblurred**. Gray (bg ~132) is the deliberate choice over black: it is the best proxy for real content (the mark sits on bright photo areas, not on black). The captured template is used only as the detection silhouette, not for pixel recovery. Solver geometry at `_ALPHA_NATIVE_WIDTH` 2048: `_ALPHA_WIDTH_FRAC` 0.202, `_ALPHA_HEIGHT_FRAC` 0.058, margins ~0.029.
 
-**Alpha rebuilt by `scripts/visible_alpha_solve.py` from the GRAY capture** (`data/jimeng_capture/captures/`, the solid captures now committed): `a = (I - B)/(255 - B)`, B a per-capture **cubic** background fit over the non-glyph pixels, **averaged over channels, full halo extent (down to a~0.02), unblurred**. Gray (bg ~132) is the deliberate choice over black: it is the best proxy for real content (the mark sits on bright photo areas, not on black), and the careful build drops the gray self-residual to ~1.3.
+**Removal is localize -> fill:** the glyph blob is localized to a solid, dilated footprint mask and the shared `watermark_registry.fill` inpaints it; the `WM_*` locate box is generous so a re-rasterized, corner-ward-shifted mark stays inside the localized box (the same widen that fixed Doubao). On corpus images this removes at ~100% with clean footprints (blends within a few LAB levels, no color shift). The registry gates removal on `detect`.
 
-**The mask quality, not the method, was the earlier limit** — a max-channel / quadratic-bg / blurred / halo-truncated build (and a black-dominated LS) left a visible outline (lesson from issue #13: when reverse-alpha leaves a ghost, suspect the captured alpha map before adding heuristics or switching method). Geometry emitted by the solver at `_ALPHA_NATIVE_WIDTH` 2048: `_ALPHA_WIDTH_FRAC` 0.202, `_ALPHA_HEIGHT_FRAC` 0.058, margins ~0.029.
-
-**Removal = reverse-alpha + a deliberately THIN residual inpaint** (`remove_watermark_reverse_alpha`, `_RESIDUAL_DILATE` 5 over the `_RESIDUAL_ALPHA_FLOOR` 0.05 footprint, `_RESIDUAL_INPAINT_RADIUS` 2, `INPAINT_NS`): a single 2048 alpha cannot pixel-cancel the mark re-rasterized at another resolution (alpha maps from independent captures correlate 0.998, not 1.0; off-native reverse-alpha alone only halves the mark), so a tight inpaint clears the residual edges WITHOUT the texture/edge smear a wide full-footprint pass caused.
-
-**Placement ALWAYS tries fixed geometry AND `_aligned_alpha_map`'s NCC scale+position search, keeping the lower-residual** — the mark re-rasterizes + jitters a few px per image even at the captured width, so fixed geometry alone misses (there is no `_ALPHA_NATIVE_BAND` fast-path; the scale search `_ALPHA_ALIGN_SEARCH` is fine-stepped, and the `WM_*` locate box is generous so a corner-ward shift stays inside the search — the same widen that fixed Doubao). Verified clean on the solid captures (native 2048; faint self-residual ~1.3 visible only on a dead-flat field, hidden by real texture) and a real 1440-wide Jimeng download (off-native, table edge preserved). `reverse_alpha_available` is just "asset present"; the registry gates on `detect`.
-
-**No committed real sample** (the real content download stays gitignored; only the solid calibration captures are committed) — `tests/test_jimeng_engine.py` synthesizes a mark from the bundled alpha asset, and `test_recovers_shifted_mark_on_texture` guards the align-on-shift path that the Doubao defect exposed. Jimeng images are independently caught by the China TC260 AIGC label in `metadata`/`identify`, so this engine is the visible-mark *removal* path, not a new `identify` signal.
+**No committed real sample** (only the solid calibration captures are committed) — `tests/test_jimeng_engine.py` synthesizes a mark from the bundled template, and `test_recovers_shifted_mark_on_texture` guards the localize-on-shift path that the Doubao defect exposed. Jimeng images are independently caught by the China TC260 AIGC label in `metadata`/`identify`, so this engine is the visible-mark *removal* path, not a new `identify` signal.
 
 ## `samsung_engine.py`
 
-`samsung_engine.py` — **a thin `TextMarkEngine` subclass (config only) since 2026-06-09.** visible Samsung Galaxy AI "✦ Contenuti generati dall'AI" remover/detector (cv2/numpy, no GPU), built 2026-06-05 from issue #37's flat captures (@f-liva). Shares the base but anchored **bottom-LEFT** (Doubao/Jimeng are bottom-right): `locate` anchors a bottom-left box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma — `LOGO_MIN_LUMA` is lowered to **110** because the mark is faint, peak alpha ~0.38, so on a mid/dark background its glyph luma is lower than Jimeng's), `detect` matches the bundled glyph silhouette (`assets/samsung_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.40** (real marks ~0.79 on a real photo, ~0.57/0.71 on the black/gray captures; 0.0 on Doubao/Jimeng captures, and Doubao/Jimeng score 0.0 on a real Samsung photo — no cross-fire, also because the corner differs).
+`samsung_engine.py` — **a thin `TextMarkEngine` subclass (config only) since 2026-06-09.** visible Samsung Galaxy AI "✦ Contenuti generati dall'AI" detector + localizer (cv2/numpy, no GPU), built 2026-06-05 from issue #37's flat captures (@f-liva). Shares the base but anchored **bottom-LEFT** (Doubao/Jimeng are bottom-right): `locate` anchors a bottom-left box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma — `LOGO_MIN_LUMA` is lowered to **110** because the mark is faint, peak alpha ~0.38, so on a mid/dark background its glyph luma is lower than Jimeng's), `detect` matches the bundled glyph silhouette (`assets/samsung_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.40** (real marks ~0.79 on a real photo, ~0.57/0.71 on the black/gray captures; 0.0 on Doubao/Jimeng captures, and Doubao/Jimeng score 0.0 on a real Samsung photo — no cross-fire, also because the corner differs).
 
-**Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; white capture confirms).
+**The detection template (`assets/samsung_alpha.png`) is solved by `scripts/visible_alpha_solve.py samsung` from the GRAY capture** (`data/samsung_capture/captures/`, the flat black/gray/white captures committed; the solver gained a `corner="bl"` mode + left-margin logging for this), same careful recipe as Jimeng (cubic background, mean-channel, full halo, unblurred). Geometry emitted at `_ALPHA_NATIVE_WIDTH` **1086** (the flat-edit capture width): `_ALPHA_WIDTH_FRAC` 0.3195, `_ALPHA_HEIGHT_FRAC` 0.0378, `_ALPHA_MARGIN_LEFT_FRAC` 0.0110, `_ALPHA_MARGIN_BOTTOM_FRAC` 0.0064. Used only as the detection silhouette, not for pixel recovery.
 
-**Alpha solved by `scripts/visible_alpha_solve.py samsung` from the GRAY capture** (`data/samsung_capture/captures/`, the flat black/gray/white captures committed; the solver gained a `corner="bl"` mode + left-margin logging for this), same careful recipe as Jimeng (cubic background, mean-channel, full halo, unblurred). Geometry emitted at `_ALPHA_NATIVE_WIDTH` **1086** (the flat-edit capture width): `_ALPHA_WIDTH_FRAC` 0.3195, `_ALPHA_HEIGHT_FRAC` 0.0378, `_ALPHA_MARGIN_LEFT_FRAC` 0.0110, `_ALPHA_MARGIN_BOTTOM_FRAC` 0.0064.
+**Removal is localize -> fill:** the glyph blob is localized to a solid, dilated footprint mask and the shared `watermark_registry.fill` inpaints it. Verified on a real 2958-wide @f-liva photo: re-detect 0.79→0.00, no readable text or outline on the recovered wooden table — checked **visually**, not just by the detector. The registry gates removal on `detect`.
 
-**Removal = reverse-alpha + a deliberately THIN residual inpaint** (`remove_watermark_reverse_alpha`, same `_RESIDUAL_*` recipe as Jimeng) with **always-try fixed AND `_aligned_alpha_map` NCC scale+position search, keep the lower-residual** (`_ALPHA_ALIGN_SEARCH` widened to (0.85, 1.18, 23) because the flat captures are far off the real-photo width).
+**Detection is locale-specific** (the string differs per language); this build detects only the Italian "Contenuti generati dall'AI" variant, so non-Italian Samsung locales are not detected — and, because detection gates removal, not removed — even though the fill mask itself is locale-independent. Other locales need their own detection silhouette — the locale string font-rendered and calibrated on real positives (the pill's `scripts/render_pill_silhouette.py` pattern), NOT an app capture (the solid/gray/white capture workflow retired with reverse-alpha). This is a pre-existing limit, unchanged by the localize -> fill refactor.
 
-**Resolution caveat:** the flat captures arrived at 1086 wide while real photos are ~2958 wide (the mark scales with width, so the captured glyph ~334px is ~2.7x smaller than the ~903px real-photo glyph); width-scale + NCC-align still removes it cleanly (verified on a real 2958-wide @f-liva photo: re-detect 0.79→0.00, no readable text or outline on the recovered wooden table — checked **visually**, not just by the detector, per the Gemini self-verify lesson), but a flat capture at the real photo resolution would make the alpha pixel-sharp instead of upscaled (open quality upgrade, noted in `data/samsung_capture/README.md`).
+**No committed real sample** (only the flat calibration captures are committed) — `tests/test_samsung_engine.py` synthesizes a mark from the bundled template (bottom-left geometry), with `test_recovers_shifted_mark_on_texture` guarding the localize-on-shift path. Samsung Galaxy AI edits are independently caught by C2PA + the `genAIType` marker in `metadata`/`identify`, so this engine is the visible-mark *removal* path; it also feeds `identify` as the medium-confidence `visible_samsung` signal via the registry (the stripped-metadata fallback).
 
-**The mark is locale-specific** (text differs per language); this build is the Italian "Contenuti generati dall'AI" variant — other locales need their own captured template. `reverse_alpha_available` is just "asset present"; the registry gates on `detect`.
+## `qwen_engine.py`
 
-**No committed real sample** (the real photo stays gitignored; only the flat calibration captures are committed) — `tests/test_samsung_engine.py` synthesizes a mark from the bundled alpha asset (bottom-left geometry), with `test_recovers_shifted_mark_on_texture` guarding the align-on-shift path. Samsung Galaxy AI edits are independently caught by C2PA + the `genAIType` marker in `metadata`/`identify`, so this engine is the visible-mark *removal* path; it also feeds `identify` as the medium-confidence `visible_samsung` signal via the registry (the stripped-metadata fallback).
+`qwen_engine.py` — **a thin `TextMarkEngine` subclass (config only), registered 2026-07-21.** visible Qwen (Alibaba Tongyi Qianwen) "千问AI生成" detector + localizer (cv2/numpy, no GPU), bottom-right, the same GB 45438-2025 6-glyph house style as Doubao (2-glyph vendor prefix + mandated `AI生成` tail; the vendor's tri-lobe logo precedes the text and is deliberately NOT in the silhouette -- logos vary between releases, the CJK run is what discriminates). The detection silhouette `assets/qwen_alpha.png` is font-rendered synthetic (`scripts/render_vendor_silhouettes.py`), never cut from an upload. Feeds `identify` as the medium-confidence `visible_qwen` signal via the registry.
+
+**Why this registration took two attempts:** the 2026-07-18 attempt died at n=1 positives; the unlock was the TC260 label's `ContentProducer` field, whose USCC names the signing entity and partitions carriers into per-vendor cohorts from metadata alone (`scripts/vendor_cohort_harvest.py` -- 117 labelled Qwen frames, owing nothing to any pixel detector). Every constant was then MEASURED on that cohort against 286 hand-labelled clean frames (`scripts/vendor_mark_calibrate.py`), not inherited from Doubao:
+
+* **Basis `short`** (frac_short CV 0.189 vs width 0.273).
+* **Per-mark 2-rung `ladder=(0.78, 1.27)`** against `alpha_width_frac` 0.160: the mark sits in TWO size modes (~0.124 and ~0.203 of the short side, ratio 1.64, both clusters tight) -- wider than the shared 3-rung ladder's 1.5625 span, so the best single fraction covers only 74.5% and the small mode lands in the comb's collapse zone (real marks at the exact rung score ~0.94 vs ~0.67 on the shared ladder). A 4-rung variant scored strictly worse (its big-mode rung sits 4.6% off the mode). The shared default is untouched for every other mark.
+* **Fitted locate box** (`width_frac` 0.231, `height_frac` 0.074, margins ~0.021): the real mark sits ~0.025 of the short side off the right edge, and Doubao's box (0.004 margin) clipped the first glyph -- an exact-size template collapsed 0.73 -> 0.26 on a real frame.
+* **`alpha_height_frac` 0.0416 from the aspect fit** (p50 aspect 0.260 at the winning width) -- not the silhouette's own aspect (0.2219) and not Doubao's ratio.
+* **Gate 0.45**: clean p99 0.301 / max 0.316 (286 frames), and every cohort frame >= 0.45 carries a visible mark (83 of ~96 eyeballed visible marks fire = 86% recall of visible marks; the misses are white-on-near-white contrast losses). 0.45 was picked over 0.32 for margin against unseen clean content at zero measured recall cost.
+* **STRICT ONLY (`provenance_ncc_factor` 1.0):** the score band just below the gate is dominated by non-Qwen banners on same-cohort frames (a 夸克 anti-forgery strip at 0.274, a 造点 mark at 0.253), so a provenance-relaxed arm would be mostly false fills. There is no provenance mapping for qwen and no relaxed arm.
+* **No rival margin:** 0 cross-fires on 400 Doubao-marked / 298 Jimeng-marked / 286 clean frames at the gate, while a 0.10 margin would have cost ~10% of genuine Qwen detections. A confident Qwen detection suppresses the Jimeng pill exactly like Doubao's does (`_keep_pill` -- a Qwen frame is TC260 too but is not Jimeng-basic).
+
+**Parity:** detect -> cv2 fill -> re-detect is clean on **83/83** real cohort marks, no empty masks (the `tophat` faint-mask fallback rides the same `_tophat_best`); the e2e suite drives one live cohort positive through the real CLI (`scripts/real_examples_e2e.py`, qwen bucket = symlinks under the gitignored `_visible_datasets/`). Regression: `tests/test_qwen_engine.py` (pins the ladder, the strict-only factor, the box anchor, and both size modes at a score floor that discriminates the shared-ladder and Doubao-margin mutations).
+
+**The clean-arm contamination trap (load-bearing for any future calibration):** the 2026-07-18 `present: []` labels are in the vocabulary of the REGISTERED marks only, so 146 of the 432 "clean" frames sit in a TC260 cohort -- including Qwen-cohort frames visibly carrying 千问AI生成. They made up the clean arm's entire top tail (clean p99 0.37 -> 0.69). `vendor_mark_calibrate.load_sets` now excludes every frame in ANY TC260 cohort from the clean arm; a gate read off the unguarded arm is meaningless.
+
+## `runninghub_engine.py`
+
+`runninghub_engine.py` — **thin `TextMarkEngine` subclass, registered 2026-07-22.** RunningHub (hosted ComfyUI platform, USCC 91340100MAEB4N8H76, 73-frame cohort) "RunningHub AI生成" detector + localizer, **top-left** (the first `corner="tl"` mark), faint mid-gray latin+CJK text. Feeds `identify` as `visible_runninghub`.
+
+* **`gray` front-end (the third one, added for this mark):** the mark's faint gray is suppressed by the white top-hat to clean-arm levels (positives 0.16-0.23 vs clean p99 0.31), while raw-grayscale silhouette NCC separates (positives 0.38-0.54 vs clean p99 0.264 / max 0.304 on 283 guarded clean frames). It is contrast-DEPENDENT, unlike tophat -- one method `_gray_best` serves both detection and the mask, same one-method parity contract as `_tophat_best`.
+* **Tight ladder (0.95, 1.0, 1.05) exactly on the measured 0.32-of-width:** the NCC comb is razor-sharp in size (0.537 on-size, 0.223 at +5.6% off -- Qwen's comb behaviour, measured again here), so the shared 3 rungs (nearest rung 5.6% off) collapsed the match to 0.22 and the first calibration showed no separation at all.
+* **Anchor gate in `detect`:** the full-corpus sweep (`data/spaces/_sweep_new_marks.py`, 42009 files) fired on 37 outside-cohort frames at 0.34-0.38 (hair tops, shelves, window frames, CJK banners) -- no NCC threshold separates them from the 0.381 positives. Every positive sits at the measured corner (x 0.008-0.014, y 0.005-0.007 of the frame) and every false fire off it (x 0.013-0.150, y 0.009-0.045), so detection additionally requires the match box inside x<=0.025 / y<=0.015 of the frame. 0/37 false, 4/4 positives kept.
+* **Footprint is always the detector's match box** (never the binary blob): the blob under-segments the faint head glyphs and left "Runni" unremoved (caught visually on the first removal). Gate 0.34, STRICT ONLY. Regression: `tests/test_runninghub_engine.py`.
+
+## `baidu_engine.py`
+
+`baidu_engine.py` — **thin `TextMarkEngine` subclass with a custom `footprint_mask`, registered 2026-07-22.** Baidu (USCC 91110000802100433B, 16-frame cohort) "百度 AI生成" detector + localizer, bottom-right: a white bold 百度 text run + a separate white rounded tag with dark "AI生成". Feeds `identify` as `visible_baidu`.
+
+* **Detection keys on the 百度 text run ONLY.** A two-component (text+pill) template was measured and rejected: the solid white pill is a bright-blob magnet and both front-ends scored the clean arm at cohort levels (tophat clean p95 0.445 / gray clean p95 0.487 vs cohort ~0.5). The text-only silhouette separates (cohort 0.39-0.65 vs clean max 0.352). The white tag is still removed: the footprint extends to the corner (below).
+* **Two load-bearing rival margins** (`rivals=("doubao_alpha.png","qwen_alpha.png")`): 百度 vs 豆包 share their second glyph, and 百度 vs 千问 are near-identical after binarization -- at the 0.37 gate the template fired on 45.8% of 400 Doubao-marked frames and, on the 741-frame blind-labelled eval set, on 12 Qwen-marked frames at 0.38-0.43. Doubao's template beats it by ~0.56 on Doubao marks, Qwen's by 0.17-0.35 on Qwen marks; the 0.10 margin suppresses all crossfire at zero genuine-Baidu cost (cohort fire+m == fire).
+* **Gate history, each step measured:** 0.37 from the clean arm (max 0.352) -> 0.43 after the eval-set crossfires (the one 抖音 AI创作 fire at 0.425 named no registered rival) -> **0.48** after the full-corpus sweep put outside-cohort TRUE carriers at 0.50-0.66 vs the false arm max 0.47 (大众点评 UI, a math blackboard, an 80s banner). Cohort keeps 7/16 (all true); the sweep also found 6 metadata-STRIPPED true Baidu carriers the TC260 cohort cannot see -- the direct evidence that registration pays beyond the cohort.
+* **Custom `footprint_mask`:** the tag's flat white interior gives no top-hat response (a top-hat answers edges, not flats), so the base blob bbox ended at the text run and the fill left the tag as a ghost. The mask is the detector's match box extended RIGHT to the corner. STRICT ONLY. Regression: `tests/test_baidu_engine.py`.
+
+## `liblib_engine.py`
+
+`liblib_engine.py` — **thin `TextMarkEngine` subclass with a custom `footprint_mask`, registered 2026-07-22.** LibLibAI (哩布哩布AI, USCC 91110105MACJ6K1C8A, 15-frame cohort) triangle logo + "LibLibAI" wordmark detector + localizer, **bottom-CENTER** (the first `corner="bc"` mark; the locate box is horizontally centered). Feeds `identify` as `visible_liblib`.
+
+* **The discriminative lever is the silhouette FONT.** With the CJK house font (STHeiti) the cohort scored 0.31-0.47 against a full-corpus false arm (latin UI text bands, website screenshots) at 0.50 -- no separation at any gate. Measured across 7 candidate fonts, **Arial** lifts the cohort to 0.42-0.73 and DROPS the false arm to max 0.398: generic latin text matches the wrong font less, which is where the discrimination comes from. Gate 0.42 keeps all 8 marked cohort frames (0.43-0.59).
+* **Per-mark size floor (`_MIN_SHORT_SIDE=480`):** the one false fire with the final template was a 200x200 icon (0.444, on a 20px template). The shared `_MIN_DETECT_SHORT_SIDE` (200) is a crash guard, not a discrimination floor; the template needs ~48px to discriminate.
+* **Custom `footprint_mask`:** the base blob bbox was wrong in both directions -- it bled UP into background structure (ate a shirt's real print on the 768x1024 cohort frame) and never owned the triangle logo. The mask is the detector's match box extended LEFT by ~1.3 glyph heights (the logo is ~1.0x the glyph height, gap ~0.3x, measured on the cohort zoom). STRICT ONLY. Regression: `tests/test_liblib_engine.py`.
 
 ## `region_eraser.py`
 
-`region_eraser.py` — universal region eraser (`erase` CLI) AND the inpaint backend for the visible-mark fallback (`watermark_registry._inpaint_remove`). `erase(image, boxes=|mask=, backend=)` accepts grayscale (2D) and RGBA (4-channel) inputs on **all** backends (each splits off any alpha plane and re-attaches it unchanged, and promotes grayscale to BGR): `boxes_to_mask` → one of three backends.
+`region_eraser.py` — universal region eraser (`erase` CLI) AND the shared fill backend behind `watermark_registry.fill` for the visible localize -> fill removal. `erase(image, boxes=|mask=, backend=)` accepts grayscale (2D) and RGBA (4-channel) inputs on **all** backends (each splits off any alpha plane and re-attaches it unchanged, and promotes grayscale to BGR): `boxes_to_mask` → one of three backends.
 - `cv2` (default, no deps): `cv2.inpaint`.
-- `migan` (extra `migan`, `andraniksargsyan/migan` ONNX, MIT, ~28 MB): `erase_migan`. The MI-GAN ONNX crops around the mask bbox and re-composites internally, so the FULL image is fed at native resolution; only masked pixels are pasted back. **Mask polarity is INVERTED** vs this package's 255-erase convention — the shipped ONNX wants 0=hole / 255=known, so `erase_migan` feeds `(mask<=127)*255`; feeding 255=hole regenerates the whole frame into stripes (corpus-validated 2026-07, cost hours to find). ~0.95 GB peak / ~0.19 s. This is the **preferred** inpaint-fallback backend.
+- `migan` (extra `migan`, `andraniksargsyan/migan` ONNX, MIT, ~28 MB): `erase_migan`. Like `erase_lama`, it crops a padded region around the mask (`pad = max(256, 2*bbox)`), feeds only that crop to the ONNX model, and pastes only masked pixels back — but since MI-GAN accepts arbitrary dims (unlike LaMa's fixed 512² square) the crop is fed at NATIVE resolution (no resize). This **bounds the ONNX working set by the mark size, not the image**: feeding the whole frame made peak RAM scale with the upload (~0.6 GB at 4 MP up to ~2.4 GB at 25 MP, measured 2026-07); cropping holds it roughly constant (~0.6-0.9 GB), so a memory-tight host (a 1-2 GB web worker) can run MI-GAN on a 25 MP upload. The crop does not degrade the fill — a small mark only needs local context, and on real marks the cropped fill is on par with / sometimes cleaner than the full-frame fill (a tighter view gives the GAN less room to hallucinate large background structure; verified by eye on real Gemini/Doubao marks + a ground-truth reconstruction sweep). **Mask polarity is INVERTED** vs this package's 255-erase convention — the shipped ONNX wants 0=hole / 255=known, so `erase_migan` feeds `(crop_mask<=127)*255`; feeding 255=hole regenerates the whole frame into stripes (corpus-validated 2026-07, cost hours to find). ~0.19 s. This is the **preferred default fill** for the visible localize -> fill path.
 - `lama` (extra `lama`, `Carve/LaMa-ONNX` Apache-2.0, ~200 MB): `erase_lama` crops a padded region around the mask, runs at LaMa's fixed 512² input, pastes only masked pixels back. Best quality but ~4.7 GB peak — explicit opt-in only, NOT auto-selected.
-Lazy `_get_{lama,migan}_session` singletons; `{lama,migan}_available()` guard the optional imports (both == onnxruntime present). Note both extras install the same onnxruntime, so the two `*_available()` checks are identical — the registry's `preferred_inpaint_backend` therefore prefers MI-GAN whenever onnxruntime is present, and big-LaMa is reachable only by explicit `--backend lama`.
+Lazy `_get_{lama,migan}_session` singletons; `{lama,migan}_available()` guard the optional imports (both == onnxruntime present). Note both extras install the same onnxruntime, so the two `*_available()` checks are identical — the fill's `auto` backend therefore resolves to MI-GAN whenever onnxruntime is present, else cv2, and big-LaMa is reachable only by an explicit `lama` backend (`--backend lama` on `erase`, or the shared fill's `backend="lama"`).
 
 **LaMa-ONNX costs ~3.5-4 GB peak RAM and ~5-6 s/call on CPU** (FFC working set, not arena — `enable_cpu_mem_arena=False` does not help), so it does NOT fit a minimal droplet; the cv2 backend (tens of MB, ~30 ms) does. LaMa quality at low RAM = serverless/GPU, mirroring how raiw.cc offloads SDXL to fal.
 
@@ -207,7 +341,7 @@ At the shared low removal strength the canny edge-conditioning keeps the regener
 
 ## `noai/tiling.py`
 
-Pure sliding-window tiling for the diffusion path (no torch import; numpy/PIL only). `plan_tiles(w, h, tile_size, overlap)` returns a row-major grid of uniform-size `Tile` boxes — every tile is exactly `tile_size` (the SDXL training size), with the last tile on each axis pulled back flush to the far edge (`_axis_positions` clamps a pathological `overlap >= tile` to `tile - 1` so the step stays >= 1). `feather_weights(w, h, overlap)` is a separable linear taper (1 in the interior, ramping toward each edge) floored at `_WEIGHT_EPS` so it is **strictly positive everywhere** — that makes the normalised `accum / weight_sum` blend a partition of unity, so identical/unchanged tiles reconstruct the input exactly (the seam-free guarantee). `run_tiled(generate_tile, image, tile_size, overlap, set_progress)` is the orchestration loop: crop each planned tile, call `generate_tile` (one diffusion pass on a single PIL tile — injected, so this stays decoupled from the pipeline), resize a latent-grid-rounded result back to the exact tile size, and feather-accumulate. All three are unit-tested without the model (`tests/test_tiling.py`: axis math, grid coverage, taper shape/symmetry/positivity, identity reconstruction, per-tile call count, and the resize-back path). New blend tuning belongs in these pure helpers, not inlined into the runner.
+Pure sliding-window tiling for the diffusion path (no torch import; numpy/PIL only). `plan_tiles(w, h, tile_size, overlap)` returns a row-major grid of uniform-size `Tile` boxes — every tile is exactly `tile_size` (the SDXL training size), with the last tile on each axis pulled back flush to the far edge (`_axis_positions` clamps a pathological `overlap >= tile` to `tile - 1` so the step stays >= 1). `feather_weights(w, h, overlap)` is a separable linear taper (1 in the interior, ramping toward each edge) floored at `_WEIGHT_EPS` so it is **strictly positive everywhere** — that makes the normalized `accum / weight_sum` blend a partition of unity, so identical/unchanged tiles reconstruct the input exactly (the seam-free guarantee). `run_tiled(generate_tile, image, tile_size, overlap, set_progress)` is the orchestration loop: crop each planned tile, call `generate_tile` (one diffusion pass on a single PIL tile — injected, so this stays decoupled from the pipeline), resize a latent-grid-rounded result back to the exact tile size, and feather-accumulate. All three are unit-tested without the model (`tests/test_tiling.py`: axis math, grid coverage, taper shape/symmetry/positivity, identity reconstruction, per-tile call count, and the resize-back path). New blend tuning belongs in these pure helpers, not inlined into the runner.
 
 `feather_region_composite(base, regenerated, box, *, feather)` is the pure region-targeted compositor for **AI-enhanced composites** (roadmap P1#8; `identify` `ai_source_kind == "enhanced"`, digitalSourceType `compositeWithTrainedAlgorithmicMedia`). It blends `regenerated` over `base` inside `box = (x, y, w, h)` with a separable linear taper of `feather` px at the box edges (the taper anchors to ~0 at the boundary, so unlike `feather_weights` it is NOT floored — the result equals `base` EXACTLY outside the box), preserving dtype and supporting HxW or HxWxC. It backs `WatermarkRemover.remove_watermark(region=..., region_feather=...)`: the remover regenerates the frame (or tiles), then composites only the AI box back over the original input, so the real photo outside the box stays pixel-exact and only the AI region is scrubbed. The box is caller-supplied (a C2PA composite manifest carries no reliable machine-readable region); the no-model lossless region path remains `region_eraser.erase`. Unit-tested in `tests/test_tiling.py::TestFeatherRegionComposite` (outside-box exactness, interior == regenerated, hard-paste at feather 0, monotonic seam ramp, dtype/grayscale/clamp/empty-box/shape-mismatch).
 
@@ -248,9 +382,11 @@ KEPT from that work (independently valid for the manual `--pipeline qwen`): the
 
 Full per-command behavior for the skip/exit branches summarized in `CLAUDE.md`'s "How to run". The CLI distinguishes three exit codes: success (0), hard error (1), and a "nothing to do" code (2, `EXIT_NO_VISIBLE_MARK` / `EXIT_NO_INVISIBLE_SIGNAL`) so a wrapping service (raiw.cc) can surface guidance instead of treating an unchanged image as done (the production "it didn't work" / score-0 trap).
 
+**Every single-image command's `source` argument declares `dir_okay=False`** (2026-07-20). `click.Path(exists=True)` accepts a directory unless told otherwise, so `identify <dir>` sailed past argument parsing and raised `IsADirectoryError` out of `metadata.scan_head`'s `open()` — a traceback, not a usage error. Refusing it at the argument layer is the right place: every command gets it, and none needs its own check. (`batch`'s `directory` argument was already correct with `file_okay=False`.) Found by the Tier E adversarial sweep; regression: `tests/test_cli_robustness.py::TestDirectoryInputIsRejected`.
+
 ### `all`
 
-Full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible`, plus the visible-pass `--inpaint/--no-inpaint`/`--inpaint-method`. **When the `[gpu]` extra is absent, step 2 (invisible/SynthID) is skipped** — `all` still writes an output (visible mark + metadata stripped) but prints a prominent end-of-run banner ("the invisible (SynthID) watermark was NOT removed") AND exits **non-zero** (1), so a skipped SynthID pass is not mistaken for a clean result (the recurring #14/#47 trap, where the old quiet inline warning was missed). `invisible` already hard-errors without the extra; only `all` continued, hence the loud end-banner. Regression-guarded by `tests/test_cli.py::TestAllCommand::test_all_loud_warning_and_nonzero_exit_when_gpu_missing`. **No-signal skip (P0#5):** step 2 also runs the same `has_invisible_target` gate (see `invisible` below) — when no invisible watermark is detectable and `--force` is not set, step 2 is skipped and the pixels are left intact, but unlike the GPU-missing skip this is a **SUCCESS (exit 0)**: the visible pass + metadata strip still ran and a file is written (the message says so without claiming the image is clean). Distinct exit semantics by design: GPU-missing = couldn't do the work (non-zero); no-signal = nothing to do (zero). Regression-guarded by `test_all_skips_invisible_on_no_signal_but_succeeds`. **Test trap:** any `all` test that exercises the full pipeline MUST `patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True)` — CI installs core+dev only (no `[gpu]`), so an unpatched `all` test takes the skip branch and now hits the non-zero exit. This passed locally (gpu present → `is_available()` True) but red-failed every matrix cell on the v0.11.0 commit (`test_all_basic`/`test_all_visible_step_uses_registry` asserted exit 0); both now patch `is_available` True.
+Full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible`, plus the visible-pass `--backend auto|cv2|migan|lama` (default `auto`) that picks the fill for the localize -> fill visible removal. **When the `[gpu]` extra is absent, step 2 (invisible/SynthID) is skipped** — `all` still writes an output (visible mark + metadata stripped) but prints a prominent end-of-run banner ("the invisible (SynthID) watermark was NOT removed") AND exits **non-zero** (1), so a skipped SynthID pass is not mistaken for a clean result (the recurring #14/#47 trap, where the old quiet inline warning was missed). `invisible` already hard-errors without the extra; only `all` continued, hence the loud end-banner. Regression-guarded by `tests/test_cli.py::TestAllCommand::test_all_loud_warning_and_nonzero_exit_when_gpu_missing`. **No-signal skip (P0#5):** step 2 also runs the same `has_invisible_target` gate (see `invisible` below) — when no invisible watermark is detectable and `--force` is not set, step 2 is skipped and the pixels are left intact, but unlike the GPU-missing skip this is a **SUCCESS (exit 0)**: the visible pass + metadata strip still ran and a file is written (the message says so without claiming the image is clean). Distinct exit semantics by design: GPU-missing = couldn't do the work (non-zero); no-signal = nothing to do (zero). Regression-guarded by `test_all_skips_invisible_on_no_signal_but_succeeds`. **Test trap:** any `all` test that exercises the full pipeline MUST `patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True)` — CI installs core+dev only (no `[gpu]`), so an unpatched `all` test takes the skip branch and now hits the non-zero exit. This passed locally (gpu present → `is_available()` True) but red-failed every matrix cell on the v0.11.0 commit (`test_all_basic`/`test_all_visible_step_uses_registry` asserted exit 0); both now patch `is_available` True.
 
 ### `invisible`
 
@@ -258,8 +394,8 @@ Diffusion SynthID removal. The `--tile/--no-tile` knob is the *lossless* alterna
 
 ### `visible`
 
-Known-visible-mark removal. Two methods via `--method` (default `auto`): `reverse-alpha` inverts the captured alpha map to recover exact pixels (CPU, no GPU, better on structured backgrounds); `inpaint` erases the mark footprint (`footprint_mask` → MI-GAN when the `migan` extra is installed, else cv2; see `preferred_inpaint_backend` — big-LaMa is NOT auto-selected). `auto` = `registry.resolve_removal_method`: reverse-alpha for capture marks, inpaint for capture-less (deterministic, model-independent -- reverse-alpha is measured cleaner + lighter than MI-GAN on the capture marks, so inpaint is reserved for the pill); the resolved method is echoed in the status line, and `--method` is shared across `visible`/`all`/`batch`. The inpaint mask is the full NCC-aligned alpha silhouette (`footprint_mask`), NOT the per-image `extract_mask` signature — the signature under-segments and leaves glyph residue (corpus-validated 2026-07; the mask is dilated to absorb alpha-alignment slop). `--mark auto` (default) removes EVERY detected mark in one pass (`registry.remove_auto_marks`, not the single strongest -- a Jimeng-basic image carries both the top-left pill and the bottom-right wordmark) from: the Gemini sparkle, the Doubao "豆包AI生成" text strip, the Jimeng "★ 即梦AI" wordmark, the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-LEFT, Italian locale), and the capture-less Jimeng "AI生成" pill (top-left, `pill_engine`, inpaint-only). The pill's weak edge-NCC detector is gated in `remove_auto_marks` via `_keep_pill` (32k real-upload corpus validation 2026-07): never on Doubao, and two confirmation arms since metadata confirms the platform, not pill presence. (1) The bottom-right wordmark fired — ~94% precise and survives metadata-STRIPPED uploads (screenshots / re-saves) — removes the pill unrestricted. (2) TC260 metadata only (CLI `_aigc_metadata_present` → `pill_metadata`, no wordmark) — ~27% precise, its false fires are textured ceilings/walls that inpaint visibly SMEARS — removes the pill ONLY when the top-left footprint is flat enough for an invisible inpaint (`pill_engine.footprint_is_flat`, median-Sobel ≤ `_FLAT_TEXTURE_MAX`). No confirmation → never removed. `--mark gemini|doubao|jimeng|samsung|jimeng_pill` forces one (choices come from the registry). Under `reverse-alpha`, Gemini/Doubao recover pixels exactly with no inpaint at native; **Jimeng and Samsung add an always-on thin residual inpaint over the glyph footprint** (their marks re-rasterize per image, so reverse-alpha alone leaves a faint outline). For arbitrary logos/objects use `erase`. **When `--mark auto` finds no known mark (the common case — ~74% of real uploads carry no registered visible mark), the command does NOT silently re-serve the input as a finished result.** It runs a cheap metadata-only `identify`, prints actionable guidance (if the image carries an invisible/metadata mark, e.g. an OpenAI/Gemini C2PA image, it points to `all`; otherwise it does NOT imply the image is clean -- it warns that an invisible pixel watermark like SynthID cannot be detected once the metadata proxy is gone and routes to both `all` and `erase --region`), writes NO output file, and exits **`EXIT_NO_VISIBLE_MARK` (2)** — distinct from success (0) and a hard error (1) so a wrapping service (raiw.cc) can surface the message instead of treating the unchanged image as done (the production "it didn't work" / score-0 trap). Same handling for an explicit `--mark <name>` that is not detected. Helper `cli._no_visible_mark_exit`; regression-guarded by `tests/test_cli.py::TestVisibleCommand::test_visible_auto_no_mark_exits_two_with_eraser_hint` and `test_visible_auto_no_mark_routes_to_all_when_metadata`. `--no-detect` still forces the gemini fallback and proceeds (exit 0).
+Known-visible-mark removal by **localize -> fill**: each detected mark is localized to a binary full-frame footprint mask, then one shared, swappable fill inpaints that mask. `--backend auto|cv2|migan|lama` (default `auto`) picks the fill: `cv2` (classical inpaint, no deps, the floor), `migan` (MI-GAN ONNX, the memory-tight pick where LaMa will not fit), `lama` (big-LaMa ONNX, best quality, heavier, auto-preferred when a learned backend is available); `auto` = LaMa > MI-GAN > cv2, best available (LaMa is auto-preferred when a learned backend is present; a memory-tight deploy pins migan). `--sensitivity auto|strict|assume-ai` (default `auto`) controls how hard a borderline mark is trusted (see the registry section: the visual detectors are metadata-independent; `auto` relaxes a mark only on same-product evidence, `assume-ai` relaxes every mark on the caller's AI assertion, subject to the assumed-trust confidence floor where the vendor is unconfirmed — the only path to higher recall on a metadata-stripped screenshot). `--backend` and `--sensitivity` are shared across `visible`/`all`/`batch`. Detection keys on each mark's own shape, and under `auto` the trust gate is relaxed when local metadata confirms the vendor (a Google/Gemini C2PA issuer relaxes gemini, a China-AIGC label relaxes doubao/jimeng, `samsung_genai` relaxes samsung), so a moved or re-rendered mark is still caught. `--mark auto` (default) removes EVERY detected mark in one pass (`registry.remove_auto_marks`, not the single strongest -- a Jimeng-basic image carries both the top-left pill and the bottom-right wordmark) from: the Gemini sparkle, the Doubao "豆包AI生成" text strip, the Jimeng "★ 即梦AI" wordmark, the Qwen "千问AI生成" text strip, the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-LEFT, Italian-locale detection), and the capture-less Jimeng "AI生成" pill (top-left, `pill_engine`). The pill's weak edge-NCC detector is gated in `remove_auto_marks` via `_keep_pill` (32k real-upload corpus validation 2026-07): never on Doubao or Qwen, and two confirmation arms since metadata confirms the platform, not pill presence. (1) The bottom-right wordmark fired — ~94% precise and survives metadata-STRIPPED uploads (screenshots / re-saves) — removes the pill unrestricted. (2) TC260 metadata confirms Jimeng (`"jimeng" in provenance`, from `cli._visible_provenance`) OR the caller asserts AI (`sensitivity == "assume_ai"`), no wordmark — **re-measured 2026-07-18 on 149 blind-labelled pill fires: 21% precise raw (CI 16-29%), 29% (CI 20-40%) among the flat footprints the guard actually PASSES, 14% among those it blocks** — its false fires are textured ceilings/walls that the fill visibly SMEARS — removes the pill ONLY when the top-left footprint is flat enough for an invisible fill (`pill_engine.footprint_is_flat`, median-Sobel ≤ `_FLAT_TEXTURE_MAX`; the flatness guard holds even under `assume_ai`). No confirmation → never removed. `--mark gemini|doubao|jimeng|qwen|samsung|jimeng_pill` forces one (choices come from the registry). Corpus validation: doubao and jimeng localize + remove at ~100% with clean footprints (the filled region blends into its surroundings within a few LAB levels, no color shift, no dark pit); clean images with no vendor signature had 0% false removal. For arbitrary logos/objects use `erase`. **When `--mark auto` finds no known mark (the common case — ~74% of real uploads carry no registered visible mark), the command does NOT silently re-serve the input as a finished result.** It runs a cheap metadata-only `identify`, prints actionable guidance (if the image carries an invisible/metadata mark, e.g. an OpenAI/Gemini C2PA image, it points to `all`; otherwise it does NOT imply the image is clean -- it warns that an invisible pixel watermark like SynthID cannot be detected once the metadata proxy is gone and routes to both `all` and `erase --region`), writes NO output file, and exits **`EXIT_NO_VISIBLE_MARK` (2)** — distinct from success (0) and a hard error (1) so a wrapping service (raiw.cc) can surface the message instead of treating the unchanged image as done (the production "it didn't work" / score-0 trap). Same handling for an explicit `--mark <name>` that is not detected. Helper `cli._no_visible_mark_exit`; regression-guarded by `tests/test_cli.py::TestVisibleCommand::test_visible_auto_no_mark_exits_two_with_eraser_hint` and `test_visible_auto_no_mark_routes_to_all_when_metadata`. `--no-detect` still forces the gemini fallback and proceeds (exit 0).
 
 ### `batch`
 
-Process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the **full `invisible` knob set** (`--strength`/`--steps`/`--guidance-scale`/`--pipeline`/`--controlnet-scale`/`--model`/`--device`/`--max-resolution`/`--min-resolution`/`--upscaler`/`--seed`/`--hf-token`/`--humanize`/`--unsharp`/`--adaptive-polish`/`--tile`/`--tile-size`/`--tile-overlap`/`--force`), plus `--inpaint/--no-inpaint` for the visible pass. `--adaptive-polish` is ON by default; `--auto` is deprecated and a no-op that only warns. **No-signal skip (P0#5):** in invisible/all mode each image runs the same `has_invisible_target` gate — a signal-less image is skipped (no diffusion); in `invisible` mode the input is copied through to the output dir so it stays complete, in `all` mode the visible-removed result is kept and metadata is still stripped. `--force` scrubs every image regardless. One engine cached per pipeline; the polish is resolved once before the loop.
+Process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the **full `invisible` knob set** (`--strength`/`--steps`/`--guidance-scale`/`--pipeline`/`--controlnet-scale`/`--model`/`--device`/`--max-resolution`/`--min-resolution`/`--upscaler`/`--seed`/`--hf-token`/`--humanize`/`--unsharp`/`--adaptive-polish`/`--tile`/`--tile-size`/`--tile-overlap`/`--force`), plus `--backend` for the visible localize -> fill pass. `--adaptive-polish` is ON by default; `--auto` is deprecated and a no-op that only warns. **No-signal skip (P0#5):** in invisible/all mode each image runs the same `has_invisible_target` gate — a signal-less image is skipped (no diffusion); in `invisible` mode the input is copied through to the output dir so it stays complete, in `all` mode the visible-removed result is kept and metadata is still stripped. `--force` scrubs every image regardless. One engine cached per pipeline; the polish is resolved once before the loop. **Exit code (`batch` used to always exit 0, hiding failures):** `cmd_batch` raises `SystemExit(1)` when any image errored, OR when a `--mode invisible`/`all` image carried an invisible signal but the GPU extra was absent so its SynthID scrub was skipped — mirroring single `all`, it emits a loud "the invisible watermark was NOT removed on N image(s)" warning and (invisible mode) copies the input through so the output dir stays complete, rather than silently dropping the signal-bearing files that most needed processing. `_process_batch_image` returns that skipped-scrub flag; the loop tallies it. Regression-guarded by `tests/test_cli.py::TestBatchCommand::{test_batch_errors_exit_nonzero, test_batch_invisible_gpu_missing_writes_output_and_exits_nonzero}`.

docs/release-and-distribution.md

@@ -16,6 +16,10 @@ stays in `CLAUDE.md`; read this before cutting a release.
 
 **This is now AUTOMATED:** the main repo's `.github/workflows/distribute.yml` fires on the GitHub Release `published` event, waits for the sdist to appear on PyPI (poll loop, the Release event races publish.yml's upload), rewrites the formula's `url`+`sha256`, and pushes to the tap using the `HOMEBREW_TAP_TOKEN` repo secret (a fine-grained PAT with Contents:write on `homebrew-tap`). The SAME workflow also factory-rebuilds the HF Space (`HfApi.restart_space(..., factory_reboot=True)`, `HF_TOKEN` secret) so the Space reinstalls the new sdist (it pins `remove-ai-watermarks>=...` and only re-resolves on a rebuild). The manual Homebrew steps above are the fallback / what the workflow automates — a normal release needs no Homebrew or HF action.
 
+**Where the HF Space's own source lives (its demo code, NOT this library):** the private repo **`wiltodelta/raiw-hf-space`** (locally `~/Documents/GitHub/raiw-hf-space`) — `app.py` (CPU-core Gradio demo), `requirements.txt`, `README.md` (the Space card), `assets/`, `examples/`. **Deploying it is a plain `git push` to that repo's `main`:** its `.github/workflows/sync-to-hf.yml` mirrors the files onto the Space via the Hub API (`HfApi.upload_folder`, secret `HF_TOKEN` = a **write**-role token), which adds a commit on top of the Space's own history — deliberately NOT a `git push --force` to the Space, which would clobber it. Do NOT edit the Space through the huggingface.co web UI any more: that was the pre-2026-07-16 workflow (it is why every Space commit before then is authored `@users.noreply.huggingface.co` and why no local write token ever existed), and a web edit now silently diverges from the GitHub source of truth. Note the demo tracks the library's **CPU-core** surface only (`identify` / `visible` / `metadata`); the invisible/SynthID path needs a GPU and stays out. Two distinct automations touch the Space and must not be confused: `sync-to-hf.yml` (in `raiw-hf-space`) ships **demo code changes**; `distribute.yml` (in this repo) factory-rebuilds the Space on a **library release** so its `remove-ai-watermarks>=...` pin re-resolves to the new version.
+
+**If the distribute.yml Homebrew job fails with "Bad credentials" (or the tap push 403s),** the `HOMEBREW_TAP_TOKEN` secret has expired or been revoked — fine-grained PATs expire on a fixed date, so this recurs. Fix: rotate the PAT (a fine-grained token with Contents:write on `wiltodelta/homebrew-tap`), update the `HOMEBREW_TAP_TOKEN` repo secret, then re-run the failed job (`gh run rerun <run-id> --failed`). While the token is being rotated, the manual formula bump above unblocks the release. The same rotate-secret-and-rerun applies to any distribute.yml credential failure (`HF_TOKEN` for the Space rebuild).
+
 **Other distribution channels:** (1) **conda-forge** — recipe source of truth committed at `packaging/conda/recipe.yaml` (v1 `recipe.yaml`, noarch core-only: pillow/piexif/numpy/py-opencv/click/python-dotenv); the initial submission is `conda-forge/staged-recipes` PR #33674 (went green only after **`pip_check: false`** in the python test — rattler-build's `pip check` defaults to ON and fails on the ancient conda-forge `piexif py_2` build's stale metadata with "piexif 1.1.3 is not supported on this platform", though the package installs/imports/works; keep it disabled). Once that merges and the `remove-ai-watermarks-feedstock` exists, the `regro-cf-autotick-bot` auto-opens a version-bump PR on the feedstock when each new PyPI sdist is detected — just review + merge it (hand-edit only if run-deps changed; keep `packaging/conda/recipe.yaml` in sync as the reference copy). (2) **ComfyUI Registry** — the node package is a SEPARATE repo `wiltodelta/ComfyUI-remove-ai-watermarks` with its OWN `pyproject.toml` `version` (independent of the library version). Publish a new node version by bumping that `version` in the node repo's `pyproject.toml` and pushing to `main` — the node repo's `.github/workflows/publish.yml` (`Comfy-Org/publish-node-action@main`, triggered on a push that touches `pyproject.toml`, secret `COMFY_REGISTRY_TOKEN`) **auto-publishes** it; `comfy node publish --token <registry-PAT>` is the manual/local fallback. It is NOT auto-published on a library release (the node has its own version), so only bump it when the node code or its `remove-ai-watermarks>=` dependency floor changes.
 
 **Sdist must exclude `data/`** (`[tool.hatch.build.targets.sdist] exclude = ["/data"]`): hatchling's default sdist bundles all VCS-tracked files, so the committed `data/` test corpora (the multi-hundred-MB synthid_corpus images + the visible-mark captures) pushed the **0.8.0** sdist past PyPI's per-project file-size limit (400 "File too large") — the wheel uploaded but the sdist was rejected, so 0.8.0 shipped wheel-only and 0.8.1 carried the fix. The wheel only ships `src/` (via `[tool.hatch.build.targets.wheel] packages`), so it was never affected.
@@ -31,4 +35,5 @@ The standing `uv-secure` gate in `maintain.sh` is clean; this is the changelog o
 - **idna** bumped 3.11 -> 3.16, fixing GHSA-65pc-fj4g-8rjx.
 - **aiohttp** bumped 3.13.5 -> 3.14.0 via `uv lock --upgrade-package aiohttp`, fixing GHSA-hg6j-4rv6-33pg + GHSA-jg22-mg44-37j8.
 - **basicsr** Dependabot alert GHSA-86w8-vhw6-q9qq is resolved by removal: the experimental `restore` extra was retired and basicsr is no longer anywhere in the dependency tree.
-- **torch** Dependabot alert **GHSA-rrmf-rvhw-rf47** (`torch.jit.script` memory corruption, vulnerable `<= 2.12.0`) is **dismissed as `not_used`** (2026-06-10): torch is a transitive dep of the optional `gpu` extra only, the codebase never calls `torch.jit` (grep-verified), and **no patched torch version exists** (`first_patched_version` is null), so it cannot be closed by an upgrade — do not re-triage it.
+- **torch** Dependabot alert **GHSA-rrmf-rvhw-rf47** (`torch.jit.script` memory corruption, alert range `<= 2.12.1`) was dismissed `not_used` on 2026-06-10 (torch is a transitive dep of the optional `gpu` extra only and the codebase never calls `torch.jit`) and **resolved by upgrade on 2026-07-21**: the lock carries torch **2.13.0**, above the patched floor, so `uv-secure` is clean. If the GitHub alert has not auto-closed on the lock bump, close it manually as fixed.
+- **setuptools** bumped 81.0.0 -> 83.0.0 (2026-07-21), fixing PYSEC-2026-3447.

docs/research-doubao-distillation.md

@@ -10,9 +10,9 @@
 
 **Conclusion (historical): pure reverse-alpha distilled from content images does NOT work, and the blocker is the WRONG kind of data, not too little of it.**
 
-The earlier framing ("need ~5-8 PRISTINE same-resolution originals") is obsolete -- a local corpus of pristine originals holds plenty. Curate them with `DoubaoEngine.detect` + an NCC filter against a clean glyph template, keeping only marks at offset ≈ (0,0): that yields e.g. **15 pixel-aligned 2048² marks** (sub-pixel drift, not the ±50 px the old lossy/mixed-res scrapes had), plus 1086x1448 / 1792x2400 clusters. With those, LaMa-clean `O` + weighted-LS (and per-pixel I-on-O regression) for `α` (+ logo colour) was tried end-to-end and **still leaves a persistent ghost outline.**
+The earlier framing ("need ~5-8 PRISTINE same-resolution originals") is obsolete -- a local corpus of pristine originals holds plenty. Curate them with `DoubaoEngine.detect` + an NCC filter against a clean glyph template, keeping only marks at offset ≈ (0,0): that yields e.g. **15 pixel-aligned 2048² marks** (sub-pixel drift, not the ±50 px the old lossy/mixed-res scrapes had), plus 1086x1448 / 1792x2400 clusters. With those, LaMa-clean `O` + weighted-LS (and per-pixel I-on-O regression) for `α` (+ logo color) was tried end-to-end and **still leaves a persistent ghost outline.**
 
-Diagnosed why, empirically (cached stacks, `/tmp/doubao_distill`): (1) the mark is a clean white overlay with **no dark halo** -- over glyph pixels ~54% are brighter than the clean bg, only ~4% darker -- so the white-logo model `I=(1-α)O+α·255` is correct; (2) but content backgrounds are almost never dark *under* the mark (median darkest available bg over glyph pixels = **58/255**; only ~13% of mark pixels are ever observed on a bg < 40), so on bright backgrounds the equation is ill-conditioned and `α` is unidentifiable; (3) LaMa's `O` is a plausible **hallucination**, not the true pre-mark background, which compounds the error, and per-pixel regression on ~15 obs overfits into colour noise.
+Diagnosed why, empirically (cached stacks, `/tmp/doubao_distill`): (1) the mark is a clean white overlay with **no dark halo** -- over glyph pixels ~54% are brighter than the clean bg, only ~4% darker -- so the white-logo model `I=(1-α)O+α·255` is correct; (2) but content backgrounds are almost never dark *under* the mark (median darkest available bg over glyph pixels = **58/255**; only ~13% of mark pixels are ever observed on a bg < 40), so on bright backgrounds the equation is ill-conditioned and `α` is unidentifiable; (3) LaMa's `O` is a plausible **hallucination**, not the true pre-mark background, which compounds the error, and per-pixel regression on ~15 obs overfits into color noise.
 
 **Why Gemini's engine is clean (verified in GeminiWatermarkTool `src/core/watermark_engine.cpp`): its alpha map is the watermark stamped on a PURE-BLACK background**, where `watermarked = α·255 + (1-α)·0 = α·255`, so `alpha = capture/255` exactly -- no estimation. (`gemini_bg_*.png` is literally the sparkle in grey on black.) So the real Doubao unlock is the same controlled capture, **not more content images**. Black/white/gray seeds exist (`data/doubao_capture/seeds/seed_*_1x1_2048x2048.png`); a capture run (feed a black seed through doubao.com edit mode, download the *original*) was requested from the #13 reporter 2026-05-29. With ~2-3 black captures we get `α = capture/255` for free, Gemini-quality.
 

docs/watermarking-landscape.md

@@ -18,7 +18,7 @@ Who embeds what, and whether it is locally detectable (so we know which gaps are
 
 **Black Forest Labs (FLUX)** API output signs C2PA: `claim_generator_info "Black Forest Labs API"` + a `c2pa.ai_generated_content` assertion + `trainedAlgorithmicMedia` (issuer `b"Black Forest Labs"` added to `C2PA_ISSUERS`, platform "Black Forest Labs (FLUX)").
 
-**ByteDance Volcano Engine (Volcengine)** — the cloud behind Doubao / Jimeng — signs its AI image output with a cert from `certificate_center@volcengine.com` + `trainedAlgorithmicMedia` (issuer `b"volcengine"` → "ByteDance (Volcano Engine)", platform "ByteDance (Doubao / Jimeng / Volcano Engine)"); note this is the C2PA-signed surface, distinct from the XMP/PNG TC260 `AIGC` label Doubao also uses. All three verified on real signed files 2026-05-29. ByteDance's **international brand (BytePlus / Seedream / Seededit)** signs the SAME content as **"Byteplus Pte. Ltd."** — the bare `volcengine` needle missed it, so real BytePlus output was mis-attributed to "Adobe Firefly" (an incidental "Adobe XMP" toolkit string in the file's XMP, picked up by the fallback byte-scan once the clean manifest issuer matched nothing). Added issuer `b"Byteplus"` → org "BytePlus (ByteDance)" (platform resolves to the shared "ByteDance (Doubao / Jimeng / Volcano Engine)" label via the common `ByteDance` needle) so the clean manifest issuer attributes it directly; found on real production traffic 2026-06-19.
+**ByteDance Volcano Engine (Volcengine)** — the cloud behind Doubao / Jimeng — signs its AI image output with a cert from `certificate_center@volcengine.com` + `trainedAlgorithmicMedia` (issuer `b"volcengine"` → "ByteDance (Volcano Engine)", platform "ByteDance (Doubao / Jimeng / Volcano Engine)"); note this is the C2PA-signed surface, distinct from the XMP/PNG TC260 `AIGC` label Doubao also uses. All three verified on real signed files 2026-05-29. ByteDance's **international brand (BytePlus / Seedream / Seededit)** signs the SAME content as **"Byteplus Pte. Ltd."** — the bare `volcengine` needle missed it, so real BytePlus output was mis-attributed to "Adobe Firefly" (an incidental "Adobe XMP" toolkit string in the file's XMP, picked up by the fallback byte-scan once the clean manifest issuer matched nothing). Added issuer `b"Byteplus"` → org "BytePlus (ByteDance)" (platform resolves to the shared "ByteDance (Doubao / Jimeng / Volcano Engine)" label via the common `ByteDance` needle) so the clean manifest issuer attributes it directly; found on real production traffic 2026-06-19. ByteDance's consumer app **Dreamina** (the international Jimeng brand) signs as **"Bytedance Pte. Ltd."** with a `Dreamina/x.y` claim generator but, unlike the Volcano Engine surface, ships **NO `trainedAlgorithmicMedia`** — the generator name is the only AI signal, and the active manifest is frequently a plain `c2pa-tool` transcode with the real `Dreamina` token on an ingredient manifest. Added issuer `b"Dreamina"` → org "ByteDance (Dreamina)" with **`asserts_ai=True`** (see `constants.py`): the caBX / store-JSON byte-scan sees the token across all manifests, and the identity-AI flag lifts the AI verdict without a source-type. Mined from the retained corpus 2026-07 (7 files read `unknown` before, all now ByteDance). Registering the **issuer** `b"Bytedance Pte"` was deliberately AVOIDED — that same Singapore entity also signs non-AI CapCut edits (`CapCut/x.y` generator, `c2pa.created`, no AI marker), which must stay unattributed per the editor-vs-generator line; keying on the `Dreamina` generator token is precise.
 - **EXIF/XMP/PNG-text generator tag (caught by `exif_generator`):** **Ideogram** writes EXIF `Make="Ideogram AI"` (collected 2026-05-24 — no C2PA, no SynthID, no imwatermark; the Make tag is the only signal). Three more mined from the retained corpus 2026-06-22, all no-C2PA generator stamps that previously read as no-signal: **NovelAI** (anime SD) writes its stamp in PNG `tEXt` chunks `Software="NovelAI"` / `Source="NovelAI Diffusion V4.5 <hash>"` / `Title="NovelAI generated image"` — so `exif_generator` now reads PNG text chunks (`Software`/`Source`/`Title`/`Description`), not just EXIF/XMP; **Reve** (reve.com) writes EXIF `Software` / XMP `CreatorTool` = `reve.com` (token is the full `reve.com`, not bare `reve`, to avoid false-firing on "forever"/"reverie"); **Aphrodite AI** writes EXIF `Make`/`Software` = `Aphrodite AI`.
 - **xAI / Grok — its own EXIF signature scheme, NOT C2PA (DETECTED by `metadata.xai_signature`, built 2026-05-26).**
 
@@ -29,7 +29,7 @@ Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC*
 **Stripped on removal too:** `remove_ai_metadata` now calls `_scrub_ai_exif` on the JPEG EXIF, which deletes the xAI Signature+UUID-Artist pair **and** any `Software`/`Make`/`Artist`/`ImageDescription` tag holding an `AI_GENERATOR_TOKENS` token (so Ideogram's `Make="Ideogram AI"` is scrubbed too), while keeping genuine camera/editor EXIF. The shared `_is_xai_signature_pair` helper (module-level compiled regexes) is the single source of truth for the pattern, used by both `xai_signature` and `_scrub_ai_exif`. (AVIF/HEIF/JXL still strip only C2PA boxes via `isobmff`, not EXIF — unchanged.)
 - **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`).
 
-**Doubao** (ByteDance) uses it (verified on the real #13 sample 2026-05-25; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **four serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on the corpus 2026-05-30) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on the corpus 2026-05-28, `ContentProducer="doubao"`), a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on the corpus 2026-05-30, `ContentProducer="001191440300708461136T1308L"`), **and** a bare `AIGC{...}` blob (the label glued straight to its JSON, no `"AIGC":` key wrapper) embedded in a **JPEG APP segment near the JFIF header** — confirmed on the corpus 2026-06-10 (`ContentProducer="00119144030008867405X210002"`; 3 files read `unknown` before this form was added). The two raw-JSON forms are scanned in one loop (`'"AIGC"'` then `AIGC{`) that **falls through on a non-TC260 / undecodable hit instead of returning** — a quoted `"AIGC"` can appear later in an XMP packet while the real label is a bare `AIGC{...}` earlier in the file, so an unconditional early return on the quoted form would shadow the bare form (the exact bug behind the 06-10 misses). All three generic forms (the PNG chunk, the bare `{"AIGC":...}` object, and the bare `AIGC{...}` blob) are gated on at least one TC260 field (`_TC260_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
+**Doubao** (ByteDance) uses it (verified on the real #13 sample 2026-05-25; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **four serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on the corpus 2026-05-30) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on the corpus 2026-05-28, `ContentProducer="doubao"`), a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on the corpus 2026-05-30, `ContentProducer="001191440300708461136T1308L"`), **and** a bare `AIGC{...}` blob (the label glued straight to its JSON, no `"AIGC":` key wrapper) embedded in a **JPEG APP segment near the JFIF header** — confirmed on the corpus 2026-06-10 (`ContentProducer="00119144030008867405X210002"`; 3 files read `unknown` before this form was added). The two raw-JSON forms are scanned in one loop (`'"AIGC"'` then `AIGC{`) that **falls through on a non-TC260 / undecodable hit instead of returning** — a quoted `"AIGC"` can appear later in an XMP packet while the real label is a bare `AIGC{...}` earlier in the file, so an unconditional early return on the quoted form would shadow the bare form (the exact bug behind the 06-10 misses). All three generic forms (the PNG chunk, the bare `{"AIGC":...}` object, and the bare `AIGC{...}` blob) are gated on at least one TC260 field (`_TC260_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. `_TC260_FIELDS` covers **two schemas**: the producer-side one (`Label` / `ContentProducer` / `ProduceID` / `ContentPropagator` / `PropagateID`, Doubao and most China gens) and the **service-provider** one (`ServiceProvider` / `ServiceUser`, plus generic `Time` / `ContentId` which are NOT gated on) — **Tencent Cloud's** AIGC variant (`ServiceProvider` = `腾讯云`), embedded in **EXIF `ImageDescription`**, mined from the retained corpus 2026-07 (11 files read `unknown` before — the block was found by the raw-JSON scan but rejected because none of its fields were in the producer-only gate; removal already stripped it since it lives in EXIF). In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
 - **HuggingFace-hosted job (caught by `metadata.huggingface_job`, surfaced by `identify` as the `hf_job` signal, MEDIUM confidence):** HuggingFace Jobs / Spaces stamp generated PNGs with an `hf-job-id` tEXt chunk holding the job UUID (3 on the corpus 2026-05-28, no other signal). It marks the *hosting job*, not a model — most commonly diffusion output — so it lifts an Unknown verdict to a tentative AI via `hf_only` (parallel to the visible sparkle) but never overrides a hard metadata signal; `_HF_JOB_CAVEAT` states the limit (job, not model; not proof of AI pixels). Stripped on removal (the PNG save whitelist keeps only `STANDARD_METADATA_KEYS`, so `hf-job-id` and the `AIGC` chunk are both dropped). The exact writer is not authoritatively documented (HF Jobs are generic GPU jobs), hence medium not high.
 - **No detectable signal on download (correctly reported `unknown`):** **Recraft** (PNG export is a re-encoded design export — strips everything), **Krea hosting FLUX 2** (no imwatermark despite FLUX — the host omits the encoder, same as Stability's hosted SDXL), and Midjourney (embeds nothing). Lesson: the imwatermark detector only fires on *pristine* output from a pipeline that runs the encoder (diffusers default, official BFL), not from re-hosts (Krea/Stability) or re-encoded exports (Recraft/Canva).
 - **Invisible but NOT locally detectable (proprietary, API/oracle only — same wall as SynthID):** Amazon Titan Image Generator + Nova Canvas (Bedrock `DetectGeneratedContent` API), Kakao (new SynthID image adopter, May 2026), NVIDIA Cosmos (SynthID video). No local detector possible; treat like SynthID.
@@ -42,3 +42,40 @@ Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC*
 - **Regulatory driver (context, not a code change):** AI-content labeling mandates are expanding, which pushes more generators toward exactly the C2PA + watermark signals we read. The full per-jurisdiction table lives in README "## Legal" -- keep it there, not duplicated here. Newly added + primary-source verified 2026-05-26: **EU AI Act Article 50** machine-readable marking applicable **2026-08-02** (verified against the article text); **South Korea AI Framework Act Art. 31(3)** in force since **22 January 2026** (verified via Kim & Chang + FPF/Korea Times; Enforcement Decree accepts an invisible-watermark label); **California AB 853** (amends the CA AI Transparency Act) latent-disclosure duty operative **2026-08-02**, requiring a disclosure "permanent or extraordinarily difficult to remove" (verified against the leginfo bill text -- this is the exact disclosure our tool strips); **India IT Amendment Rules 2026** in force **2026-02-20** (verified via Chambers), which prominently-label + permanent-provenance-id all synthetic media AND **expressly prohibit removing/suppressing the label or metadata** -- the first major all-content removal ban outside China.
 
 **Removal liability (README "## Legal" disclaimer):** the tool is lawful general-purpose software; liability sits with the remover and is intent-gated -- downstream acts (fraud/deception/IP), plus US DMCA 17 USC 1202 (removing copyright-management info to conceal infringement), plus the removal-as-such bans in China + India. When extending the README table, verify each date/article against the statute/bill text before committing, not against search summaries.
+
+## Visible AI-generation marks + detection methods (deep-research 2026-07-10, adversarially verified)
+
+**Google Gemini visible "sparkle" -- tier-dependent, and spec-undocumented by Google.** Google primary sources (the Nano Banana Pro blog and the gemini.google image-generation page, both WebFetch-verified) confirm Gemini images carry BOTH the invisible SynthID (on ALL Google-AI media) AND a visible sparkle, but the visible mark is **tier-gated**: applied for FREE and Google AI **Pro** users, and **REMOVED** for Google AI **Ultra** subscribers, inside **Google AI Studio**, and on **API / dev** output. So a Google-C2PA image with NO visible sparkle is expected (Ultra / API), not evidence it is clean -- this reinforces the `identify` "no visible mark != clean" rule. The ONLY official verifier is the SynthID flow (upload to the Gemini app, ask if it is AI-generated), which reads the INVISIBLE mark; there is **no official visible-sparkle detector**, and Google publishes **no** glyph geometry / size / opacity / color / locale / placement spec. So our capture-based sparkle template is the only source of truth and cannot be validated against a vendor spec -- keep reverse-engineering from real captures (do not expect a published spec).
+
+**The faint-visible-mark precision/recall wall is fundamental, not a heuristic artifact.** The visible-watermark-detection literature has moved to LEARNED segmentation / object-detection (WDNet WACV'21 arXiv:2012.07616; SLBR ACM MM'21, open code+weights; the PRCV'18 large-scale detector; Su et al. survey 2025), but three verified findings bound what a learned detector actually buys: (1) a claim that a confidence threshold "cleanly separates" true from false matches even with a learned CNN front-end was **REFUTED** in verification (arXiv:1705.08593) -- the precision/recall wall persists even with learned features. (2) Learned detectors need a LARGE, pattern-diverse labeled dataset trained on synthetic composites (PRCV'18: 60k images / 80 watermark classes; CLWD: 60k / 160 marks), and off-distribution degradation is a documented real axis (models trained on limited-pattern LVW transfer worse; diversity of training patterns drives generalization). (3) Inference is cheap (WDNet ~8 ms at 256x256) -- the cost is the data pipeline, not runtime. Net: a learned detector shifts the frontier but does NOT remove the wall; for a SINGLE mark the cheapest next step is a small patch classifier (real-sparkle vs false-positive) on top of the existing NCC localizer, not a full segmentation model. SLBR is a ready baseline. The current NCC + false-positive gate (core-ring brightness margin + gradient-NCC crispness + white-core saturation) is a sound operating point, and the residual miss is the information-theoretic wall the literature confirms.
+
+**Visible-mark landscape beyond the registry.** Meta stamps a visible "Imagined with AI" mark (bottom-LEFT, a small symbol) on its OWN Meta AI / "Imagine" output; for third-party images it relies on C2PA / IPTC, not a visible mark. Samsung Galaxy AI additionally uses a **four-star icon** variant in a corner alongside the localized text wordmark `samsung_engine` calibrates (only the Italian text variant is covered) -- the icon is a distinct, uncovered variant. Every source agrees visible + metadata marks are trivially removable (crop / screenshot, ~2 s), which is the tool's premise.
+
+**Regulatory driver -- China GB 45438-2025 is the strongest VISIBLE-mark mandate.** The CAC / TC260 "Measures for Labeling AI-Generated Synthesized Content" (issued March 2025, **effective 2025-09-01**, technical standard **GB 45438-2025**, building on the TC260 Aug-2023 practice guide) MANDATE a **visible** label for AI images -- a visible textual mark whose height must be **>= 5% of the image's shortest side** -- plus the metadata (implicit) label. So every major Chinese platform now ships visible "AI生成"-style text marks (we cover Doubao / Jimeng; expect more CJK-text marks under this driver). By contrast EU AI Act Article 50 mandates only the MACHINE-READABLE mark (enforceable 2026-08-02, grace to 2026-12-02); a visible label is proposed and modality-specific (visible for images) but is NOT a hard "fixed icon" mandate -- a claim that Art 50 requires a clearly-visible fixed icon for images was refuted in verification. Primary-source dates verified against the article/standard text, not search summaries.
+
+## Uncovered visible marks: implementation specs (deep-research 2026-07-18)
+
+Triggered by a corpus finding: **50% of TC260-labelled uploads (1452 of 2896 unique) produced no detection at all**, and hand-inspection showed the bulk are MISSED Doubao marks (a localization defect, now fixed -- see `scale_basis` in `docs/module-internals.md`) plus a minority of genuinely uncovered vendors. Verification status is labelled per claim; treat (b)/(c) as leads, not ground truth.
+
+**GB 45438-2025 clause 5.2, the binding constraint for every Chinese mark (VERIFIED (a) -- full standard text extracted from the TC260-hosted PDF).** Verbatim requirements for an image's explicit label:
+- 应采用文字提示 (must be a TEXT prompt);
+- must contain BOTH an AI element (`人工智能` or `AI`) AND a generation element (`生成` and/or `合成`);
+- 应位于图片的边或角 -- **edge OR corner**, so bottom-right is NOT mandated (Annex C.2's bottom-right figure is a non-normative example);
+- 字型应清晰可辨 (legible typeface -- no family named);
+- **文字高度不应低于画面最短边长度的 5%** -- glyph HEIGHT >= 5% of the frame's SHORTEST side, with a note defining the shortest side for non-rectangular images.
+
+Two consequences we can exploit: (1) the 5% floor is a **scale prior** -- a compliant CN mark's glyphs are large (>= 51 px on a 1024² image), so a CN silhouette ladder can be anchored at ~5-10% of the short side instead of swept broadly, which should cut false fires; (2) every compliant string shares the tail `AI生成` / `AI合成`, so a shared suffix silhouette plus a per-vendor prefix may beat five independent templates. NOT established: whether 文字高度 means cap height, em box, or rendered bounding box (a ~1.3x spread in template scale). Sources: `https://www.tc260.org.cn/upload/2025-03-15/1742009439794081593.pdf`, parent CAC measure `https://www.cac.gov.cn/2025-03/14/c_1743654684782215.htm` (the CAC text itself specifies no size or corner).
+
+**Alibaba Qwen -- two surfaces that differ (API tier VERIFIED (a)).** Model Studio docs state verbatim that the API adds a `Qwen-Image` watermark 在图像右下角 and 默认值为 false -- so API output is **unwatermarked by default**, and when enabled the mark is a LATIN wordmark, not CJK, and not GB-compliant in wording. The consumer app's `千问AI生成` (bottom-right) is (b) secondary only -- no Alibaba primary page states it. So Qwen needs TWO templates, and its absence is never evidence of a clean image. Source: `https://help.aliyun.com/zh/model-studio/qwen-image-api`.
+
+**星绘 is ByteDance (VERIFIED (a): Baidu Baike + App Store listing, now branded 豆包旗下, team folded into Doubao April 2025).** So `星绘AI生成` is very likely the Doubao house style -- same typeface, same corner, possibly the same top-left `AI生成` pill. Starting from the Doubao `TextMarkConfig` and swapping the two lead glyphs is the cheap path. String/position themselves are (c) inferred.
+
+**Baidu: RESOLVED 2026-07-22, registered (`baidu_engine.py`).** The mark is a white bold "百度" text run + a separate white rounded tag with dark "AI生成", bottom-right -- settled by the TC260 USCC cohort harvest (16 frames, USCC 91110000802100433B), not by web research. Detection keys on the text run only; details in `docs/module-internals.md`.
+
+**Meta `Imagined with AI` (string VERIFIED (a) from Meta's own newsroom; POSITION NOT VERIFIED).** Sources conflict (bottom-left vs bottom-right) and one claims newer Meta models dropped the visible mark for invisible watermarking; none survived a fetch. Do NOT encode a corner without a corpus sample. Meta also embeds IPTC + invisible watermarks, which `identify` already reads. Source: `https://about.fb.com/news/2024/02/labeling-ai-generated-images-on-facebook-instagram-and-threads/`.
+
+**Samsung English/other locales: still not established.** Samsung's own support page says only that "A Galaxy AI watermark will appear on AI-generated images" -- no string, no corner. Every community thread carrying the exact English string returned HTTP 403 to WebFetch, so the search paraphrase (bottom-left) is deliberately NOT recorded as fact. Feature-tier detail (b): the mark is applied by Generative Edit / sketch-to-image but reportedly NOT by Object Eraser, so Samsung absence is feature-dependent. The four-star icon variant: nothing found.
+
+**The one document that would settle ByteDance placement is BLOCKED.** Douyin's 《抖音关于人工智能生成内容标识的水印与元数据规范》 aims to give AI tools a unified watermark style and position, which would cover Doubao / Jimeng / 星绘 at once. Both mirrors return HTTP 403 to WebFetch; a secondary report (b, unconfirmed) says the watermark is `AI生成` + tool name + company name placed **top-left** -- which would explain the Jimeng pill's top-left position but contradicts the GB annex's bottom-right example. Worth one retry through Chrome MCP with a real browser session.
+
+**No vendor publishes typeface, colour, opacity, plate, or margin for ANY of these marks.** The only font-adjacent requirement anywhere is GB's "legible typeface". So each synthetic silhouette's font must be calibrated against corpus positives exactly as the Jimeng pill was; candidate CJK families by platform convention (inference): HarmonyOS Sans / Source Han Sans / Noto Sans CJK SC for Android-origin apps, PingFang SC for iOS-origin.

maintain.sh

@@ -3,8 +3,24 @@
 set -euo pipefail
 
 uv sync --all-extras
-uv run uv-outdated
-uv run uv-secure --ignore-unfixed
+# uv-outdated / uv-secure run via uvx (isolated env), NOT `uv run`: resolving them
+# inside the project env crashes and, with set -e, aborts the whole gate before
+# ruff/pyright/tests (see CLAUDE.md "Test and lint").
+uvx uv-outdated
+# uv-secure prints its verdict but can then crash in an internal teardown with a
+# NON-ZERO exit -- observed as "annotated-doc raised exception" and later "anyio raised
+# exception"; both are bugs in uv-secure's OWN uvx env, not a project vulnerability. With
+# set -e that teardown crash aborts the whole gate before ruff/pyright/tests. So gate on
+# the VERDICT, not the exit code: capture the output, accept the run when uv-secure
+# reported all-safe (even if it then crashed), but still FAIL on a real finding (no
+# all-safe line) so a genuine CVE is never masked, and fail loud if it never got a
+# verdict at all (so a broken run is never silently skipped).
+secure_out="$(uvx uv-secure --ignore-unfixed 2>&1)" || true
+printf '%s\n' "$secure_out"
+if ! grep -qE "No vulnerabilities or maintenance issues detected|All dependencies appear safe" <<<"$secure_out"; then
+    echo "maintain.sh: uv-secure reported a finding or failed before its verdict -- triage before committing." >&2
+    exit 1
+fi
 uv run ruff check --fix
 uv run ruff format
 # Scoped to src/: a full-project pyright run OOM-crashes node on this ML-heavy

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.13.0"
+version = "0.18.0"
 description = "AI watermark remover: strip visible and invisible AI watermarks (Gemini / Nano Banana sparkle, SynthID) and provenance metadata (C2PA, EXIF) from images"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -46,6 +46,12 @@ classifiers = [
 ]
 dependencies = [
     "pillow>=10.0.0",
+    # HEIC/AVIF pixel decode for the removal path (iPhone photos, modern exports):
+    # OpenCV cannot decode these containers, so image_io.imread falls back to Pillow
+    # and pillow-heif (bundled libheif, prebuilt wheels) registers the HEIF+AVIF
+    # openers. The metadata path already handles them via a plugin-free binary scan;
+    # this closes the same gap for the pixel path so `visible`/`all` work on them.
+    "pillow-heif>=0.13.0",
     "piexif>=1.1.3",
     "numpy>=1.24.0",
     "opencv-python-headless>=4.8.0",

scripts/cjk_tail_probe.py

@@ -0,0 +1,272 @@
+"""Can one GENERIC template cover the CJK AI labels no per-vendor detector fires on?
+
+THE OPPORTUNITY
+  Corpus inspection of doubao-provenance misses turned up `千问AI生成` (Alibaba Qwen) and
+  `百度 AI生成` (Baidu) sitting in the same bottom-right corner as the marks we do cover,
+  bold and plainly legible, with no detector able to fire on either. `docs/...landscape`
+  puts uncovered vendors at ~6% of sampled images -- larger than any tuning gain left in
+  the covered ones (a dense scale ladder recovers 1 miss in 26; see ladder_headroom.py).
+
+WHY A SHARED TEMPLATE IS EVEN PLAUSIBLE
+  China's GB 45438-2025 mandates the label, and every compliant vendor ends it with the
+  same run: `AI生成`. The vendor PREFIX varies (豆包 / 千问 / 百度 / 星绘) and is what makes
+  per-vendor silhouettes expensive; the TAIL is guaranteed. So the tail is the part worth
+  detecting, and vendor attribution -- which the shared tail cannot provide anyway
+  (measured 千问-vs-doubao AUC ~0.5) -- moves to metadata, where it is reliable.
+
+WHY IT IS WORTH RETRYING NOW
+  `render_vendor_silhouettes.py` records 千问 as ruled out, and its reasoning was sound:
+  the then-current front-end binarized the glyph, and a thin translucent overlay shatters
+  into specks that no template can match. It closes by naming what would be needed --
+  "a detection front-end that does not depend on binarizing the glyph (grayscale/edge
+  correlation on the raw top-hat)". That front-end now EXISTS: `detect_frontend="tophat"`
+  was built for doubao and correlates a soft template against the continuous response.
+  The blocker was removed by unrelated work, so the ruling deserves re-measurement rather
+  than inheritance.
+
+THE MEASUREMENT
+  Three arms, one scorer (the tail template on the tophat response, swept over a dense
+  size ladder because an unregistered vendor's glyph size is genuinely unknown -- the one
+  place a dense ladder earns its cost):
+
+    covered    a registered mark already fires -- a sanity arm; the tail is inside those
+               marks too, so a tail template that cannot score THESE is simply broken
+    uncovered  TC260 provenance but no detector fires -- the target population
+    clean      no metadata signal at all -- the precision arm
+
+  The decision rests on whether `uncovered` carries a high-scoring subpopulation that
+  `clean` does not. It does NOT rest on the raw rate: TC260 provenance does not imply a
+  visible mark, so a modest fire rate on that arm is expected even if the detector is
+  perfect. Any threshold this suggests must then be confirmed by eyeballing the crops it
+  selects -- the script writes a contact sheet for exactly that.
+
+DATA SAFETY
+  Corpus images are user uploads: read-only, local analysis, gitignored output. The
+  template is font-rendered synthetic, never cut from a user upload.
+
+    uv run python scripts/cjk_tail_probe.py --n 6000
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import random
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent))
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS = REPO / "data" / "spaces" / "originals"
+OUT = REPO / "data" / "spaces" / "_cjk_tail_probe.jsonl"
+# Cached under the gitignored data dir, not in scripts/: this is a probe artifact, not a
+# product asset. If the tail mark is ever registered, `render_vendor_silhouettes.py` is
+# what writes the committed silhouette into src/.../assets/.
+TAIL_PNG = REPO / "data" / "spaces" / "_cjk_tail_silhouette.png"
+
+# The tail is a fraction of a full vendor mark's width (`豆包AI生成` is ~5 CJK widths,
+# `AI生成` ~3), and the prefix length differs per vendor, so the size is genuinely
+# unknown here -- unlike a registered mark, whose fraction is calibrated. Hence a wide,
+# dense ladder: this is the case a dense ladder is actually for.
+TAIL_SCALES = tuple(round(0.30 * (1.08**i), 4) for i in range(18))  # ~0.30 .. ~1.15
+
+
+def build_tail_silhouette() -> np.ndarray:
+    """Font-rendered `AI生成` silhouette, cached next to this script (data-safe)."""
+    if TAIL_PNG.exists():
+        img = cv2.imread(str(TAIL_PNG), cv2.IMREAD_GRAYSCALE)
+        if img is not None:
+            return img
+    from render_vendor_silhouettes import render
+
+    sil = render("AI生成", width=200)
+    cv2.imwrite(str(TAIL_PNG), sil)
+    return sil
+
+
+def tail_score(engine: Any, image: np.ndarray, sil: np.ndarray) -> tuple[float, float]:
+    """Best tail correlation over the size ladder; returns (score, winning_scale)."""
+    loc = engine.locate(image)
+    resp = engine.tophat_response(image, loc)
+    if resp is None:
+        return (0.0, 0.0)
+    c = engine.config
+    base = engine.scale_base(image)
+    ar = sil.shape[0] / max(1, sil.shape[1])
+    best, best_s = 0.0, 0.0
+    for s in TAIL_SCALES:
+        gw = max(12, int(c.alpha_width_frac * base * s))
+        gh = max(6, int(gw * ar))
+        if gw >= resp.shape[1] or gh >= resp.shape[0]:
+            continue
+        t = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
+        v = float(cv2.matchTemplate(resp, t, cv2.TM_CCOEFF_NORMED).max())
+        if v > best:
+            best, best_s = v, s
+    return (best, best_s)
+
+
+def _one(path_str: str) -> dict[str, Any] | None:
+    from remove_ai_watermarks.api import visible_provenance
+    from remove_ai_watermarks.doubao_engine import DoubaoEngine
+    from remove_ai_watermarks.identify import identify
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.watermark_registry import detect_marks
+
+    path = Path(path_str)
+    try:
+        prov = visible_provenance(path)
+    except Exception:
+        return None
+    tc260 = bool({"doubao", "jimeng"} & prov)
+
+    if not tc260:
+        try:
+            if identify(path, check_visible=False).signals:
+                return None  # some other provenance: neither target nor clean control
+        except Exception:
+            return None
+
+    img = imread(path_str)
+    if img is None or min(img.shape[:2]) < 200:
+        return None
+    try:
+        fired = [d.key for d in detect_marks(img) if d.detected]
+    except Exception:
+        return None
+
+    if fired:
+        arm = "covered"
+    elif tc260:
+        arm = "uncovered"
+    else:
+        arm = "clean"
+
+    score, scale = tail_score(DoubaoEngine(), img, build_tail_silhouette())
+    return {
+        "src": path.name,
+        "arm": arm,
+        "fired": fired,
+        "tail_score": round(score, 4),
+        "tail_scale": scale,
+    }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=6000)
+    ap.add_argument("--workers", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--report-only", action="store_true")
+    ap.add_argument(
+        "--sheet-at", type=float, default=0.0, help="write a contact sheet of `uncovered` crops scoring >= this"
+    )
+    a = ap.parse_args()
+
+    if a.report_only:
+        rows = [json.loads(x) for x in a.out.read_text(encoding="utf-8").splitlines() if x.strip()]
+        report(rows)
+        if a.sheet_at:
+            contact_sheet(rows, a.sheet_at)
+        return
+
+    build_tail_silhouette()
+    pool = glob.glob(str(CORPUS / "*" / "*"))
+    random.Random(19).shuffle(pool)  # noqa: S311 -- deterministic sampling, not crypto
+    pool = pool[: a.n]
+    print(f"scanning {len(pool)} corpus files  workers={a.workers}")
+    print(f"tail ladder {TAIL_SCALES[0]} .. {TAIL_SCALES[-1]} ({len(TAIL_SCALES)} rungs)\n", flush=True)
+
+    rows: list[dict[str, Any]] = []
+    a.out.parent.mkdir(parents=True, exist_ok=True)
+    with open(a.out, "w", encoding="utf-8") as fh, ProcessPoolExecutor(max_workers=a.workers) as ex:
+        futures = [ex.submit(_one, p) for p in pool]
+        for i, fut in enumerate(as_completed(futures), 1):
+            try:
+                rec = fut.result()
+            except Exception:  # noqa: S112 -- one bad file must not kill the sweep
+                continue
+            if rec is None:
+                continue
+            fh.write(json.dumps(rec) + "\n")
+            rows.append(rec)
+            if i % 500 == 0:
+                fh.flush()
+                print(f"  {i}/{len(pool)}  usable={len(rows)}", flush=True)
+    report(rows)
+    if a.sheet_at:
+        contact_sheet(rows, a.sheet_at)
+
+
+def report(rows: list[dict[str, Any]]) -> None:
+    arms = {k: [r for r in rows if r["arm"] == k] for k in ("covered", "uncovered", "clean")}
+    print(f"\n{'=' * 80}\nGENERIC CJK TAIL PROBE  ({', '.join(f'{k}={len(v)}' for k, v in arms.items())})\n{'=' * 80}")
+    print("\nScore distribution of the shared `AI生成` tail on the tophat response\n")
+    print(f"{'arm':11s} {'n':>6s} {'p50':>7s} {'p75':>7s} {'p90':>7s} {'p95':>7s} {'p99':>7s} {'max':>7s}")
+    for k, v in arms.items():
+        if not v:
+            continue
+        s = np.array([r["tail_score"] for r in v])
+        qs = [np.percentile(s, q) for q in (50, 75, 90, 95, 99)]
+        print(f"{k:11s} {len(v):6d} " + " ".join(f"{q:7.3f}" for q in qs) + f" {s.max():7.3f}")
+
+    if arms["clean"] and arms["uncovered"]:
+        clean = np.array([r["tail_score"] for r in arms["clean"]])
+        unc = np.array([r["tail_score"] for r in arms["uncovered"]])
+        print("\n\nOPERATING POINTS -- threshold set on the CLEAN arm, yield read on `uncovered`")
+        print("`clean` fires are the cost; `uncovered` fires are candidate recoveries that")
+        print("still need eyeballing, since TC260 provenance does not imply a visible mark.\n")
+        print(f"{'threshold':>10s} {'clean fire':>12s} {'uncovered fire':>16s} {'candidates':>12s}")
+        for q in (95, 97.5, 99, 99.5, 99.9):
+            t = float(np.percentile(clean, q))
+            cf = float((clean >= t).mean())
+            uf = float((unc >= t).mean())
+            print(f"{t:10.3f} {100 * cf:11.2f}% {100 * uf:15.1f}% {int((unc >= t).sum()):12d}")
+
+    cov = arms["covered"]
+    if cov:
+        s = np.array([r["tail_score"] for r in cov])
+        print(f"\n\nSANITY: on frames where a registered mark fires, the tail scores median {np.median(s):.3f}.")
+        print("A tail template that cannot score these is broken, whatever it does elsewhere.")
+
+
+def contact_sheet(rows: list[dict[str, Any]], thresh: float, limit: int = 30) -> None:
+    """Crop the corner of the top-scoring `uncovered` frames so the fires can be judged."""
+    from remove_ai_watermarks.doubao_engine import DoubaoEngine
+    from remove_ai_watermarks.image_io import imread
+
+    eng = DoubaoEngine()
+    picks = sorted(
+        (r for r in rows if r["arm"] == "uncovered" and r["tail_score"] >= thresh),
+        key=lambda r: -r["tail_score"],
+    )[:limit]
+    tiles = []
+    for r in picks:
+        hits = glob.glob(str(CORPUS / "*" / r["src"]))
+        if not hits:
+            continue
+        img = imread(hits[0])
+        if img is None:
+            continue
+        loc = eng.locate(img)
+        crop = img[loc.y : loc.y + loc.h, loc.x : loc.x + loc.w]
+        if crop.size:
+            tiles.append(cv2.resize(crop, (320, 96), interpolation=cv2.INTER_AREA))
+    if tiles:
+        dest = REPO / "data" / "spaces" / "_cjk_tail_sheet.png"
+        cv2.imwrite(str(dest), np.vstack(tiles))
+        print(f"\ncontact sheet ({len(tiles)} crops, score >= {thresh:.3f}) -> {dest}")
+        print("scores: " + ", ".join(f"{r['tail_score']:.2f}" for r in picks[: len(tiles)]))
+
+
+if __name__ == "__main__":
+    main()

scripts/detector_response.py

@@ -0,0 +1,319 @@
+"""Tier B2: detector response curves -- recall vs mark size, contrast, background and aspect.
+
+WHY THIS EXISTS
+  Every recall number the project quotes rests on found positives: doubao 89% on n=240,
+  jimeng 71% on n=14, the pill 50% on n=6. Those tell you how the detectors do on the
+  marks a corpus happened to contain, and nothing about WHERE they fall over. Two bugs
+  have now shipped in exactly that blind spot:
+
+    * `scale_basis` -- doubao detected 0 of 435 LANDSCAPE marks, a 100% miss, because
+      every fraction was calibrated on portrait captures where width == short side.
+    * the front-end mismatch -- detection moved to the continuous `tophat` response while
+      the removal mask still came from the BINARIZED blob, so ~8% of doubao detections
+      produced an empty mask and removal was a silent no-op.
+
+  Both are geometry/plumbing failures at the edge of the operating range, and both were
+  invisible to a corpus sweep because the corpus is concentrated in the middle of it.
+  This harness constructs the edges instead of waiting for them to turn up.
+
+THE AGGREGATE HERE IS NOT RECALL
+  The grid deliberately visits sizes and opacities the engines were never calibrated for,
+  so a mark counted as missed at size=0.6 is not evidence of a weak detector -- it is the
+  point of the sweep. Quote the NOMINAL cell (size=1.0, alpha=1.0) as the reference, and
+  read the per-axis tables for shape. Production recall comes from an unbiased corpus
+  sample (`scripts/visible_recall_sample.py`), never from here.
+
+WHAT IT MEASURES -- TWO NUMBERS, NOT ONE
+  `detected`  the detector fires.
+  `maskable`  the same call path then yields a NON-EMPTY removal mask.
+
+  The second is the one that has no natural home anywhere else. A mark that is detected
+  but not maskable is reported by `identify` and silently skipped by `visible` -- the user
+  sees a mark the tool says it removed. Anything that measures only detection scores that
+  bug as a success. They are reported side by side and their GAP is the headline.
+
+THE CONSTRUCTION
+  Take a verified-clean corpus image, stamp a real mark onto it with the forward model the
+  reverse-alpha work established (`stamped = (1-a)*bg + a*white`), and sweep two knobs the
+  engine's own geometry normally pins:
+
+    size    multiplies the glyph box the engine would use (a re-rendered or rescaled mark)
+    alpha   multiplies the captured opacity (bold stamp -> faint translucent overlay)
+
+  Background texture and frame aspect are not swept -- they come from the corpus and are
+  recorded, so the grid is crossed with real backgrounds rather than synthetic flats.
+
+WHY EVERY SOURCE ALSO RUNS UNSTAMPED
+  A recall curve with no false-fire baseline is uninterpretable in the same way a fill
+  PSNR with no damage baseline is: "detected on 70% of faint marks" is a triumph or a
+  scandal depending on whether the detector also fires on 70% of the clean frames those
+  marks were stamped onto. The control runs the identical call path on the identical
+  image with no stamp.
+
+READING `mask_hit`
+  Fraction of the stamped glyph box the removal mask covers -- real localization accuracy
+  for the text marks and gemini, because the mask has to be placed from a detection.
+  For `jimeng_pill` it is CONSTRUCTED and means nothing: the pill's footprint is a fixed
+  top-left geometry box, so it covers the stamp by definition. Reported, and flagged.
+
+DATA SAFETY
+  Corpus images are user uploads: read-only, local analysis, gitignored output under
+  data/spaces/. Records source filenames and measurements, never image content.
+
+    uv run python scripts/detector_response.py --n 12          # trial, measures throughput
+    uv run python scripts/detector_response.py --n 150         # the real run, resumable
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import math
+import os
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent))
+
+from fill_quality import SLOT_STAMPABLE, STAMPABLE, clean_sources, stamp_any, texture_of
+
+REPO = Path(__file__).resolve().parents[1]
+OUT = REPO / "data" / "spaces" / "_detector_response.jsonl"
+
+# 1.0 = the geometry/opacity the engine's own constants assume. The sweep reaches below
+# it (a mark rendered smaller, or a faint translucent overlay -- the class the tophat
+# front-end was introduced for) and above it (a larger re-render, or an upscaled upload).
+SIZES = (0.6, 0.8, 1.0, 1.3)
+ALPHAS = (0.3, 0.5, 0.75, 1.0)
+MARKS = (*STAMPABLE, *SLOT_STAMPABLE)
+
+
+def aspect_of(image: np.ndarray) -> str:
+    h, w = image.shape[:2]
+    r = w / max(1, h)
+    return "portrait" if r < 0.9 else ("landscape" if r > 1.1 else "square")
+
+
+def _probe(image: np.ndarray, mark_key: str, box: tuple[int, int, int, int] | None) -> dict[str, Any]:
+    """Run the product detect -> localize path once and score it.
+
+    ``box`` is the stamped glyph box, or None for the unstamped control.
+    """
+    from remove_ai_watermarks.watermark_registry import get_mark
+
+    mark = get_mark(mark_key)
+    loc = mark.localize(image, force=False)
+    mask_px = 0 if loc.mask is None else int(np.count_nonzero(loc.mask))
+    hit = None
+    if box is not None and loc.mask is not None:
+        x, y, w, h = box
+        inside = loc.mask[y : y + h, x : x + w]
+        hit = round(float(np.count_nonzero(inside)) / max(1, w * h), 3)
+    return {
+        "detected": bool(loc.detected),
+        "confidence": round(float(loc.confidence), 4),
+        "maskable": mask_px > 0,
+        "mask_px": mask_px,
+        "mask_hit": hit,
+    }
+
+
+def _one_source(path_str: str) -> list[dict[str, Any]]:
+    """Every (mark, size, alpha) cell for one clean background, plus its controls."""
+    from remove_ai_watermarks.image_io import imread
+
+    base = imread(path_str)
+    if base is None:
+        return []
+    name = Path(path_str).name
+    asp = aspect_of(base)
+    h, w = base.shape[:2]
+    rows: list[dict[str, Any]] = []
+
+    for key in MARKS:
+        common = {"src": name, "mark": key, "aspect": asp, "px": w * h}
+        # Control first: the same call path on the same frame with nothing stamped.
+        rows.append({**common, "cell": "control", "size": None, "alpha": None, **_probe(base, key, None)})
+        for size in SIZES:
+            for alpha in ALPHAS:
+                st = stamp_any(base, key, size_mult=size, alpha_mult=alpha)
+                if st is None:
+                    continue
+                stamped, box = st
+                # Texture of the region the mark sits on, from the CLEAN frame -- the
+                # same median-Sobel proxy the pill's flatness gate uses.
+                x, y, gw, gh = box
+                rows.append(
+                    {
+                        **common,
+                        "cell": "stamped",
+                        "size": size,
+                        "alpha": alpha,
+                        "texture": round(texture_of(base[y : y + gh, x : x + gw]), 2),
+                        **_probe(stamped, key, box),
+                    }
+                )
+    return rows
+
+
+def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    if n == 0:
+        return (0.0, 0.0)
+    p, d = k / n, 1 + z * z / n
+    c = (p + z * z / (2 * n)) / d
+    hw = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
+    return (100 * (c - hw), 100 * (c + hw))
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=150, help="verified-clean source images")
+    ap.add_argument("--workers", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--restart", action="store_true")
+    ap.add_argument("--report-only", action="store_true", help="re-read --out and print the report")
+    a = ap.parse_args()
+
+    if a.report_only:
+        rows = [json.loads(line) for line in a.out.read_text(encoding="utf-8").splitlines() if line.strip()]
+        report(rows)
+        return
+
+    if a.restart and a.out.exists():
+        a.out.unlink()
+    done: set[str] = set()
+    if a.out.exists():
+        with open(a.out, encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    done.add(json.loads(line)["src"])
+                except Exception:  # noqa: S112 -- tolerate a torn last line
+                    continue
+
+    print(f"selecting {a.n} verified-clean sources (already measured: {len(done)})...", flush=True)
+    sources = [p for p in clean_sources(a.n) if p.name not in done]
+    print(f"to do {len(sources)}  workers {a.workers}  grid {len(MARKS)}x{len(SIZES)}x{len(ALPHAS)}\n", flush=True)
+
+    rows: list[dict[str, Any]] = []
+    a.out.parent.mkdir(parents=True, exist_ok=True)
+    with open(a.out, "a", encoding="utf-8") as fh, ProcessPoolExecutor(max_workers=a.workers) as ex:
+        futures = {ex.submit(_one_source, str(p)): p for p in sources}
+        for i, fut in enumerate(as_completed(futures), 1):
+            try:
+                got = fut.result()
+            except Exception as e:  # a crashed source must not kill the sweep
+                print(f"  source failed: {type(e).__name__}: {e}", flush=True)
+                continue
+            for r in got:
+                fh.write(json.dumps(r) + "\n")
+            rows += got
+            if i % 10 == 0:
+                fh.flush()
+                print(f"  {i}/{len(sources)}", flush=True)
+
+    if done:  # merge the resumed rows so the report covers the whole file
+        rows = [json.loads(line) for line in a.out.read_text(encoding="utf-8").splitlines() if line.strip()]
+    report(rows)
+
+
+def _rate(rs: list[dict[str, Any]], field: str) -> tuple[float, float, float, int]:
+    k, n = sum(bool(r[field]) for r in rs), len(rs)
+    lo, hi = wilson(k, n)
+    return (100 * k / n if n else 0.0, lo, hi, n)
+
+
+def report(rows: list[dict[str, Any]]) -> None:
+    stamped = [r for r in rows if r["cell"] == "stamped"]
+    control = [r for r in rows if r["cell"] == "control"]
+    if not stamped:
+        print("no measurements")
+        return
+    srcs = len({r["src"] for r in rows})
+    print(f"\n{'=' * 84}\nDETECTOR RESPONSE  {len(stamped)} stamped cells over {srcs} clean backgrounds\n{'=' * 84}")
+
+    # Lead with the nominal cell. The grid deliberately includes sizes and opacities the
+    # engines were never calibrated for, so an aggregate over the whole grid is an
+    # adversarial score, NOT production recall -- quoting it as recall would understate
+    # the detectors badly. The nominal cell is the honest reference point: the mark at the
+    # exact geometry and opacity the engine assumes, on a real clean background.
+    print("\nNOMINAL CELL (size=1.0, alpha=1.0) -- a mark exactly as the engine expects it.")
+    print("Read every other number against THIS, not as production recall: the grid is")
+    print("adversarial by design and its aggregate is not a recall figure.\n")
+    print(f"{'mark':13s} {'n':>5s} {'detected':>10s} {'maskable':>10s}")
+    for key in MARKS:
+        rs = [r for r in stamped if r["mark"] == key and r["size"] == 1.0 and r["alpha"] == 1.0]
+        if rs:
+            print(f"{key:13s} {len(rs):5d} {_rate(rs, 'detected')[0]:9.1f}% {_rate(rs, 'maskable')[0]:9.1f}%")
+
+    print("\n\nFALSE FIRE on the unstamped controls (the baseline every recall below is read against)\n")
+    print(f"{'mark':13s} {'n':>5s} {'fires':>8s} {'95% CI':>16s}")
+    for key in MARKS:
+        rs = [r for r in control if r["mark"] == key]
+        if rs:
+            pct, lo, hi, n = _rate(rs, "detected")
+            print(f"{key:13s} {n:5d} {pct:7.1f}% {f'{lo:.1f}-{hi:.1f}':>16s}")
+
+    print("\n\nDETECTED vs MASKABLE by mark. The GAP is the silent-no-op rate:")
+    print("a mark counted here as detected-but-not-maskable is reported by `identify` and")
+    print("skipped by `visible`, so the user is told it was removed when it was not.\n")
+    print(f"{'mark':13s} {'n':>6s} {'detected':>10s} {'maskable':>10s} {'gap':>7s} {'mask_hit':>9s}")
+    for key in MARKS:
+        rs = [r for r in stamped if r["mark"] == key]
+        if not rs:
+            continue
+        det = [r for r in rs if r["detected"]]
+        d, m = _rate(rs, "detected")[0], _rate(rs, "maskable")[0]
+        gap = (100 * sum(1 for r in det if not r["maskable"]) / len(det)) if det else 0.0
+        hits = [r["mask_hit"] for r in det if r["mask_hit"] is not None]
+        note = "  (constructed)" if key == "jimeng_pill" else ""
+        hv = f"{float(np.median(hits)):.2f}" if hits else "-"
+        print(f"{key:13s} {len(rs):6d} {d:9.1f}% {m:9.1f}% {gap:6.1f}% {hv:>9s}{note}")
+
+    for axis, label in (("alpha", "CONTRAST (alpha multiplier)"), ("size", "SIZE (glyph box multiplier)")):
+        print(f"\n\nRECALL BY {label}  -- 1.0 is the geometry/opacity the engine assumes\n")
+        vals = sorted({r[axis] for r in stamped})
+        print(f"{'mark':13s}" + "".join(f"{v:>12}" for v in vals))
+        for key in MARKS:
+            cells = []
+            for v in vals:
+                rs = [r for r in stamped if r["mark"] == key and r[axis] == v]
+                cells.append(f"{_rate(rs, 'detected')[0]:10.0f}%" if rs else f"{'-':>11s}")
+            print(f"{key:13s}" + "".join(f"{c:>12}" for c in cells))
+
+    print("\n\nRECALL BY FRAME ASPECT  -- the axis the `scale_basis` bug lived on\n")
+    asps = ["portrait", "square", "landscape"]
+    print(f"{'mark':13s}" + "".join(f"{x:>14s}" for x in asps))
+    for key in MARKS:
+        cells = []
+        for asp in asps:
+            rs = [r for r in stamped if r["mark"] == key and r["aspect"] == asp]
+            cells.append(f"{_rate(rs, 'detected')[0]:.0f}% (n={len(rs)})" if rs else "-")
+        print(f"{key:13s}" + "".join(f"{c:>14s}" for c in cells))
+
+    tex = sorted(r["texture"] for r in stamped if "texture" in r)
+    if tex:
+        t1, t2 = tex[len(tex) // 3], tex[2 * len(tex) // 3]
+        print(f"\n\nRECALL BY BACKGROUND TEXTURE  (terciles at {t1:.1f} / {t2:.1f} median-Sobel)\n")
+        print(f"{'mark':13s}" + "".join(f"{x:>14s}" for x in ("flat", "mid", "textured")))
+        for key in MARKS:
+            cells = []
+            for lo, hi in ((-1, t1), (t1, t2), (t2, 1e9)):
+                rs = [r for r in stamped if r["mark"] == key and lo < r.get("texture", -2) <= hi]
+                cells.append(f"{_rate(rs, 'detected')[0]:.0f}% (n={len(rs)})" if rs else "-")
+            print(f"{key:13s}" + "".join(f"{c:>14s}" for c in cells))
+
+    worst = collections.Counter((r["mark"], r["size"], r["alpha"]) for r in stamped if not r["detected"]).most_common(8)
+    if worst:
+        print("\n\nWORST CELLS (most misses)\n")
+        for (mark, size, alpha), n in worst:
+            print(f"  {mark:13s} size={size}  alpha={alpha}   {n} misses")
+
+
+if __name__ == "__main__":
+    main()

scripts/fill_quality.py

@@ -0,0 +1,345 @@
+"""Tier B1: measure visible-mark FILL quality against a constructed ground truth.
+
+THE PROBLEM THIS SOLVES
+  A real watermarked image has no clean counterpart, so fill quality has only ever been
+  eyeballed ("cv2 smears on texture, LaMa is best") and never carried a number. The docs
+  state a preference order for `--backend auto` that rests on no measurement.
+
+THE CONSTRUCTION
+  Take a VERIFIED-CLEAN corpus image, stamp a known mark onto it using the mark's own
+  captured alpha map (the forward model the reverse-alpha work established:
+  `stamped = (1-a)*bg + a*white`), then remove it and compare against the TRUE original.
+  The original is the answer key that reality never provides.
+
+TWO MEASUREMENT DECISIONS THAT MAKE OR BREAK THIS
+  * Score INSIDE the footprint only. The fill touches a tiny corner, so whole-frame PSNR
+    sits near 60 dB whatever the backend does and would rank them all "excellent".
+  * Report the DAMAGE baseline (stamped vs original) next to the recovery (filled vs
+    original). Without it a PSNR is uninterpretable: 30 dB is a triumph if the mark cost
+    12 dB and a failure if it cost 29 dB. The honest metric is how much of the gap the
+    fill closes.
+
+WHAT IT DOES NOT MEASURE
+  Detection. The mark is localized with `force=True`, so a miss cannot contaminate the
+  fill numbers -- this isolates the FILL. Detection accuracy is Tier C's job.
+
+DATA SAFETY
+  Corpus images are user uploads: read-only, local analysis, output under a gitignored
+  data/spaces/ path. No image content is written into the report.
+
+    uv run python scripts/fill_quality.py --n 60
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import glob
+import json
+import random
+import sys
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent))
+
+from invisible_quality_audit import _ssim  # reuse, do not reimplement a third SSIM
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS = REPO / "data" / "spaces" / "originals"
+OUT = REPO / "data" / "spaces" / "_fill_quality.jsonl"
+
+# Text marks: a bundled alpha PNG plus the engine's own corner geometry.
+STAMPABLE = ("doubao", "jimeng", "samsung")
+# Marks with no bundled alpha asset. Both expose a default footprint via
+# `footprint_mask(force=True)`, so they are stamped by fitting their own alpha source
+# into that slot: Gemini's alpha is derived from its background captures, the pill's
+# from its synthetic font-rendered silhouette.
+SLOT_STAMPABLE = ("gemini", "jimeng_pill")
+
+
+def psnr(a: np.ndarray, b: np.ndarray) -> float:
+    mse = float(np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2))
+    return float("inf") if mse == 0 else 10 * float(np.log10(255.0**2 / mse))
+
+
+def texture_of(box: np.ndarray) -> float:
+    """Median Sobel magnitude -- the same texture proxy the pill's flatness gate uses."""
+    g = cv2.cvtColor(box, cv2.COLOR_BGR2GRAY) if box.ndim == 3 else box
+    gx = cv2.Sobel(g, cv2.CV_32F, 1, 0, ksize=3)
+    gy = cv2.Sobel(g, cv2.CV_32F, 0, 1, ksize=3)
+    return float(np.median(cv2.magnitude(gx, gy)))
+
+
+def engine_for(mark_key: str) -> Any:
+    """The TextMarkEngine instance for a mark key (the registry does not expose one)."""
+    import importlib
+
+    mod = importlib.import_module(f"remove_ai_watermarks.{mark_key}_engine")
+    cls = next(
+        obj
+        for name, obj in vars(mod).items()
+        # Exclude the imported base class: it takes a `config` arg, the subclasses do not.
+        if isinstance(obj, type) and name.endswith("Engine") and name != "TextMarkEngine"
+    )
+    return cls()
+
+
+def composite(image: np.ndarray, alpha: np.ndarray, x: int, y: int) -> np.ndarray:
+    """The single forward model every stamp uses: ``stamped = (1-a)*bg + a*white``.
+
+    ``alpha`` is float and clipped to [0,1] here, so a caller may pre-multiply it by an
+    opacity factor without worrying about overflow. Shared by ``stamp``/``stamp_slot``
+    here and by ``scripts/detector_response.py`` (which imports it) so the model is
+    written ONCE.
+    """
+    gh, gw = alpha.shape[:2]
+    out = image.copy()
+    roi = out[y : y + gh, x : x + gw].astype(np.float32)
+    a3 = np.clip(alpha, 0.0, 1.0)[..., None]
+    out[y : y + gh, x : x + gw] = np.clip(roi * (1 - a3) + 255.0 * a3, 0, 255).astype(np.uint8)
+    return out
+
+
+def stamp(
+    image: np.ndarray, mark_key: str, *, size_mult: float = 1.0, alpha_mult: float = 1.0
+) -> tuple[np.ndarray, tuple[int, int, int, int]] | None:
+    """Composite a mark's alpha glyph into its canonical corner. Returns (stamped, bbox).
+
+    ``size_mult`` scales the glyph box off the engine's nominal geometry and ``alpha_mult``
+    its opacity -- both default to 1.0 (the geometry the engine assumes), and
+    `scripts/detector_response.py` sweeps them to build response curves.
+    """
+    from remove_ai_watermarks._text_mark_engine import load_alpha_template
+
+    engine = engine_for(mark_key)
+    cfg = engine.config
+    alpha = load_alpha_template(cfg.asset_name)
+    if alpha is None:
+        return None
+
+    loc = engine.locate(image)
+    base = engine.scale_base(image)
+    gw = max(cfg.min_gw, int(cfg.alpha_width_frac * base * size_mult))
+    gh = max(4, int(cfg.alpha_height_frac * base * size_mult))
+    if gw < 8 or gh < 4 or gw > loc.w or gh > loc.h:
+        return None
+
+    a = cv2.resize(alpha, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32) * alpha_mult
+    x = loc.x + (loc.w - gw) // 2
+    y = loc.y + (loc.h - gh) // 2
+    return composite(image, a, x, y), (x, y, gw, gh)
+
+
+def _slot_alpha(mark_key: str) -> np.ndarray | None:
+    """The alpha source for a mark that ships no bundled alpha PNG."""
+    if mark_key == "gemini":
+        from remove_ai_watermarks.gemini_engine import _shared_engine
+
+        # _shared_engine is the package's own lru_cache singleton: constructing
+        # GeminiEngine() per image reloads its captures, recomputes both alpha maps and
+        # rebuilds the whole template ladder -- the exact cost that singleton exists to
+        # avoid. Private attribute access is deliberate (no accessor exists); a
+        # measurement script may reach in, product code must not.
+        return np.asarray(_shared_engine()._alpha_large, dtype=np.float32)
+    if mark_key == "jimeng_pill":
+        from remove_ai_watermarks._text_mark_engine import load_alpha_template
+
+        return load_alpha_template("jimeng_pill.png")
+    return None
+
+
+def stamp_slot(
+    image: np.ndarray, mark_key: str, *, size_mult: float = 1.0, alpha_mult: float = 1.0
+) -> tuple[np.ndarray, tuple[int, int, int, int]] | None:
+    """Stamp a mark into its OWN default footprint slot (the `--no-detect` geometry).
+
+    Used for gemini and the pill, which have no bundled alpha asset with corner
+    fractions. The mark is fitted into the middle of its slot so the fill has to
+    recover the same kind of region it would in production. ``size_mult``/``alpha_mult``
+    match ``stamp`` (both default to 1.0).
+    """
+    from remove_ai_watermarks.watermark_registry import get_mark
+
+    alpha = _slot_alpha(mark_key)
+    if alpha is None:
+        return None
+    loc = get_mark(mark_key).localize(image, force=True)
+    if loc.mask is None:
+        return None
+    ys, xs = np.nonzero(loc.mask)
+    if ys.size == 0:
+        return None
+    y0, y1, x0, x1 = int(ys.min()), int(ys.max()), int(xs.min()), int(xs.max())
+    bw, bh = x1 - x0 + 1, y1 - y0 + 1
+    gw, gh = max(8, int(bw * 0.7 * size_mult)), max(8, int(bh * 0.7 * size_mult))
+    a = cv2.resize(alpha, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32) * alpha_mult
+    x, y = x0 + (bw - gw) // 2, y0 + (bh - gh) // 2
+    # A large size_mult can grow the glyph past its slot and push x/y negative; guard so
+    # composite never writes out of bounds (numpy would wrap a negative index silently).
+    if x < 0 or y < 0 or x + gw > image.shape[1] or y + gh > image.shape[0]:
+        return None
+    return composite(image, a, x, y), (x, y, gw, gh)
+
+
+def stamp_any(
+    image: np.ndarray, mark_key: str, *, size_mult: float = 1.0, alpha_mult: float = 1.0
+) -> tuple[np.ndarray, tuple[int, int, int, int]] | None:
+    fn = stamp if mark_key in STAMPABLE else stamp_slot
+    return fn(image, mark_key, size_mult=size_mult, alpha_mult=alpha_mult)
+
+
+def clean_sources(n: int, seed: int = 11) -> list[Path]:
+    """Corpus images with NO metadata signal and NO mark detection -- verified clean."""
+    from remove_ai_watermarks.identify import identify
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.watermark_registry import detect_marks
+
+    pool = glob.glob(str(CORPUS / "*" / "*"))
+    random.Random(seed).shuffle(pool)  # noqa: S311 -- deterministic sampling, not crypto
+    out: list[Path] = []
+    for p in pool:
+        if len(out) >= n:
+            break
+        path = Path(p)
+        try:
+            img = imread(str(path))
+            if img is None or min(img.shape[:2]) < 400:
+                continue
+            # check_visible=False: identify would otherwise decode the file a second
+            # time and run the very same visible detectors as detect_marks below.
+            if identify(path, check_visible=False).signals:
+                continue
+            if any(d.detected for d in detect_marks(img)):
+                continue
+        except Exception:  # noqa: S112 -- a bad corpus file just is not a candidate
+            continue
+        out.append(path)
+    return out
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=60, help="clean source images")
+    ap.add_argument("--out", type=Path, default=OUT)
+    a = ap.parse_args()
+
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.region_eraser import lama_available, migan_available
+    from remove_ai_watermarks.watermark_registry import fill, get_mark
+
+    backends = ["cv2"] + (["migan"] if migan_available() else []) + (["lama"] if lama_available() else [])
+    print(f"backends under test: {backends}")
+    print(f"selecting {a.n} verified-clean sources...", flush=True)
+    sources = clean_sources(a.n)
+    print(f"got {len(sources)}\n", flush=True)
+
+    rows: list[dict[str, Any]] = []
+    with open(a.out, "w", encoding="utf-8") as fh:
+        for i, src in enumerate(sources, 1):
+            base = imread(str(src))
+            if base is None:
+                continue
+            for key in (*STAMPABLE, *SLOT_STAMPABLE):
+                st = stamp_any(base, key)
+                if st is None:
+                    continue
+                stamped, (x, y, w, h) = st
+                # Score a slightly padded box: the fill dilates, so a tight glyph box
+                # would miss damage the backend does just outside the glyph.
+                pad = 8
+                y0, y1 = max(0, y - pad), min(base.shape[0], y + h + pad)
+                x0, x1 = max(0, x - pad), min(base.shape[1], x + w + pad)
+                truth = base[y0:y1, x0:x1]
+                dmg_psnr = psnr(stamped[y0:y1, x0:x1], truth)
+                dmg_ssim = _ssim(
+                    cv2.cvtColor(stamped[y0:y1, x0:x1], cv2.COLOR_BGR2GRAY), cv2.cvtColor(truth, cv2.COLOR_BGR2GRAY)
+                )
+                tex = texture_of(truth)
+
+                mark = get_mark(key)
+                loc = mark.localize(stamped, force=True)
+                if loc.mask is None:
+                    continue
+                for backend in backends:
+                    try:
+                        filled = fill(stamped, loc.mask, backend=backend)
+                    except Exception as e:
+                        rows.append({"src": src.name, "mark": key, "backend": backend, "error": str(e)[:150]})
+                        continue
+                    # Invariant: the fill must not touch anything outside its mask.
+                    outside = loc.mask == 0
+                    untouched = bool(np.array_equal(filled[outside], stamped[outside]))
+                    rec = {
+                        "src": src.name,
+                        "mark": key,
+                        "backend": backend,
+                        "texture": round(tex, 2),
+                        "damage_psnr": round(dmg_psnr, 2),
+                        "damage_ssim": round(dmg_ssim, 4),
+                        "filled_psnr": round(psnr(filled[y0:y1, x0:x1], truth), 2),
+                        "filled_ssim": round(
+                            _ssim(
+                                cv2.cvtColor(filled[y0:y1, x0:x1], cv2.COLOR_BGR2GRAY),
+                                cv2.cvtColor(truth, cv2.COLOR_BGR2GRAY),
+                            ),
+                            4,
+                        ),
+                        "outside_mask_untouched": untouched,
+                    }
+                    rows.append(rec)
+                    fh.write(json.dumps(rec) + "\n")
+            if i % 10 == 0:
+                fh.flush()
+                print(f"  {i}/{len(sources)}", flush=True)
+
+    report(rows, a.out)
+
+
+def report(rows: list[dict[str, Any]], out: Path) -> None:
+    good = [r for r in rows if "error" not in r]
+    if not good:
+        print("no measurements")
+        return
+    tex = sorted(r["texture"] for r in good)
+    t1, t2 = tex[len(tex) // 3], tex[2 * len(tex) // 3]
+
+    def bucket(t: float) -> str:
+        return "flat" if t <= t1 else ("mid" if t <= t2 else "textured")
+
+    print(f"\n{'=' * 78}\nFILL QUALITY  n={len(good)} measurements  (texture terciles at {t1:.1f} / {t2:.1f})")
+    print(f"{'=' * 78}")
+    print("recovered = filled PSNR minus damaged PSNR; how much of the mark's damage the fill undoes\n")
+    hdr = f"{'mark':9s} {'backend':8s} {'bg':9s} {'n':>4s} {'damaged':>9s} {'filled':>9s}"
+    print(f"{hdr} {'recovered':>10s} {'ssim':>7s}")
+    agg: dict[tuple[str, str, str], list[dict[str, Any]]] = collections.defaultdict(list)
+    for r in good:
+        agg[(r["mark"], r["backend"], bucket(r["texture"]))].append(r)
+    for (mark, backend, bg), rs in sorted(agg.items()):
+        # MEDIAN, not mean: a fill that reproduces a flat background EXACTLY scores
+        # PSNR=inf, and a single inf makes the mean inf -- which reported "+inf" for
+        # every flat bucket on the first run and hid the real numbers.
+        finite = [r for r in rs if np.isfinite(r["filled_psnr"])]
+        perfect = len(rs) - len(finite)
+        d = float(np.median([r["damage_psnr"] for r in rs]))
+        f = float(np.median([r["filled_psnr"] for r in finite])) if finite else float("inf")
+        sv = float(np.median([r["filled_ssim"] for r in rs]))
+        # Recovery is the MEDIAN OF THE PER-IMAGE DIFFERENCES, not the difference of the
+        # two medians. Those are not the same statistic on skewed data and they can even
+        # disagree in SIGN: the first version of this report subtracted medians and
+        # produced a backend ranking that a paired comparison did not support.
+        rec = float(np.median([r["filled_psnr"] - r["damage_psnr"] for r in finite])) if finite else float("inf")
+        tail = f"  ({perfect} exact)" if perfect else ""
+        print(f"{mark:9s} {backend:8s} {bg:9s} {len(rs):4d} {d:9.2f} {f:9.2f} {rec:+10.2f} {sv:7.4f}{tail}")
+
+    bad = [r for r in good if not r["outside_mask_untouched"]]
+    print(f"\noutside-mask invariant violations: {len(bad)}" + (" <-- BUG" if bad else " (none)"))
+    print(f"records: {out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/ladder_headroom.py

@@ -0,0 +1,305 @@
+"""How much recall is the coarse scale ladder costing, and what would a denser one cost?
+
+THE FINDING THIS MEASURES
+  `_tophat_score` sweeps three rungs -- (0.8, 1.0, 1.25) -- and the `binary` front-end
+  sweeps none at all. Measured on stamped marks over controlled backgrounds
+  (`scripts/detector_response.py`), the response is a COMB: doubao scores 0.99 exactly at
+  each rung and collapses to 0.37-0.48 between them, against a 0.50 gate. So a mark whose
+  rendered size lands mid-gap is missed at FULL contrast. Jimeng (binary, one nominal
+  size) holds a single 0.90-1.20 lobe; samsung only 0.95-1.05.
+
+WHY A SYNTHETIC SWEEP IS NOT ENOUGH TO JUSTIFY A FIX
+  Dead zones only cost recall if real marks land in them. The fractions were calibrated on
+  real captures, so it is entirely possible that real marks cluster at ratio 1.0 and the
+  gaps are never visited. That question is not answerable by stamping -- it needs the
+  corpus.
+
+THE MEASUREMENT
+  Positives are images carrying INDEPENDENT vendor provenance (TC260 / C2PA metadata
+  naming the vendor), which is evidence that does not come from the pixel detector we are
+  grading -- the same discriminator that settled the pill gate. For every such image the
+  detector currently MISSES, rescore at a dense ladder and ask whether it would now cross
+  the gate, and at which scale.
+
+  Negatives are images with NO metadata signal at all. That is deliberately NOT "and no
+  mark was detected": defining the set by the detector's own verdict would make its
+  false-fire rate 0 by construction and the comparison vacuous. The cost is that a
+  metadata-stripped screenshot of a marked image sits in the negative set and its correct
+  detection is counted as a false fire -- but that impurity is identical under both
+  ladders, so the DELTA between them, which is what the fix is judged on, stays sound.
+
+  Two more impurities to keep in view when reading the positive arm. Provenance says the
+  vendor produced the file, not that a visible mark is on it. And the TC260 label names no
+  specific vendor, so `visible_provenance` maps it to BOTH doubao and jimeng -- a "doubao
+  positive" may carry a jimeng mark or none. Both inflate the miss count, so the recovery
+  percentage is an upper bound on what a denser ladder buys.
+
+DATA SAFETY
+  Corpus images are user uploads: read-only, local analysis, gitignored output.
+
+    uv run python scripts/ladder_headroom.py --mark doubao --n 4000
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import glob
+import json
+import math
+import os
+import random
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS = REPO / "data" / "spaces" / "originals"
+OUT = REPO / "data" / "spaces" / "_ladder_headroom.jsonl"
+
+# The rungs the product ships today, and the dense ladder under evaluation. The dense one
+# is geometric with a ~6% step, chosen from the measured half-width of a rung's lobe
+# (doubao holds >=0.5 for about +/-6% around each peak), so no gap is left uncovered.
+SHIPPED = (0.8, 1.0, 1.25)
+LADDERS: dict[str, tuple[float, ...]] = {
+    # A geometric ~6% step across the whole plausible range. Measures the CEILING of what
+    # any ladder change can buy, and the worst case of what it costs in false fires.
+    "dense": tuple(round(0.70 * (1.06**i), 4) for i in range(13)),  # 0.70 .. ~1.49
+    # The targeted alternative. On the full run, 26 of 28 recoveries came from ONE rung
+    # (~1.116) and 22 of 28 were LANDSCAPE frames -- that is a geometry gap, not a density
+    # gap, so the honest comparison is one extra rung against thirteen.
+    "plus_one": (0.8, 1.0, 1.1157, 1.25),
+    "shipped": SHIPPED,
+}
+DENSE = LADDERS["dense"]
+# Score every rung any candidate ladder might use and store them all, so a new candidate
+# is evaluated by re-reading the JSONL instead of re-running the hour-long sweep.
+PROBE_SCALES: tuple[float, ...] = tuple(sorted({s for rungs in LADDERS.values() for s in rungs}))
+
+
+def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    if n == 0:
+        return (0.0, 0.0)
+    p, d = k / n, 1 + z * z / n
+    c = (p + z * z / (2 * n)) / d
+    hw = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
+    return (100 * (c - hw), 100 * (c + hw))
+
+
+def score_at_scales(engine: Any, image: np.ndarray, scales: tuple[float, ...]) -> dict[float, float]:
+    """`_tophat_score`'s inner loop, opened up so the ladder is a parameter.
+
+    Deliberately reaches into the engine (`tophat_response`, `_glyph_silhouette`): a
+    measurement script may, product code may not. Kept a faithful copy of the shipped
+    scoring -- if it drifts, the numbers below stop describing the product.
+    """
+    c = engine.config
+    loc = engine.locate(image)
+    resp = engine.tophat_response(image, loc)
+    sil = engine._glyph_silhouette()
+    if resp is None or sil is None:
+        return {}
+    base = engine.scale_base(image)
+    out: dict[float, float] = {}
+    for scale in scales:
+        gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
+        gh = max(4, int(c.alpha_height_frac * base * scale))
+        if gw >= resp.shape[1] or gh >= resp.shape[0]:
+            continue
+        tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32)
+        if c.template_blur > 0:
+            tmpl = cv2.GaussianBlur(tmpl, (0, 0), sigmaX=c.template_blur, sigmaY=c.template_blur)
+        out[scale] = float(cv2.matchTemplate(resp, tmpl.astype(np.uint8), cv2.TM_CCOEFF_NORMED).max())
+    return out
+
+
+def _one(args: tuple[str, str]) -> dict[str, Any] | None:
+    path_str, mark_key = args
+    from remove_ai_watermarks.api import visible_provenance
+    from remove_ai_watermarks.identify import identify
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.watermark_registry import get_mark
+
+    path = Path(path_str)
+    try:
+        prov = visible_provenance(path)
+    except Exception:
+        return None
+    positive = mark_key in prov
+
+    if not positive:
+        # A negative is a frame with NO metadata signal at all -- evidence independent of
+        # the detector being graded. Do NOT also require that no mark was detected: that
+        # defines the negative set by the very verdict under test, and "false fire today"
+        # would then be 0 by construction on every run.
+        try:
+            if identify(path, check_visible=False).signals:
+                return None
+        except Exception:
+            return None
+
+    img = imread(path_str)
+    if img is None or min(img.shape[:2]) < 200:
+        return None
+
+    mark = get_mark(mark_key)
+    det = mark.detect(img)
+
+    import importlib
+
+    mod = importlib.import_module(f"remove_ai_watermarks.{mark_key}_engine")
+    cls = next(
+        o for n, o in vars(mod).items() if isinstance(o, type) and n.endswith("Engine") and n != "TextMarkEngine"
+    )
+    engine = cls()
+    scores = score_at_scales(engine, img, PROBE_SCALES)
+    if not scores:
+        return None
+    gate = engine.config.detect_ncc_threshold
+    dense = {s: v for s, v in scores.items() if s in LADDERS["dense"]}
+    best_scale = max(dense, key=lambda s: dense[s]) if dense else 0.0
+    h, w = img.shape[:2]
+    return {
+        "src": path.name,
+        "arm": "positive" if positive else "negative",
+        "detected_now": bool(det.detected),
+        "conf_now": round(float(det.confidence), 4),
+        "gate": gate,
+        # Every rung, so a new candidate ladder is evaluated by re-reading this file.
+        "scores": {str(s): round(v, 4) for s, v in scores.items()},
+        "dense_best": round(dense[best_scale], 4) if dense else 0.0,
+        "dense_best_scale": best_scale,
+        "dense_crosses": bool(dense) and dense[best_scale] >= gate,
+        "aspect": "portrait" if w / h < 0.9 else ("landscape" if w / h > 1.1 else "square"),
+    }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    # doubao only, and that is not laziness. `score_at_scales` reproduces the TOPHAT
+    # front-end, which is the only one with a ladder to widen; scoring it for jimeng or
+    # samsung would measure a code path their detectors never run. Doubao is also the one
+    # mark that declares NO rival, so crossing its NCC gate really is the whole verdict --
+    # for a mark with rivals, `dense_crosses` would ignore the competitive margin and read
+    # optimistically. Widening the binary front-end is a separate experiment.
+    ap.add_argument("--mark", default="doubao", choices=["doubao"])
+    ap.add_argument("--n", type=int, default=4000, help="corpus files to scan")
+    ap.add_argument("--workers", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--report-only", action="store_true")
+    a = ap.parse_args()
+
+    out = a.out.with_name(f"{a.out.stem}_{a.mark}{a.out.suffix}")
+    if a.report_only:
+        report([json.loads(x) for x in out.read_text(encoding="utf-8").splitlines() if x.strip()], a.mark)
+        return
+
+    pool = glob.glob(str(CORPUS / "*" / "*"))
+    random.Random(19).shuffle(pool)  # noqa: S311 -- deterministic sampling, not crypto
+    pool = pool[: a.n]
+    print(f"mark={a.mark}  scanning {len(pool)} corpus files  workers={a.workers}")
+    print(f"shipped ladder {SHIPPED}\ndense ladder   {DENSE}\n", flush=True)
+
+    rows: list[dict[str, Any]] = []
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with open(out, "w", encoding="utf-8") as fh, ProcessPoolExecutor(max_workers=a.workers) as ex:
+        futures = [ex.submit(_one, (p, a.mark)) for p in pool]
+        for i, fut in enumerate(as_completed(futures), 1):
+            try:
+                rec = fut.result()
+            except Exception:  # noqa: S112 -- one bad file must not kill the sweep
+                continue
+            if rec is None:
+                continue
+            fh.write(json.dumps(rec) + "\n")
+            rows.append(rec)
+            if i % 500 == 0:
+                fh.flush()
+                pos = sum(1 for r in rows if r["arm"] == "positive")
+                print(f"  {i}/{len(pool)}  usable={len(rows)} (pos={pos})", flush=True)
+    report(rows, a.mark)
+
+
+def report(rows: list[dict[str, Any]], mark: str) -> None:
+    pos = [r for r in rows if r["arm"] == "positive"]
+    neg = [r for r in rows if r["arm"] == "negative"]
+    print(f"\n{'=' * 82}\nLADDER HEADROOM  mark={mark}   positives={len(pos)}  verified-clean negatives={len(neg)}")
+    print(f"{'=' * 82}")
+    if not pos and not neg:
+        print("no usable rows")
+        return
+
+    if pos:
+        miss = [r for r in pos if not r["detected_now"]]
+        rec = [r for r in miss if r["dense_crosses"]]
+        now = len(pos) - len(miss)
+        lo, hi = wilson(len(rec), len(miss)) if miss else (0.0, 0.0)
+        print("\nPOSITIVE ARM  (images whose METADATA names this vendor -- an upper bound,")
+        print("provenance says the vendor produced the file, not that a mark is visible on it)\n")
+        print(f"  detected today            {now:5d} / {len(pos)}  ({100 * now / len(pos):.1f}%)")
+        print(f"  of the {len(miss)} misses, the dense ladder crosses the gate on {len(rec)}")
+        if miss:
+            print(f"                            ({100 * len(rec) / len(miss):.1f}%, 95% CI {lo:.1f}-{hi:.1f})")
+            after = now + len(rec)
+            print(f"  detection would go        {100 * now / len(pos):.1f}%  ->  {100 * after / len(pos):.1f}%")
+        if rec:
+            by_scale = collections.Counter(r["dense_best_scale"] for r in rec)
+            print("\n  which rung recovers them (a rung near a SHIPPED one recovering many means")
+            print("  the gain is the finer STEP, not the wider RANGE):")
+            for s, n in sorted(by_scale.items()):
+                near = "  <- shipped" if any(abs(s - x) < 0.02 for x in SHIPPED) else ""
+                print(f"    scale {s:<6} {n:4d}{near}")
+            by_asp = collections.Counter(r["aspect"] for r in rec)
+            print(f"\n  by aspect: {dict(by_asp)}")
+
+    if neg:
+        fires_now = sum(1 for r in neg if r["detected_now"])
+        fires_dense = sum(1 for r in neg if r["dense_crosses"])
+        lo0, hi0 = wilson(fires_now, len(neg))
+        lo1, hi1 = wilson(fires_dense, len(neg))
+        print("\n\nNEGATIVE ARM  (no metadata signal; NOT filtered on the detector's own verdict)\n")
+        p0, p1 = 100 * fires_now / len(neg), 100 * fires_dense / len(neg)
+        print(f"  false fire today          {fires_now:4d} / {len(neg)}  {p0:.2f}%  (CI {lo0:.2f}-{hi0:.2f})")
+        print(f"  false fire, dense ladder  {fires_dense:4d} / {len(neg)}  {p1:.2f}%  (CI {lo1:.2f}-{hi1:.2f})")
+        print("\n  This is the price. A denser ladder gives a spurious blob more chances to")
+        print("  match at SOME scale, so the gain above is only real if this line barely moves.")
+
+    ladder_table(pos, neg)
+
+
+def _crosses(row: dict[str, Any], rungs: tuple[float, ...]) -> bool:
+    """Would this frame cross its gate on the given ladder, from the stored per-rung scores."""
+    sc = row.get("scores") or {}
+    gate = row["gate"]
+    return any(v >= gate for k, v in sc.items() if float(k) in rungs)
+
+
+def ladder_table(pos: list[dict[str, Any]], neg: list[dict[str, Any]]) -> None:
+    """Every candidate ladder side by side: what it recovers against what it costs."""
+    if not (pos and neg) or "scores" not in pos[0]:
+        return  # older run without per-rung scores
+    miss = [r for r in pos if not r["detected_now"]]
+    base_fire = sum(1 for r in neg if r["detected_now"])
+    print("\n\nLADDER CANDIDATES -- recovered marks against the false fires they cost\n")
+    print("A candidate is only worth shipping if the recovered column beats the added-fires")
+    print("column by enough to survive the base rates: clean frames vastly outnumber marked")
+    print("ones in real traffic, so a small percentage on the negative arm is a large count.\n")
+    hdr = f"{'ladder':10s} {'rungs':>6s} {'recovered':>10s} {'of misses':>10s}"
+    print(f"{hdr} {'false fire':>11s} {'added':>7s} {'ratio':>7s}")
+    for name, rungs in LADDERS.items():
+        rec = sum(1 for r in miss if _crosses(r, rungs))
+        fire = sum(1 for r in neg if _crosses(r, rungs) or r["detected_now"])
+        added = fire - base_fire
+        ratio = f"{rec / added:.1f}:1" if added > 0 else ("inf" if rec else "-")
+        pct = 100 * rec / len(miss) if miss else 0.0
+        print(f"{name:10s} {len(rungs):6d} {rec:10d} {pct:9.1f}% {100 * fire / len(neg):10.2f}% {added:7d} {ratio:>7s}")
+
+
+if __name__ == "__main__":
+    main()

scripts/metadata_removal_audit.py

@@ -0,0 +1,256 @@
+"""Audit AI-metadata REMOVAL over a local image corpus (detection<->removal parity).
+
+`corpus_gap_scan.py` proves the DETECTOR sees a marker; this proves the STRIPPER
+reaches it. For every file that carries an AI-metadata signal, run
+``remove_ai_metadata`` and re-scan the output with the SAME oracle
+(``get_ai_metadata``). Any signal that survives is a real parity bug: a re-served
+file still reads as AI. Also assert the strip is lossless -- decoded pixels
+(and alpha) bit-identical before/after -- since the removal must only touch
+metadata, never the coded image.
+
+A no-op control set (clean images with no AI metadata) verifies the stripper
+neither ADDS a signal nor corrupts pixels on files it should leave alone.
+
+Operates on gitignored data only (data/spaces/...); writes nothing tracked.
+
+    uv run python scripts/metadata_removal_audit.py \
+        --corpus data/spaces/originals --identify data/spaces/identify \
+        --out data/spaces/_metadata_removal_audit.csv --jobs 8
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import logging
+import random
+import tempfile
+from collections import Counter
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+import click
+import numpy as np
+
+from remove_ai_watermarks.noai.constants import SUPPORTED_FORMATS
+
+log = logging.getLogger(__name__)
+
+# identify-JSON watermark substrings that imply a METADATA-borne signal (as
+# opposed to a purely visual sparkle/text mark). Used only to pick the candidate
+# population fast; get_ai_metadata is the per-file ground truth.
+_META_HINTS = (
+    "C2PA",
+    "Content Credentials",
+    "IPTC",
+    "Made with AI",
+    "AIGC",
+    "TC260",
+    "EXIF",
+    "Signature",
+    "SynthID",
+    "hf-job",
+    "HuggingFace",
+    "Samsung",
+    "soft-binding",
+    "metadata",
+)
+
+
+def _pixels(path: Path) -> tuple[np.ndarray | None, np.ndarray | None]:
+    """Decoded BGR + alpha, for the lossless-strip integrity check."""
+    from remove_ai_watermarks import image_io
+
+    return image_io.read_bgr_and_alpha(path)
+
+
+def _same_pixels(a: Path, b: Path) -> bool | None:
+    """True/False if both decode; None if either is undecodable (can't compare)."""
+    try:
+        bgr_a, al_a = _pixels(a)
+        bgr_b, al_b = _pixels(b)
+    except Exception:
+        return None
+    if bgr_a is None or bgr_b is None:
+        return None
+    if bgr_a.shape != bgr_b.shape or not np.array_equal(bgr_a, bgr_b):
+        return False
+    if (al_a is None) != (al_b is None):
+        return False
+    return al_a is None or al_b is None or np.array_equal(al_a, al_b)
+
+
+def _audit_one(path_str: str) -> dict[str, object]:
+    """Worker: detect -> strip -> re-detect + pixel-integrity for one file."""
+    from remove_ai_watermarks.metadata import get_ai_metadata, remove_ai_metadata
+
+    path = Path(path_str)
+    row: dict[str, object] = {
+        "path": path.name,
+        "ext": path.suffix.lower(),
+        "carrier": False,
+        "before": "",
+        "after": "",
+        "parity_ok": "",
+        "pixels_identical": "",
+        "status": "ok",
+    }
+    try:
+        before = get_ai_metadata(path)
+    except Exception as exc:
+        row["status"] = f"scan_error:{type(exc).__name__}"
+        return row
+    row["before"] = "|".join(sorted(before))
+    row["carrier"] = bool(before)
+
+    with tempfile.TemporaryDirectory() as td:
+        out = Path(td) / f"clean{path.suffix.lower()}"
+        try:
+            remove_ai_metadata(path, out)
+        except Exception as exc:
+            row["status"] = f"strip_error:{type(exc).__name__}"
+            return row
+        if not out.exists():
+            row["status"] = "no_output"
+            return row
+        try:
+            after = get_ai_metadata(out)
+        except Exception as exc:
+            row["status"] = f"rescan_error:{type(exc).__name__}"
+            return row
+        row["after"] = "|".join(sorted(after))
+        row["parity_ok"] = not after  # every AI signal must be gone
+        same = _same_pixels(path, out)
+        row["pixels_identical"] = "" if same is None else same
+    return row
+
+
+def _candidate_paths(corpus: Path, identify: Path | None, clean_sample: int) -> tuple[list[Path], list[Path]]:
+    """Return (carriers, clean_controls). Uses identify JSONs when present to pick
+    metadata carriers fast; falls back to scanning every file."""
+    if identify is None or not identify.exists():
+        files = sorted(p for p in corpus.rglob("*") if p.is_file() and p.suffix.lower() in SUPPORTED_FORMATS)
+        return files, []
+
+    carriers: list[Path] = []
+    clean: list[Path] = []
+    for jf in identify.rglob("*.json"):
+        try:
+            d = json.loads(jf.read_text())
+        except Exception:  # noqa: S112 -- skip an unreadable identify JSON, not security-relevant
+            continue
+        src = d.get("src")
+        if not src:
+            continue
+        img = corpus / jf.parent.name / src
+        if not img.exists() or img.suffix.lower() not in SUPPORTED_FORMATS:
+            continue
+        wm = " | ".join(d.get("watermarks") or [])
+        if any(h in wm for h in _META_HINTS):
+            carriers.append(img)
+        elif not d.get("is_ai_generated"):
+            clean.append(img)
+    rng = random.Random(0)  # noqa: S311 -- deterministic sampling seed, not cryptographic
+    rng.shuffle(clean)
+    return carriers, clean[:clean_sample]
+
+
+@click.command()
+@click.option(
+    "--corpus", type=click.Path(exists=True, file_okay=False, path_type=Path), default=Path("data/spaces/originals")
+)
+@click.option(
+    "--identify",
+    type=click.Path(path_type=Path),
+    default=Path("data/spaces/identify"),
+    help="identify-JSON dir to pick carriers (skip = scan all).",
+)
+@click.option("--out", type=click.Path(path_type=Path), default=Path("data/spaces/_metadata_removal_audit.csv"))
+@click.option(
+    "--clean-sample", type=int, default=1500, help="No-op control: N clean images to prove the strip is a no-op."
+)
+@click.option("--limit", type=int, default=0, help="Cap carriers scanned (0 = all).")
+@click.option("--jobs", type=int, default=8)
+def main(corpus: Path, identify: Path | None, out: Path, clean_sample: int, limit: int, jobs: int) -> None:
+    logging.basicConfig(level=logging.ERROR, format="%(message)s")
+    carriers, clean = _candidate_paths(corpus, identify, clean_sample)
+    if limit:
+        carriers = carriers[:limit]
+    tasks = [(p, "carrier") for p in carriers] + [(p, "clean") for p in clean]
+    click.echo(f"Carriers: {len(carriers)} | clean controls: {len(clean)} | jobs {jobs}")
+
+    rows: list[dict[str, object]] = []
+    with ProcessPoolExecutor(max_workers=jobs) as ex:
+        futs = {ex.submit(_audit_one, str(p)): k for p, k in tasks}
+        for done, fut in enumerate(as_completed(futs), 1):
+            row = fut.result()
+            row["kind"] = futs[fut]
+            rows.append(row)
+            if done % 500 == 0:
+                click.echo(f"  {done}/{len(tasks)}")
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    fields = ["kind", "path", "ext", "carrier", "before", "after", "parity_ok", "pixels_identical", "status"]
+    with out.open("w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=fields)
+        w.writeheader()
+        for r in rows:
+            w.writerow({k: r.get(k, "") for k in fields})
+
+    # ---- Summary ----
+    car = [r for r in rows if r["kind"] == "carrier"]
+    ctl = [r for r in rows if r["kind"] == "clean"]
+    real_carriers = [r for r in car if r["carrier"] and r["status"] == "ok"]
+    parity_fail = [r for r in real_carriers if r["parity_ok"] is False]
+    pixel_fail = [r for r in real_carriers if r["pixels_identical"] is False]
+    errors = [r for r in rows if r["status"] != "ok"]
+
+    click.echo("\n===== METADATA REMOVAL PARITY =====")
+    click.echo(f"Carrier candidates:      {len(car)}")
+    click.echo(f"Confirmed carriers:      {len(real_carriers)} (get_ai_metadata non-empty)")
+    click.echo(f"Parity FAILS (signal survives strip): {len(parity_fail)}")
+    click.echo(f"Pixel-integrity FAILS (strip altered pixels): {len(pixel_fail)}")
+    click.echo(f"Errors (scan/strip/decode): {len(errors)}")
+
+    # Per-signal parity breakdown.
+    sig_total: Counter[str] = Counter()
+    sig_fail: Counter[str] = Counter()
+    for r in real_carriers:
+        for s in str(r["before"]).split("|"):
+            if s:
+                sig_total[s] += 1
+        if r["parity_ok"] is False:
+            for s in str(r["after"]).split("|"):
+                if s:
+                    sig_fail[s] += 1
+    click.echo("\nPer-signal (carriers / surviving-after-strip):")
+    for s, n in sig_total.most_common():
+        click.echo(f"  {s:24} {n:6}  survived: {sig_fail.get(s, 0)}")
+
+    click.echo("\n===== NO-OP CONTROL (clean images) =====")
+    ctl_ok = [r for r in ctl if r["status"] == "ok"]
+    added = [r for r in ctl_ok if r["after"]]  # strip must not ADD a signal
+    corrupted = [r for r in ctl_ok if r["pixels_identical"] is False]
+    click.echo(f"Clean controls scanned:  {len(ctl_ok)}")
+    click.echo(f"Strip ADDED a signal:    {len(added)}")
+    click.echo(f"Strip corrupted pixels:  {len(corrupted)}")
+
+    if parity_fail:
+        click.echo("\n--- Parity failures (first 30) ---")
+        for r in parity_fail[:30]:
+            click.echo(f"  {r['ext']:6} survived=[{r['after']}]  {r['path']}")
+    if pixel_fail:
+        click.echo("\n--- Pixel-integrity failures (first 30) ---")
+        for r in pixel_fail[:30]:
+            click.echo(f"  {r['ext']:6} {r['path']}")
+    if errors:
+        ec: Counter[str] = Counter(str(r["status"]) for r in errors)
+        click.echo("\n--- Errors by kind ---")
+        for k, n in ec.most_common():
+            click.echo(f"  {n:5}  {k}")
+
+    click.echo(f"\nReport: {out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/pill_gate_audit.py

@@ -0,0 +1,224 @@
+"""Measure the Jimeng pill on the PRODUCT path, not the raw detector.
+
+WHY THIS EXISTS
+  `visible_removal_audit.py` calls `get_mark(key).remove` directly, which bypasses
+  `_keep_pill`. For the pill that is the wrong path and it reads as a disaster: on a
+  300-image sample the raw path was "detector still fires after removal" 68-75% of the
+  time. The product does not do that -- `--mark auto` gates the pill hard (never on
+  Doubao; unrestricted only when the bottom-right wordmark fired; otherwise only on a
+  flat footprint). Measured through the gate on the same sample, 7 of 80 raw detections
+  survived to removal and 6 of those were corroborated real.
+
+  That sample was too small to state a precision (95% CI 49-97%). This script runs the
+  gated path over EVERY pill positive in the corpus so the interval is usable.
+
+THE CORROBORATION PROXY AND ITS BIAS
+  "Real pill" here means: TC260 metadata names Jimeng, OR the bottom-right "★ 即梦AI"
+  wordmark is detected. Both are independent of the pill detector, which is the point.
+  But the proxy MISSES a real pill on a metadata-stripped screenshot with no visible
+  wordmark -- so measured precision is a LOWER BOUND, not a point estimate. Do not quote
+  it as if it were exact.
+
+Corpus images are user uploads: read-only, local analysis, gitignored output.
+
+    uv run python scripts/pill_gate_audit.py --jobs 7
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import math
+import os
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from concurrent.futures import TimeoutError as FutureTimeout
+from concurrent.futures.process import BrokenProcessPool
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+REPO = Path(__file__).resolve().parents[1]
+POSITIVES = REPO / "data" / "spaces" / "_visible_positives.jsonl"
+OUT = REPO / "data" / "spaces" / "_pill_gate_audit.jsonl"
+
+
+def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    if n == 0:
+        return (0.0, 0.0)
+    p = k / n
+    d = 1 + z * z / n
+    c = (p + z * z / (2 * n)) / d
+    h = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
+    return (100 * (c - h), 100 * (c + h))
+
+
+def _one(path_str: str) -> dict[str, object]:
+    from remove_ai_watermarks.api import visible_provenance
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.pill_engine import PillEngine
+    from remove_ai_watermarks.watermark_registry import detect_marks, get_mark, remove_auto_marks
+
+    rec: dict[str, object] = {"path": Path(path_str).name, "status": "ok"}
+    try:
+        img = imread(path_str)
+        if img is None:
+            return {**rec, "status": "unreadable"}
+        prov = visible_provenance(Path(path_str))
+        dets = {d.key: d for d in detect_marks(img) if d.detected}
+        wordmark = "jimeng" in dets
+        tc260 = "jimeng" in prov
+        eng = PillEngine()
+        _, labels = remove_auto_marks(img, sensitivity="auto", provenance=prov, backend="cv2")
+        # Match the EXACT pill label. A substring test on "AI生成" also matches Doubao's
+        # label ("Doubao 豆包AI生成 text"), which counted Doubao removals as pill removals
+        # and inflated the pill's measured precision.
+        pill_label = get_mark("jimeng_pill").label
+        removed = any(str(x) == pill_label for x in labels)
+        # The gate reads the ARBITRATED keys, not strict detection: jimeng can be accepted
+        # on its relaxed (provenance-confirmed) arm, which `detect_marks` never shows. Take
+        # the arm from what was actually removed, or every such case lands in "other".
+        jimeng_decided = any(str(x) == get_mark("jimeng").label for x in labels)
+        return {
+            **rec,
+            "removed_by_product": bool(removed),
+            "corroborated": bool(wordmark or tc260),
+            "wordmark": bool(wordmark),
+            "jimeng_decided": bool(jimeng_decided),
+            "tc260": bool(tc260),
+            "doubao_fired": "doubao" in dets,
+            "footprint_flat": bool(eng.footprint_is_flat(img)),
+        }
+    except Exception as e:
+        return {**rec, "status": f"error:{type(e).__name__}"}
+
+
+def _batch(paths: list[str], jobs: int, timeout: int) -> list[dict[str, object]]:
+    try:
+        with ProcessPoolExecutor(max_workers=jobs) as ex:
+            futs = [ex.submit(_one, p) for p in paths]
+            return [f.result() for f in as_completed(futs, timeout=timeout)]
+    except (FutureTimeout, BrokenProcessPool, OSError, RuntimeError):
+        out = []
+        for p in paths:
+            try:
+                out.append(_one(p))
+            except BaseException:  # a native crash costs one file, not the sweep
+                out.append({"path": Path(p).name, "status": "crashed"})
+        return out
+
+
+def report(rows: list[dict[str, object]]) -> None:
+    ok = [r for r in rows if r.get("status") == "ok"]
+    if not ok:
+        print("no usable rows")
+        return
+    removed = [r for r in ok if r["removed_by_product"]]
+    corro = [r for r in ok if r["corroborated"]]
+    tp = [r for r in removed if r["corroborated"]]
+    missed = [r for r in corro if not r["removed_by_product"]]
+
+    print(f"\n{'=' * 76}\nJIMENG PILL ON THE PRODUCT PATH   n={len(ok)} raw detections\n{'=' * 76}")
+    print(f"raw detections corroborated as real : {len(corro):5d}  ({100 * len(corro) / len(ok):.1f}%)")
+    print(f"the gate lets through to removal    : {len(removed):5d}  ({100 * len(removed) / len(ok):.1f}%)")
+    if removed:
+        lo, hi = wilson(len(tp), len(removed))
+        pct = 100 * len(tp) / len(removed)
+        print(f"  of those, corroborated real       : {len(tp):5d}  -> precision {pct:.1f}% (95% CI {lo:.1f}-{hi:.1f})")
+    if corro:
+        lo, hi = wilson(len(tp), len(corro))
+        pct = 100 * len(tp) / len(corro)
+        head = f"corroborated pills removed          : {len(tp):5d}/{len(corro)}"
+        print(f"{head}  -> recall {pct:.1f}% (95% CI {lo:.1f}-{hi:.1f})")
+    print(f"corroborated pills the gate suppressed: {len(missed):5d}")
+    print("\nprecision is a LOWER BOUND: the corroboration proxy cannot see a real pill on a")
+    print("metadata-stripped image whose wordmark is absent or missed.\n")
+
+    print("which gate arm let it through:")
+    arms: collections.Counter[str] = collections.Counter()
+    for r in removed:
+        if r.get("jimeng_decided"):
+            arms["jimeng wordmark accepted -> unrestricted"] += 1
+        elif r["tc260"]:
+            arms["tc260 metadata + flat footprint"] += 1
+        else:
+            arms["other (unexpected -- the gate has no third arm)"] += 1
+    for k, v in arms.most_common():
+        print(f"   {v:5d}  {k}")
+
+    print("\nwhy the rest were suppressed:")
+    sup: collections.Counter[str] = collections.Counter()
+    for r in ok:
+        if r["removed_by_product"]:
+            continue
+        if r["doubao_fired"]:
+            sup["doubao fired (pill never rides on it)"] += 1
+        elif not r["corroborated"]:
+            sup["no corroboration (no wordmark, no TC260)"] += 1
+        elif not r["footprint_flat"]:
+            sup["corroborated but footprint too textured"] += 1
+        else:
+            sup["other"] += 1
+    for k, v in sup.most_common():
+        print(f"   {v:5d}  {k}")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--jobs", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--limit", type=int, default=0)
+    ap.add_argument("--batch", type=int, default=200)
+    ap.add_argument("--timeout", type=int, default=900)
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--restart", action="store_true")
+    a = ap.parse_args()
+
+    paths = []
+    with open(POSITIVES, encoding="utf-8") as fh:
+        for line in fh:
+            try:
+                r = json.loads(line)
+            except Exception:  # noqa: S112
+                continue
+            if "jimeng_pill" in (r.get("keys") or []):
+                paths.append(r["path"])
+    paths.sort()
+    if a.limit:
+        paths = paths[: a.limit]
+
+    done: set[str] = set()
+    if a.restart and a.out.exists():
+        a.out.unlink()  # --restart must TRUNCATE; appending kept the old rows in the report
+    if a.out.exists() and not a.restart:
+        with open(a.out, encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    done.add(json.loads(line)["path"])
+                except Exception:  # noqa: S112
+                    continue
+    todo = [p for p in paths if Path(p).name not in done]
+    print(f"pill positives {len(paths)}  done {len(done)}  to do {len(todo)}  jobs {a.jobs}", flush=True)
+
+    rows: list[dict[str, object]] = []
+    with open(a.out, "a", encoding="utf-8") as fh:
+        for i in range(0, len(todo), a.batch):
+            for rec in _batch(todo[i : i + a.batch], a.jobs, a.timeout):
+                fh.write(json.dumps(rec) + "\n")
+                rows.append(rec)
+            fh.flush()
+            print(f"  {len(rows)}/{len(todo)}", flush=True)
+
+    with open(a.out, encoding="utf-8") as fh:
+        allrows = []
+        for line in fh:
+            try:
+                allrows.append(json.loads(line))
+            except Exception:  # noqa: S112
+                continue
+    report(allrows)
+    print(f"records -> {a.out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/real_examples_e2e.py

@@ -0,0 +1,328 @@
+"""End-to-end confidence run: drive the ACTUAL CLI over REAL corpus examples.
+
+WHY THIS EXISTS AND WHAT IT IS NOT
+  The 849-test suite and `smoke_matrix.py` prove the code paths behave on fixtures and
+  synthetic inputs. This is the other half: run the real `remove-ai-watermarks` entry point,
+  as a user would, over real corpus images spanning every command and every provenance
+  class, and CHECK THE OUTPUT -- not that it exited 0, but that it did the right thing (the
+  mark is actually gone on re-detect, the metadata actually strips, the diffusion actually
+  writes a changed image). A green exit is not evidence the work happened.
+
+WHAT IT COVERS
+  identify   one real image per provenance class -> the verdict is right
+  metadata   real AI-metadata files -> --check detects, --remove strip-and-verifies clean
+  visible    real marked images per mark -> the mark is gone on re-detect, output written
+  erase      a real image, each fill backend (cv2 / migan / lama) -> output written
+  invisible  a real SynthID image on MPS at reduced resolution -> a CHANGED image is written
+  all        a real marked image through the full pipeline -> output written
+  batch      a real directory -> every input produces an output
+
+  invisible/all run the diffusion model, so they are gated behind --diffusion and run at a
+  small --max-resolution on MPS (the user's "reduced size on MPS" path). Everything else is
+  cv2/numpy and fast.
+
+DATA SAFETY
+  Corpus images are user uploads: read-only, local analysis, outputs to a gitignored temp
+  dir. Records example uids and pass/fail, never image content.
+
+    uv run python scripts/real_examples_e2e.py                 # fast surface (no diffusion)
+    uv run python scripts/real_examples_e2e.py --diffusion     # + invisible/all on MPS
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import random
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS = REPO / "data" / "spaces" / "originals"
+DATASETS = REPO / "data" / "spaces" / "_visible_datasets"
+SAMPLES = REPO / "data" / "samples"
+_UV = shutil.which("uv") or "uv"  # full path avoids the partial-executable lint
+
+
+def run(args: list[str], timeout: int = 300) -> tuple[int, str]:
+    """Invoke the real installed CLI. Returns (exit_code, combined output)."""
+    proc = subprocess.run(  # noqa: S603 -- fixed argv, the whole point is the real entry point
+        [_UV, "run", "remove-ai-watermarks", *args],
+        cwd=REPO,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+    return proc.returncode, (proc.stdout + proc.stderr)
+
+
+def find_visible_positive(mark: str) -> Path | None:
+    """A real corpus image the parity run bucketed as carrying this mark, that the current
+    detector STILL fires on (the bucket was built by an older run; re-confirm live)."""
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.watermark_registry import detect_marks
+
+    pool = sorted(glob.glob(str(DATASETS / mark / "*")))
+    random.Random(3).shuffle(pool)  # noqa: S311 -- deterministic sampling, not cryptography
+    for p in pool[:60]:
+        img = imread(p)
+        if img is None:
+            continue
+        if any(d.detected and d.key == mark for d in detect_marks(img)):
+            return Path(p)
+    return None
+
+
+class Results:
+    """Collects one row per checked behaviour.
+
+    A FAIL keeps the command's OUTPUT. That is not cosmetic: the first run of this harness
+    discarded it, an `all` invocation failed once with exit 1, and because the output was
+    gone there was no way to tell which of that command's three distinct `SystemExit(1)`
+    paths had fired -- the failure was undiagnosable and did not reproduce. Keep the tail
+    so a transient is at least identifiable after the fact.
+    """
+
+    def __init__(self) -> None:
+        self.rows: list[tuple[str, str, bool, str, str]] = []
+
+    def add(self, cmd: str, example: str, ok: bool, detail: str, output: str = "") -> None:
+        self.rows.append((cmd, example, ok, detail, "" if ok else output[-800:]))
+        mark = "PASS" if ok else "FAIL"
+        print(f"  [{mark}] {cmd:28s} {example:26s} {detail}", flush=True)
+
+    def report(self) -> int:
+        n = len(self.rows)
+        bad = [r for r in self.rows if not r[2]]
+        print(f"\n{'=' * 78}\nREAL-EXAMPLE E2E  {n - len(bad)}/{n} passed")
+        print(f"{'=' * 78}")
+        for cmd, ex, ok, detail, out in self.rows:
+            if not ok:
+                print(f"  FAIL  {cmd}  {ex}  {detail}")
+                if out.strip():
+                    print("        --- command output (tail) ---")
+                    for line in out.strip().splitlines()[-12:]:
+                        print(f"        {line}")
+        if not bad:
+            print("  every command produced the right result on real corpus examples")
+        return 1 if bad else 0
+
+
+def check_identify(res: Results) -> None:
+    """One real image per provenance class -> the verdict is right (--json must parse)."""
+    print("\nidentify -- real image per provenance class")
+    cases = [
+        ("chatgpt-1.png", True),
+        ("firefly-1.png", True),
+        ("mj-1.png", True),
+        ("doubao-1.png", True),
+        ("grok-1.jpg", True),
+        ("flux-1.jpg", True),
+    ]
+    for name, want_ai in cases:
+        p = SAMPLES / name
+        if not p.exists():
+            res.add("identify", name, False, "sample missing")
+            continue
+        code, out = run(["identify", str(p), "--json"])
+        try:
+            data = json.loads(out[out.index("{") : out.rindex("}") + 1])
+        except (ValueError, json.JSONDecodeError):
+            res.add("identify", name, False, f"json did not parse (exit {code})")
+            continue
+        is_ai = data.get("is_ai_generated")
+        plat = (data.get("platform") or "").lower()
+        ok = bool(is_ai) is want_ai
+        res.add("identify", name, ok, f"is_ai={is_ai} platform={plat or '-'}")
+
+
+def check_metadata(res: Results, tmp: Path) -> None:
+    """Real AI-metadata files -> --check detects, --remove strip-and-verifies clean."""
+    print("\nmetadata -- real AI-metadata files, detect then strip-and-verify")
+    for name in ("chatgpt-1.png", "doubao-1.png", "mj-1.png", "grok-1.jpg", "flux-1.jpg"):
+        p = SAMPLES / name
+        if not p.exists():
+            res.add("metadata --check", name, False, "sample missing")
+            continue
+        code, out = run(["metadata", str(p), "--check"])
+        detected = "no ai" not in out.lower() and code == 0
+        res.add("metadata --check", name, detected, "AI metadata detected" if detected else "nothing detected")
+
+        outp = tmp / f"stripped_{name}"
+        code, out = run(["metadata", str(p), "--remove", "-o", str(outp)])
+        # strip-and-verify: the command re-scans the OUTPUT and fails loudly on leftovers.
+        clean = outp.exists() and code == 0 and "still" not in out.lower()
+        res.add("metadata --remove", name, clean, "output re-scanned clean" if clean else f"exit {code}")
+
+
+def check_visible(res: Results, tmp: Path) -> None:
+    """Real marked images -> the PRODUCT'S DECISION is honoured, and a removed mark clears.
+
+    The success criterion is not "the mark is always gone" -- it is "the product did what it
+    decided, and the decision is right". Two designed behaviours make a blind re-detect
+    misleading:
+      * The pill is GATED (`_keep_pill`): a low-confidence pill with no corroboration is
+        deliberately NOT removed, so `visible` correctly writes nothing and exits 2. That is
+        the gate working, not a miss -- checked by asking `remove_auto_marks` whether it
+        chose to act.
+      * Samsung is the faintest mark (peak alpha ~0.38) at a razor-thin 0.40 gate, so a
+        borderline positive can be reduced yet re-detect just above threshold. Reported as
+        the measured before->after confidence, not a bare pass/fail.
+    """
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.watermark_registry import detect_marks, get_mark, remove_auto_marks
+
+    print("\nvisible --mark auto -- real marked image per mark, product decision then re-detect")
+    for mark in ("doubao", "jimeng", "qwen", "gemini", "samsung", "jimeng_pill"):
+        src = find_visible_positive(mark)
+        if src is None:
+            res.add("visible", mark, True, "no live positive in bucket (skipped, not a failure)")
+            continue
+        img = imread(str(src))
+        conf_before = next((d.confidence for d in detect_marks(img) if d.detected and d.key == mark), 0.0)
+        # What does the product DECIDE to do? (labels lists the marks it removed.)
+        _out_img, labels = remove_auto_marks(img, sensitivity="auto", provenance=frozenset(), backend="cv2")
+        acted = get_mark(mark).label in labels
+
+        outp = tmp / f"visible_{mark}{src.suffix}"
+        code, out = run(["visible", str(src), "--mark", "auto", "-o", str(outp)])
+
+        if not acted:
+            # The gate declined this mark. The CLI must then write nothing and exit 2 --
+            # that is the correct outcome, so verify the CLI agrees with the decision.
+            ok = code == 2 and not outp.exists()
+            res.add(
+                "visible", mark, ok, f"gate declined (conf {conf_before:.2f}); CLI exit {code}, no output -- correct"
+            )
+            continue
+
+        if not outp.exists():
+            res.add("visible", mark, False, f"product removed it but CLI wrote no output (exit {code})", out)
+            continue
+        cleaned = imread(str(outp))
+        conf_after = next((d.confidence for d in detect_marks(cleaned) if d.detected and d.key == mark), 0.0)
+        clean = conf_after == 0.0
+        if clean:
+            res.add("visible", mark, True, f"removed, re-detect clean ({conf_before:.2f} -> below gate)")
+        else:
+            # Reduced but still over the gate: a real residual. Honest partial, flagged.
+            res.add(
+                "visible",
+                mark,
+                False,
+                f"reduced {conf_before:.2f} -> {conf_after:.2f} but still over gate (faint-mark residual)",
+            )
+
+
+def check_erase(res: Results, tmp: Path) -> None:
+    """A real image, each fill backend actually runs and writes an output."""
+    from remove_ai_watermarks.region_eraser import lama_available, migan_available
+
+    print("\nerase --region -- each fill backend on a real image")
+    src = next((Path(p) for p in sorted(glob.glob(str(CORPUS / "*" / "*"))) if Path(p).stat().st_size > 50_000), None)
+    if src is None:
+        res.add("erase", "-", False, "no corpus image")
+        return
+    backends = ["cv2"] + (["migan"] if migan_available() else []) + (["lama"] if lama_available() else [])
+    for backend in backends:
+        outp = tmp / f"erase_{backend}{src.suffix}"
+        code, out = run(["erase", str(src), "--region", "10,10,120,60", "--backend", backend, "-o", str(outp)])
+        ok = outp.exists() and code == 0 and outp.stat().st_size > 0
+        res.add(f"erase --backend {backend}", src.name[:12], ok, "output written" if ok else f"exit {code}", out)
+
+
+def check_diffusion(res: Results, tmp: Path, gemini_src: str, openai_src: str) -> None:
+    """The GPU path: invisible + all on MPS at reduced resolution -> a CHANGED image."""
+    import numpy as np
+
+    from remove_ai_watermarks.image_io import imread
+
+    print("\ninvisible / all -- real SynthID image on MPS, reduced resolution")
+    for label, src in (("invisible/gemini", gemini_src), ("invisible/openai", openai_src)):
+        if not src:
+            res.add(label, "-", True, "no real positive found (skipped)")
+            continue
+        sp = Path(src)
+        outp = tmp / f"inv_{sp.stem}.png"
+        code, out = run(
+            ["invisible", src, "-o", str(outp), "--device", "mps", "--max-resolution", "512", "--seed", "0"],
+            timeout=1200,
+        )
+        if not outp.exists():
+            res.add(label, sp.name[:12], False, f"no output (exit {code})", out)
+            continue
+        before, after = imread(src), imread(str(outp))
+        # Diffusion regenerates every pixel; the output must actually differ from the input.
+        # A DIFFERENT SHAPE is itself proof it changed (the pipeline resizes), so treat it
+        # as changed rather than comparing arrays that cannot be compared. The first
+        # version wrote `array_equal(after, before if shapes match else after)`, which
+        # compares `after` WITH ITSELF on the mismatch branch and is therefore always
+        # "unchanged" -- it would have reported a genuinely resized output as a no-op.
+        changed = (
+            after is not None
+            and before is not None
+            and (before.shape != after.shape or not np.array_equal(before, after))
+        )
+        res.add(label, sp.name[:12], changed, "diffusion wrote a changed image" if changed else "output == input", out)
+
+    if gemini_src:
+        sp = Path(gemini_src)
+        outp = tmp / f"all_{sp.stem}.png"
+        code, out = run(
+            ["all", gemini_src, "-o", str(outp), "--device", "mps", "--max-resolution", "512", "--seed", "0"],
+            timeout=1200,
+        )
+        ok = outp.exists() and outp.stat().st_size > 0
+        res.add("all (full pipeline)", sp.name[:12], ok, "output written" if ok else f"exit {code}", out)
+
+
+def check_batch(res: Results, tmp: Path) -> None:
+    """A real directory -> every supported input produces an output."""
+    print("\nbatch -- a real directory")
+    indir = tmp / "batch_in"
+    indir.mkdir(exist_ok=True)
+    picks = sorted(glob.glob(str(DATASETS / "doubao" / "*")))[:5]
+    for p in picks:
+        shutil.copy2(p, indir / Path(p).name)
+    n_in = len(list(indir.glob("*")))
+    if n_in == 0:
+        res.add("batch", "-", False, "no inputs to seed")
+        return
+    outdir = tmp / "batch_out"
+    code, out = run(["batch", str(indir), "-o", str(outdir), "--mode", "visible"], timeout=600)
+    n_out = len(list(outdir.glob("*"))) if outdir.exists() else 0
+    ok = code == 0 and n_out >= n_in
+    res.add("batch --mode visible", f"{n_in} imgs", ok, f"{n_out}/{n_in} outputs (exit {code})", out)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--diffusion", action="store_true", help="also run invisible/all on MPS (slow)")
+    ap.add_argument("--gemini", default="")
+    ap.add_argument("--openai", default="")
+    a = ap.parse_args()
+
+    res = Results()
+    with tempfile.TemporaryDirectory(prefix="raiw_e2e_") as td:
+        tmp = Path(td)
+        check_identify(res)
+        check_metadata(res, tmp)
+        check_visible(res, tmp)
+        check_erase(res, tmp)
+        check_batch(res, tmp)
+        if a.diffusion:
+            check_diffusion(res, tmp, a.gemini, a.openai)
+        else:
+            print("\n(diffusion skipped -- pass --diffusion to run invisible/all on MPS)")
+    raise SystemExit(res.report())
+
+
+if __name__ == "__main__":
+    main()

scripts/render_vendor_silhouettes.py

@@ -0,0 +1,291 @@
+"""Render SYNTHETIC detection silhouettes for the CJK vendor text marks (data-safe).
+
+Adding a mark needs only a DETECTION silhouette, and it must be font-rendered rather
+than derived from user uploads: the corpus is real user content and may never reach a
+tracked asset (see the repo CLAUDE.md data-safety rule). Seeing real samples to learn
+the glyphs, weight and layout is fine; the committed template stays synthetic.
+
+Covered here:
+  qwen     "千问AI生成"  -- Alibaba Tongyi Qianwen, bottom-right, 3-lobed logo + text
+  xinghui  "星绘AI生成"  -- ByteDance 星绘, bottom-right, 4-point sparkle + text
+  yuanbao  "元宝\nAI生成" -- Tencent Yuanbao, bottom-right, two-line italic block
+           (MEASURED NEGATIVE 2026-07-21, parked: the slanted two-line template does
+           not separate the cohort from clean corners on either front-end; the recipe
+           + MARK_OPTS stay as the starting point if a structural/learned lever is
+           built -- full record in docs/verification-plan.md)
+  kling    "可灵AI 3.0"  -- Kuaishou Kling, bottom-right, spiral logo + text
+           (REGISTERED 2026-07-21, kling_engine.py)
+
+The leading LOGO is deliberately NOT rendered. It is the part that varies most between
+releases and is hardest to reproduce synthetically, while the CJK run is stable and is
+what actually discriminates one vendor from another (the shared `AI生成` tail is exactly
+what does NOT discriminate -- see the rival-margin mechanism in _text_mark_engine).
+
+Regenerate with:  uv run python scripts/render_vendor_silhouettes.py
+
+STATUS 2026-07-21: `qwen_alpha.png` IS registered (`qwen_engine.py`) -- the 2026-07-18
+blocker quoted below turned out to be mis-sized GEOMETRY (two size modes + a locate box
+that clipped the first glyph), not segmentation, and was solved by the TC260-producer
+cohort harvest + `vendor_mark_calibrate.py` (117 labelled frames; full record in
+`docs/verification-plan.md`). `xinghui_alpha.png` is still NOT registered: one confirmed
+corpus example is nothing to calibrate a gate against.
+
+--- the 2026-07-18 record, kept as the history of the failed first attempt ---
+Measured on 14 hand-verified 千问 positives from the corpus,
+the then-current detect architecture (top-hat glyph blob -> binary TM_CCOEFF_NORMED)
+could not see this mark AT ALL:
+
+    same pipeline, each mark scored with its OWN template, on real positives
+      doubao   n=40   mean NCC 0.723   median 0.835   >= 0.40 gate: 82%
+      qwen     n=14   mean NCC 0.170   median 0.179   >= 0.40 gate:  0%
+
+Three checks ruled out the obvious explanations, in order:
+  1. NOT the synthetic render. A template cut from an ACTUAL Qwen mark scores the same
+     as the font-rendered one (real-vs-real 0.307 vs synthetic 0.308) -- and real masks
+     do not even match EACH OTHER.
+  2. NOT the morphology kernel size. Scaling MORPH_OPEN/CLOSE with the box height (they
+     are fixed 5px, ~9% of a 57px-tall box) gained only +0.014 mean and moved nothing
+     across the gate.
+  3. NOT the appearance thresholds. Sweeping tophat_delta / logo_min_luma / kernel
+     reached at best mean 0.35 with 4/14 over the gate.
+
+The blocker was named SEGMENTATION on a faint mark: Doubao is stamped bold and opaque,
+so the white top-hat returns a clean glyph blob; the Qwen mark is a thin translucent
+overlay that shatters into specks, and no template can match a blob that is not there.
+The `tophat` front-end (built later, for doubao) removed that blocker -- and 千问 STILL
+did not register, because the real residual was geometry. See the 2026-07-21 status
+above.
+
+星绘 additionally has only ONE confirmed example in the corpus, so even a working
+front-end could not have its threshold calibrated yet.
+
+UPDATE 2026-07-20: the named blocker is GONE, and the retry is still inconclusive.
+`detect_frontend="tophat"` (built later, for doubao) is exactly the "grayscale correlation
+on the raw top-hat" this note asked for, so the 2026-07-18 ruling rests on a premise that
+no longer holds and must not simply be inherited. Two things were measured against it, and
+neither settles the question:
+
+  * A GENERIC template of the shared `AI生成` tail -- attractive because GB 45438-2025
+    guarantees that run across vendors, so one template would cover 千问 / 百度 / 星绘 and
+    anything compliant that ships next. Measured on the tophat front-end at the shipped
+    3-rung ladder: a bold 千问 positive scores 0.407 against clean corners at p99 0.298 /
+    max 0.321. It separates on that one frame, but only by a hair, and a 4-glyph template
+    is inherently less specific than a 6-glyph one -- the shorter the run, the more
+    arbitrary corner structure correlates with it.
+  * The FULL 千问 template on the same front-end scores 0.248 against a clean max of 0.537,
+    i.e. no separation at all -- WORSE than the generic tail, which is the opposite of
+    what the specificity argument predicts and is itself a reason to distrust n=1.
+
+The blocker is now EVIDENCE, not architecture: this session found exactly one 千问 and one
+百度 positive (both by eyeballing doubao-provenance misses), and the 14 positives quoted
+above were not preserved anywhere the current scripts can reach. Nothing should be
+registered off a single frame.
+
+UPDATE 2026-07-21 (the resolution): the evidence arrived via the TC260 producer-USCC
+cohort trick (`scripts/vendor_cohort_harvest.py` -- 117 labelled 千问 frames from metadata
+alone), and the registration shipped the same day (`qwen_engine.py`). The "no separation
+at all" reading above was the MIS-SIZED geometry, not the mark: at the fitted geometry the
+full template separates the cohort from clean corners 0.662 vs 0.134 (p50). The traps
+below still bind any NEXT vendor: score with `alpha_height_frac`, not the silhouette's own
+aspect ratio (the latter inflated the clean p99 from 0.30 to 0.58 and made every
+comparison meaningless); keep the ladder at the shipped rungs for gate-setting, since a
+wide sweep hands clean corners many extra chances to match; and re-filter the clean arm
+per candidate -- the 2026-07-18 `present: []` labels mean "no REGISTERED mark", so qwen
+-cohort frames visibly carrying 千问AI生成 sat in it (see `vendor_mark_calibrate.load_sets`).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+_ASSETS = Path(__file__).resolve().parents[1] / "src" / "remove_ai_watermarks" / "assets"
+# STHeiti Medium approximates the semibold CJK sans these marks are set in; the exact
+# family is unpublished for every vendor (GB 45438-2025 only requires a legible face).
+_FONT = "/System/Library/Fonts/STHeiti Medium.ttc"
+
+MARKS = {
+    "qwen_alpha.png": "千问AI生成",
+    "xinghui_alpha.png": "星绘AI生成",
+    # Yuanbao's stamp is a TWO-LINE block (元宝 over AI生成), left-aligned, tightly
+    # stacked and ITALIC-SLANTED (measured on the 2026-07-21 cohort sheet + real tophat
+    # responses); a rare one-line variant exists but the stacked block is dominant.
+    "yuanbao_alpha.png": "元宝\nAI生成",
+    # Kling (可灵) stamps a thin light-gray one-line "可灵AI 3.0" bottom-right (an
+    # "Omni" suffix variant and a latin "KlingAI 3.0" variant also exist; the CJK
+    # run without the suffix is the common core). The leading spiral logo is NOT
+    # rendered (logos vary; the text run discriminates).
+    "kling_alpha.png": "可灵AI 3.0",
+    # The "cat-logo" cohort (USCC 91110108562144110X) stamps an outline cat-head +
+    # bold "AI生成", bottom-right. PARKED 2026-07-21: the cohort is 19 copies of
+    # only 2 unique carriers -- nothing to calibrate recall against (the xinghui
+    # rule). The probe is ready: this silhouette scores 0.50 on the mark vs 0.333
+    # max on a diverse clean arm, so registration is a gate pick (0.42) the moment
+    # more unique carriers arrive.
+    "catlogo_alpha.png": "CATLOGO",  # sentinel: drawn by draw_catlogo(), not font-rendered
+    # RunningHub (ComfyUI platform, USCC 91340100MAEB4N8H76, 73-frame cohort
+    # 2026-07-22): white one-line "RunningHub AI生成" text mark.
+    "runninghub_alpha.png": "RunningHub AI生成",
+    # LibLibAI / 哩布哩布AI (USCC 91110105MACJ6K1C8A, 15-frame cohort): white
+    # "LibLibAI" wordmark with a triangle logo (logo not rendered, logos vary).
+    "liblib_alpha.png": "LibLibAI",
+    # Zhipu Qingyan (USCC 91110108MA01KP2T5U, 7-frame cohort): white bold
+    # "清言·AI生成" with a circular logo (logo not rendered). PARKED 2026-07-22
+    # as a measured negative: on both front-ends the cohort scores 0.34-0.39
+    # against a clean-arm max of 0.34-0.37 -- no separation at any render/box
+    # setting (text-only and logo-composite templates both plateau ~0.34 raw;
+    # the white semi-transparent text on variable backgrounds is the wall).
+    # Silhouette stays as the starting point for a structural/learned lever.
+    "qingyan_alpha.png": "清言·AI生成",
+    # MiniMax / Hailuo (6-frame cohort): "MINIMAX" + "Hailuo AI" latin wordmarks.
+    # PARKED 2026-07-22: only 1 of the 6 cohort frames carries a visible mark --
+    # nothing to calibrate recall against (the xinghui rule). Registration is a
+    # gate pick once more unique carriers arrive.
+    "hailuo_alpha.png": "Hailuo AI",
+    # Baidu (USCC 91110000802100433B, 16-frame cohort): white bold "百度" text
+    # + a separate white rounded tag with dark "AI生成", bottom-right. Detection
+    # keys on the 百度 text run ONLY: a two-component template (text+pill) scored
+    # at clean-arm levels (pill = bright-blob magnet, clean p95 0.45-0.55 vs cohort
+    # ~0.5, no separation on either front-end, 2026-07-22); the text-only silhouette
+    # separates (cohort 0.39-0.65 vs clean max 0.352). The white tag is removed
+    # with the mark because the fill blob covers both bright components.
+    "baidu_alpha.png": "百度",
+}
+
+# Per-mark post-processing for the multi-line / slanted stamps (see render()).
+MARK_OPTS: dict[str, dict[str, Any]] = {
+    # Fitted against real tophat responses on the Yuanbao cohort (2026-07-21): a
+    # right-aligned, gapped, unslanted render plateaued at ~0.34 NCC; left-align +
+    # tight gap + stroke dilation + shear -0.75 reaches 0.65-0.70 on the same frames,
+    # at/above the real-vs-real ceiling (~0.6).
+    "yuanbao_alpha.png": {"gap_frac": 0.05, "dilate": 2, "shear": -0.75},
+    # Qingyan's real stamp is a heavier weight than STHeiti Medium -- Hiragino
+    # Sans GB W6 matches the measured stroke (2026-07-22; with Medium the
+    # silhouette aspect came out 0.19 vs the real 0.28 and NCC plateaued ~0.3).
+    "qingyan_alpha.png": {"font": "/System/Library/Fonts/Hiragino Sans GB.ttc", "font_index": 2},
+    # LibLibAI's wordmark is set in an Arial-class grotesque, not STHeiti:
+    # measured 2026-07-22 across 7 candidate fonts, Arial lifts the cohort
+    # positives from 0.31-0.47 to 0.42-0.73 while the full-corpus false-fire arm
+    # DROPS to max 0.398 (generic latin UI text matches the wrong font less).
+    "liblib_alpha.png": {"font": "/System/Library/Fonts/Supplemental/Arial.ttf"},
+}
+
+
+def render(text: str, width: int = 335, opts: dict[str, Any] | None = None) -> np.ndarray:
+    """Binary glyph silhouette (255 = glyph), sized to the doubao asset's convention.
+
+    Matching doubao's 335px asset width keeps the `alpha_*_frac` numbers transferable,
+    since these marks are the same house style and scale. A "\n" in ``text`` renders a
+    multi-line block: lines drawn left-aligned at one shared font size with a tight
+    gap, then optional stroke dilation and an italic shear (see MARK_OPTS).
+    """
+    opts = opts or {}
+    gap_frac = float(opts.get("gap_frac", 0.15))
+    dilate = int(opts.get("dilate", 0))
+    shear_k = float(opts.get("shear", 0.0))
+    font_path = str(opts.get("font", _FONT))
+    font_index = int(opts.get("font_index", 0))
+    probe = Image.new("L", (10, 10))
+    d0 = ImageDraw.Draw(probe)
+    lines = text.split("\n")
+    size = 8
+    while size < 200:  # grow until the LONGEST line fills the target width
+        f = ImageFont.truetype(font_path, size, index=font_index)
+        if max(d0.textbbox((0, 0), ln, font=f)[2] for ln in lines) >= width * 0.98:
+            break
+        size += 1
+    font = ImageFont.truetype(font_path, size, index=font_index)
+    boxes = [d0.textbbox((0, 0), ln, font=font) for ln in lines]
+    line_h = max(bb[3] - bb[1] for bb in boxes)
+    gap = max(1, int(line_h * gap_frac))
+    w = max(bb[2] - bb[0] for bb in boxes)
+    h = line_h * len(lines) + gap * (len(lines) - 1)
+    pad = max(2, int(line_h * 0.12))
+    im = Image.new("L", (w + 2 * pad, h + 2 * pad), 0)
+    draw = ImageDraw.Draw(im)
+    y = pad
+    for ln, bb in zip(lines, boxes, strict=True):
+        draw.text((pad - bb[0], y - bb[1]), ln, font=font, fill=255)
+        y += line_h + gap
+    sil = np.array(im)
+    if dilate or shear_k:
+        import cv2
+
+        if dilate:
+            sil = cv2.dilate(sil, np.ones((dilate, dilate), np.uint8))
+        if shear_k:
+            hh, ww = sil.shape
+            sil = cv2.warpAffine(sil, np.float32([[1, shear_k, 0], [0, 1, 0]]), (ww + int(abs(shear_k) * hh), hh))
+    return sil
+
+
+def draw_catlogo(width: int = 335) -> np.ndarray:
+    """The cat-logo mark: an outline cat-head (integrated pointy ears, two dot eyes)
+    + a bold "AI生成" run, drawn synthetically from the measured layout (cat ~1.08x
+    the glyph height, stroke ~9%, gap ~35%). Proportions were iterated against a real
+    tophat response (2026-07-21): a solid filled head scored 0.35, this outline form
+    0.50 -- the parked probe, see MARKS."""
+    probe = Image.new("L", (10, 10))
+    d0 = ImageDraw.Draw(probe)
+    text = "AI生成"
+    size = 8
+    while size < 200:
+        f = ImageFont.truetype(_FONT, size)
+        if d0.textbbox((0, 0), text, font=f)[2] >= width * 0.60:
+            break
+        size += 1
+    font = ImageFont.truetype(_FONT, size)
+    bb = d0.textbbox((0, 0), text, font=font)
+    tw, th = bb[2] - bb[0], bb[3] - bb[1]
+    cs = int(th * 1.08)
+    stroke = max(2, int(th * 0.09))
+    gap = int(th * 0.35)
+
+    def head(s: int) -> Image.Image:
+        im = Image.new("L", (s, s), 0)
+        d = ImageDraw.Draw(im)
+        f = float(s)
+        pts = [
+            (0.12 * f, 0.95 * f),
+            (0.10 * f, 0.45 * f),
+            (0.12 * f, 0.30 * f),
+            (0.20 * f, 0.05 * f),  # left ear tip
+            (0.40 * f, 0.24 * f),  # left ear valley
+            (0.60 * f, 0.24 * f),  # right ear valley
+            (0.80 * f, 0.05 * f),  # right ear tip
+            (0.88 * f, 0.30 * f),
+            (0.90 * f, 0.45 * f),
+            (0.88 * f, 0.95 * f),
+        ]
+        d.line([*pts, pts[0]], fill=255, width=stroke, joint="curve")
+        r = max(1.5, stroke * 0.7)
+        d.ellipse([0.35 * f - r, 0.60 * f - r, 0.35 * f + r, 0.60 * f + r], fill=255)
+        d.ellipse([0.65 * f - r, 0.60 * f - r, 0.65 * f + r, 0.60 * f + r], fill=255)
+        return im
+
+    w = cs + gap + tw
+    h = max(th, cs)
+    pad = max(2, int(h * 0.12))
+    im = Image.new("L", (w + 2 * pad, h + 2 * pad), 0)
+    im.paste(head(cs), (pad, pad + (h - cs) // 2))
+    ImageDraw.Draw(im).text((pad + cs + gap - bb[0], pad + (h - th) // 2 - bb[1]), text, font=font, fill=255)
+    return np.array(im)
+
+
+def main() -> None:
+    try:
+        for name, text in MARKS.items():
+            sil = draw_catlogo() if text == "CATLOGO" else render(text, opts=MARK_OPTS.get(name))
+            Image.fromarray(sil).save(_ASSETS / name)
+            print(f"wrote {_ASSETS / name}  ({sil.shape[1]}x{sil.shape[0]})  text={text!r}")
+    except OSError as e:
+        print(f"Font not found ({e}); install a CJK font or edit _FONT.", file=sys.stderr)
+        raise SystemExit(1) from e
+
+
+if __name__ == "__main__":
+    main()

scripts/resource_ceilings.py

@@ -0,0 +1,156 @@
+"""Tier B4: peak RSS and wall time per fill backend across input sizes.
+
+WHY THIS EXISTS
+  The docs describe the backends in CAPABILITY prose -- "MI-GAN is the memory-tight pick",
+  "big-LaMa does not fit a minimal droplet", "~0.6-0.9 GB regardless of upload size". Those
+  numbers were measured once, informally, and are now load-bearing for a real deployment
+  decision (the free tier runs `migan`, the paid tier runs `lama`). This measures them.
+
+WHAT IT MEASURES
+  For each (backend, input size): peak RSS of a FRESH process doing exactly one erase, and
+  the wall time. A fresh subprocess per measurement is the point -- peak RSS inside a
+  long-lived process is contaminated by whatever ran before it, and the question here is
+  what a per-request worker actually needs.
+
+  The mask is a fixed, small corner region at every size, because the claim under test is
+  that the learned backends crop around the mask and so their memory is bounded by the MARK
+  size, not the image size. If that holds, the curve is flat in input size; if it does not,
+  it climbs and the droplet sizing is wrong.
+
+READING IT
+  RSS is the peak resident set of the whole worker, which includes the interpreter, numpy,
+  cv2 and (for the learned backends) onnxruntime plus the model. That is the honest number
+  for sizing a container -- not the model tensor alone.
+
+DATA SAFETY
+  Generates its own synthetic inputs. Reads nothing from the corpus, writes nothing tracked.
+
+    uv run python scripts/resource_ceilings.py                  # cv2 + whatever is installed
+    uv run python scripts/resource_ceilings.py --max-mp 25      # push to 25 MP
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+REPO = Path(__file__).resolve().parents[1]
+_UV = shutil.which("uv") or "uv"
+
+# (label, width, height) -- 1 MP up to 25 MP, the range a phone photo upload spans.
+SIZES = (("1MP", 1000, 1000), ("4MP", 2000, 2000), ("12MP", 4000, 3000), ("25MP", 5000, 5000))
+
+# The child process: build an image, erase one small corner region, report peak RSS.
+# Kept as a string so each measurement is a genuinely fresh interpreter.
+_CHILD = """
+import json, resource, sys, time
+import numpy as np
+from remove_ai_watermarks.region_eraser import erase
+
+w, h, backend = int(sys.argv[1]), int(sys.argv[2]), sys.argv[3]
+rng = np.random.default_rng(0)
+# Textured, not flat: a flat image compresses and can let a backend shortcut work.
+img = rng.integers(0, 255, (h, w, 3), dtype=np.uint8)
+box = (w - 320, h - 90, 300, 70)   # a mark-sized corner region at every input size
+t0 = time.monotonic()
+try:
+    out = erase(img, boxes=[box], backend=backend)
+    # Assert the fill actually RAN. A wrong call signature or a silently-declining
+    # backend would otherwise report the process's numpy footprint as if it were the
+    # backend's cost -- the first version of this script did exactly that on all 12
+    # cells and the numbers looked plausible.
+    # Compare ONLY the mask box. A full-frame `(out != img).any()` allocates a boolean
+    # temp the size of the image BEFORE getrusage is read -- 75 MB at 25 MP, ~17% of the
+    # cv2 figure, and it GROWS with the input, so the harness would partly manufacture
+    # the very "cv2 scales with input size" conclusion it is measuring.
+    bx, by, bw_, bh_ = box
+    changed = int((out[by:by+bh_, bx:bx+bw_] != img[by:by+bh_, bx:bx+bw_]).any())
+    err = "" if changed else "NO-OP: backend did not modify the masked region"
+except Exception as e:
+    err = f"{type(e).__name__}: {e}"[:200]
+elapsed = time.monotonic() - t0
+peak_kb = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+print("RESULT" + json.dumps({"peak_kb": peak_kb, "sec": round(elapsed, 2), "error": err}))
+"""
+
+
+def peak_rss_mb(peak_kb: int) -> float:
+    """ru_maxrss is BYTES on macOS and KILOBYTES on Linux -- normalize to MB.
+
+    Getting this wrong silently reports 1024x off, which would look like a dramatic
+    finding rather than a unit bug.
+    """
+    return peak_kb / (1024 * 1024) if sys.platform == "darwin" else peak_kb / 1024
+
+
+def measure(backend: str, w: int, h: int, timeout: int = 900) -> dict[str, object] | None:
+    with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False) as fh:
+        fh.write(_CHILD)
+        child = fh.name
+    try:
+        p = subprocess.run(  # noqa: S603 -- fixed argv, our own child script
+            [_UV, "run", "python", child, str(w), str(h), backend],
+            cwd=REPO,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return {"error": f"TIMEOUT >{timeout}s", "sec": float(timeout), "peak_mb": float("nan")}
+    finally:
+        Path(child).unlink(missing_ok=True)
+
+    line = next((x for x in p.stdout.splitlines() if x.startswith("RESULT")), None)
+    if line is None:
+        return {"error": (p.stderr or p.stdout)[-200:], "sec": 0.0, "peak_mb": float("nan")}
+    data = json.loads(line[len("RESULT") :])
+    return {"error": data["error"], "sec": data["sec"], "peak_mb": round(peak_rss_mb(data["peak_kb"]), 1)}
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--max-mp", type=int, default=25, help="skip sizes above this megapixel count")
+    a = ap.parse_args()
+
+    from remove_ai_watermarks.region_eraser import lama_available, migan_available
+
+    backends = ["cv2"] + (["migan"] if migan_available() else []) + (["lama"] if lama_available() else [])
+    sizes = [s for s in SIZES if (s[1] * s[2]) / 1e6 <= a.max_mp + 0.5]
+    print(f"backends: {backends}\nsizes: {[s[0] for s in sizes]}")
+    print("\nOne FRESH process per cell; the mask is a fixed small corner at every size.")
+    print("If the learned backends really crop around the mask, RSS stays flat in input size.\n")
+
+    print(f"{'backend':8s} {'size':6s} {'peak RSS':>11s} {'wall':>8s}  note")
+    rows: list[tuple[str, str, dict[str, object]]] = []
+    for backend in backends:
+        for label, w, h in sizes:
+            r = measure(backend, w, h)
+            if r is None:
+                continue
+            rows.append((backend, label, r))
+            note = str(r["error"])[:48] or "ok"
+            print(f"{backend:8s} {label:6s} {r['peak_mb']:8} MB {r['sec']:7}s  {note}", flush=True)
+
+    print(f"\n{'=' * 72}\nRESOURCE CEILINGS\n{'=' * 72}")
+    for backend in backends:
+        cells = [(lbl, r) for b, lbl, r in rows if b == backend and not r["error"]]
+        if not cells:
+            continue
+        peaks = [float(r["peak_mb"]) for _, r in cells]  # type: ignore[arg-type]
+        lo, hi = min(peaks), max(peaks)
+        growth = "flat in input size" if hi <= lo * 1.6 else f"GROWS {hi / max(lo, 0.1):.1f}x with input size"
+        print(f"  {backend:6s} peak {lo:.0f}-{hi:.0f} MB across {cells[0][0]}..{cells[-1][0]}  -- {growth}")
+    print("\nRSS is the whole worker (interpreter + numpy + cv2 + any model), i.e. the")
+    print("number to size a container with, not the model tensor alone.")
+
+
+if __name__ == "__main__":
+    main()

scripts/robustness_suite.py

@@ -0,0 +1,341 @@
+"""Tier E: does the real CLI fail GRACEFULLY on adversarial and degenerate inputs?
+
+WHAT "PASS" MEANS HERE
+  Not "it succeeded" -- most of these inputs SHOULD be rejected. A pass is a graceful
+  outcome: a clear message, a sane exit code, and **no unhandled traceback**, within the
+  timeout. The failure modes this is hunting are the ones a user actually hits and that no
+  unit test covers, because unit tests feed well-formed fixtures:
+
+    * an unhandled traceback  -- the library crashed instead of reporting
+    * a hang                  -- worse than a crash for a batch caller
+    * a silent success on garbage -- it "processed" a corrupt file and wrote something
+
+  A non-zero exit with a readable error is a PASS. A Python traceback is a FAIL even when
+  the exit code looks tidy.
+
+WHY THESE INPUTS
+  Every case is drawn from something real: ~0.2% of corpus uploads are truncated, ~2% carry
+  a mismatched extension, Unicode filenames were issue #17, and a wrapping service will run
+  concurrent jobs against one path. Decompression bombs and absurd geometry are the cheap
+  denial-of-service shapes any tool taking user uploads must survive.
+
+DATA SAFETY
+  Builds its own inputs (synthetic, or truncated copies of committed fixtures) inside a
+  temp dir. Reads corpus images read-only for the one large-input case. Writes nothing
+  tracked.
+
+    uv run python scripts/robustness_suite.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import zlib
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+REPO = Path(__file__).resolve().parents[1]
+SAMPLES = REPO / "data" / "samples"
+_UV = shutil.which("uv") or "uv"
+
+# A traceback in the output means the failure escaped the error handling, whatever the
+# exit code says.
+_CRASH_MARKERS = ("Traceback (most recent call last)", "Fatal Python error", "Segmentation fault")
+
+
+class Results:
+    def __init__(self) -> None:
+        self.rows: list[tuple[str, str, bool, str, str]] = []
+
+    def add(self, case: str, cmd: str, ok: bool, detail: str, output: str = "") -> None:
+        self.rows.append((case, cmd, ok, detail, "" if ok else output[-600:]))
+        print(f"  [{'PASS' if ok else 'FAIL'}] {case:34s} {cmd:10s} {detail}", flush=True)
+
+    def report(self) -> int:
+        bad = [r for r in self.rows if not r[2]]
+        print(f"\n{'=' * 78}\nROBUSTNESS (Tier E)  {len(self.rows) - len(bad)}/{len(self.rows)} graceful")
+        print(f"{'=' * 78}")
+        for case, cmd, ok, detail, out in self.rows:
+            if not ok:
+                print(f"  FAIL  {case}  ({cmd})  {detail}")
+                for line in out.strip().splitlines()[-10:]:
+                    print(f"        {line}")
+        if not bad:
+            print("  every adversarial input was handled without a crash or a hang")
+        return 1 if bad else 0
+
+
+def run(args: list[str], timeout: int = 120) -> tuple[int, str, bool]:
+    """Returns (exit_code, output, timed_out)."""
+    try:
+        p = subprocess.run(  # noqa: S603 -- fixed argv, driving our own CLI on purpose
+            [_UV, "run", "remove-ai-watermarks", *args],
+            cwd=REPO,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return (-1, "", True)
+    return (p.returncode, p.stdout + p.stderr, False)
+
+
+def graceful(res: Results, case: str, cmd: str, args: list[str], timeout: int = 120) -> None:
+    """Run one adversarial case and score it on gracefulness, not on success."""
+    code, out, timed_out = run(args, timeout=timeout)
+    if timed_out:
+        res.add(case, cmd, False, f"HUNG (> {timeout}s)", out)
+        return
+    crashed = next((m for m in _CRASH_MARKERS if m in out), None)
+    if crashed:
+        res.add(case, cmd, False, f"unhandled {crashed} (exit {code})", out)
+        return
+    res.add(case, cmd, True, f"handled cleanly, exit {code}")
+
+
+def make_inputs(tmp: Path) -> dict[str, Path]:
+    """Build the adversarial corpus. Each entry is something a real upload can be."""
+    import numpy as np
+
+    from remove_ai_watermarks.image_io import imwrite
+
+    made: dict[str, Path] = {}
+
+    # A well-formed baseline, so a failure elsewhere is attributable to the input.
+    good = tmp / "good.png"
+    imwrite(good, np.full((600, 800, 3), 128, np.uint8))
+    made["good"] = good
+
+    # Truncated: a real PNG cut mid-stream (~0.2% of real uploads).
+    src = SAMPLES / "chatgpt-1.png"
+    if src.exists():
+        raw = src.read_bytes()
+        trunc = tmp / "truncated.png"
+        trunc.write_bytes(raw[: len(raw) // 3])
+        made["truncated"] = trunc
+
+    # Corrupt: correct magic bytes, garbage body.
+    corrupt = tmp / "corrupt.png"
+    corrupt.write_bytes(b"\x89PNG\r\n\x1a\n" + os.urandom(4096))
+    made["corrupt"] = corrupt
+
+    # Zero-byte file with a valid extension.
+    empty = tmp / "empty.png"
+    empty.write_bytes(b"")
+    made["empty"] = empty
+
+    # Not an image at all, but named like one.
+    text = tmp / "actually_text.jpg"
+    text.write_bytes(b"this is not an image, it is a text file pretending\n" * 50)
+    made["not_an_image"] = text
+
+    # Degenerate geometry: a 1x1, and a 1-pixel-tall sliver (the shape that once faulted
+    # cv2's GaussianBlur natively on Windows).
+    imwrite(tmp / "tiny.png", np.full((1, 1, 3), 200, np.uint8))
+    made["tiny_1x1"] = tmp / "tiny.png"
+    imwrite(tmp / "sliver.png", np.full((1, 4000, 3), 200, np.uint8))
+    made["sliver_1x4000"] = tmp / "sliver.png"
+
+    # Decompression bomb: a tiny file that decodes to a huge canvas. Hand-built so the
+    # on-disk size stays trivial while the declared dimensions are enormous.
+    bomb = tmp / "bomb.png"
+    bomb.write_bytes(_png_bomb(16000, 16000))
+    made["decompression_bomb"] = bomb
+
+    # Unicode + RTL filenames (issue #17 was Unicode-safe IO).
+    uni = tmp / "изображение-测试-🎨.png"
+    shutil.copy2(good, uni)
+    made["unicode_filename"] = uni
+    rtl = tmp / "صورة-اختبار.png"
+    shutil.copy2(good, rtl)
+    made["rtl_filename"] = rtl
+
+    # Mismatched extension: PNG content named .jpg (~2% of real uploads).
+    mismatch = tmp / "png_named_jpg.jpg"
+    shutil.copy2(good, mismatch)
+    made["mismatched_extension"] = mismatch
+
+    return made
+
+
+def _png_bomb(w: int, h: int) -> bytes:
+    """A valid PNG header declaring a huge canvas over highly-compressible data."""
+
+    def chunk(tag: bytes, data: bytes) -> bytes:
+        return len(data).to_bytes(4, "big") + tag + data + zlib.crc32(tag + data).to_bytes(4, "big")
+
+    ihdr = w.to_bytes(4, "big") + h.to_bytes(4, "big") + bytes([8, 2, 0, 0, 0])  # 8-bit RGB
+    raw = b"".join(b"\x00" + b"\x00" * (w * 3) for _ in range(h))
+    return b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr) + chunk(b"IDAT", zlib.compress(raw, 9)) + chunk(b"IEND", b"")
+
+
+def check_bad_inputs(res: Results, tmp: Path, inputs: dict[str, Path]) -> None:
+    print("\nmalformed and degenerate inputs -- every command must refuse, not crash")
+    out = tmp / "out.png"
+    for case in ("truncated", "corrupt", "empty", "not_an_image", "tiny_1x1", "sliver_1x4000"):
+        src = inputs.get(case)
+        if src is None:
+            continue
+        graceful(res, case, "identify", ["identify", str(src)])
+        graceful(res, case, "visible", ["visible", str(src), "-o", str(out)])
+        graceful(res, case, "metadata", ["metadata", str(src), "--check"])
+
+
+def check_bomb(res: Results, tmp: Path, inputs: dict[str, Path]) -> None:
+    print("\ndecompression bomb -- must not exhaust memory or hang")
+    bomb = inputs.get("decompression_bomb")
+    if bomb is None:
+        return
+    size_kb = bomb.stat().st_size / 1024
+    print(f"  (bomb is {size_kb:.0f} KB on disk, declares 16000x16000)")
+    graceful(res, "decompression_bomb", "identify", ["identify", str(bomb)], timeout=180)
+    graceful(res, "decompression_bomb", "visible", ["visible", str(bomb), "-o", str(tmp / "b.png")], timeout=180)
+
+
+def check_filenames(res: Results, tmp: Path, inputs: dict[str, Path]) -> None:
+    """Unicode/RTL paths must round-trip on BOTH read and write (issue #17)."""
+    print("\nunicode / RTL / mismatched-extension paths")
+    for case in ("unicode_filename", "rtl_filename", "mismatched_extension"):
+        src = inputs.get(case)
+        if src is None:
+            continue
+        # Write to a Unicode OUTPUT path too -- the read side alone does not prove the IO.
+        outp = tmp / f"вывод-{case}-📤.png"
+        code, out, timed = run(["identify", str(src)])
+        if timed or any(m in out for m in _CRASH_MARKERS):
+            res.add(case, "identify", False, "crashed or hung", out)
+        else:
+            res.add(case, "identify", True, f"read fine, exit {code}")
+        code, out, timed = run(["erase", str(src), "--region", "5,5,50,30", "-o", str(outp)])
+        wrote = outp.exists() and outp.stat().st_size > 0
+        crash = any(m in out for m in _CRASH_MARKERS)
+        res.add(case, "erase", wrote and not crash and not timed, f"unicode output written={wrote} exit={code}", out)
+
+
+def check_output_paths(res: Results, tmp: Path, inputs: dict[str, Path]) -> None:
+    print("\nhostile output paths")
+    good = inputs["good"]
+
+    # A nested output dir that does not exist yet -- the CLI should create it.
+    nested = tmp / "a" / "b" / "c" / "out.png"
+    code, out, timed = run(["erase", str(good), "--region", "5,5,40,20", "-o", str(nested)])
+    crash = any(m in out for m in _CRASH_MARKERS)
+    res.add(
+        "nonexistent_nested_outdir",
+        "erase",
+        nested.exists() and not crash and not timed,
+        f"created={nested.exists()} exit={code}",
+        out,
+    )
+
+    # A READ-ONLY output directory -- must report, not traceback.
+    ro = tmp / "readonly"
+    ro.mkdir(exist_ok=True)
+    ro.chmod(stat.S_IRUSR | stat.S_IXUSR)
+    try:
+        graceful(
+            res, "readonly_output_dir", "erase", ["erase", str(good), "--region", "5,5,40,20", "-o", str(ro / "x.png")]
+        )
+    finally:
+        ro.chmod(stat.S_IRWXU)  # restore so the temp dir can be cleaned up
+
+    # A directory where a file is expected.
+    graceful(res, "directory_as_input", "identify", ["identify", str(tmp)])
+
+    # A path that simply is not there.
+    graceful(res, "missing_input", "identify", ["identify", str(tmp / "nope.png")])
+
+
+def check_concurrency(res: Results, tmp: Path, inputs: dict[str, Path]) -> None:
+    """A wrapping service will run jobs in parallel against one input path."""
+    print("\nconcurrent runs against a single input")
+    good = inputs["good"]
+
+    def one(i: int) -> tuple[int, str, bool]:
+        return run(["erase", str(good), "--region", "5,5,40,20", "-o", str(tmp / f"conc_{i}.png")])
+
+    with ThreadPoolExecutor(max_workers=4) as ex:
+        outs = list(ex.map(one, range(4)))
+    crashed = [o for o in outs if any(m in o[1] for m in _CRASH_MARKERS) or o[2]]
+    all_written = all((tmp / f"conc_{i}.png").exists() for i in range(4))
+    res.add(
+        "4x concurrent on one input",
+        "erase",
+        not crashed and all_written,
+        f"{sum(1 for i in range(4) if (tmp / f'conc_{i}.png').exists())}/4 outputs, {len(crashed)} crashed",
+        "".join(o[1] for o in crashed),
+    )
+
+
+def check_batch_silent_loss(res: Results, tmp: Path, inputs: dict[str, Path]) -> None:
+    """The nastiest shape: NO output files AND a success exit code.
+
+    `graceful()` cannot see this class -- it scores exit code and traceback markers, and a
+    run that writes nothing while exiting 0 has neither. Corpus-reproduced 2026-07-20:
+    `batch --mode visible` into a read-only directory wrote 0 of 2 files and exited 0, so a
+    wrapping service would treat an empty output directory as a completed run. Any check
+    for a silent no-op must assert on the ARTIFACTS, not on the status.
+    """
+    print("\nbatch into a read-only output dir -- must NOT exit 0 with nothing written")
+    indir = tmp / "loss_in"
+    indir.mkdir(exist_ok=True)
+    for i in range(2):
+        shutil.copy2(inputs["good"], indir / f"img{i}.png")
+    ro = tmp / "loss_out"
+    ro.mkdir(exist_ok=True)
+    ro.chmod(stat.S_IRUSR | stat.S_IXUSR)
+    try:
+        code, out, timed = run(["batch", str(indir), "-o", str(ro)], timeout=180)
+        written = len(list(ro.glob("*")))
+    finally:
+        ro.chmod(stat.S_IRWXU)
+    ok = not timed and not (code == 0 and written == 0)
+    res.add(
+        "batch_readonly_outdir", "batch", ok, f"exit {code}, {written}/2 written (exit 0 + 0 files = data loss)", out
+    )
+
+
+def check_batch_edges(res: Results, tmp: Path) -> None:
+    print("\nbatch edge cases")
+    empty_dir = tmp / "empty_dir"
+    empty_dir.mkdir(exist_ok=True)
+    graceful(res, "batch_on_empty_dir", "batch", ["batch", str(empty_dir), "-o", str(tmp / "bo")])
+
+    # A directory of junk: nothing decodable, must not crash the whole run.
+    junk = tmp / "junk_dir"
+    junk.mkdir(exist_ok=True)
+    (junk / "a.png").write_bytes(b"\x89PNG\r\n\x1a\n" + os.urandom(500))
+    (junk / "b.jpg").write_bytes(b"not an image at all")
+    graceful(res, "batch_on_undecodable_dir", "batch", ["batch", str(junk), "-o", str(tmp / "jo")], timeout=180)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.parse_args()
+    res = Results()
+    with tempfile.TemporaryDirectory(prefix="raiw_robust_") as td:
+        tmp = Path(td)
+        print("building adversarial inputs...")
+        inputs = make_inputs(tmp)
+        print(f"built {len(inputs)} inputs\n")
+        check_bad_inputs(res, tmp, inputs)
+        check_bomb(res, tmp, inputs)
+        check_filenames(res, tmp, inputs)
+        check_output_paths(res, tmp, inputs)
+        check_concurrency(res, tmp, inputs)
+        check_batch_silent_loss(res, tmp, inputs)
+        check_batch_edges(res, tmp)
+    raise SystemExit(res.report())
+
+
+if __name__ == "__main__":
+    main()

scripts/sidecar_regression.py

@@ -0,0 +1,216 @@
+"""Tier A1: diff today's `identify` against the verdicts recorded in the corpus sidecars.
+
+`data/spaces/identify/<day>/<uid>.json` holds the verdict a past run produced for
+`data/spaces/originals/<day>/<uid>_src.<ext>`. Re-running identify and diffing turns the
+corpus into a ~39k-image behavioral regression suite that needs no new labelling.
+
+WHAT A DIFF MEANS -- READ THIS BEFORE PANICKING
+  The sidecars were written by OLDER versions, so an intended improvement shows up as a
+  diff exactly like a regression does. The output is therefore CLASSIFIED, not pass/fail:
+
+    lost_ai        verdict was AI, now is not          <- the alarm; almost always a bug
+    lost_signal    a signal family stopped firing      <- the alarm
+    new_ai         verdict was not AI, now is          <- usually an improvement
+    new_signal     a signal family started firing      <- usually an improvement
+    platform       attribution changed
+    confidence     confidence level changed
+    unchanged      identical on every compared axis
+
+  Only `lost_*` is a regression by default. Everything else needs a look before the
+  baseline is moved.
+
+WHY FAMILIES, NOT RAW STRINGS
+  Watermark descriptions are human-readable prose and their WORDING has changed between
+  versions ("C2PA Content Credentials (OpenAI)" vs "... (OpenAI, Truepic)"). Diffing raw
+  strings would report every rewording as a lost+new signal pair and bury the real
+  regressions. Signals are normalized to families (c2pa, synthid, visible_sparkle, ...)
+  so the comparison tracks BEHAVIOR, not phrasing.
+
+DATA SAFETY
+  Corpus images are user uploads: read-only, local analysis. Output goes to a gitignored
+  path under data/spaces/ and records uids, never image content.
+
+    uv run python scripts/sidecar_regression.py --sample 500     # representative trial
+    uv run python scripts/sidecar_regression.py                  # full corpus, resumable
+
+Use `--sample` for a trial, never `--limit`: the sidecar list is sorted by day, so
+`--limit N` reads only the EARLIEST day and its result does not generalize (the first
+trial run of this script took 200 files that were all 2026-05-29).
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import glob
+import json
+import os
+import random
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+REPO = Path(__file__).resolve().parents[1]
+IDENTIFY_DIR = REPO / "data" / "spaces" / "identify"
+ORIGINALS = REPO / "data" / "spaces" / "originals"
+OUT = REPO / "data" / "spaces" / "_sidecar_regression.jsonl"
+
+# Map a watermark description to a stable behavior family. Order matters: the first
+# matching pattern wins, so put the specific tokens above the generic ones.
+_FAMILIES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("synthid", ("synthid",)),
+    ("visible_sparkle", ("sparkle",)),
+    ("visible_doubao", ("豆包", "doubao")),
+    ("visible_jimeng", ("即梦", "jimeng")),
+    ("visible_samsung", ("galaxy ai", "generati dall")),
+    ("aigc_tc260", ("aigc", "tc260")),
+    ("iptc", ("iptc", "digitalsourcetype", "made with ai", "made-with-ai")),
+    ("c2pa", ("c2pa", "content credentials")),
+    ("trustmark", ("trustmark",)),
+    ("open_invisible", ("open invisible", "dwt", "stable diffusion xl")),
+    ("xai_signature", ("xai", "grok signature")),
+    ("exif_generator", ("exif", "software tag", "png text")),
+)
+
+
+def family_of(description: str) -> str:
+    low = description.lower()
+    for name, tokens in _FAMILIES:
+        if any(t in low for t in tokens):
+            return name
+    return "other"
+
+
+def families(descriptions: list[str]) -> set[str]:
+    return {family_of(d) for d in descriptions or []}
+
+
+def compare(sidecar: dict, report: object) -> dict:
+    """Classify the difference between a recorded verdict and a fresh one."""
+    old_ai, new_ai = sidecar.get("is_ai_generated"), getattr(report, "is_ai_generated", None)
+    old_fam = families(sidecar.get("watermarks") or [])
+    new_fam = families(list(getattr(report, "watermarks", []) or []))
+    old_plat, new_plat = sidecar.get("platform"), getattr(report, "platform", None)
+    old_conf, new_conf = sidecar.get("confidence"), getattr(report, "confidence", None)
+
+    classes: list[str] = []
+    # Treat only a real True->not-True transition as lost. None means "unknown", and the
+    # library never asserts False, so None->None is not a change.
+    if bool(old_ai) and not bool(new_ai):
+        classes.append("lost_ai")
+    if not bool(old_ai) and bool(new_ai):
+        classes.append("new_ai")
+    if old_fam - new_fam:
+        classes.append("lost_signal")
+    if new_fam - old_fam:
+        classes.append("new_signal")
+    if old_plat != new_plat:
+        classes.append("platform")
+    if old_conf != new_conf:
+        classes.append("confidence")
+
+    return {
+        "classes": classes or ["unchanged"],
+        "old_ai": old_ai,
+        "new_ai": new_ai,
+        "lost_families": sorted(old_fam - new_fam),
+        "new_families": sorted(new_fam - old_fam),
+        "old_platform": old_plat,
+        "new_platform": new_plat,
+        "old_confidence": old_conf,
+        "new_confidence": new_conf,
+    }
+
+
+def _one(sidecar_path: str) -> dict:
+    uid = os.path.basename(sidecar_path)[:-5]
+    day = os.path.basename(os.path.dirname(sidecar_path))
+    try:
+        with open(sidecar_path, encoding="utf-8") as fh:
+            sidecar = json.load(fh)
+    except Exception as e:  # a corrupt sidecar must not kill the sweep
+        return {"uid": uid, "day": day, "status": "sidecar_unreadable", "error": str(e)[:200]}
+
+    src = sidecar.get("src") or ""
+    image = ORIGINALS / day / src
+    if not src or not image.exists():
+        found = glob.glob(str(ORIGINALS / day / f"{uid}*"))
+        if not found:
+            return {"uid": uid, "day": day, "status": "image_missing"}
+        image = Path(found[0])
+
+    try:
+        from remove_ai_watermarks.identify import identify
+
+        report = identify(image)
+    except Exception as e:  # record and continue; a crash IS a finding
+        return {"uid": uid, "day": day, "status": "identify_raised", "error": f"{type(e).__name__}: {e}"[:300]}
+
+    return {"uid": uid, "day": day, "status": "ok", **compare(sidecar, report)}
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--limit", type=int, default=0, help="only N sidecars (trial run)")
+    ap.add_argument(
+        "--sample",
+        type=int,
+        default=0,
+        help="randomly sample N across ALL days -- use this for a trial, not --limit: "
+        "the sidecar list is sorted, so --limit takes one day and is not representative",
+    )
+    ap.add_argument("--workers", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--restart", action="store_true", help="ignore existing output and start over")
+    a = ap.parse_args()
+
+    sidecars = sorted(glob.glob(str(IDENTIFY_DIR / "*" / "*.json")))
+    if a.sample:
+        random.Random(7).shuffle(sidecars)  # noqa: S311 -- deterministic sampling, not crypto
+        sidecars = sorted(sidecars[: a.sample])
+    elif a.limit:
+        sidecars = sidecars[: a.limit]
+    if not sidecars:
+        raise SystemExit(f"no sidecars under {IDENTIFY_DIR}")
+
+    # Resume: a full sweep is ~1 h, so never redo work an interrupted run already did.
+    done: set[str] = set()
+    if a.restart and a.out.exists():
+        a.out.unlink()  # --restart must TRUNCATE; the file is reopened in append mode below
+    if a.out.exists() and not a.restart:
+        with open(a.out, encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    done.add(json.loads(line)["uid"])
+                except Exception:  # noqa: S112 -- tolerate a torn last line from an interrupted run
+                    continue
+    todo = [s for s in sidecars if os.path.basename(s)[:-5] not in done]
+    print(f"sidecars {len(sidecars)}  already done {len(done)}  to do {len(todo)}  workers {a.workers}")
+
+    counts: collections.Counter[str] = collections.Counter()
+    a.out.parent.mkdir(parents=True, exist_ok=True)
+    with open(a.out, "a", encoding="utf-8") as fh, ProcessPoolExecutor(max_workers=a.workers) as ex:
+        futures = {ex.submit(_one, s): s for s in todo}
+        for i, fut in enumerate(as_completed(futures), 1):
+            rec = fut.result()
+            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
+            if rec["status"] != "ok":
+                counts[rec["status"]] += 1
+            else:
+                for c in rec["classes"]:
+                    counts[c] += 1
+            if i % 500 == 0:
+                fh.flush()
+                print(f"  {i}/{len(todo)}  " + "  ".join(f"{k}={v}" for k, v in counts.most_common(6)), flush=True)
+
+    print(f"\n{'=' * 70}\nSIDECAR REGRESSION  processed={len(todo)}\n{'=' * 70}")
+    for k, v in counts.most_common():
+        flag = "  <-- REGRESSION" if k.startswith("lost_") or k in ("identify_raised",) else ""
+        print(f"  {k:22s} {v:7d}{flag}")
+    print(f"\nfull records: {a.out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/smoke_matrix.py

@@ -0,0 +1,621 @@
+"""Release smoke matrix: exercise every CLI parameter CHOICE on REAL data.
+
+Run before a release. This is not a unit-test substitute -- it drives the real CLI as a
+subprocess, so it covers argument parsing, exit-code semantics and the file-writing
+contracts that unit tests with fakes cannot.
+
+WHAT IT COVERS AND WHY THAT SHAPE
+  * Every choice-valued flag at least once (`--backend`, `--sensitivity`, `--mark`,
+    `--mode`, `--inpaint-method`, ...). Full permutation is combinatorially large and
+    mostly meaningless; dead branches and typos hide in the CHOICES, not in their
+    products.
+  * Every input FORMAT and shape edge case through the pixel paths -- PNG/JPEG/WebP/
+    HEIC/AVIF, alpha, unicode names, misnamed extensions, truncated files, tiny and
+    landscape frames. Real-world breakage lives here far more than in flag combos.
+  * CONTRACTS, not just exit codes: `visible` must write NO output and exit 2 when no
+    mark is found (re-serving the input reads as success -- the recurring "it didn't
+    work" report); a no-op must be byte-identical; `metadata --remove` must actually
+    strip; a JPEG strip must not touch the pixels. Note the pixel-lossless contract is
+    the DEFAULT path's -- `--remove-all` deliberately re-encodes (see metadata.py).
+  * The diffusion bodies under `--diffusion`, at `--max-resolution 512` so they fit MPS
+    (~1 min/image on 32 GB unified memory). Not just exit codes: `invisible` must
+    restore the input resolution and must NOT re-stamp SDXL's own open watermark.
+
+WHAT IT DOES NOT COVER, DELIBERATELY AND LOUDLY
+  * Without `--diffusion`, the model-running bodies are reported as SKIPPED with a
+    reason, never as passes -- a green run that quietly skipped half the surface is
+    worse than a red one.
+  * Removal STRENGTH is never certified here. Whether a watermark is actually gone
+    needs the per-vendor oracles (docs/known-limitations.md); these rows prove the
+    paths run and keep their contracts, nothing more.
+  * The re-embed row is gated on a POSITIVE CONTROL. imwatermark is positive-only and
+    fails to round-trip on some pristine carriers, so "no watermark found" proves
+    nothing there; the row degrades to a skip rather than a false pass.
+
+    uv run python scripts/smoke_matrix.py                 # corpus + fixtures
+    uv run python scripts/smoke_matrix.py --quick         # fixtures only, no corpus
+    uv run python scripts/smoke_matrix.py --diffusion     # + the SDXL model paths
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import random
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+SAMPLES = REPO / "data" / "samples"
+CORPUS = REPO / "data" / "spaces" / "originals"
+EXIT_NO_VISIBLE_MARK = 2
+
+
+def _capture(args: list[str]) -> str:
+    """Run the CLI and return stdout (for the rows that inspect output, not exit code)."""
+    exe = shutil.which("uv") or "uv"
+    p = subprocess.run(  # noqa: S603
+        [exe, "run", "remove-ai-watermarks", *args], capture_output=True, text=True, cwd=REPO, check=False
+    )
+    return p.stdout
+
+
+@dataclass
+class Result:
+    name: str
+    status: str  # pass | FAIL | skip
+    detail: str = ""
+    cmd: str = ""
+
+
+@dataclass
+class Runner:
+    tmp: Path
+    results: list[Result] = field(default_factory=list)
+
+    def run(self, name: str, args: list[str], *, expect_exit: int | None = 0, timeout: int = 180) -> Result:
+        exe = shutil.which("uv") or "uv"
+        cmd = [exe, "run", "remove-ai-watermarks", *args]
+        try:
+            p = subprocess.run(  # noqa: S603
+                cmd, capture_output=True, text=True, timeout=timeout, cwd=REPO, check=False
+            )
+        except subprocess.TimeoutExpired:
+            r = Result(name, "FAIL", f"timeout after {timeout}s", " ".join(args))
+            self.results.append(r)
+            return r
+        ok = expect_exit is None or p.returncode == expect_exit
+        detail = "" if ok else f"exit {p.returncode} (want {expect_exit}): {(p.stderr or p.stdout).strip()[-200:]}"
+        r = Result(name, "pass" if ok else "FAIL", detail, " ".join(args))
+        self.results.append(r)
+        return r
+
+    def check(self, name: str, ok: bool, detail: str = "") -> None:
+        self.results.append(Result(name, "pass" if ok else "FAIL", "" if ok else detail))
+
+    def skip(self, name: str, why: str) -> None:
+        self.results.append(Result(name, "skip", why))
+
+
+def corpus_pick(n: int, suffixes: tuple[str, ...]) -> list[Path]:
+    """Real uploads, chosen deterministically so a failure is reproducible."""
+    if not CORPUS.exists():
+        return []
+    pool = [p for p in CORPUS.glob("*/*") if p.suffix.lower() in suffixes]
+    random.Random(7).shuffle(pool)  # noqa: S311 -- deterministic sampling, not cryptography
+    return pool[:n]
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--quick", action="store_true", help="fixtures only; skip the corpus rows")
+    ap.add_argument(
+        "--diffusion", action="store_true", help="also run the model-running paths (SDXL weights, ~1 min/image)"
+    )
+    a = ap.parse_args()
+
+    tmp = Path(tempfile.mkdtemp(prefix="raiw-smoke-"))
+    r = Runner(tmp)
+    doubao = SAMPLES / "doubao-1.png"
+    chatgpt = SAMPLES / "chatgpt-1.png"
+    grok = SAMPLES / "grok-1.jpg"
+
+    # ---- identify: every flag, and JSON must actually parse -------------------
+    r.run("identify plain", ["identify", str(doubao)])
+    r.run("identify --no-visible", ["identify", str(doubao), "--no-visible"])
+    try:
+        json.loads(_capture(["identify", str(doubao), "--json"]))
+        r.check("identify --json parses", True)
+    except Exception as e:
+        r.check("identify --json parses", False, str(e))
+
+    # ---- metadata: check/remove, and the strip must be REAL ------------------
+    r.run("metadata --check", ["metadata", str(doubao), "--check"])
+    out = tmp / "meta.png"
+    r.run("metadata --remove", ["metadata", str(doubao), "--remove", "-o", str(out)])
+    if out.exists():
+        try:
+            rep = json.loads(_capture(["identify", str(out), "--json"]))
+            # Scope the assert to METADATA. doubao-1 also carries a visible pixel mark,
+            # which `metadata --remove` must NOT touch -- demanding an empty watermark
+            # list would fail on correct behavior (and hide a real metadata leak behind
+            # a permanently-red row).
+            leftover = [s for s in rep.get("signals", []) if not s.get("name", "").startswith("visible_")]
+            r.check(
+                "metadata --remove strips every metadata signal",
+                not leftover and not rep.get("ai_from_metadata"),
+                f"still reports metadata signals {[s.get('name') for s in leftover]}",
+            )
+            r.check(
+                "metadata --remove leaves the visible mark alone",
+                any(s.get("name", "").startswith("visible_") for s in rep.get("signals", [])),
+                "the pixel mark vanished -- a metadata strip must not touch pixels",
+            )
+        except Exception as e:
+            r.check("metadata --remove strips every metadata signal", False, str(e))
+
+    # The pixel-lossless contract belongs to the DEFAULT path. `--remove-all`
+    # (keep_standard=False) deliberately falls through to the full PIL re-encode
+    # (metadata.py: the lossless marker walk preserves standard segments, so it cannot
+    # serve a strip-everything caller), which is lossy for JPEG -- measured ~49 dB.
+    # Asserting losslessness there tested a contract the code never made.
+    import numpy as np
+
+    from remove_ai_watermarks.image_io import imread
+
+    out2 = tmp / "meta2.jpg"
+    r.run("metadata --remove (jpeg, default)", ["metadata", str(grok), "--remove", "-o", str(out2)])
+    if out2.exists():
+        a_, b_ = imread(str(grok)), imread(str(out2))
+        same = a_ is not None and b_ is not None and a_.shape == b_.shape and bool(np.array_equal(a_, b_))
+        r.check("jpeg metadata strip is pixel-lossless", same, "pixels changed -- the strip re-encoded")
+    out3 = tmp / "meta3.jpg"
+    r.run("metadata --remove --remove-all (jpeg)", ["metadata", str(grok), "--remove", "--remove-all", "-o", str(out3)])
+    if out3.exists():
+        rep3 = json.loads(_capture(["identify", str(out3), "--json"]))
+        r.check(
+            "--remove-all strips the AI metadata too",
+            not [s for s in rep3.get("signals", []) if not s.get("name", "").startswith("visible_")],
+            f"still reports {rep3.get('signals')}",
+        )
+
+    # ---- visible: every --mark choice, every --backend, every --sensitivity ---
+    for mark in ("auto", "gemini", "doubao", "jimeng", "samsung", "jimeng_pill"):
+        # doubao-1 carries only the doubao mark, so every other --mark must exit 2
+        want = 0 if mark in ("auto", "doubao") else EXIT_NO_VISIBLE_MARK
+        r.run(
+            f"visible --mark {mark}",
+            ["visible", str(doubao), "--mark", mark, "-o", str(tmp / f"m_{mark}.png")],
+            expect_exit=want,
+        )
+    # Every backend CHOICE, not just the two that need no extra. migan/lama were
+    # measured at library level (scripts/fill_quality.py) but had never been driven
+    # through the CLI, which is a different code path (resolve_backend + the warning).
+    from remove_ai_watermarks.region_eraser import lama_available, migan_available
+
+    for backend in ("auto", "cv2", "migan", "lama"):
+        have = {"migan": migan_available(), "lama": lama_available()}.get(backend, True)
+        if not have:
+            r.skip(f"visible --backend {backend}", f"the `{backend}` extra is not installed")
+            continue
+        r.run(
+            f"visible --backend {backend}",
+            ["visible", str(doubao), "--backend", backend, "-o", str(tmp / f"b_{backend}.png")],
+            timeout=600,
+        )
+    for sens in ("auto", "strict"):
+        r.run(
+            f"visible --sensitivity {sens}",
+            ["visible", str(doubao), "--sensitivity", sens, "-o", str(tmp / f"s_{sens}.png")],
+        )
+    r.run("visible --keep-metadata", ["visible", str(doubao), "--keep-metadata", "-o", str(tmp / "keep.png")])
+    r.run("visible --no-detect (forced)", ["visible", str(doubao), "--no-detect", "-o", str(tmp / "force.png")])
+    for removed in ("assume-ai", "aggressive"):
+        r.run(
+            f"visible rejects --sensitivity {removed}",
+            ["visible", str(doubao), "--sensitivity", removed],
+            expect_exit=2,
+        )
+
+    # CONTRACT: no mark -> no output file, exit 2 (never re-serve the input as success)
+    noout = tmp / "must_not_exist.png"
+    r.run("visible no-mark exits 2", ["visible", str(chatgpt), "-o", str(noout)], expect_exit=EXIT_NO_VISIBLE_MARK)
+    r.check("visible no-mark writes NO output", not noout.exists(), "wrote an output for an undetected mark")
+
+    # ---- erase: backends, methods, repeated regions, dilate ------------------
+    for method in ("telea", "ns"):
+        r.run(
+            f"erase --inpaint-method {method}",
+            [
+                "erase",
+                str(doubao),
+                "--region",
+                "10,10,60,30",
+                "--inpaint-method",
+                method,
+                "-o",
+                str(tmp / f"e_{method}.png"),
+            ],
+        )
+    r.run(
+        "erase repeated --region",
+        ["erase", str(doubao), "--region", "10,10,40,20", "--region", "80,80,40,20", "-o", str(tmp / "e_multi.png")],
+    )
+    r.run(
+        "erase --dilate",
+        ["erase", str(doubao), "--region", "10,10,40,20", "--dilate", "5", "-o", str(tmp / "e_dil.png")],
+    )
+    for backend in ("cv2", "migan", "lama"):
+        have = {"migan": migan_available(), "lama": lama_available()}.get(backend, True)
+        if not have:
+            r.skip(f"erase --backend {backend}", f"the `{backend}` extra is not installed")
+            continue
+        r.run(
+            f"erase --backend {backend}",
+            [
+                "erase",
+                str(doubao),
+                "--region",
+                "10,10,40,20",
+                "--backend",
+                backend,
+                "-o",
+                str(tmp / f"e_{backend}.png"),
+            ],
+            timeout=600,
+        )
+    r.run(
+        "erase --dilate 0 (no dilation)",
+        ["erase", str(doubao), "--region", "10,10,40,20", "--dilate", "0", "-o", str(tmp / "e_d0.png")],
+    )
+    r.run("erase rejects a malformed --region", ["erase", str(doubao), "--region", "not,a,box"], expect_exit=2)
+
+    # ---- global + explicit-default flags that had never been exercised -------
+    r.run("--verbose", ["--verbose", "identify", str(doubao)])
+    r.run("--version", ["--version"])
+    r.run("metadata --keep-standard (explicit)", ["metadata", str(doubao), "--check", "--keep-standard"])
+    r.run(
+        "visible --strip-metadata (explicit)",
+        ["visible", str(doubao), "--strip-metadata", "-o", str(tmp / "sm.png")],
+    )
+    r.run("visible --detect (explicit default)", ["visible", str(doubao), "--detect", "-o", str(tmp / "det.png")])
+
+    # ---- batch: the non-diffusion modes -------------------------------------
+    bd = tmp / "batch_in"
+    bd.mkdir()
+    for f in (doubao, chatgpt):
+        shutil.copy(f, bd / f.name)
+    for mode in ("visible", "metadata"):
+        r.run(
+            f"batch --mode {mode}",
+            ["batch", str(bd), "--mode", mode, "-o", str(tmp / f"batch_{mode}")],
+            expect_exit=None,
+        )
+
+    # ---- diffusion: argument handling always; the model body under --diffusion ----
+    r.run("invisible --help parses full knob set", ["invisible", "--help"])
+    r.run("all --help parses full knob set", ["all", "--help"])
+    _media_rows(r, tmp)
+    if a.diffusion:
+        _diffusion_rows(r, tmp, doubao)
+    else:
+        for name in ("invisible", "all", "batch --mode invisible"):
+            r.skip(f"{name} (model-running body)", "pass --diffusion to exercise it (needs the SDXL weights)")
+
+    # ---- real-data formats and shapes ---------------------------------------
+    if not a.quick:
+        picks: list[tuple[str, Path]] = []
+        for suf, label in ((".heic", "heic"), (".avif", "avif"), (".webp", "webp"), (".jpeg", "jpeg")):
+            picks += [(label, p) for p in corpus_pick(2, (suf,))]
+        picks += [("png", p) for p in corpus_pick(3, (".png",))]
+        if not picks:
+            r.skip("real-format rows", "corpus not present (data/spaces/originals)")
+        for label, p in picks:
+            r.run(f"identify real {label}", ["identify", str(p), "--json"])
+            r.run(
+                f"visible auto real {label}",
+                ["visible", str(p), "-o", str(tmp / f"r_{label}_{p.stem[:8]}.png")],
+                expect_exit=None,
+            )  # 0 or 2 are both correct; a CRASH is not
+
+        # unicode + misnamed extension + truncated: the documented real-world traps
+        if picks:
+            src = picks[0][1]
+            uni = tmp / "тест изображение 测试.png"
+            shutil.copy(src, uni)
+            r.run("unicode filename", ["identify", str(uni), "--json"])
+            mis = tmp / "actually_png.jpg"  # content PNG, extension JPEG
+            shutil.copy(SAMPLES / "chatgpt-1.png", mis)
+            r.run("misnamed extension", ["identify", str(mis), "--json"])
+            trunc = tmp / "truncated.png"
+            trunc.write_bytes((SAMPLES / "chatgpt-1.png").read_bytes()[:4096])
+            r.run("truncated file does not crash", ["identify", str(trunc), "--json"], expect_exit=None)
+
+    # ---- report --------------------------------------------------------------
+    bad = [x for x in r.results if x.status == "FAIL"]
+    skipped = [x for x in r.results if x.status == "skip"]
+    ok = [x for x in r.results if x.status == "pass"]
+    print(f"\n{'=' * 74}\nSMOKE MATRIX  pass={len(ok)}  FAIL={len(bad)}  skipped={len(skipped)}\n{'=' * 74}")
+    for x in skipped:
+        print(f"  SKIP  {x.name:46s} {x.detail}")
+    for x in bad:
+        print(f"  FAIL  {x.name:46s} {x.detail}")
+        if x.cmd:
+            print(f"        cmd: {x.cmd}")
+    if not bad:
+        print("  no failures")
+    print(f"\ntmp artifacts: {tmp}")
+    raise SystemExit(1 if bad else 0)
+
+
+def _knob_rows(r: Runner, tmp: Path, img: Path) -> None:
+    """Every diffusion knob the matrix never touched.
+
+    Deliberately cheap (`--steps 4`, `--max-resolution 384`): these rows answer "is the
+    knob accepted and does the run complete", NOT "is the output good". Quality per knob
+    needs a per-knob oracle and most of them have none (`--humanize` has no oracle at
+    all), so claiming more here would be dishonest.
+    """
+    from remove_ai_watermarks import upscaler
+
+    # --steps 20 is the floor that WORKS, not an arbitrary choice: effective timesteps
+    # are int(steps * strength), so at the default strength 0.15 anything below
+    # --steps 7 rounds to ZERO and the pipeline dies inside torch. The first version of
+    # these rows used --steps 4 and every single one failed with the same reshape error.
+    fast = ["--max-resolution", "384", "--min-resolution", "0", "--steps", "20", "--force", "--seed", "0"]
+
+    def run(name: str, extra: list[str], *, tag: str, expect: int | None = 0) -> None:
+        r.run(
+            name,
+            ["invisible", str(img), "-o", str(tmp / f"k_{tag}.png"), *fast, *extra],
+            expect_exit=expect,
+            timeout=2400,
+        )
+
+    run("--pipeline sdxl", ["--pipeline", "sdxl"], tag="sdxl")
+    run("--pipeline controlnet", ["--pipeline", "controlnet"], tag="cnet")
+    run("--strength", ["--strength", "0.2"], tag="strength")
+    run("--guidance-scale", ["--guidance-scale", "5.0"], tag="gs")
+    run("--controlnet-scale", ["--controlnet-scale", "0.5"], tag="cns")
+    run("--humanize", ["--humanize", "0.3"], tag="hum")
+    run("--unsharp", ["--unsharp", "0.5"], tag="uns")
+    run("--no-adaptive-polish", ["--no-adaptive-polish"], tag="nap")
+    run("--tile", ["--tile", "--tile-size", "256", "--tile-overlap", "64"], tag="tile")
+    run("--device mps", ["--device", "mps"], tag="mps")
+    run("--upscaler lanczos", ["--upscaler", "lanczos"], tag="lanczos")
+    run("--auto (deprecated no-op)", ["--auto"], tag="auto")
+
+    if upscaler.is_available():
+        run("--upscaler esrgan", ["--upscaler", "esrgan"], tag="esrgan")
+    else:
+        r.skip("--upscaler esrgan", "the `esrgan` extra is not installed")
+
+    # CPU is correctness-relevant (it is the documented MPS-OOM fallback) but slow, so
+    # it gets the smallest possible run rather than being skipped.
+    r.run(
+        "--device cpu",
+        [
+            "invisible",
+            str(img),
+            "-o",
+            str(tmp / "k_cpu.png"),
+            "--device",
+            "cpu",
+            "--max-resolution",
+            "256",
+            "--min-resolution",
+            "0",
+            "--steps",
+            "20",
+            "--force",
+            "--seed",
+            "0",
+        ],
+        timeout=3600,
+    )
+
+    # qwen is CUDA-class by design (bf16 MMDiT, no MPS fallback). On this host the
+    # honest outcome is a CLEAN failure, not a crash -- assert it does not hang or
+    # dump a traceback at the user.
+    try:
+        import torch
+
+        cuda = bool(torch.cuda.is_available())
+    except Exception:
+        cuda = False
+    if cuda:
+        run("--pipeline qwen", ["--pipeline", "qwen"], tag="qwen")
+    else:
+        r.skip("--pipeline qwen", "CUDA-class pipeline; no CUDA device on this host")
+
+    # --model and --hf-token are deliberately not exercised: one would download a second
+    # multi-GB checkpoint, the other needs a real credential. Skipped loudly, not passed.
+    r.skip("--model", "would download a second multi-GB checkpoint")
+    r.skip("--hf-token", "needs a real credential; cannot be exercised meaningfully here")
+
+    # CONTRACT, not just execution: the same seed must reproduce the same pixels.
+    a_out, b_out = tmp / "seed_a.png", tmp / "seed_b.png"
+    for out in (a_out, b_out):
+        r.run(
+            f"seed determinism run ({out.name})",
+            ["invisible", str(img), "-o", str(out), *fast],
+            timeout=2400,
+        )
+    if a_out.exists() and b_out.exists():
+        import numpy as np
+
+        from remove_ai_watermarks.image_io import imread
+
+        x, y = imread(str(a_out)), imread(str(b_out))
+        r.check(
+            "same --seed reproduces identical pixels",
+            x is not None and y is not None and x.shape == y.shape and bool(np.array_equal(x, y)),
+            "two runs with the same seed differed",
+        )
+
+
+def _media_rows(r: Runner, tmp: Path) -> None:
+    """Audio/video metadata strip via ffmpeg -- a supported path with no corpus coverage.
+
+    The corpus is images only, so the media is synthesized here with ffmpeg rather than
+    left untested.
+    """
+    if not shutil.which("ffmpeg"):
+        r.skip("audio/video metadata strip", "ffmpeg not on PATH")
+        return
+    for name, gen in (
+        ("mp4", ["-f", "lavfi", "-i", "testsrc=duration=1:size=128x128:rate=8", "-pix_fmt", "yuv420p"]),
+        ("mp3", ["-f", "lavfi", "-i", "sine=frequency=440:duration=1"]),
+    ):
+        src = tmp / f"media.{name}"
+        ff = shutil.which("ffmpeg") or "ffmpeg"
+        made = subprocess.run(  # noqa: S603
+            [ff, "-y", *gen, "-metadata", "comment=Made with AI", str(src)],
+            capture_output=True,
+            check=False,
+        )
+        if made.returncode != 0 or not src.exists():
+            r.skip(f"{name} metadata strip", "ffmpeg could not synthesize the fixture")
+            continue
+        out = tmp / f"media_clean.{name}"
+        r.run(f"{name} metadata strip runs", ["metadata", str(src), "--remove", "-o", str(out)], expect_exit=None)
+        if out.exists():
+            r.check(f"{name} strip produced a non-empty file", out.stat().st_size > 0, "empty output")
+
+
+def _sdxl_watermark_bits(img: object) -> float:
+    """Bits of the open SDXL DWT-DCT watermark recovered from `img` (128 = perfect)."""
+    import numpy as np
+    from imwatermark import WatermarkDecoder
+
+    truth = np.frombuffer(b"StableDiffusionV1"[:16], dtype=np.uint8)
+    rec = WatermarkDecoder("bytes", 128).decode(img, "dwtDct")
+    return float(128 - np.unpackbits(truth ^ np.frombuffer(bytes(rec), dtype=np.uint8)).sum())
+
+
+def _diffusion_rows(r: Runner, tmp: Path, doubao: Path) -> None:
+    """Exercise the model-running bodies at a reduced resolution (MPS-friendly).
+
+    Bounded with `--max-resolution 512` and a fixed seed: the point is that the paths
+    RUN and keep their contracts, not to certify removal strength (that needs the
+    per-vendor oracles, see docs/known-limitations.md).
+    """
+    import numpy as np
+
+    from remove_ai_watermarks.image_io import imread
+
+    small = ["--max-resolution", "512", "--seed", "0"]
+
+    # `invisible` must restore the original resolution and NOT re-stamp SDXL's own
+    # open watermark (add_watermarker=False; a remover that re-marks its output is the
+    # regression this row exists for).
+    #
+    # The carrier matters: imwatermark is positive-only and fails to round-trip on some
+    # pristine images, so an "absent" verdict on a fragile carrier proves NOTHING. mj-1
+    # is used because it round-trips at 128/128; the control is re-checked on the actual
+    # OUTPUT and the row degrades to a skip rather than a false pass if it goes fragile.
+    mj = SAMPLES / "mj-1.png"
+    inv = tmp / "inv_mj.png"
+    res = r.run("invisible runs (mps, 512px)", ["invisible", str(mj), "-o", str(inv), "--force", *small], timeout=1800)
+    if res.status == "pass" and inv.exists():
+        src_img, out_img = imread(str(mj)), imread(str(inv))
+        r.check(
+            "invisible restores the input resolution",
+            src_img is not None and out_img is not None and src_img.shape == out_img.shape,
+            f"{None if src_img is None else src_img.shape} -> {None if out_img is None else out_img.shape}",
+        )
+        try:
+            from imwatermark import WatermarkEncoder
+
+            enc = WatermarkEncoder()
+            enc.set_watermark("bytes", b"StableDiffusionV1"[:16])
+            control = _sdxl_watermark_bits(enc.encode(np.array(out_img).copy(), "dwtDct"))
+            if control < 118:
+                r.skip("invisible does not re-embed an SDXL watermark", f"carrier fragile (control {control:.0f}/128)")
+            else:
+                bits = _sdxl_watermark_bits(out_img)
+                r.check(
+                    "invisible does not re-embed an SDXL watermark",
+                    bits < 118,
+                    f"re-embedded: {bits:.0f}/128 recovered (control {control:.0f}/128)",
+                )
+        except ImportError:
+            r.skip("invisible does not re-embed an SDXL watermark", "imwatermark absent (extra `detect`)")
+
+    # `all`: every stage must land -- the visible mark AND the metadata both gone.
+    allout = tmp / "all_out.png"
+    res = r.run("all runs (mps, 512px)", ["all", str(doubao), "-o", str(allout), *small], timeout=1800)
+    if res.status == "pass" and allout.exists():
+        rep = json.loads(_capture(["identify", str(allout), "--json"]))
+        r.check(
+            "all clears visible + metadata in one pass",
+            not rep.get("signals"),
+            f"still reports {[s.get('name') for s in rep.get('signals', [])]}",
+        )
+
+    _knob_rows(r, tmp, mj)
+
+    # `batch --mode invisible`: every input must produce an output (a silent short
+    # write is the failure this row guards).
+    bd = tmp / "batch_inv"
+    bd.mkdir(exist_ok=True)
+    for f in (SAMPLES / "chatgpt-2.png", mj):
+        shutil.copy(f, bd / f.name)
+    bout = tmp / "batch_inv_out"
+    res = r.run(
+        "batch --mode invisible runs (mps, 512px)",
+        ["batch", str(bd), "--mode", "invisible", "-o", str(bout), *small],
+        expect_exit=None,
+        timeout=3600,
+    )
+    if res.status == "pass":
+        produced = len(list(bout.glob("*"))) if bout.exists() else 0
+        r.check("batch invisible writes one output per input", produced == 2, f"{produced} outputs for 2 inputs")
+
+    # `batch --mode all` -- the only --mode value the matrix never ran.
+    aout = tmp / "batch_all_out"
+    r.run(
+        "batch --mode all runs (mps, 512px)",
+        ["batch", str(bd), "--mode", "all", "-o", str(aout), *small],
+        expect_exit=None,
+        timeout=3600,
+    )
+
+    # The AI-enhanced composite path: regenerate ONLY a region and feather it back,
+    # leaving everything outside the box pixel-exact. Library-level -- the CLI has no
+    # flag for it, so it would otherwise never be exercised on real data.
+    try:
+        import numpy as np
+
+        from remove_ai_watermarks.image_io import imread
+        from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
+
+        src = imread(str(mj))
+        h, w = src.shape[:2]
+        box = (w // 4, h // 4, w // 4, h // 4)
+        rem = WatermarkRemover(pipeline="controlnet")
+        rout = tmp / "region_composite.png"
+        rem.remove_watermark(mj, rout, strength=0.15, num_inference_steps=20, seed=0, region=box)
+        got = imread(str(rout))
+        if got is None or got.shape != src.shape:
+            r.check("region composite keeps the frame outside the box", False, "shape changed or unreadable")
+        else:
+            mask = np.ones(src.shape[:2], dtype=bool)
+            x, y, bw, bh = box
+            # Outside the box PLUS the feather margin must be untouched.
+            pad = 96
+            mask[max(0, y - pad) : y + bh + pad, max(0, x - pad) : x + bw + pad] = False
+            r.check(
+                "region composite keeps the frame outside the box",
+                bool(np.array_equal(src[mask], got[mask])),
+                "pixels changed outside the regenerated region",
+            )
+    except Exception as e:
+        r.skip("region composite (remove_watermark(region=...))", f"{type(e).__name__}: {e}"[:120])
+
+
+if __name__ == "__main__":
+    main()

scripts/vendor_cohort_harvest.py

@@ -0,0 +1,241 @@
+"""Partition China-AIGC carriers into VENDOR COHORTS by their TC260 producer code.
+
+THE PROBLEM THIS SOLVES
+  Coverage of uncovered vendors is the largest remaining detection lever
+  (`docs/verification-plan.md`, "Where detection work should go next"), and it is
+  blocked on EVIDENCE: nothing may be registered off a single frame, and the
+  previous session found exactly one confirmed positive each for `千问` and `百度`.
+  Harvesting more by PIXELS is circular -- a detector is what we are trying to
+  build -- and the generic shared-tail probe is too weak to label with (0.407 on a
+  bold positive against a clean p99 of 0.298; see `cjk_tail_probe.py`).
+
+THE KEY
+  The TC260 label is not anonymous. Its `ContentProducer` field carries the
+  producer's Chinese Unified Social Credit Code (USCC), e.g.
+  ``001191110102MACQD9K64010000`` -> USCC ``91110102MACQD9K640``, which names a
+  specific legal entity. So the metadata partitions carriers into per-ENTITY
+  cohorts without looking at a single pixel. A cohort is a LABEL: once one frame
+  in it is eyeballed, every frame in it is a labelled example of that vendor's
+  mark. That is what turns "one confirmed positive" into "30+ per vendor".
+
+  CLAUDE.md's "the generic TC260 label names no specific vendor" is about the
+  label MARKER (the bare presence of `TC260:AIGC`), which indeed names nobody.
+  The producer FIELD inside the block is a different thing and does name one.
+
+  Caveat kept in view: the code names the SIGNING ENTITY, which is not always the
+  consumer brand (an aggregator or a cloud host signs for several apps, and one
+  vendor can hold several codes). So a cohort is a strong grouping key and a
+  hypothesis about the brand -- the brand itself is settled by reading the crop,
+  which is what `--sheets` is for.
+
+WHAT IT COSTS
+  Metadata only. The expensive pixel pass is NOT re-run: which detectors fired is
+  joined from `_visible_positives.jsonl` (the completed full-corpus artifact), per
+  the standing rule against relaunching finished sweeps to re-check them.
+
+DATA SAFETY
+  Corpus images are real user uploads: read-only, local analysis, gitignored
+  output. Contact sheets stay under `data/spaces/`; nothing here is committed.
+
+    uv run python scripts/vendor_cohort_harvest.py
+    uv run python scripts/vendor_cohort_harvest.py --report-only --sheets 12
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import sys
+from collections import Counter
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent))
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS = REPO / "data" / "spaces" / "originals"
+OUT = REPO / "data" / "spaces" / "_vendor_cohorts.jsonl"
+FIRED = REPO / "data" / "spaces" / "_visible_positives.jsonl"
+SHEET_DIR = REPO / "data" / "spaces" / "_vendor_cohort_sheets"
+
+# A producer code is `001` + `1` + USCC(18) + a 5-digit app/product suffix, so two
+# codes sharing the USCC are the same legal entity registering different products.
+# Slicing is defensive: anything not matching the layout is grouped by its raw value.
+_USCC_START, _USCC_END = 4, 22
+
+
+def uscc_of(code: str) -> str:
+    """The 18-char Unified Social Credit Code embedded in a TC260 producer code."""
+    if len(code) >= _USCC_END and code[:3] == "001":
+        return code[_USCC_START:_USCC_END]
+    return code
+
+
+def _one(path_str: str) -> dict[str, Any] | None:
+    from remove_ai_watermarks.metadata import aigc_label
+
+    try:
+        label = aigc_label(Path(path_str))
+    except Exception:
+        return None
+    if not label:
+        return None
+    producer = str(label.get("ContentProducer") or "")
+    return {
+        "path": path_str,
+        "producer": producer,
+        "uscc": uscc_of(producer),
+        "propagator": str(label.get("ContentPropagator") or ""),
+        "service_provider": str(label.get("ServiceProvider") or ""),
+    }
+
+
+def load_fired() -> dict[str, list[str]]:
+    """path -> detector keys that fired, from the completed full-corpus artifact."""
+    if not FIRED.exists():
+        print(f"WARNING: {FIRED.name} missing; cohorts will show no detector state")
+        return {}
+    out: dict[str, list[str]] = {}
+    for line in FIRED.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        rec = json.loads(line)
+        out[rec["path"]] = rec.get("keys") or []
+    return out
+
+
+def scan(limit: int, workers: int, out_path: Path) -> list[dict[str, Any]]:
+    pool = sorted(glob.glob(str(CORPUS / "*" / "*")))
+    if limit:
+        pool = pool[:limit]
+    print(f"scanning {len(pool)} corpus files for TC260 labels  workers={workers}", flush=True)
+    rows: list[dict[str, Any]] = []
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(out_path, "w", encoding="utf-8") as fh, ProcessPoolExecutor(max_workers=workers) as ex:
+        futures = [ex.submit(_one, p) for p in pool]
+        for i, fut in enumerate(as_completed(futures), 1):
+            try:
+                rec = fut.result()
+            except Exception:  # noqa: S112 -- one bad file must not kill the scan
+                continue
+            if rec is not None:
+                fh.write(json.dumps(rec) + "\n")
+                rows.append(rec)
+            if i % 5000 == 0:
+                fh.flush()
+                print(f"  {i}/{len(pool)}  carriers={len(rows)}", flush=True)
+    return rows
+
+
+def report(rows: list[dict[str, Any]], fired: dict[str, list[str]], min_size: int) -> None:
+    by_uscc: dict[str, list[dict[str, Any]]] = {}
+    for r in rows:
+        by_uscc.setdefault(r["uscc"], []).append(r)
+
+    print(f"\n{'=' * 92}\nVENDOR COHORTS  ({len(rows)} TC260 carriers, {len(by_uscc)} distinct entities)\n{'=' * 92}")
+    print("\n`fires` = share of the cohort where SOME registered detector fires.")
+    print("A large cohort with a low fire rate is an uncovered vendor -- the harvest target.\n")
+    print(f"{'entity (USCC)':22s} {'n':>6s} {'fires':>7s}  {'detectors seen':38s} {'products':>8s}")
+    print("-" * 92)
+
+    cohorts = sorted(by_uscc.items(), key=lambda kv: -len(kv[1]))
+    for uscc, members in cohorts:
+        if len(members) < min_size:
+            continue
+        keys: Counter[str] = Counter()
+        hit = 0
+        for m in members:
+            ks = fired.get(m["path"], [])
+            if ks:
+                hit += 1
+            keys.update(ks)
+        seen = ", ".join(f"{k}:{c}" for k, c in keys.most_common(4)) or "-- none --"
+        products = len({m["producer"] for m in members})
+        print(f"{uscc:22s} {len(members):6d} {100 * hit / len(members):6.1f}%  {seen:38s} {products:8d}")
+
+    small = sum(1 for _, m in cohorts if len(m) < min_size)
+    if small:
+        print(f"\n({small} cohorts below --min-size {min_size} not shown)")
+
+
+def _bands(img: Any, width: int, band: int) -> list[Any]:
+    """Full-width top and bottom bands, scaled to a readable common width.
+
+    An unregistered vendor's placement is unknown, so cropping the bottom-RIGHT
+    corner (where the marks we already cover happen to sit) would beg the
+    question. Full-width bands catch any horizontal position, and the two bands
+    together cover every corner the standard's implementers actually use.
+    """
+    import cv2
+
+    h = img.shape[0]
+    strip = max(24, int(h * band))
+    out = []
+    for piece in (img[:strip], img[h - strip :]):
+        scale = width / max(1, piece.shape[1])
+        out.append(cv2.resize(piece, (width, max(12, int(piece.shape[0] * scale))), interpolation=cv2.INTER_AREA))
+    return out
+
+
+def sheets(rows: list[dict[str, Any]], fired: dict[str, list[str]], per: int, min_size: int) -> None:
+    """Top/bottom bands per uncovered cohort, so the vendor and mark can be read off."""
+    import cv2
+    import numpy as np
+
+    from remove_ai_watermarks.image_io import imread
+
+    by_uscc: dict[str, list[dict[str, Any]]] = {}
+    for r in rows:
+        by_uscc.setdefault(r["uscc"], []).append(r)
+
+    SHEET_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"\nwriting contact sheets -> {SHEET_DIR}")
+
+    for uscc, members in sorted(by_uscc.items(), key=lambda kv: -len(kv[1])):
+        if len(members) < min_size:
+            continue
+        quiet = [m for m in members if not fired.get(m["path"])]
+        if not quiet:
+            continue
+        width = 900
+        tiles: list[Any] = []
+        for m in quiet[:per]:
+            img = imread(m["path"])
+            if img is None:
+                continue
+            for b in _bands(img, width, 0.10):
+                tiles.append(b)
+                tiles.append(np.full((3, width, 3), 60, np.uint8))
+        if tiles:
+            dest = SHEET_DIR / f"{uscc}_n{len(members)}_quiet{len(quiet)}.png"
+            cv2.imwrite(str(dest), np.vstack(tiles))
+            print(f"  {dest.name}  ({len(tiles) // 4} frames)")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--limit", type=int, default=0, help="cap files scanned (0 = whole corpus)")
+    ap.add_argument("--workers", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--report-only", action="store_true")
+    ap.add_argument("--min-size", type=int, default=5, help="hide cohorts smaller than this")
+    ap.add_argument("--sheets", type=int, default=0, help="crops per cohort contact sheet")
+    a = ap.parse_args()
+
+    if a.report_only:
+        rows = [json.loads(x) for x in a.out.read_text(encoding="utf-8").splitlines() if x.strip()]
+    else:
+        rows = scan(a.limit, a.workers, a.out)
+
+    fired = load_fired()
+    report(rows, fired, a.min_size)
+    if a.sheets:
+        sheets(rows, fired, a.sheets, a.min_size)
+
+
+if __name__ == "__main__":
+    main()

scripts/vendor_mark_calibrate.py

@@ -0,0 +1,620 @@
+"""Calibrate a candidate text-mark detector for an UNCOVERED vendor, on real positives.
+
+WHERE THE POSITIVES COME FROM
+  `vendor_cohort_harvest.py` partitions China-AIGC carriers into per-entity cohorts by
+  their TC260 producer code, so a cohort is a vendor LABEL that owes nothing to any
+  pixel detector. That is what makes this calibration non-circular: the previous attempt
+  (`render_vendor_silhouettes.py`, 2026-07-18) died at n=1 because the only way it knew
+  to find 千问 frames was to eyeball the misses of a detector that cannot see them.
+
+  A cohort is NOT automatically a set of visible-mark positives: TC260 provenance is
+  metadata, and a vendor may label a frame without stamping it. So the cohort is the
+  CANDIDATE pool, and mark presence is settled by eye -- `--sheets` writes the corner
+  crops sorted by score, which makes that pass cheap and makes the separation (or its
+  absence) visible directly.
+
+NEGATIVES
+  The 432 frames hand-labelled `present: []` in the 2026-07-18 round -- already-adjudicated
+  no-visible-mark images, so the false-fire arm rests on human labels rather than on the
+  absence of a detection.
+
+THE TRAPS, INHERITED FROM THE 2026-07-18 MEASUREMENT
+  Both are encoded below rather than left to the caller:
+    * size the template with `alpha_height_frac`, NOT the silhouette's own aspect ratio
+      (the latter inflated the clean p99 from 0.30 to 0.58 and made comparison meaningless)
+    * keep the ladder at the shipped 3 rungs -- a wide sweep hands clean corners extra
+      chances to match, which flatters the positives and the negatives alike
+
+DATA SAFETY
+  Corpus images are real user uploads: read-only, local, gitignored output. The template
+  is font-rendered synthetic (`render_vendor_silhouettes.py`), never cut from an upload.
+
+    uv run python scripts/vendor_mark_calibrate.py --cohort 91440101MA9Y9T4H7A \\
+        --asset qwen_alpha.png --sheets
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent))
+
+REPO = Path(__file__).resolve().parents[1]
+COHORTS = REPO / "data" / "spaces" / "_vendor_cohorts.jsonl"
+SHEET_DIR = REPO / "data" / "spaces" / "_vendor_calib_sheets"
+OUT = REPO / "data" / "spaces" / "_vendor_calibration.jsonl"
+
+
+def build_config(
+    asset: str,
+    name: str,
+    scale_basis: str = "short",
+    overrides: dict[str, Any] | None = None,
+) -> Any:
+    """A candidate config: doubao's tuned geometry with this vendor's silhouette.
+
+    Transferring doubao's numbers is justified by LAYOUT, not by hope: every one of these
+    marks is the same GB 45438-2025 house style -- a 2-glyph vendor prefix, then the
+    mandated `AI生成` tail, set in a semibold CJK sans in the bottom-right corner. So
+    `豆包AI生成` and `千问AI生成` are the same 6 glyph cells at the same scale, and the
+    width/height fractions carry over. The NCC gate does NOT carry over and is what this
+    script exists to measure. Any tuned value can be overridden with what
+    `--fit-geometry` measured -- inheriting the locate box blindly clipped the big-mode
+    qwen mark, which is exactly the trap this tool exists to avoid.
+    """
+    import dataclasses
+
+    from remove_ai_watermarks._text_mark_engine import TextMarkConfig
+    from remove_ai_watermarks.doubao_engine import _CONFIG
+
+    return dataclasses.replace(
+        TextMarkConfig(**dataclasses.asdict(_CONFIG)),
+        name=name,
+        asset_name=asset,
+        scale_basis=scale_basis,
+        **(overrides or {}),
+    )
+
+
+ScoreArgs = tuple[str, str, str, str, "dict[str, Any]"]
+
+
+def _score(args: ScoreArgs) -> dict[str, Any] | None:
+    path_str, asset, name, basis, overrides = args
+    from remove_ai_watermarks._text_mark_engine import TextMarkEngine
+    from remove_ai_watermarks.image_io import imread
+
+    img = imread(path_str)
+    if img is None or min(img.shape[:2]) < 64:
+        return None
+    eng = TextMarkEngine(build_config(asset, name, basis, overrides))
+    loc = eng.locate(img)
+    try:
+        score, box = eng._tophat_best(img, loc)
+    except Exception:
+        return None
+    return {"path": path_str, "score": round(float(score), 4), "box": box}
+
+
+NEGATIVES = REPO / "data" / "spaces" / "_research_20260718_textmark_relaxation" / "groundtruth.jsonl"
+
+
+def load_sets(cohort: str) -> tuple[list[str], list[str]]:
+    pos = [
+        json.loads(x)["path"]
+        for x in COHORTS.read_text(encoding="utf-8").splitlines()
+        if x.strip() and json.loads(x)["uscc"] == cohort
+    ]
+    # The 2026-07-18 labels are in the vocabulary of the REGISTERED marks only
+    # (gemini/doubao/jimeng/jimeng_pill): `present: []` means "no registered mark", NOT
+    # "no mark at all" -- 146 of the 432 sit in a TC260 cohort, and qwen-cohort frames
+    # visibly carrying 千问AI生成 are labelled `present: []` there (measured 2026-07-21:
+    # they made up the clean arm's whole top tail, clean p99 0.37 -> 0.69). A gate read
+    # off that arm is meaningless, so the clean arm excludes every frame in ANY TC260
+    # cohort -- cohort membership is the cheap proxy for "may carry a CJK AI label".
+    in_any_cohort = {
+        str(Path(json.loads(x)["path"]).resolve())
+        for x in COHORTS.read_text(encoding="utf-8").splitlines()
+        if x.strip()
+    }
+    neg: list[str] = []
+    dropped = 0
+    for line in NEGATIVES.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        rec = json.loads(line)
+        if rec.get("present"):
+            continue
+        p = str((REPO / rec["path"]).resolve())
+        if p in in_any_cohort:
+            dropped += 1
+            continue
+        neg.append(p)
+    if dropped:
+        print(f"clean arm: dropped {dropped} negatives that sit in a TC260 cohort (contamination guard)")
+    return pos, neg
+
+
+def run(
+    paths: list[str],
+    asset: str,
+    name: str,
+    workers: int,
+    basis: str = "short",
+    overrides: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    with ProcessPoolExecutor(max_workers=workers) as ex:
+        futs = [ex.submit(_score, (p, asset, name, basis, overrides or {})) for p in paths]
+        for f in as_completed(futs):
+            try:
+                r = f.result()
+            except Exception:  # noqa: S112 -- one bad file must not kill the sweep
+                continue
+            if r:
+                out.append(r)
+    return out
+
+
+def report(pos: list[dict[str, Any]], neg: list[dict[str, Any]], name: str) -> None:
+    import numpy as np
+
+    p = np.array([r["score"] for r in pos])
+    n = np.array([r["score"] for r in neg])
+    print(f"\n{'=' * 78}\n{name}: candidate-cohort vs hand-labelled clean\n{'=' * 78}")
+    print(f"\n{'arm':10s} {'n':>5s} {'p10':>7s} {'p50':>7s} {'p90':>7s} {'p95':>7s} {'p99':>7s} {'max':>7s}")
+    for label, arr in (("cohort", p), ("clean", n)):
+        if not len(arr):
+            continue
+        qs = [np.percentile(arr, q) for q in (10, 50, 90, 95, 99)]
+        print(f"{label:10s} {len(arr):5d} " + " ".join(f"{q:7.3f}" for q in qs) + f" {arr.max():7.3f}")
+
+    if len(p) and len(n):
+        print("\n\nOPERATING POINTS -- gate set on the CLEAN arm")
+        print("`cohort fire` is an UPPER BOUND on recall: the cohort also holds")
+        print("metadata-only frames that carry no visible mark to find.\n")
+        print(f"{'gate':>7s} {'clean fire':>12s} {'cohort fire':>13s} {'cohort n':>10s}")
+        for q in (90, 95, 99, 99.5, 100):
+            t = float(np.percentile(n, q))
+            cf, pf = 100 * float((n >= t).mean()), 100 * float((p >= t).mean())
+            print(f"{t:7.3f} {cf:11.2f}% {pf:12.1f}% {int((p >= t).sum()):10d}")
+
+
+def sheets(pos: list[dict[str, Any]], name: str, per_sheet: int = 24) -> None:
+    """Corner crops sorted by score, so mark presence and the gate are read in one pass."""
+    import cv2
+    import numpy as np
+
+    from remove_ai_watermarks._text_mark_engine import TextMarkEngine
+    from remove_ai_watermarks.image_io import imread
+
+    eng = TextMarkEngine(build_config("doubao_alpha.png", "roi"))
+    SHEET_DIR.mkdir(parents=True, exist_ok=True)
+    ranked = sorted(pos, key=lambda r: -r["score"])
+    width = 660
+    for start in range(0, len(ranked), per_sheet):
+        chunk = ranked[start : start + per_sheet]
+        tiles: list[Any] = []
+        for rank, r in enumerate(chunk, start + 1):
+            img = imread(r["path"])
+            if img is None:
+                continue
+            loc = eng.locate(img)
+            crop = img[loc.y : loc.y + loc.h, loc.x : loc.x + loc.w]
+            if not crop.size:
+                continue
+            tile = cv2.resize(crop, (width, 96), interpolation=cv2.INTER_AREA)
+            cv2.rectangle(tile, (0, 0), (118, 22), (0, 0, 0), -1)
+            cv2.putText(tile, f"#{rank} {r['score']:.3f}", (4, 16), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
+            tiles.append(tile)
+            tiles.append(np.full((2, width, 3), 70, np.uint8))
+        if tiles:
+            dest = SHEET_DIR / f"{name}_ranked_{start // per_sheet:02d}.png"
+            cv2.imwrite(str(dest), np.vstack(tiles))
+            print(f"  {dest.name}  (#{start + 1}..#{start + len(chunk)})")
+
+
+# Wide and dense, for the geometry FIT only. An unregistered vendor's glyph size is
+# genuinely unknown, which is the one case a dense ladder earns its cost -- but it also
+# hands clean corners extra chances to match, so it must never set a gate.
+_FIT_SCALES = tuple(round(0.4 * (1.03**i), 4) for i in range(80))  # 0.40 .. ~4.1
+# The ladder the product actually ships (`_text_mark_engine._tophat_best`).
+_SHIPPED_LADDER = (0.8, 1.0, 1.25)
+
+
+def _fit_one(args: tuple[str, str, dict[str, Any]]) -> dict[str, Any] | None:
+    """Best match over the WIDE ladder, reported as a mark width in pixels.
+
+    Also measures the template ASPECT at the winning width: the mark's true height is
+    fitted by sweeping gh at the winning gw and reading the argmax, because
+    `alpha_height_frac` must be measured, not taken from the silhouette's own aspect
+    (that inflated the clean p99 from 0.30 to 0.58 on the 2026-07-18 attempt) and not
+    inherited from doubao.
+    """
+    path_str, asset, overrides = args
+    import cv2
+    import numpy as np
+
+    from remove_ai_watermarks._text_mark_engine import TextMarkEngine
+    from remove_ai_watermarks.image_io import imread
+
+    cfg = build_config(asset, "fit", "width", overrides)
+    eng = TextMarkEngine(cfg)
+    img = imread(path_str)
+    if img is None:
+        return None
+    loc = eng.locate(img)
+    resp = eng.tophat_response(img, loc)
+    sil = eng._glyph_silhouette()
+    if resp is None or sil is None:
+        return None
+    w = img.shape[1]
+    best, best_gw = 0.0, 0
+    best_tl = (0, 0)
+    for s in _FIT_SCALES:
+        gw = max(cfg.min_gw, int(cfg.alpha_width_frac * w * s))
+        gh = max(4, int(cfg.alpha_height_frac * w * s))
+        if gw >= resp.shape[1] or gh >= resp.shape[0]:
+            continue
+        t = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
+        res = cv2.matchTemplate(resp, t, cv2.TM_CCOEFF_NORMED)
+        _, v, _, tl = cv2.minMaxLoc(res)
+        if v > best:
+            best, best_gw, best_tl = v, gw, (int(tl[0]), int(tl[1]))
+    # Aspect fit at the winning width: sweep gh/gw and keep the argmax. Range covers
+    # everything between samsung's 0.12 and jimeng's 0.29 house styles, plus the
+    # two-line stacked marks (Yuanbao ~0.45), plus slack.
+    best_aspect = 0.0
+    if best_gw > 0:
+        best_gh_score = -1.0
+        # Upper bound raised 0.42 -> 0.62 for two-line marks (Yuanbao's stacked block
+        # has silhouette aspect ~0.45; the old range's 0.12 floor was its own trap --
+        # the fit "won" by squashing the template to a one-line strip).
+        for ratio in np.arange(0.12, 0.62, 0.01):
+            gh = max(4, int(best_gw * float(ratio)))
+            if gh >= resp.shape[0]:
+                continue
+            t = cv2.resize(sil, (best_gw, gh), interpolation=cv2.INTER_AREA)
+            v = float(cv2.matchTemplate(resp, t, cv2.TM_CCOEFF_NORMED).max())
+            if v > best_gh_score:
+                best_gh_score, best_aspect = v, float(ratio)
+    # The ABSOLUTE mark rect, so the LOCATE box fractions can be fitted too: inheriting
+    # doubao's corner box clipped the big-mode qwen mark's first glyph (the qwen mark
+    # sits ~0.025 of the short side off the right edge, doubao's box assumes ~0.004),
+    # which collapsed an exact-size template to 0.26.
+    ax = loc.x + best_tl[0]
+    ay = loc.y + best_tl[1]
+    return {
+        "path": path_str,
+        "best": round(best, 4),
+        "mark_w": best_gw,
+        "aspect": round(best_aspect, 3),
+        "x": ax,
+        "y": ay,
+        "w": w,
+        "h": img.shape[0],
+    }
+
+
+def fit_geometry(
+    paths: list[str],
+    asset: str,
+    workers: int,
+    floor: float = 0.50,
+    paths_name: str = "cohort",
+    overrides: dict[str, Any] | None = None,
+) -> None:
+    """Which basis and fraction does this vendor's mark actually scale with?
+
+    Only frames matching above ``floor`` are used: below it the winning size is the
+    ladder's best fit to background texture, not a measurement of the mark.
+    ``overrides`` adjusts the LOCATE box for the fit (a two-line mark like Yuanbao's
+    is taller than Doubao's inherited box -- scoring it in the inherited box clips
+    the template to zero overlap).
+    """
+    import numpy as np
+
+    rows: list[dict[str, Any]] = []
+    with ProcessPoolExecutor(max_workers=workers) as ex:
+        for f in as_completed([ex.submit(_fit_one, (p, asset, overrides or {})) for p in paths]):
+            try:
+                r = f.result()
+            except Exception:  # noqa: S112 -- one bad file must not kill the fit
+                continue
+            if r:
+                rows.append(r)
+
+    strong = [r for r in rows if r["best"] >= floor]
+    fit_out = REPO / "data" / "spaces" / f"_vendor_fit_{paths_name}.jsonl"
+    fit_out.write_text("\n".join(json.dumps(r) for r in rows), encoding="utf-8")
+    print(f"\n{'=' * 78}\nGEOMETRY FIT  (n={len(rows)}, usable best>={floor}: {len(strong)})\n{'=' * 78}")
+    print(f"rows -> {fit_out}")
+    if len(strong) < 20:
+        print("too few strong frames to fit a basis -- do not ship a fraction off this")
+        return
+
+    mw = np.array([r["mark_w"] for r in strong], float)
+    w = np.array([r["w"] for r in strong], float)
+    h = np.array([r["h"] for r in strong], float)
+    bases = {
+        "width": w,
+        "height": h,
+        "short": np.minimum(w, h),
+        "long": np.maximum(w, h),
+        "sqrt(w*h)": np.sqrt(w * h),
+        "diagonal": np.hypot(w, h),
+    }
+    print(f"\n{'basis':12s} {'mean frac':>10s} {'CV':>8s} {'p10':>8s} {'p90':>8s}")
+    print("-" * 52)
+    for nm, b in sorted(bases.items(), key=lambda kv: float(np.std(mw / kv[1]) / np.mean(mw / kv[1]))):
+        r = mw / b
+        print(
+            f"{nm:12s} {np.mean(r):10.4f} {float(np.std(r) / np.mean(r)):8.3f} "
+            f"{np.percentile(r, 10):8.4f} {np.percentile(r, 90):8.4f}"
+        )
+
+    lo_l, hi_l = _SHIPPED_LADDER[0], _SHIPPED_LADDER[-1]
+    print(f"\nCoverage by a single fraction on the SHIPPED ladder ({lo_l} .. {hi_l}, span {hi_l / lo_l:.3f}x):")
+    print(f"{'basis':12s} {'frac':>7s} {'window':>16s} {'covered':>9s}")
+    for nm in ("short", "sqrt(w*h)", "width"):
+        fs = mw / bases[nm]
+        best_f, best_cov = 0.0, -1.0
+        for f in np.arange(float(fs.min()) * 0.9, float(fs.max()) * 1.1, 0.002):
+            cov = float(((fs >= f * lo_l) & (fs <= f * hi_l)).mean())
+            if cov > best_cov:
+                best_f, best_cov = float(f), cov
+        print(f"{nm:12s} {best_f:7.3f} {best_f * lo_l:7.3f}-{best_f * hi_l:.3f} {100 * best_cov:8.1f}%")
+
+    # The raw distribution behind the coverage number: where the mark actually sits,
+    # so the mode structure (and what a 4th rung would recover) is visible directly.
+    fs = mw / bases["short"]
+    qs = [np.percentile(fs, q) for q in (5, 25, 50, 75, 95)]
+    print(f"\nfrac_short distribution: p5 {qs[0]:.3f} p25 {qs[1]:.3f} p50 {qs[2]:.3f} p75 {qs[3]:.3f} p95 {qs[4]:.3f}")
+    hist, edges = np.histogram(fs, bins=16)
+    for c, e0, e1 in zip(hist, edges[:-1], edges[1:], strict=True):
+        print(f"  {e0:.3f}-{e1:.3f}  {'#' * c}")
+
+    # Template aspect at the winning width -> the alpha_height_frac recommendation.
+    # Measured, per the standing rule: not the silhouette's own aspect, not doubao's.
+    aspects = np.array([r["aspect"] for r in strong if r["aspect"] > 0], float)
+    if len(aspects) >= 20:
+        med = float(np.median(aspects))
+        print(
+            f"\nASPECT FIT (n={len(aspects)}): p10 {np.percentile(aspects, 10):.3f} "
+            f"p50 {med:.3f} p90 {np.percentile(aspects, 90):.3f}"
+        )
+        print("alpha_height_frac = alpha_width_frac * p50(aspect), per basis:")
+        for nm in ("short", "sqrt(w*h)", "width"):
+            fxs = mw / bases[nm]
+            best_f = max(
+                np.arange(float(fxs.min()) * 0.9, float(fxs.max()) * 1.1, 0.002),
+                key=lambda f: float(((fxs >= f * lo_l) & (fxs <= f * hi_l)).mean()),
+            )
+            print(f"  {nm:12s} width {best_f:.3f}  ->  height {best_f * med:.4f}")
+
+    # LOCATE-box fit. The box fractions are as mark-specific as the template size:
+    # doubao's box clipped qwen's big-mode mark (see _fit_one). Derive the box from the
+    # measured absolute mark rects: margins must not exceed the mark's own (else the
+    # mark exits the anchored box), and the box must cover the mark plus NCC slack.
+    if len(aspects) >= 20:
+        short = np.minimum(w, h).astype(float)
+        mark_h = np.array([r["mark_w"] * r["aspect"] for r in strong], float)
+        ax = np.array([r["x"] for r in strong], float)
+        ay = np.array([r["y"] for r in strong], float)
+        right = (w - (ax + mw)) / short  # frame right edge to mark right edge
+        bottom = (h - (ay + mark_h)) / short
+        print(f"\nLOCATE FIT (basis=short, n={len(strong)}):")
+        print(f"  right-margin frac  p5 {np.percentile(right, 5):.4f} p50 {np.percentile(right, 50):.4f}")
+        print(f"  bottom-margin frac p5 {np.percentile(bottom, 5):.4f} p50 {np.percentile(bottom, 50):.4f}")
+        print(
+            f"  mark height frac   p50 {np.percentile(mark_h / short, 50):.4f} "
+            f"p95 {np.percentile(mark_h / short, 95):.4f}"
+        )
+        mx = max(0.002, float(np.percentile(right, 5)) - 0.004)
+        mb = max(0.002, float(np.percentile(bottom, 5)) - 0.004)
+        need_w = float(np.percentile(mw / short + right, 95)) - mx + 0.02
+        need_h = float(np.percentile(mark_h / short + bottom, 95)) - mb + 0.015
+        print(f"  recommended: margin_x_frac={mx:.4f} margin_bottom_frac={mb:.4f}")
+        print(f"               width_frac={need_w:.3f} height_frac={need_h:.3f}")
+
+    print("\nThese are DIAGNOSTIC. Re-score both arms on the shipped ladder with the")
+    print("fitted geometry before reading any gate off the clean arm.")
+
+
+FIRED = REPO / "data" / "spaces" / "_visible_positives.jsonl"
+
+
+def _fired_pool(mark: str, limit: int, seed: int = 7) -> list[str]:
+    """Paths where ``mark`` fired, from the COMPLETED full-corpus artifact -- the
+    standing rule: detector firings are joined, never re-run."""
+    import random
+
+    pool = [
+        json.loads(x)["path"]
+        for x in FIRED.read_text(encoding="utf-8").splitlines()
+        if x.strip() and mark in (json.loads(x).get("keys") or [])
+    ]
+    rng = random.Random(seed)  # noqa: S311 -- reproducible sampling, not crypto
+    rng.shuffle(pool)
+    return pool[:limit]
+
+
+def _cross_score(args: tuple[str, Any, Any]) -> dict[str, Any] | None:
+    """One frame scored by BOTH the candidate and the doubao production configs."""
+    path_str, cand_cfg, db_cfg = args
+    from remove_ai_watermarks._text_mark_engine import TextMarkEngine
+    from remove_ai_watermarks.image_io import imread
+
+    img = imread(path_str)
+    if img is None or min(img.shape[:2]) < 200:
+        return None
+    out: dict[str, Any] = {"path": path_str}
+    for key, cfg in (("cand", cand_cfg), ("doubao", db_cfg)):
+        eng = TextMarkEngine(cfg)
+        loc = eng.locate(img)
+        try:
+            score, _ = eng._tophat_best(img, loc)
+        except Exception:
+            return None
+        out[key] = round(float(score), 4)
+    return out
+
+
+def crossfire(
+    pools: dict[str, list[str]],
+    cand_cfg: Any,
+    workers: int,
+    gate: float,
+    margin: float = 0.10,
+) -> None:
+    """Score the candidate AND doubao's production template on the same frames.
+
+    The registration question a cohort-vs-clean run cannot answer: the candidate shares
+    the mandated `AI生成` tail with doubao (4 of 6 glyph cells), so its template will
+    correlate with doubao marks too. If the candidate fires on the doubao pool at the
+    candidate gate, registering it double-fills every doubao frame and mislabels it --
+    unless the rival margin suppresses it, which then has to be shown NOT to kill the
+    candidate on its own marks. Measured here in the tophat domain (the gate's domain);
+    production's `_rival_margin_ok` runs the same comparison on the binary blob.
+    """
+    import numpy as np
+
+    from remove_ai_watermarks.doubao_engine import _CONFIG as db_cfg
+
+    print(f"\n{'=' * 78}\nCROSSFIRE -- candidate vs doubao, same frames, tophat domain\n{'=' * 78}")
+    print(f"candidate gate {gate:.3f} | rival margin {margin:.2f}\n")
+    print(
+        f"{'pool':8s} {'n':>5s} {'cand p50':>9s} {'cand p90':>9s} {'db p50':>7s} {'db p90':>7s} "
+        f"{'m-d p10':>8s} {'m-d p50':>8s} {'fire':>7s} {'fire+m':>7s}"
+    )
+    with ProcessPoolExecutor(max_workers=workers) as ex:
+        for pool_name, paths in pools.items():
+            rows: list[dict[str, Any]] = []
+            futs = [ex.submit(_cross_score, (p, cand_cfg, db_cfg)) for p in paths]
+            for f in as_completed(futs):
+                try:
+                    r = f.result()
+                except Exception:  # noqa: S112 -- one bad file must not kill the pool
+                    continue
+                if r:
+                    rows.append(r)
+            if not rows:
+                continue
+            c = np.array([r["cand"] for r in rows])
+            d = np.array([r["doubao"] for r in rows])
+            m = c - d
+            fire = c >= gate
+            fire_m = fire & (m >= margin)
+            print(
+                f"{pool_name:8s} {len(rows):5d} {np.percentile(c, 50):9.3f} {np.percentile(c, 90):9.3f} "
+                f"{np.percentile(d, 50):7.3f} {np.percentile(d, 90):7.3f} "
+                f"{np.percentile(m, 10):8.3f} {np.percentile(m, 50):8.3f} "
+                f"{100 * float(fire.mean()):6.1f}% {100 * float(fire_m.mean()):6.1f}%"
+            )
+    print("\nReading: on `qwen` the margin column must stay high (the candidate keeps its")
+    print("own marks); on `doubao` fire+m must sit near zero (the candidate stays off")
+    print("doubao marks). If fire is high on `doubao` and fire+m is not, the rival margin")
+    print("is load-bearing for registration; if both are high, the mark cannot be")
+    print("registered on this front-end at all.")
+
+
+def _parse_ladder(raw: str) -> tuple[float, ...] | None:
+    if not raw:
+        return None
+    return tuple(float(x) for x in raw.split(","))
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--cohort", required=True, help="cohort USCC from vendor_cohort_harvest.py")
+    ap.add_argument("--asset", required=True, help="silhouette asset name, e.g. qwen_alpha.png")
+    ap.add_argument("--name", default="", help="label for output files (defaults to the asset stem)")
+    ap.add_argument("--workers", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--scale-basis", choices=("short", "width"), default="short")
+    ap.add_argument(
+        "--corner",
+        choices=("br", "bl", "tl"),
+        default=None,
+        help="override the inherited br corner (e.g. tl for RunningHub)",
+    )
+    ap.add_argument("--sheets", action="store_true")
+    ap.add_argument(
+        "--fit-geometry",
+        action="store_true",
+        help="fit the basis + fraction + template aspect the mark scales with",
+    )
+    ap.add_argument("--width-frac", type=float, default=None, help="fitted alpha_width_frac (default: inherit doubao)")
+    ap.add_argument(
+        "--height-frac", type=float, default=None, help="fitted alpha_height_frac (default: inherit doubao)"
+    )
+    ap.add_argument("--ladder", default="", help="comma scale rungs, e.g. 0.8,1.0,1.25,1.6 (default: shipped 3)")
+    ap.add_argument("--gate", type=float, default=0.45, help="candidate gate for the crossfire fire rates")
+    ap.add_argument("--box-width-frac", type=float, default=None, help="fitted locate width_frac")
+    ap.add_argument("--box-height-frac", type=float, default=None, help="fitted locate height_frac")
+    ap.add_argument("--margin-x-frac", type=float, default=None, help="fitted locate margin_x_frac")
+    ap.add_argument("--margin-bottom-frac", type=float, default=None, help="fitted locate margin_bottom_frac")
+    ap.add_argument(
+        "--crossfire",
+        action="store_true",
+        help="score the candidate AND doubao on the cohort, the doubao/jimeng pools and the clean arm",
+    )
+    a = ap.parse_args()
+    name = a.name or a.asset.split("_")[0]
+    ladder = _parse_ladder(a.ladder)
+    overrides: dict[str, Any] = {}
+    for arg, field in (
+        (a.width_frac, "alpha_width_frac"),
+        (a.height_frac, "alpha_height_frac"),
+        (a.box_width_frac, "width_frac"),
+        (a.box_height_frac, "height_frac"),
+        (a.margin_x_frac, "margin_x_frac"),
+        (a.margin_bottom_frac, "margin_bottom_frac"),
+    ):
+        if arg is not None:
+            overrides[field] = arg
+    if a.corner is not None:
+        overrides["corner"] = a.corner
+    if ladder is not None:
+        overrides["ladder"] = ladder
+
+    pos_paths, neg_paths = load_sets(a.cohort)
+    if a.fit_geometry:
+        print(f"cohort {a.cohort}: {len(pos_paths)} candidates")
+        fit_geometry(pos_paths, a.asset, a.workers, paths_name=name, overrides=overrides)
+        return
+
+    if a.crossfire:
+        cand = build_config(a.asset, name, a.scale_basis, overrides)
+        pools = {
+            "qwen": pos_paths,
+            "doubao": _fired_pool("doubao", 400),
+            "jimeng": _fired_pool("jimeng", 300),
+            "clean": neg_paths,
+        }
+        print("pools: " + ", ".join(f"{k}={len(v)}" for k, v in pools.items()))
+        crossfire(pools, cand, a.workers, a.gate)
+        return
+
+    print(f"cohort {a.cohort}: {len(pos_paths)} candidates | clean: {len(neg_paths)} hand-labelled")
+    print(f"scale_basis={a.scale_basis} overrides={overrides}")
+    pos = run(pos_paths, a.asset, name, a.workers, a.scale_basis, overrides)
+    neg = run(neg_paths, a.asset, name, a.workers, a.scale_basis, overrides)
+    OUT.write_text(
+        "\n".join(json.dumps({**r, "arm": arm}) for arm, rows in (("cohort", pos), ("clean", neg)) for r in rows),
+        encoding="utf-8",
+    )
+    report(pos, neg, name)
+    if a.sheets:
+        print(f"\nsheets -> {SHEET_DIR}")
+        sheets(pos, name)
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_eval.py

@@ -0,0 +1,164 @@
+"""Benchmark harness for the visible-mark detectors.
+
+Run this before AND after any detector change. It re-runs perception over the
+hand-labelled ground truth and reports, per mark, how often a fire is correct --
+with Wilson intervals, so a change inside the noise is visible as such.
+
+    uv run python scripts/visible_eval.py                 # score current code
+    uv run python scripts/visible_eval.py --save baseline # snapshot for comparison
+    uv run python scripts/visible_eval.py --vs baseline   # diff against a snapshot
+
+WHAT THIS SET CAN AND CANNOT MEASURE -- read before quoting a number:
+
+  * PRECISION: sound. Every labelled crop is centred on the region a detector
+    pointed at, so "the detector fired mark K here, was K actually there" is
+    exactly the question the labels answer.
+  * RECALL: NOT measurable here, and the harness refuses to print it. The labelled
+    images were SAMPLED WHERE DETECTORS FIRED (relaxation additions plus controls),
+    so images carrying a mark that every detector missed are absent by construction.
+    Computing recall on this set would divide by a denominator that excludes exactly
+    the failures recall is meant to expose, and would report a flattering number.
+    Recall needs a RANDOM corpus sample laballed exhaustively -- a separate round.
+
+  * `other_ai_label` (千问 / 百度 / 星绘 / 抖音) counts as a FALSE fire for any
+    registered mark, because it is a different vendor's label. It is tracked
+    separately in the confusion output since it is the dominant jimeng failure.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from remove_ai_watermarks import watermark_registry as wr
+from remove_ai_watermarks.image_io import imread
+
+GT = Path("data/spaces/_research_20260718_textmark_relaxation/groundtruth.jsonl")
+SNAP = Path("data/spaces/_research_20260718_textmark_relaxation/snapshots")
+MARKS = ("gemini", "doubao", "jimeng", "samsung", "jimeng_pill")
+
+
+def wilson(k: int, n: int) -> tuple[float, float]:
+    if n == 0:
+        return (0.0, 0.0)
+    z, p = 1.96, k / n
+    d = 1 + z * z / n
+    c = p + z * z / (2 * n)
+    s = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n))
+    return ((c - s) / d, (c + s) / d)
+
+
+def provenance_for(rec: dict) -> frozenset[str]:
+    """The provenance production would have: read from the file's own METADATA.
+
+    Never derive this from the labels. A relaxation arm only fires when provenance
+    names the vendor, so label-derived provenance silently tells the detector the
+    answer and every arm scores near-perfect (observed: gemini 99% instead of 34%).
+    """
+    return frozenset(rec.get("provenance", []))
+
+
+def score(sensitivity: str = "auto") -> dict:
+    recs = [json.loads(line) for line in GT.open()]
+    per: dict[str, Counter] = {m: Counter() for m in MARKS}
+    confusion: dict[str, Counter] = {m: Counter() for m in MARKS}
+    missing = 0
+    for rec in recs:
+        img = imread(rec["path"])
+        if img is None:
+            missing += 1
+            continue
+        cands = wr._build_candidates(img)
+        ctx = wr.Context(sensitivity=sensitivity, provenance=provenance_for(rec))
+        fired = {d.candidate.key for d in wr.decide(cands, ctx)}
+        for m in MARKS:
+            # Only score a mark on images whose shown crop could rule on it. Scoring
+            # outside that scope books real detections as false fires -- see the
+            # adjudication note in visible_groundtruth.py.
+            if m not in rec.get("adjudicated", []):
+                continue
+            if m not in fired:
+                per[m]["fn"] += 1 if m in rec["present"] else 0
+                continue
+            if m in rec["present"]:
+                per[m]["tp"] += 1
+            else:
+                per[m]["fp"] += 1
+                for s in rec["seen"]:
+                    confusion[m][s] += 1
+    scope = {m: sum(1 for r in recs if m in r.get("adjudicated", [])) for m in MARKS}
+    return {
+        "per": {m: dict(c) for m, c in per.items()},
+        "scope": scope,
+        "confusion": {m: dict(c) for m, c in confusion.items()},
+        "missing": missing,
+        "n": len(recs),
+        "sensitivity": sensitivity,
+    }
+
+
+def report(res: dict, prev: dict | None = None) -> None:
+    print(f"\nground truth: {res['n']} images ({res['missing']} unreadable)   sensitivity={res['sensitivity']}")
+    print("=" * 78)
+    print(
+        f"{'mark':12s} {'scope':>6s} {'fires':>6s} {'correct':>8s} "
+        f"{'precision':>11s} {'95% CI':>13s}  {'missed':>7s}  delta"
+    )
+    print("-" * 78)
+    for m in MARKS:
+        c = res["per"][m]
+        tp, fp, fn = c.get("tp", 0), c.get("fp", 0), c.get("fn", 0)
+        n = tp + fp
+        scope = res["scope"].get(m, 0)
+        if n == 0:
+            print(f"{m:12s} {scope:6d} {0:6d} {'-':>8s} {'-':>11s} {'-':>13s} {fn:7d}")
+            continue
+        lo, hi = wilson(tp, n)
+        delta = ""
+        if prev:
+            pc = prev["per"][m]
+            pn = pc.get("tp", 0) + pc.get("fp", 0)
+            if pn:
+                d = tp / n - pc.get("tp", 0) / pn
+                delta = f"{d:+.1%} (fires {pn}->{n})"
+        print(f"{m:12s} {scope:6d} {n:6d} {tp:8d} {tp / n:10.0%} {lo:5.0%}-{hi:<6.0%} {fn:7d}  {delta}")
+    print("\nwhat the FALSE fires actually were:")
+    for m in MARKS:
+        conf = {k: v for k, v in res["confusion"][m].items() if k != m}
+        if conf:
+            print(f"  {m:12s} {dict(sorted(conf.items(), key=lambda kv: -kv[1]))}")
+    print("\n'scope' = images whose crop could rule on that mark; 'missed' = labelled marks it did not fire on.")
+    print("NOTE: 'missed' is NOT recall -- this set was sampled where detectors fired, so images")
+    print("      every detector missed are absent by construction. Use it only to catch a change")
+    print("      LOSING marks it used to find; an unbiased random sample is needed for true recall.")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--save", metavar="NAME")
+    ap.add_argument("--vs", metavar="NAME")
+    ap.add_argument("--sensitivity", default="auto")
+    a = ap.parse_args()
+    res = score(a.sensitivity)
+    prev = None
+    if a.vs:
+        f = SNAP / f"{a.vs}.json"
+        if f.exists():
+            prev = json.loads(f.read_text())
+        else:
+            print(f"(no snapshot {f}; showing absolute numbers)")
+    report(res, prev)
+    if a.save:
+        SNAP.mkdir(parents=True, exist_ok=True)
+        (SNAP / f"{a.save}.json").write_text(json.dumps(res, indent=1))
+        print(f"\nsaved snapshot -> {SNAP / f'{a.save}.json'}")
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_groundtruth.py

@@ -0,0 +1,134 @@
+"""Consolidate the hand-labelled contact-sheet rounds into ONE ground-truth file.
+
+Ground truth is `uid -> the set of visible marks actually present`, hand-labelled
+blind against contact sheets with a two-sided control in every round. Rounds so far:
+
+  2026-07-18 text-mark/pill round : 423 cells (doubao / jimeng / jimeng_pill arms)
+  2026-07-18 gemini round         : 356 cells (gemini relaxation additions)
+
+DATA SAFETY: the corpus is real user uploads. This script reads the gitignored
+corpus and writes a gitignored ground-truth file. Neither the images nor this
+output may be committed; only the harness is. See the repo CLAUDE.md.
+
+The labels record what the LABELLER SAW in the crop, one of:
+  doubao | jimeng | pill | sparkle | other_ai_label | none | uncertain
+`other_ai_label` is a real visible AI label from a vendor we do NOT have a mark for
+(千问 / 百度 / 星绘 / 抖音); it is NOT a positive for any registered mark, but it is
+also not "clean" -- it is exactly what the relaxed jimeng detector confuses.
+`uncertain` rows are EXCLUDED from scoring rather than coerced, so a labeller's
+honest doubt never becomes a fabricated data point.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from pathlib import Path
+
+SEEN_TO_MARK = {
+    "doubao": "doubao",
+    "jimeng": "jimeng",
+    "pill": "jimeng_pill",
+    "sparkle": "gemini",
+}
+# Which marks a crop centred on `key` lets the labeller rule on (same corner = visible
+# in the same crop). Doubao and Jimeng share the bottom-right corner.
+_ADJUDICATES = {
+    "doubao": ("doubao", "jimeng"),
+    "jimeng": ("doubao", "jimeng"),
+    "jimeng_pill": ("jimeng_pill",),
+    "gemini": ("gemini",),
+    "samsung": ("samsung",),
+}
+
+ROUNDS = [
+    ("textmark", "labels.csv", "manifest.csv"),
+    ("gemini", "gemini_labels.csv", "gemini_manifest.csv"),
+]
+
+
+def metadata_provenance(path: str) -> list[str]:
+    """The vendor keys LOCAL METADATA confirms -- what cli._visible_provenance reads.
+
+    Must come from the file's own metadata, never from the labels: deriving it from
+    the ground truth would hand the detector the answer it is being scored on (a
+    relaxation only fires when provenance names the vendor, so label-derived
+    provenance makes every arm look near-perfect). Read from the corpus `identify`
+    sidecar, which is the same signal production computes.
+    """
+    p = Path(path)
+    sidecar = Path(str(p.parent).replace("/originals/", "/identify/")) / (p.name.split("_src")[0] + ".json")
+    if not sidecar.exists():
+        return []
+    try:
+        with sidecar.open() as fh:
+            wm = " | ".join(json.load(fh).get("watermarks", []))
+    except Exception:
+        return []
+    keys: list[str] = []
+    if "China AIGC label" in wm:
+        keys += ["doubao", "jimeng"]
+    if "C2PA Content Credentials (Google LLC" in wm:
+        keys.append("gemini")
+    if "Samsung Galaxy AI" in wm:
+        keys.append("samsung")
+    return keys
+
+
+def main() -> None:
+    root = Path(sys.argv[1] if len(sys.argv) > 1 else "data/spaces/_research_20260718_textmark_relaxation")
+    out = root / "groundtruth.jsonl"
+    rows: dict[str, dict] = {}
+    stats: dict[str, int] = {}
+    for round_name, labels_file, manifest_file in ROUNDS:
+        with (root / labels_file).open() as fh:
+            labels = {int(r["idx"]): r["seen"] for r in csv.DictReader(fh)}
+        with (root / manifest_file).open() as fh:
+            manifest_rows = list(csv.DictReader(fh))
+        for m in manifest_rows:
+            seen = labels.get(int(m["idx"]))
+            if seen is None:
+                continue
+            stats[seen] = stats.get(seen, 0) + 1
+            if seen == "uncertain":
+                continue  # excluded by design -- never coerce a doubt into a label
+            rec = rows.setdefault(
+                m["uid"],
+                {"uid": m["uid"], "path": m["path"], "present": [], "seen": [], "rounds": [], "adjudicated": []},
+            )
+            # ADJUDICATION SCOPE -- load-bearing. A crop centred on one mark only lets
+            # the labeller rule on marks visible IN THAT CROP. A pill crop (top-left)
+            # says nothing about a bottom-right wordmark, so scoring jimeng against a
+            # pill-round image would book real detections as false fires (~61% of pills
+            # carry a wordmark). Bottom-right marks co-adjudicate each other: one crop
+            # of that corner shows whichever of Doubao/Jimeng is there.
+            for k in _ADJUDICATES.get(m["key"], (m["key"],)):
+                if k not in rec["adjudicated"]:
+                    rec["adjudicated"].append(k)
+            mark = SEEN_TO_MARK.get(seen)
+            if mark and mark not in rec["present"]:
+                rec["present"].append(mark)
+            if seen not in rec["seen"]:
+                rec["seen"].append(seen)
+            if round_name not in rec["rounds"]:
+                rec["rounds"].append(round_name)
+
+    for r in rows.values():
+        r["provenance"] = metadata_provenance(r["path"])
+    with out.open("w") as fh:
+        for r in rows.values():
+            fh.write(json.dumps(r) + "\n")
+    print(f"wrote {out}  images={len(rows)}")
+    print("label distribution across all rounds:", dict(sorted(stats.items(), key=lambda kv: -kv[1])))
+    n_pos = sum(1 for r in rows.values() if r["present"])
+    print(f"images with at least one registered mark: {n_pos}; clean-of-registered-marks: {len(rows) - n_pos}")
+    adj: dict[str, int] = {}
+    for r in rows.values():
+        for k in r["adjudicated"]:
+            adj[k] = adj.get(k, 0) + 1
+    print("images each mark can be SCORED on (adjudication scope):", dict(sorted(adj.items())))
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_positives.py

@@ -0,0 +1,141 @@
+"""Parallel detection pass: list every corpus image carrying a known visible mark.
+
+Why this exists separately from `visible_removal_audit.py`: that audit is single-process,
+so a full-corpus sweep costs ~10 h and running it once per backend costs ~30 h. But its
+expensive half is DETECTION, and detection does not depend on the fill backend. Splitting
+it out means detecting once in parallel and then feeding the positives to the audit via
+its `--paths-file` seam, over a few thousand images instead of forty thousand.
+
+CRASH TOLERANCE IS NOT OPTIONAL AT THIS SCALE
+  cv2/libpng decode native-crash on some real uploads. A plain `ProcessPoolExecutor.map`
+  over 39k files then DEADLOCKS: the worker dies without a Python traceback and the parent
+  waits forever on a result that never arrives (observed 2026-07-19 -- 26 min of work lost
+  because results were only written at the end). So this script:
+    * writes every result to JSONL as it arrives -- a kill never costs more than a batch;
+    * is resumable -- an interrupted run skips what it already recorded;
+    * runs a FRESH pool per batch with a timeout, so one poisoned file costs one batch,
+      and that batch is retried serially to find and record the offender.
+
+Corpus images are user uploads: read-only, local analysis, gitignored output.
+
+    uv run python scripts/visible_positives.py --jobs 6
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import glob
+import json
+import os
+import sys
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from concurrent.futures import TimeoutError as FutureTimeout
+from concurrent.futures.process import BrokenProcessPool
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# The package's own format set. An inlined copy here silently skipped .heif, which
+# CLAUDE.md documents as supported.
+from remove_ai_watermarks.noai.constants import SUPPORTED_FORMATS as _EXTS
+
+REPO = Path(__file__).resolve().parents[1]
+CORPUS = REPO / "data" / "spaces" / "originals"
+OUT = REPO / "data" / "spaces" / "_visible_positives.jsonl"
+PATHS = REPO / "data" / "spaces" / "_visible_positives.txt"
+
+
+def _one(path: str) -> dict[str, object]:
+    from remove_ai_watermarks.image_io import imread
+    from remove_ai_watermarks.watermark_registry import detect_marks
+
+    try:
+        img = imread(path)
+        if img is None:
+            return {"path": path, "keys": [], "status": "unreadable"}
+        return {"path": path, "keys": [d.key for d in detect_marks(img) if d.detected], "status": "ok"}
+    except Exception as e:
+        return {"path": path, "keys": [], "status": f"error:{type(e).__name__}"}
+
+
+def _run_batch(batch: list[str], jobs: int, timeout: int) -> list[dict[str, object]]:
+    """One batch in a fresh pool. On a native worker crash or timeout, retry serially so
+    the poisoned file is identified and recorded instead of stalling the whole sweep."""
+    try:
+        with ProcessPoolExecutor(max_workers=jobs) as ex:
+            futs = {ex.submit(_one, p): p for p in batch}
+            return [f.result() for f in as_completed(futs, timeout=timeout)]
+    except (FutureTimeout, BrokenProcessPool, OSError, RuntimeError):
+        out: list[dict[str, object]] = []
+        for p in batch:
+            try:
+                out.append(_one(p))
+            except BaseException:  # a native crash here kills only this file, not the sweep
+                out.append({"path": p, "keys": [], "status": "crashed"})
+        return out
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--jobs", type=int, default=max(1, (os.cpu_count() or 4) - 2))
+    ap.add_argument("--limit", type=int, default=0)
+    ap.add_argument("--batch", type=int, default=200)
+    ap.add_argument("--timeout", type=int, default=600, help="seconds per batch before falling back to serial")
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--restart", action="store_true")
+    a = ap.parse_args()
+
+    files = sorted(p for p in glob.glob(str(CORPUS / "*" / "*")) if Path(p).suffix.lower() in _EXTS)
+    if a.limit:
+        files = files[: a.limit]
+
+    done: set[str] = set()
+    if a.restart and a.out.exists():
+        a.out.unlink()  # --restart must TRUNCATE; the file is reopened in append mode below
+    if a.out.exists() and not a.restart:
+        with open(a.out, encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    done.add(json.loads(line)["path"])
+                except Exception:  # noqa: S112 -- tolerate a torn last line
+                    continue
+    todo = [p for p in files if p not in done]
+    print(f"images {len(files)}  already done {len(done)}  to do {len(todo)}  jobs {a.jobs}", flush=True)
+
+    counts: collections.Counter[str] = collections.Counter()
+    status: collections.Counter[str] = collections.Counter()
+    seen = 0
+    with open(a.out, "a", encoding="utf-8") as fh:
+        for start in range(0, len(todo), a.batch):
+            for rec in _run_batch(todo[start : start + a.batch], a.jobs, a.timeout):
+                fh.write(json.dumps(rec) + "\n")
+                status[str(rec["status"])] += 1
+                for k in rec["keys"]:  # type: ignore[union-attr]
+                    counts[str(k)] += 1
+                seen += 1
+            fh.flush()
+            print(f"  {seen}/{len(todo)}  {dict(counts)}  {dict(status)}", flush=True)
+
+    # Rebuild the paths file from the FULL record set, not just this run's slice.
+    hits = []
+    with open(a.out, encoding="utf-8") as fh:
+        for line in fh:
+            try:
+                r = json.loads(line)
+            except Exception:  # noqa: S112
+                continue
+            if r.get("keys"):
+                hits.append(r["path"])
+    # Derive the paths file from --out so a trial run with a scratch --out cannot
+    # overwrite the shared list a full sweep produced.
+    paths_out = a.out.with_suffix(".txt")
+    paths_out.write_text("\n".join(sorted(set(hits))) + "\n", encoding="utf-8")
+    print(f"\npositives: {len(set(hits))} images")
+    for k, v in counts.most_common():
+        print(f"   {v:6d}  {k}")
+    print(f"statuses: {dict(status)}\npaths -> {paths_out}\nrecords -> {a.out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_recall_sample.py

@@ -0,0 +1,126 @@
+"""Build an UNBIASED random sample for measuring visible-mark RECALL.
+
+Every earlier labelling round sampled where detectors FIRED, so images that every
+detector missed were absent by construction and recall was unmeasurable. This round
+samples at random within a provenance class and shows the labeller the corners where
+a mark can physically be, so a MISSED mark is visible as such.
+
+Design decisions that matter:
+
+* SAMPLING FRAME is per provenance class, not the whole corpus. Recall is only
+  meaningful against a denominator where the mark CAN occur: TC260 carriers for the
+  ByteDance marks and the pill, Google-C2PA for the sparkle. Reporting one blended
+  recall over all uploads would mostly measure how often each vendor appears.
+* NATIVE RESOLUTION crops, never a downscaled whole image: a 220px preview destroys a
+  faint mark (measured in an earlier round), which would inflate the miss count with
+  the labeller's own blindness rather than the detector's.
+* BOTH corners per image (top-left pill, bottom-right wordmark/strip/sparkle), so one
+  pass adjudicates every registered mark instead of one mark per crop.
+* The detector's verdict is NOT shown and is not in the sheet order -- the manifest
+  holds it and must not be opened until labelling ends.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import random
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import cv2
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+from remove_ai_watermarks.image_io import imread
+
+CELL_W = 300
+COLS, ROWS = 4, 3
+PER = COLS * ROWS
+
+
+def corner_strip(img: NDArray[Any]) -> NDArray[Any] | None:
+    """Top-left and bottom-right corners stacked, at (near) native scale.
+
+    Crop size is a fraction of the SHORT side because that is what marks scale with
+    (China's GB 45438-2025 sizes the mandated label off the shortest side).
+    """
+    h, w = img.shape[:2]
+    short = min(h, w)
+    cw, ch = int(short * 0.46), int(short * 0.17)
+    cw, ch = min(cw, w), min(ch, h)
+    tl = img[0:ch, 0:cw]
+    br = img[h - ch : h, w - cw : w]
+    strip = np.vstack([tl, np.full((6, cw, 3), 90, np.uint8), br])
+    s = min(1.0, CELL_W / strip.shape[1])  # never UPSCALE past native
+    if s < 1.0:
+        strip = cv2.resize(strip, (CELL_W, max(1, int(strip.shape[0] * s))), interpolation=cv2.INTER_AREA)
+    return strip
+
+
+def main() -> None:
+    scan = Path(sys.argv[1])
+    out = Path(sys.argv[2])
+    n_tc260 = int(sys.argv[3]) if len(sys.argv) > 3 else 160
+    n_google = int(sys.argv[4]) if len(sys.argv) > 4 else 80
+    out.mkdir(parents=True, exist_ok=True)
+
+    recs = [json.loads(line) for line in scan.open() if '"marks"' in line]
+    seen: dict[tuple, dict] = {}
+    for r in recs:  # exact-duplicate uploads share the whole NCC vector
+        seen.setdefault(tuple(r.get("shape", ())) + tuple(sorted((k, m["conf"]) for k, m in r["marks"].items())), r)
+    uniq = list(seen.values())
+
+    tc = [r for r in uniq if r["cls"] == "tc260"]
+    goog = [r for r in uniq if r["cls"] == "neg" and "Google" in r.get("platform", "")]
+    rng = random.Random(2026)  # noqa: S311 -- sampling, not cryptography
+    rng.shuffle(tc)
+    rng.shuffle(goog)
+    picked = [("tc260", r) for r in tc[:n_tc260]] + [("google", r) for r in goog[:n_google]]
+    rng.shuffle(picked)
+
+    manifest, cells = [], []
+    for cls, r in picked:
+        img = imread(r["path"])
+        if img is None:
+            continue
+        strip = corner_strip(img)
+        if strip is None:
+            continue
+        cells.append(strip)
+        manifest.append(
+            {
+                "idx": len(cells) - 1,
+                "uid": r["uid"],
+                "cls": cls,
+                "path": r["path"],
+                "fired": "|".join(sorted(k for k, m in r["marks"].items() if m["strict"])),
+                **{f"ncc_{k}": m["conf"] for k, m in r["marks"].items()},
+            }
+        )
+
+    cell_h = max(c.shape[0] for c in cells)
+    for si in range(0, len(cells), PER):
+        chunk = cells[si : si + PER]
+        sheet = np.full((ROWS * (cell_h + 26), COLS * (CELL_W + 8), 3), 40, np.uint8)
+        for i, c in enumerate(chunk):
+            rr, cc = divmod(i, COLS)
+            y0, x0 = rr * (cell_h + 26) + 22, cc * (CELL_W + 8) + 4
+            sheet[y0 : y0 + c.shape[0], x0 : x0 + c.shape[1]] = c
+            cv2.putText(sheet, f"{si + i:03d}", (x0, y0 - 6), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
+        cv2.imwrite(str(out / f"r{si // PER:02d}.png"), sheet)
+
+    with (out / "MANIFEST_DO_NOT_OPEN.csv").open("w", newline="") as fh:
+        w = csv.DictWriter(fh, fieldnames=list(manifest[0]))
+        w.writeheader()
+        w.writerows(manifest)
+    print(f"cells={len(cells)}  sheets={(len(cells) + PER - 1) // PER} -> {out}")
+    print("each cell = TOP-LEFT corner above, BOTTOM-RIGHT corner below, near native scale")
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_removal_audit.py

@@ -10,6 +10,11 @@ NOT sufficient (their NCC detector is fooled by a thin residual outline -- see
 CLAUDE.md). Treat a detector-clean Doubao/Jimeng as "detector passes"; visual
 residual is a separate check.
 
+Backend: for a REALISTIC quality audit pass ``--backend migan`` (the production
+fill), not ``cv2``. Removal SUCCESS (detector-clean) is backend-independent, so cv2
+is fine for a fast pass/fail sweep, but only migan/lama reflect the recovered-region
+quality a user actually gets. Run migan when validating the visible pipeline for real.
+
 Operates on gitignored data only (data/spaces/...); writes nothing tracked.
 
     uv run python scripts/visible_removal_audit.py \
@@ -54,7 +59,14 @@ def _rel(p: Path, corpus: Path) -> str:
     help="Audit only these paths (one per line), skipping the full rglob.",
 )
 @click.option("--limit", type=int, default=0, help="Scan at most N files (0 = all).")
-def main(corpus: Path, out: Path, dataset_root: Path, paths_file: Path | None, limit: int) -> None:
+@click.option(
+    "--backend",
+    type=click.Choice(["auto", "cv2", "migan", "lama"]),
+    default="auto",
+    help="Fill backend for removal. Removal SUCCESS (detector-clean) is backend-independent; "
+    "cv2 is fastest for a bulk audit, migan/lama only change recovered-region quality.",
+)
+def main(corpus: Path, out: Path, dataset_root: Path, paths_file: Path | None, limit: int, backend: str) -> None:
     logging.basicConfig(level=logging.WARNING, format="%(message)s")
     if paths_file is not None:
         files = [Path(s) for line in paths_file.read_text().splitlines() if (s := line.strip()) and Path(s).is_file()]
@@ -86,7 +98,7 @@ def main(corpus: Path, out: Path, dataset_root: Path, paths_file: Path | None, l
                     shutil.copy2(p, ddir / p.name)
                 # Remove, then re-detect with the SAME mark's detector.
                 try:
-                    cleaned, _ = mark.remove(img)
+                    cleaned, _ = mark.remove(img, backend=backend)
                     after = mark.detect(cleaned)
                 except Exception as exc:
                     log.warning("remove failed on %s (%s): %s", p.name, det.key, exc)

scripts/visible_sheets.py

@@ -0,0 +1,101 @@
+"""Build BLIND contact sheets for hand-labelling relaxation additions.
+
+Crops are centered on the DETECTED REGION (not the corner), padded by ~0.9x the mark
+size, and resized to 240px with INTER_NEAREST -- a downscaled preview destroys a faint
+mark, so nothing here may smooth. The manifest is written to a separate file that must
+NOT be read until labelling is finished.
+
+Each sheet mixes three strata in shuffled order:
+  add    - the relaxation additions whose precision we are measuring
+  pos    - strict-consistent detections (a mark is really there): labeller sensitivity
+  clean  - verified-clean negatives (no mark can be there): labeller specificity
+The two control strata are what make a low measured precision trustworthy.
+"""
+
+import csv
+import json
+import random
+import sys
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+from numpy.typing import NDArray
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+from remove_ai_watermarks import watermark_registry as wr
+from remove_ai_watermarks.image_io import imread
+
+CELL = 240
+COLS, ROWS = 6, 3
+PER = COLS * ROWS
+
+
+def region_for(path: str, key: str) -> tuple[int, int, int, int] | None:
+    """Re-detect to recover the mark bbox (Candidate carries no region)."""
+    img = imread(path)
+    if img is None:
+        return None
+    mark = next(m for m in wr._REGISTRY if m.key == key)
+    d = mark.detect(img, provenance=True)
+    return d.region if d.region else None
+
+
+def crop(path: str, region: tuple[int, int, int, int] | None, pad_factor: float = 0.9) -> NDArray[Any] | None:
+    img = imread(path)
+    if img is None:
+        return None
+    h, w = img.shape[:2]
+    if region:
+        x, y, rw, rh = region
+    else:
+        return None
+    px, py = int(rw * pad_factor), int(rh * pad_factor)
+    x0, y0 = max(0, x - px), max(0, y - py)
+    x1, y1 = min(w, x + rw + px), min(h, y + rh + py)
+    c = img[y0:y1, x0:x1]
+    if c.size == 0:
+        return None
+    s = CELL / max(c.shape[0], c.shape[1])
+    return cv2.resize(c, (max(1, int(c.shape[1] * s)), max(1, int(c.shape[0] * s))), interpolation=cv2.INTER_NEAREST)
+
+
+def main() -> None:
+    with open(sys.argv[1]) as fh:
+        items = json.load(fh)  # [{uid,path,key,stratum,conf}]
+    outdir = Path(sys.argv[2])
+    outdir.mkdir(parents=True, exist_ok=True)
+    random.Random(1234).shuffle(items)  # noqa: S311 -- sheet ordering, not cryptography
+
+    manifest = []
+    cells = []
+    for it in items:
+        reg = region_for(it["path"], it["key"])
+        c = crop(it["path"], reg)
+        if c is None:
+            continue
+        cells.append((it, c))
+
+    for si in range(0, len(cells), PER):
+        chunk = cells[si : si + PER]
+        sheet = np.full((ROWS * (CELL + 26), COLS * (CELL + 8), 3), 40, np.uint8)
+        for i, (it, c) in enumerate(chunk):
+            r, col = divmod(i, COLS)
+            y0 = r * (CELL + 26) + 22
+            x0 = col * (CELL + 8) + 4
+            sheet[y0 : y0 + c.shape[0], x0 : x0 + c.shape[1]] = c
+            label = f"{si + i:04d}"  # index ONLY -- no stratum, no confidence
+            cv2.putText(sheet, label, (x0, y0 - 6), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
+            manifest.append({"idx": si + i, **it})
+        cv2.imwrite(str(outdir / f"sheet_{si // PER:03d}.png"), sheet)
+
+    with open(outdir / "MANIFEST_DO_NOT_OPEN.csv", "w", newline="") as fh:
+        w = csv.DictWriter(fh, fieldnames=list(manifest[0]))
+        w.writeheader()
+        w.writerows(manifest)
+    print(f"sheets={(len(cells) + PER - 1) // PER} cells={len(cells)} -> {outdir}")
+
+
+if __name__ == "__main__":
+    main()

src/remove_ai_watermarks/__init__.py

@@ -1,7 +1,21 @@
-"""Remove-AI-Watermarks: Unified tool for removing visible and invisible AI watermarks."""
+"""Remove-AI-Watermarks: Unified tool for removing visible and invisible AI watermarks.
+
+High-level API (lazy, so ``import remove_ai_watermarks`` stays cheap)::
+
+    import remove_ai_watermarks as raiw
+    raiw.remove_visible("in.png", "out.png")            # clean a file (provenance auto)
+    result, removed = raiw.remove_visible(bgr_array)    # array -> array
+    raiw.visible_provenance("in.png")                   # -> frozenset of confirmed vendors
+
+For a provenance verdict use the ``identify`` submodule::
+
+    from remove_ai_watermarks.identify import identify
+    report = identify("in.png")
+"""
 
 import os as _os
 import warnings as _warnings
+from typing import TYPE_CHECKING
 
 # transformers prints a noisy deprecation for the Siglip2ImageProcessorFast
 # alias when it is imported (by the optional GPU/ML path). Silence it before
@@ -11,4 +25,19 @@ _os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
 _warnings.filterwarnings("ignore", message=r".*ImageProcessorFast.*")
 
 
-__version__ = "0.13.0"
+__version__ = "0.18.0"
+
+__all__ = ["__version__", "remove_visible", "visible_provenance"]
+
+if TYPE_CHECKING:
+    from remove_ai_watermarks.api import remove_visible, visible_provenance
+
+
+def __getattr__(name: str) -> object:
+    """Lazily resolve the high-level API (PEP 562), so the heavy imports (cv2, the
+    metadata/identify stack) load only when a caller actually reaches for them."""
+    if name in ("remove_visible", "visible_provenance"):
+        from remove_ai_watermarks import api
+
+        return getattr(api, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/remove_ai_watermarks/_text_mark_engine.py

@@ -1,20 +1,22 @@
-"""Shared base for the reverse-alpha visible text-mark engines.
+"""Shared base for the visible text-mark detectors/localizers (localize -> fill).
 
 The Doubao "豆包AI生成", Jimeng "★ 即梦AI", and Samsung "✦ Contenuti generati
-dall'AI" marks are the SAME algorithm: anchor a bottom-corner box by width-relative
-geometry, extract the light low-saturation glyph candidate, detect by matching the
-bundled alpha-glyph silhouette via ``TM_CCOEFF_NORMED``, and remove by inverting the
-alpha blend ``original = (wm - a*logo)/(1-a)`` (always trying fixed AND NCC-aligned
-placement, keeping the lower-residual one) plus a thin footprint inpaint.
+dall'AI" marks are the SAME algorithm: anchor a bottom-corner box by geometry
+relative to the image's SHORT side, extract the light low-saturation glyph candidate (white top-hat), detect
+by matching the bundled alpha-glyph silhouette via ``TM_CCOEFF_NORMED``, and build a
+removal MASK from the glyph blob's bounding box (:meth:`footprint_mask`) for the
+shared fill (region_eraser). The mask is template-FREE -- the top-hat glyph bbox, not
+a fixed alpha-template placement -- so a re-rendered or differently-placed mark (e.g.
+a non-Italian Samsung string) is still masked. The old reverse-alpha pixel recovery
+(``original = (wm - a*logo)/(1-a)``) is gone.
 
 They differ ONLY in a bounded set of tuned values captured by :class:`TextMarkConfig`:
-the constants, the bundled asset, the corner (Doubao/Jimeng bottom-right, Samsung
-bottom-left), and a few structural knobs (the morphology-open kernel size and the
-minimum glyph width used by the alignment / template-match). Each engine module is a
-thin :class:`TextMarkEngine` subclass plus the test-facing module constants/helpers.
+the constants, the bundled silhouette asset, the corner (Doubao/Jimeng bottom-right,
+Samsung bottom-left), and a few structural knobs. Each engine module is a thin
+:class:`TextMarkEngine` subclass plus the test-facing module constants/helpers.
 
-Gemini stays a SEPARATE engine (``gemini_engine``): its multi-size fixed-slot sparkle
-model is genuinely different, not a tuned variant of this one.
+Gemini stays a SEPARATE engine (``gemini_engine``): its multi-size sparkle model is
+genuinely different, not a tuned variant of this one.
 """
 
 # cv2/numpy boundary: third-party libs ship no usable element types; relax the
@@ -37,28 +39,6 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# Reverse-alpha over-subtraction guard (ported from gemini_engine, 2026-06-20).
-# The reverse-alpha blend ``(wm - a*logo)/(1-a)`` over-subtracts when the captured
-# alpha over-estimates THIS image's mark opacity: on a dark or mid-tone background
-# it drives the glyph footprint into a visibly DARKER-than-background ghost (a
-# "dark pit") instead of recovering the true pixels. The retained-corpus mining
-# (2026-06-20) showed the sparkle-only fix (commit 41f6797) left this unhandled
-# for the Doubao/Jimeng text marks. Mirror the sparkle gate: when the recovered
-# glyph body lands more than this many gray levels below the local background
-# ring, abandon the reverse-alpha output for the footprint and inpaint it from
-# the surroundings instead. Calibrated to the same 25-level margin the sparkle
-# gate uses -- clean text-mark removals recover within ~10 of the ring, the dark
-# pit lands tens of levels below.
-_OVERSUB_DARK_MARGIN = 25.0
-# Glyph-body / background-ring sampling for the guard. The ring is a pad around
-# the glyph box (excluding the box); the body is the bright-core glyph pixels.
-_OVERSUB_RING_PAD_FRAC = 0.6  # ring pad as a fraction of the glyph-box height
-_OVERSUB_BODY_ALPHA_FLOOR = 0.15  # alpha above which a block pixel counts as glyph body
-# Footprint inpaint when the guard trips: dilate the glyph mask wider than the
-# thin residual pass so the whole darkened ghost is reconstructed, not just its edge.
-_OVERSUB_INPAINT_DILATE = 9
-_OVERSUB_INPAINT_RADIUS = 4
-
 # Minimum image short side (px) for text-mark DETECTION. Below this the glyph
 # template degrades to the ``min_gw`` floor (~8 px) and TM_CCOEFF_NORMED on a few
 # pixels is noise, so an unrelated small geometric shape can spuriously correlate
@@ -72,16 +52,56 @@ _OVERSUB_INPAINT_RADIUS = 4
 # positive; removal is gated on detection, so it is suppressed too.
 _MIN_DETECT_SHORT_SIDE = 200
 
+# Provenance-confirmed NCC relaxation. When external metadata already confirms the
+# vendor (so the mark is present with high prior), a faint or slightly re-rendered
+# glyph that scores just below the standard NCC gate is still trusted. The relaxed
+# gate is ``detect_ncc_threshold * provenance_ncc_factor``; the coverage gate still
+# applies on top.
+#
+# This used to be ONE shared 0.7 for every text mark. Measured 2026-07-18 on the
+# `auto` path (the default -- no flag, driven by TC260 metadata), it turned out to
+# mean two completely different things per mark. Blind hand-label of the ADDITIONS
+# (accepted with provenance, rejected without) over 4417 unique TC260 carriers,
+# two-sided control (labeller sensitivity 100%/96%, specificity 100%/100%):
+#
+#   mark     band            precision   95% CI     n
+#   doubao   whole arm             76%    61-87%    42
+#            [0.280,0.340)         58%    36-77%    19
+#            [0.340,0.400)         91%    73-98%    23
+#   jimeng   whole arm             17%    10-27%    82
+#            [0.315,0.383)         12%     6-22%    68
+#            [0.383,0.450)         43%    21-67%    14
+#
+# Doubao stays at 0.70: both its bands return more true marks than false fills, so
+# tightening would cost 11 genuine recoveries to prevent 8 false ones.
+#
+# Jimeng moves to 0.85. Its relaxed detector does not key on the "★ 即梦AI" wordmark
+# any more -- it keys on "some text in the bottom-right corner": of 68 false
+# additions, 33 were DOUBAO marks and 17 were other vendors' AI labels (千问, 百度,
+# 星绘, 抖音). 45 of those 68 fill a corner nothing else would touch (the other 23
+# are harmless -- doubao fires strictly there and fills the same box anyway). At
+# 0.85 the [0.315,0.383) band is dropped: 8 genuine recoveries lost, 60 false fills
+# prevented (7.5:1). A false fill is the worse error -- it destroys pixels AND makes
+# the caller report a removal that did not happen, while a miss leaves the image
+# untouched.
+#
+# NOTE: 0.85 is a patch on a detector problem, not a fix. Jimeng's silhouette is not
+# discriminative against Doubao's (same corner, same script, both ByteDance), and no
+# threshold repairs that -- it needs a better detection silhouette.
+_DEFAULT_PROVENANCE_NCC_FACTOR = 0.7
+
 
 @dataclass(frozen=True)
 class TextMarkConfig:
-    """All per-mark tuning for a reverse-alpha text-mark engine."""
+    """All per-mark tuning for a text-mark detector/localizer."""
 
     name: str  # short label for log lines (e.g. "Doubao")
     asset_name: str  # bundled alpha PNG under assets/ (e.g. "doubao_alpha.png")
-    corner: Literal["br", "bl"]  # bottom-right (Doubao/Jimeng) or bottom-left (Samsung)
+    corner: Literal[
+        "br", "bl", "tl", "bc"
+    ]  # bottom-right (Doubao/Jimeng), bottom-left (Samsung), top-left (RunningHub), bottom-center (LibLibAI)
     margin_floor: int  # min margin in px for locate (4 for br marks, 2 for Samsung)
-    # locate geometry (fraction of image WIDTH)
+    # locate geometry (fraction of scale_base -- see scale_base())
     width_frac: float
     height_frac: float
     margin_x_frac: float  # right margin (br) or left margin (bl)
@@ -94,18 +114,44 @@ class TextMarkConfig:
     # detection
     detect_min_coverage: float
     detect_ncc_threshold: float
-    # alpha-map geometry (fraction of WIDTH) emitted by scripts/visible_alpha_solve.py
+    # alpha-map glyph geometry (fraction of scale_base) emitted by
+    # scripts/visible_alpha_solve.py, sizing the detection silhouette for
+    # template_match_score
     alpha_width_frac: float
     alpha_height_frac: float
-    alpha_margin_x_frac: float
-    alpha_margin_bottom_frac: float
-    alpha_align_search: tuple[float, float, int]  # np.linspace(start, stop, num) scale search
-    min_gw: int  # minimum glyph width for the template match / align search (8 br, 16 Samsung)
-    alpha_logo_bgr: tuple[float, float, float] = (255.0, 255.0, 255.0)
-    # residual inpaint over the glyph footprint (thin)
-    residual_alpha_floor: float = 0.05
-    residual_dilate: int = 5
-    residual_inpaint_radius: int = 2
+    min_gw: int  # minimum glyph width for the template match (8 br, 16 Samsung)
+    # Asset names of RIVAL marks that occupy the same corner and can therefore be
+    # scored against the same glyph blob. Detection becomes COMPETITIVE: this mark's
+    # template must beat every rival's by `rival_margin`. See _rival_margin_ok.
+    # Detection front-end. "binary" thresholds the top-hat into a glyph blob and
+    # correlates a binary silhouette against it; "tophat" correlates the CONTINUOUS
+    # top-hat response against a soft template and never binarizes. See
+    # TextMarkEngine.tophat_response for the measurement that motivated the split.
+    # "gray" correlates the silhouette against the raw GRAYSCALE of the locate box:
+    # for a faint mid-gray mark (RunningHub) the top-hat's background-subtraction and
+    # max-normalization suppress the response to clean-arm levels (positives 0.16-0.23
+    # vs clean p99 0.31), while raw gray NCC separates (positives 0.38-0.54 vs clean
+    # p99 0.264 / max 0.304, measured 2026-07-22). Contrast-DEPENDENT, unlike tophat.
+    detect_frontend: Literal["binary", "tophat", "gray"] = "binary"
+    # Gaussian sigma applied to the template in the "tophat" front-end (0 = none).
+    template_blur: float = 0.0
+    # Which image dimension the mark's size and margins scale with. VENDOR-SPECIFIC,
+    # measured, not assumed -- see TextMarkEngine.scale_base. "short" = min(h, w), "width" = w.
+    scale_basis: Literal["short", "width"] = "width"
+    # Scale rungs ``_tophat_best`` sweeps (the detection comb). PER-MARK: a vendor
+    # whose stamp sizes do not land on the shared 3-rung comb carries its own ladder
+    # (measured for 千问, whose marks sit in two size modes ~1.6x apart -- one fraction
+    # on 3 rungs covers only ~75% of them). Densifying the SHARED ladder for everyone
+    # was measured and rejected (false fire 2.52% -> 3.05%; see docs/verification-plan.md
+    # B2), so the default stays the shipped 3 rungs and a deviation must be calibrated
+    # per mark on real positives, never ported.
+    ladder: tuple[float, ...] = (0.8, 1.0, 1.25)
+    rivals: tuple[str, ...] = ()
+    rival_margin: float = 0.10
+    # Multiplier applied to detect_ncc_threshold when provenance confirms the vendor.
+    # Per-mark, NOT shared: see _DEFAULT_PROVENANCE_NCC_FACTOR for the measured
+    # precision that forced the split. Last field so it can carry a default.
+    provenance_ncc_factor: float = _DEFAULT_PROVENANCE_NCC_FACTOR
 
 
 @dataclass
@@ -165,18 +211,49 @@ def glyph_silhouette(asset_name: str) -> NDArray[Any] | None:
     return _silhouette_cache[asset_name]
 
 
-def template_match_score(box_mask: NDArray[Any], image_width: int, config: TextMarkConfig) -> float:
+_RIVAL_MODULES = {
+    "doubao_alpha.png": "remove_ai_watermarks.doubao_engine",
+    "jimeng_alpha.png": "remove_ai_watermarks.jimeng_engine",
+    "samsung_alpha.png": "remove_ai_watermarks.samsung_engine",
+}
+
+
+def _rival_config(asset_name: str, fallback: TextMarkConfig) -> TextMarkConfig:
+    """The rival mark's own config, for scoring its template on a shared blob.
+
+    Looked up LAZILY by asset name: a rival's template geometry
+    (``alpha_*_frac`` / ``min_gw``) is its own, and scoring it with this mark's
+    geometry would compare a correctly-sized template against a mis-sized one and
+    hand the margin a free win. Lazy because the engine modules import this one.
+    """
+    mod_path = _RIVAL_MODULES.get(asset_name)
+    if mod_path is None:
+        return fallback
+    from importlib import import_module
+
+    try:
+        return import_module(mod_path)._CONFIG
+    except Exception:  # a missing/renamed engine must not break detection
+        logger.debug("rival config %s unavailable; skipping its margin check.", asset_name)
+        return fallback
+
+
+def template_match_score(box_mask: NDArray[Any], scale_base: int, config: TextMarkConfig) -> float:
     """Zero-mean normalized correlation of the alpha-template glyph silhouette
     (scaled to the mark's expected size) against the candidate ``box_mask``.
 
     ``TM_CCOEFF_NORMED`` keys on glyph SHAPE, not coverage, so a dense textured
     corner does not score highly -- only the actual glyph shape does.
+
+    ``scale_base`` is the mark's own scaling dimension (:meth:`TextMarkEngine.scale_base`),
+    not always the width: sizing the template on the wrong basis stretches it by the
+    aspect ratio on landscape inputs and the correlation collapses.
     """
     sil = glyph_silhouette(config.asset_name)
     if sil is None or box_mask.size == 0:
         return 0.0
-    gw = min(box_mask.shape[1] - 1, max(config.min_gw, int(config.alpha_width_frac * image_width)))
-    gh = min(box_mask.shape[0] - 1, max(4, int(config.alpha_height_frac * image_width)))
+    gw = min(box_mask.shape[1] - 1, max(config.min_gw, int(config.alpha_width_frac * scale_base)))
+    gh = min(box_mask.shape[0] - 1, max(4, int(config.alpha_height_frac * scale_base)))
     if gw < config.min_gw or gh < 4:
         return 0.0
     template = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_NEAREST)
@@ -184,7 +261,7 @@ def template_match_score(box_mask: NDArray[Any], image_width: int, config: TextM
 
 
 class TextMarkEngine:
-    """Reverse-alpha visible text-mark remover (locate -> mask -> detect -> reverse-alpha)."""
+    """Visible text-mark detector/localizer (locate -> mask -> detect; mask feeds the fill)."""
 
     def __init__(self, config: TextMarkConfig) -> None:
         self.config = config
@@ -197,21 +274,216 @@ class TextMarkEngine:
     def _glyph_silhouette(self) -> NDArray[Any] | None:
         return glyph_silhouette(self.config.asset_name)
 
-    def _template_match_score(self, box_mask: NDArray[Any], image_width: int) -> float:
-        return template_match_score(box_mask, image_width, self.config)
+    def _template_match_score(self, box_mask: NDArray[Any], scale_base: int) -> float:
+        return template_match_score(box_mask, scale_base, self.config)
+
+    def _rival_margin_ok(self, score: float, box_mask: NDArray[Any], scale_base: int) -> bool:
+        """Whether this mark's template beats every same-corner RIVAL's on the SAME blob.
+
+        Detection was purely ABSOLUTE -- each engine scored its own template and
+        compared against its own threshold, so nothing ever asked the discriminative
+        question "does this blob look more like the neighbour's mark than like mine?".
+        Two marks sharing a corner and a script (Doubao "豆包AI生成" and Jimeng
+        "★ 即梦AI", both bottom-right, both near-white CJK) survive binarization into
+        very similar blobs, so an absolute gate cannot separate them -- and under the
+        provenance relaxation it stopped trying: 33 of jimeng's 68 false additions
+        were Doubao marks (corpus-measured 2026-07-18).
+
+        Measured separability on hand-labelled examples, scoring BOTH templates
+        against the same glyph blob (n=40 jimeng / 75 doubao / 20 other-vendor labels
+        / 89 clean):
+
+            feature                       separability   (0.5 = useless, 1.0 = perfect)
+            absolute ncc_jimeng                   0.96
+            ncc_jimeng MINUS ncc_doubao           0.99
+
+        At a 0.10 margin: real Jimeng wordmarks pass 100%, Doubao strips 8%, other
+        vendors' AI labels (千问/百度/星绘/抖音) 55%, no-mark corners 12%. Because the
+        real marks pass at 100%, this costs NO recall -- it is a pure precision gain,
+        unlike raising the threshold, which trades recall away.
+
+        Marks with no same-corner rival declare `rivals=()` and are unaffected.
+        """
+        c = self.config
+        if not c.rivals:
+            return True
+        for rival_asset in c.rivals:
+            rival = _rival_config(rival_asset, c)
+            if score - template_match_score(box_mask, scale_base, rival) < c.rival_margin:
+                logger.debug("%s detect: loses the %s rival margin; rejecting.", c.name, rival_asset)
+                return False
+        return True
 
     # ── Locate ──────────────────────────────────────────────────────────
 
+    def tophat_response(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any] | None:
+        """The CONTINUOUS white top-hat in the located box -- the glyph signal, unbinarized.
+
+        :meth:`extract_mask` thresholds this same response into a 0/255 glyph blob. That
+        is fine for a mark stamped bold and opaque, and destructive for a faint one: a
+        thin translucent overlay shatters into specks under the threshold, and no
+        template can match a blob that is not there.
+
+        Measured 2026-07-18 on hand-verified corpus positives (40 doubao, 14 千问, 60
+        verified-clean), scoring each mark with its own template:
+
+            front-end   doubao   clean neg   AUC doubao/neg
+            binary       0.723       ~0.12             --
+            tophat       0.781        0.122          1.00
+
+        The gates that were hard cuts in the binary path (saturation, absolute luma)
+        become WEIGHTS here, so a faint stroke contributes in proportion to its strength
+        instead of being dropped at a threshold. The response is max-normalized, which
+        makes the score contrast-invariant -- the point of the exercise.
+
+        Kept per-mark (``detect_frontend``) rather than switched globally, because a
+        front-end change must be measured per mark before it ships.
+        """
+        c = self.config
+        x, y, bw, bh = loc.bbox
+        if bh < 16 or bw < 16:
+            return None
+        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
+        luma = roi.mean(axis=2)
+        sat = roi.max(axis=2) - roi.min(axis=2)
+        sigma = max(4.0, bh * 0.4)
+        tophat = luma - cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
+        resp = np.clip(tophat, 0, None) * (sat < c.max_saturation)
+        peak = float(resp.max())
+        if peak <= 1e-6:
+            return None
+        return (resp / peak * 255).astype(np.uint8)
+
+    def _tophat_best(
+        self, image: NDArray[Any], loc: TextMarkLocation
+    ) -> tuple[float, tuple[int, int, int, int] | None]:
+        """Best TM_CCOEFF_NORMED of a soft template against the continuous response, and
+        the ROI-local box (x0, y0, x1, y1) where that best match sits.
+
+        Sweeps the mark's scale ladder: the nominal glyph size is derived from the mark's
+        geometry, but a vendor re-rasterization shifts it by a few percent and the
+        continuous response is sharp enough that an exact-size template would miss. The
+        ladder is per-mark (``TextMarkConfig.ladder``), defaulting to the shipped 3 rungs.
+
+        Detection and the removal mask BOTH read this one method -- the score gates
+        detection, the box bounds the fill. Sharing it is deliberate: the standing rule is
+        that detection and the mask use the same front-end, and the way that rule was last
+        broken was a drift between two separate implementations. One method makes the drift
+        impossible instead of merely discouraged.
+        """
+        c = self.config
+        resp = self.tophat_response(image, loc)
+        sil = self._glyph_silhouette()
+        if resp is None or sil is None:
+            return (0.0, None)
+        base = self.scale_base(image)
+        best_score = 0.0
+        best_box: tuple[int, int, int, int] | None = None
+        for scale in c.ladder:
+            gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
+            gh = max(4, int(c.alpha_height_frac * base * scale))
+            if gw >= resp.shape[1] or gh >= resp.shape[0]:
+                continue
+            tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32)
+            if c.template_blur > 0:
+                tmpl = cv2.GaussianBlur(tmpl, (0, 0), sigmaX=c.template_blur, sigmaY=c.template_blur)
+            result = cv2.matchTemplate(resp, tmpl.astype(np.uint8), cv2.TM_CCOEFF_NORMED)
+            _, score, _, top_left = cv2.minMaxLoc(result)
+            if score > best_score:
+                tx, ty = int(top_left[0]), int(top_left[1])
+                best_score, best_box = float(score), (tx, ty, tx + gw - 1, ty + gh - 1)
+        return (best_score, best_box)
+
+    def _tophat_score(self, image: NDArray[Any], loc: TextMarkLocation) -> float:
+        """The detection score alone -- the box the removal mask needs is discarded here."""
+        return self._tophat_best(image, loc)[0]
+
+    def _gray_best(self, image: NDArray[Any], loc: TextMarkLocation) -> tuple[float, tuple[int, int, int, int] | None]:
+        """Best TM_CCOEFF_NORMED of the silhouette against the raw GRAYSCALE ROI, and
+        the ROI-local box (x0, y0, x1, y1) of that best match.
+
+        Mirrors :meth:`_tophat_best` (same ladder sweep, same one-method contract so
+        detection and the removal mask can never drift), but skips the top-hat
+        entirely: the RunningHub mark is a faint mid-gray text the top-hat's
+        background subtraction suppresses to clean-arm levels, while raw gray NCC
+        separates (see ``TextMarkConfig.detect_frontend``). Contrast-DEPENDENT by
+        construction, so the gate must be picked against the clean arm, which is
+        what ``scripts/vendor_mark_calibrate.py`` does.
+        """
+        c = self.config
+        x, y, bw, bh = loc.bbox
+        if bh < 16 or bw < 16:
+            return (0.0, None)
+        roi = cv2.cvtColor(image_io.to_bgr(image[y : y + bh, x : x + bw]), cv2.COLOR_BGR2GRAY)
+        sil = self._glyph_silhouette()
+        if sil is None:
+            return (0.0, None)
+        base = self.scale_base(image)
+        best_score = 0.0
+        best_box: tuple[int, int, int, int] | None = None
+        for scale in c.ladder:
+            gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
+            gh = max(4, int(c.alpha_height_frac * base * scale))
+            if gw >= roi.shape[1] or gh >= roi.shape[0]:
+                continue
+            tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
+            result = cv2.matchTemplate(roi, tmpl, cv2.TM_CCOEFF_NORMED)
+            _, score, _, top_left = cv2.minMaxLoc(result)
+            if score > best_score:
+                tx, ty = int(top_left[0]), int(top_left[1])
+                best_score, best_box = float(score), (tx, ty, tx + gw - 1, ty + gh - 1)
+        return (best_score, best_box)
+
+    def scale_base(self, image: NDArray[Any]) -> int:
+        """The image dimension this mark's geometry scales with.
+
+        Per-mark, and MEASURED -- a single shared basis is wrong. The tuned fractions
+        were all calibrated on PORTRAIT captures, where width and short side coincide,
+        so the basis was never exercised until landscape inputs were measured.
+
+        Corpus-measured 2026-07-18 (2572 unique TC260 carriers; the harness is
+        `scripts/visible_eval.py`). Before any fix, doubao detection by aspect ratio:
+        portrait 60%, square 41%, **landscape 0% (0 of 435)** -- the width-scaled box
+        is inflated by the aspect ratio on a wide image and the glyph never lands in
+        it. Re-running the previously-undetected set with a short-side basis recovered
+        **56% of landscape** images (12% square, 4% portrait).
+
+        But the same switch took JIMENG's labelled landscape positives from 13/13 to
+        0/13: its wordmark tracks the WIDTH. Both marks are ByteDance and share a
+        corner, and they still scale differently -- so this is a per-mark measurement,
+        not a house rule to generalize. Samsung keeps ``width`` because there is no
+        corpus evidence either way (1 addition corpus-wide) and an unmeasured change
+        is not an improvement.
+
+        China's GB 45438-2025 clause 5.2(e) mandates glyph height >= 5% of "the
+        shortest side" for CN marks, which is why a short-side basis is the natural
+        prior -- but Jimeng's measured behaviour overrides the prior, and measurement
+        wins over the standard's wording.
+        """
+        return min(image.shape[:2]) if self.config.scale_basis == "short" else image.shape[1]
+
     def locate(self, image: NDArray[Any]) -> TextMarkLocation:
-        """Anchor the watermark box in the configured bottom corner by geometry."""
+        """Anchor the watermark box in the configured corner, scaled by ``scale_basis``.
+
+        Every fraction is taken against ``scale_base(image)`` -- see
+        :data:`TextMarkConfig.scale_basis`, which is per-mark because the vendors
+        genuinely differ.
+        """
         c = self.config
         h, w = image.shape[:2]
-        wm_w = max(40, int(w * c.width_frac))
-        wm_h = max(16, int(w * c.height_frac))
-        margin_x = max(c.margin_floor, int(w * c.margin_x_frac))
-        margin_b = max(c.margin_floor, int(w * c.margin_bottom_frac))
-        x = max(0, w - margin_x - wm_w) if c.corner == "br" else min(margin_x, max(0, w - wm_w))
-        y = max(0, h - margin_b - wm_h)
+        base = self.scale_base(image)
+        wm_w = max(40, int(base * c.width_frac))
+        wm_h = max(16, int(base * c.height_frac))
+        margin_x = max(c.margin_floor, int(base * c.margin_x_frac))
+        margin_b = max(c.margin_floor, int(base * c.margin_bottom_frac))
+        if c.corner == "br":
+            x = max(0, w - margin_x - wm_w)
+        elif c.corner == "bc":  # bottom-center: horizontally centered, margin_x unused
+            x = max(0, (w - wm_w) // 2)
+        else:
+            x = min(margin_x, max(0, w - wm_w))
+        # "tl" anchors at the top instead: margin_bottom_frac is then the TOP margin.
+        y = min(margin_b, max(0, h - wm_h)) if c.corner == "tl" else max(0, h - margin_b - wm_h)
         wm_w = min(wm_w, w - x)
         wm_h = min(wm_h, h - y)
         return TextMarkLocation(x=x, y=y, w=wm_w, h=wm_h, is_fallback=True)
@@ -262,9 +534,17 @@ class TextMarkEngine:
 
     # ── Detect ──────────────────────────────────────────────────────────
 
-    def detect(self, image: NDArray[Any]) -> TextMarkDetection:
+    def detect(self, image: NDArray[Any], *, provenance: bool = False) -> TextMarkDetection:
         """Detect the mark by matching the alpha-template glyph silhouette against
-        the corner candidate (``TM_CCOEFF_NORMED``); keys on glyph SHAPE, not coverage."""
+        the corner candidate (``TM_CCOEFF_NORMED``); keys on glyph SHAPE, not coverage.
+
+        ``provenance`` signals that external metadata already confirms this vendor
+        (China-AIGC / byteimg for Doubao/Jimeng, ``samsung_genai`` for Samsung); the
+        NCC gate exists to keep a corner texture on an UNRELATED image from matching
+        the glyph silhouette, so when provenance confirms the vendor it is relaxed by
+        the mark's own ``provenance_ncc_factor`` to recover a faint or slightly
+        re-rendered mark (per-mark, not shared -- see _DEFAULT_PROVENANCE_NCC_FACTOR).
+        """
         c = self.config
         det = TextMarkDetection()
         if image is None or image.size == 0:
@@ -286,262 +566,115 @@ class TextMarkEngine:
         coverage = float((box > 0).sum()) / float(max(1, bw * bh))
         det.region = loc.bbox
         det.coverage = coverage
-        if coverage >= c.detect_min_coverage:
-            score = self._template_match_score(box, image.shape[1])
+        if c.detect_frontend == "tophat":
+            # The continuous front-end does not depend on the binarized blob, so the
+            # coverage gate (a blob-area heuristic) does not apply to it.
+            score = self._tophat_score(image, loc)
+            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
             det.confidence = score
-            det.detected = score >= c.detect_ncc_threshold
-            logger.debug("%s detect: coverage=%.3f ncc=%.2f detected=%s", c.name, coverage, score, det.detected)
+            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
+            logger.debug("%s detect (tophat): ncc=%.2f thr=%.2f detected=%s", c.name, score, threshold, det.detected)
+            return det
+        if c.detect_frontend == "gray":
+            # Same no-coverage-gate reasoning as tophat: the gray front-end never
+            # binarizes, so a blob-area heuristic does not apply to it either.
+            score = self._gray_best(image, loc)[0]
+            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
+            det.confidence = score
+            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
+            logger.debug("%s detect (gray): ncc=%.2f thr=%.2f detected=%s", c.name, score, threshold, det.detected)
+            return det
+        if coverage >= c.detect_min_coverage:
+            score = self._template_match_score(box, self.scale_base(image))
+            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
+            det.confidence = score
+            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
+            logger.debug(
+                "%s detect: coverage=%.3f ncc=%.2f thr=%.2f detected=%s",
+                c.name,
+                coverage,
+                score,
+                threshold,
+                det.detected,
+            )
         return det
 
-    # ── Reverse-alpha (recovery + thin residual inpaint) ────────────────
-
-    def reverse_alpha_available(self, image: NDArray[Any]) -> bool:
-        """True if the bundled alpha map is loadable (NCC alignment places it at any
-        resolution; the caller still gates on ``detect`` so a clean corner is untouched)."""
-        return image is not None and image.size > 0 and self._alpha_template() is not None
-
-    def _fixed_alpha_map(self, image: NDArray[Any]) -> tuple[NDArray[Any], tuple[int, int, int, int]] | None:
-        """Place the template by fixed width-relative geometry (pixel-exact at the
-        captured width).
-
-        Returns the glyph-sized alpha BLOCK (shape ``(gh, gw)``) plus its placement
-        ``(ax, ay, gw, gh)``, not a full-frame ``(h, w)`` map. The map is non-zero
-        only inside the glyph box and every consumer reads exactly that box, so a
-        full-frame float32 map was O(image*4 bytes) of mostly zeros -- ~48 MB on a
-        12 MP frame, and two were held at once (fixed + aligned). The block is
-        byte-identical to the old full-frame map's ``[ay:ay+gh, ax:ax+gw]`` slice.
-        """
-        c = self.config
-        at = self._alpha_template()
-        if at is None:
-            return None
-        h, w = image.shape[:2]
-        # Clamp both dims so a wide/short image cannot overflow the slice assignment.
-        gw = min(w, max(1, int(c.alpha_width_frac * w)))
-        gh = min(h, max(1, int(c.alpha_height_frac * w)))
-        if c.corner == "br":
-            ax = max(0, w - int(c.alpha_margin_x_frac * w) - gw)
-        else:  # bottom-left
-            ax = min(max(0, int(c.alpha_margin_x_frac * w)), max(0, w - gw))
-        ay = max(0, h - int(c.alpha_margin_bottom_frac * w) - gh)
-        block = cv2.resize(at, (gw, gh), interpolation=cv2.INTER_LINEAR)
-        return block, (ax, ay, gw, gh)
-
-    def _aligned_alpha_map(self, image: NDArray[Any]) -> tuple[NDArray[Any], tuple[int, int, int, int]] | None:
-        """Register the captured template to the actual mark via a TM_CCOEFF_NORMED
-        scale + position search. Returns the glyph-sized alpha BLOCK and its
-        placement ``(ax, ay, gw, gh)`` (see :meth:`_fixed_alpha_map` for why the
-        block, not a full-frame map), or None."""
-        c = self.config
-        at = self._alpha_template()
-        sil = self._glyph_silhouette()
-        if at is None or sil is None:
-            return None
-        w = image.shape[1]
-        loc = self.locate(image)
-        bx, by, bw, bh = loc.bbox
-        box_mask = self.extract_mask(image, loc)  # box-sized (== old full-frame cropped to bbox)
-        expected = c.alpha_width_frac * w
-        best: tuple[float, int, int, int, int] | None = None
-        for scale in np.linspace(*c.alpha_align_search):
-            gw, gh = int(expected * scale), int(c.alpha_height_frac * w * scale)
-            if gw < c.min_gw or gh < 4 or gw >= bw or gh >= bh:
-                continue
-            t = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_NEAREST)
-            _, score, _, top_left = cv2.minMaxLoc(cv2.matchTemplate(box_mask, t, cv2.TM_CCOEFF_NORMED))
-            if best is None or score > best[0]:
-                best = (score, gw, gh, top_left[0], top_left[1])
-        if best is None:
-            return None
-        _, gw, gh, ox, oy = best
-        ax, ay = bx + ox, by + oy
-        block = cv2.resize(at, (gw, gh), interpolation=cv2.INTER_LINEAR)
-        return block, (ax, ay, gw, gh)
-
-    def _apply_reverse_alpha(
-        self, image: NDArray[Any], amap: NDArray[Any], region: tuple[int, int, int, int]
-    ) -> NDArray[Any]:
-        """Invert the alpha blend with ``amap``: ``original = (wm - a*logo)/(1-a)``.
-
-        ``amap`` is the glyph-sized alpha BLOCK for ``region`` (x, y, w, h); outside
-        it the blend is a no-op (``(wm - 0)/(1 - 0) == wm``). Compute the math on the
-        glyph crop only and copy the rest through unchanged -- byte-identical to a
-        full-frame pass (a uint8 round-trip through float32 is exact), but O(glyph)
-        instead of O(image): a full-frame pass costs ~275 ms on a 12 MP frame for a
-        glyph that is <0.1% of it, and it runs once per candidate placement.
-        """
-        out = image.copy()
-        x1, y1, gw, gh = region
-        x2, y2 = x1 + gw, y1 + gh
-        if y1 >= y2 or x1 >= x2:
-            return out
-        a3 = np.clip(amap, 0.0, 1.0)[:, :, None]
-        logo = np.array(self.config.alpha_logo_bgr, np.float32)
-        roi = out[y1:y2, x1:x2].astype(np.float32)
-        out[y1:y2, x1:x2] = np.clip((roi - a3 * logo) / np.clip(1.0 - a3, 0.25, 1.0), 0, 255).astype(np.uint8)
-        return out
-
-    def _reverse_alpha_oversubtracts(
-        self, image: NDArray[Any], amap: NDArray[Any], region: tuple[int, int, int, int]
-    ) -> bool:
-        """True when reverse-alpha would darken the glyph footprint into a dark pit.
-
-        Ported from ``gemini_engine._reverse_alpha_oversubtracts`` (2026-06-20):
-        PREDICT the reverse-alpha output at the bright glyph core directly from the
-        INPUT and the captured alpha, ``(core_obs - a*logo)/(1-a)``, and trip when it
-        lands more than ``_OVERSUB_DARK_MARGIN`` gray levels below the local
-        background ring. Predicting from the input (not the produced output) keeps the
-        gate independent of which placement the reverse-alpha picked, so a clean
-        full-strength mark (whose strokes predict back to the background) never trips,
-        while a mark fainter than the capture (over-subtracted into a ghost) does.
-        """
-        ax, ay, gw, gh = region
-        ih, iw = image.shape[:2]
-        if gw < 4 or gh < 4:
-            return False
-        if float(amap.max()) < 0.2:  # too faint a capture to over-subtract meaningfully
-            return False
-        body_box = amap >= _OVERSUB_BODY_ALPHA_FLOOR  # glyph strokes
-        if not bool(body_box.any()):
-            return False
-        pad = max(4, int(gh * _OVERSUB_RING_PAD_FRAC))
-        ry1, ry2 = max(0, ay - pad), min(ih, ay + gh + pad)
-        rx1, rx2 = max(0, ax - pad), min(iw, ax + gw + pad)
-        ring = image[ry1:ry2, rx1:rx2].astype(np.float32).mean(axis=2)
-        fy1, fy2, fx1, fx2 = ay - ry1, ay - ry1 + gh, ax - rx1, ax - rx1 + gw
-        ring_mask = np.ones(ring.shape, dtype=bool)
-        ring_mask[fy1:fy2, fx1:fx2] = False
-        if int(ring_mask.sum()) < 10:
-            return False
-        # Predict the reverse-alpha output PER PIXEL over the glyph body -- exactly
-        # the (obs - a*logo)/(1-a) math the remover applies -- so a cleanly captured
-        # mark predicts back to the true background everywhere (no trip), while a mark
-        # fainter than the capture predicts a body far below the local ring. The
-        # per-pixel alpha (not a single peak value) keeps the prediction faithful
-        # across the glyph's anti-aliased alpha gradient.
-        obs = ring[fy1:fy2, fx1:fx2]
-        a = np.clip(amap, 0.0, 0.99)
-        logo = float(np.mean(self.config.alpha_logo_bgr))
-        predicted = (obs - a * logo) / (1.0 - a)
-        predicted_core = float(np.median(predicted[body_box]))
-        bg = float(np.median(ring[ring_mask]))
-        oversub = predicted_core < bg - _OVERSUB_DARK_MARGIN
-        if oversub:
-            logger.debug(
-                "%s reverse-alpha over-subtracts: predicted core=%.1f bg=%.1f (margin %.0f) -> footprint inpaint",
-                self.config.name,
-                predicted_core,
-                bg,
-                _OVERSUB_DARK_MARGIN,
-            )
-        return oversub
-
-    def _inpaint_footprint(
-        self, image: NDArray[Any], amap: NDArray[Any], region: tuple[int, int, int, int]
-    ) -> NDArray[Any]:
-        """Reconstruct the glyph footprint from its surroundings (used when
-        reverse-alpha would over-subtract into a dark pit). Inpaints the ORIGINAL
-        image over a dilated glyph mask, so the result never contains the darkened
-        reverse-alpha pixels."""
-        ax, ay, gw, gh = region
-        mask = np.zeros(image.shape[:2], np.uint8)
-        mask[ay : ay + gh, ax : ax + gw] = (amap > self.config.residual_alpha_floor).astype(np.uint8) * 255
-        mask = cv2.dilate(mask, np.ones((_OVERSUB_INPAINT_DILATE, _OVERSUB_INPAINT_DILATE), np.uint8))
-        return cv2.inpaint(image, mask, _OVERSUB_INPAINT_RADIUS, cv2.INPAINT_NS)
-
-    def remove_watermark_reverse_alpha(self, image: NDArray[Any], *, residual_inpaint: bool = True) -> NDArray[Any]:
-        """Recover the original pixels by inverting the alpha blend, then clear the
-        residual outline with a thin inpaint over the glyph footprint.
-
-        Placement: fixed geometry AND the NCC-aligned placement are always tried and
-        the one leaving the least residual mark (lowest re-``detect`` confidence) is
-        kept -- the mark re-rasterizes a few px per image, so fixed geometry alone is
-        not reliable. A single capture cannot pixel-cancel the mark on every image, so
-        a deliberately THIN residual inpaint (``residual_*``) follows: reverse-alpha
-        has already recovered the true background under the mark, so the inpaint only
-        finishes the residual edges instead of smearing the whole footprint. Call only
-        when :meth:`reverse_alpha_available` and the mark is detected.
-        """
-        c = self.config
-        # Normalize to 3-channel BGR (the reverse-alpha math assumes a 3-channel logo).
-        image = image_io.to_bgr(image)
-        # An image too small to hold the mark would make the geometry boxes degenerate
-        # and feed cv2.resize a ~1-px-tall target; skip cv2 entirely.
-        h, w = image.shape[:2]
-        if h < 32 or w < 64:
-            return image.copy()
-        maps = [m for m in (self._fixed_alpha_map(image), self._aligned_alpha_map(image)) if m is not None]
-        if not maps:
-            return image.copy()
-        best_out: NDArray[Any] | None = None
-        best_amap: NDArray[Any] | None = None
-        best_region: tuple[int, int, int, int] | None = None
-        best_residual = float("inf")
-        for amap, region in maps:
-            out = self._apply_reverse_alpha(image, amap, region)
-            residual = self.detect(out).confidence
-            if residual < best_residual:
-                best_residual, best_out, best_amap, best_region = residual, out, amap, region
-        if best_out is None or best_amap is None or best_region is None:  # pragma: no cover - maps is non-empty
-            return image.copy()
-        # Over-subtraction guard: on a dark/mid-tone background the captured alpha can
-        # over-estimate the mark's opacity and reverse-alpha leaves a darker-than-
-        # background ghost. When the recovered glyph body sits far below the local
-        # ring, reconstruct the footprint from its surroundings instead of shipping the
-        # dark pit (the thin residual inpaint cannot fix a footprint-wide darkening).
-        if self._reverse_alpha_oversubtracts(image, best_amap, best_region):
-            return self._inpaint_footprint(image, best_amap, best_region)
-        if residual_inpaint:
-            # Embed the glyph-sized alpha block into a full-frame uint8 mask only for
-            # the inpaint (cv2.inpaint needs a mask matching best_out). One uint8
-            # full-frame array, built once, vs the old two full-frame float32 maps;
-            # byte-identical to thresholding the old full-frame float32 map (zero
-            # outside the block, so the dilate/inpaint see the same mask).
-            ax, ay, gw, gh = best_region
-            rm = np.zeros(best_out.shape[:2], np.uint8)
-            rm[ay : ay + gh, ax : ax + gw] = (best_amap > c.residual_alpha_floor).astype(np.uint8) * 255
-            kernel = np.ones((c.residual_dilate, c.residual_dilate), np.uint8)
-            rm = cv2.dilate(rm, kernel)
-            best_out = cv2.inpaint(best_out, rm, c.residual_inpaint_radius, cv2.INPAINT_NS)
-        return best_out
-
     # ── Inpaint footprint (for the inpaint-fallback removal path) ────────
 
+    # Minimum glyph pixels for a template-free footprint. Below this the corner has
+    # no real wordmark (a few top-hat specks), so without ``force`` there is nothing
+    # to mask. A real strip covers hundreds of pixels.
+    _MIN_GLYPH_PIXELS = 20
+
     def footprint_mask(
         self, image: NDArray[Any], *, force: bool = False, dilate: int | None = None
     ) -> NDArray[Any] | None:
-        """Full-frame uint8 mask (255 = mark) of the mark footprint, for the
-        inpaint-fallback removal path (LaMa / cv2), or None if no placement fits.
+        """Full-frame uint8 mask (255 = mark) of the mark footprint, for the shared
+        fill removal path (cv2 / MI-GAN / LaMa), or None if no glyph is found.
 
-        ``force`` is accepted for a uniform engine signature (the caller passes it to
-        every engine) but ignored here -- the text-mark footprint is always the
-        geometry-placed captured silhouette, present with or without a detection.
+        Template-FREE: localize the glyph blob with the top-hat :meth:`extract_mask`,
+        take its bounding box in the corner, and fill that box solid (plus a small
+        margin + dilation). Filling the enclosing rectangle -- not the sparse glyph
+        strokes -- is what makes it robust: the top-hat under-segments individual
+        strokes (which used to leave a "三包"-style residual ghost when the strokes
+        themselves were the mask), but the inpaint reconstructs the whole wordmark
+        rectangle from its surroundings, so a stroke missed by the top-hat is still
+        covered. This drops the fixed alpha-template dependency, so a re-rendered or
+        differently-localized mark (e.g. a non-Italian Samsung string) is still masked.
 
-        Uses the NCC-ALIGNED captured silhouette, NOT the per-image
-        :meth:`extract_mask` signature: the signature under-segments the glyphs, so
-        inpainting it leaves a residual ghost (corpus-validated 2026-07 -- Doubao
-        left a "三包" remnant). The mask is dilated to absorb alpha-alignment slop
-        (a scale/position mismatch at low detect confidence otherwise leaves a thin
-        residual ring); ``dilate`` defaults to a mark-relative margin.
-
-        The caller gates on detection -- this returns the geometric footprint
-        regardless, so a clean corner would be masked too.
+        With ``force`` and no glyph found, falls back to the whole geometry box (the
+        ``--no-detect`` path). The caller gates on detection.
         """
+        if image is None or image.size == 0:
+            return None  # guard before to_bgr (cvtColor raises on an empty Mat); mirror detect()
         image = image_io.to_bgr(image)
         h, w = image.shape[:2]
         if h < 32 or w < 64:
             return None
-        placed = self._aligned_alpha_map(image) or self._fixed_alpha_map(image)
-        if placed is None:
+        loc = self.locate(image)
+        bx, by, bw, bh = loc.bbox
+        glyph = self.extract_mask(image, loc)  # box-sized, 255 = glyph
+        ys, xs = np.where(glyph > 0)
+        box: tuple[int, int, int, int] | None = None
+        if self.config.detect_frontend == "gray" and self.detect(image).detected:
+            # The gray front-end exists for marks the top-hat under-segments, so the
+            # binary blob is NOT authoritative here: trusting it first bounded the
+            # fill by a PARTIAL blob (the faint head glyphs dropped out) and left the
+            # leftmost "Runni" of "RunningHub AI生成" unremoved (2026-07-22). Use the
+            # detector's own best-match box, same as the tophat faint path below.
+            _, box = self._gray_best(image, loc)
+        elif xs.size >= self._MIN_GLYPH_PIXELS:
+            box = (int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max()))
+        elif self.config.detect_frontend == "tophat" and self.detect(image).detected:
+            # A mark found only by the CONTINUOUS front-end has no binary glyph blob to
+            # bound, so the mask came back empty and removal was a silent no-op while
+            # `identify` still reported the mark (corpus-measured 2026-07-20: 57 of 60
+            # sampled still-detected Doubao marks were untouched, ~8% of its detections).
+            # Use the DETECTOR'S OWN best-match box: the correlation already located the
+            # mark at a position and scale, and thresholding the response was a strictly
+            # worse proxy for that. An earlier fix thresholded the max-normalized uint8
+            # response at 0.5 -- which selects every non-zero pixel, not "half the peak" as
+            # its comment claimed -- and filled ~120% of the corner box on textured frames
+            # (measured: whole corner vs 58.7% for the match box, both detector-clean).
+            # Gated on an actual detection: on a clean corner the box would be spurious.
+            _, box = self._tophat_best(image, loc)
+        if box is not None:
+            gx0, gy0, gx1, gy1 = box
+            pad = max(4, int(0.10 * bh))
+            rx1 = max(0, bx + gx0 - pad)
+            rx2 = min(w, bx + gx1 + 1 + pad)
+            ry1 = max(0, by + gy0 - pad)
+            ry2 = min(h, by + gy1 + 1 + pad)
+        elif force:
+            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
+        else:
             return None
-        block, (ax, ay, gw, gh) = placed
-        sil = (block > self.config.residual_alpha_floor).astype(np.uint8) * 255
-        if int((sil > 0).sum()) == 0:
+        if rx1 >= rx2 or ry1 >= ry2:
             return None
-        mask = np.zeros((h, w), np.uint8)
-        ch, cw = min(gh, h - ay), min(gw, w - ax)
-        mask[ay : ay + ch, ax : ax + cw] = sil[:ch, :cw]
-        d = dilate if dilate is not None else max(9, int(0.05 * gw))
-        if d > 0:
-            mask = cv2.dilate(mask, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * d + 1, 2 * d + 1)))
-        return mask
+        # Rectangular footprint + dilation is exactly region_eraser.boxes_to_mask (the
+        # same primitive the shared fill uses); reuse it instead of re-inlining the
+        # zeros/fill/MORPH_ELLIPSE-dilate here.
+        from remove_ai_watermarks import region_eraser
+
+        d = dilate if dilate is not None else max(3, int(0.02 * bw))
+        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)

src/remove_ai_watermarks/api.py

@@ -0,0 +1,178 @@
+"""High-level convenience API: clean an image (or array) in one call.
+
+The low-level building blocks live in ``watermark_registry`` (localize -> fill) and
+``image_io`` (Unicode-safe, alpha-preserving IO). This module ties them into the two
+calls a caller usually wants, so a library user does not have to decode images, wire
+up metadata provenance, or preserve the alpha channel by hand:
+
+    import remove_ai_watermarks as raiw
+    raiw.remove_visible("in.png", "out.png")                 # path -> file, provenance auto
+    result, removed = raiw.remove_visible(bgr_array)         # array -> array
+    raiw.remove_visible("shot.png", "out.png", sensitivity="strict")
+    raiw.visible_provenance("in.png")                        # -> frozenset({"gemini"})
+
+Imports stay lazy (inside the functions), so ``import remove_ai_watermarks`` is cheap.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from remove_ai_watermarks.watermark_registry import Backend, Sensitivity
+
+
+@dataclass(frozen=True)
+class _VisibleInput:
+    """Normalized visible-removal input with its file-only context."""
+
+    bgr: NDArray[Any]
+    alpha: NDArray[Any] | None = None
+    path: Path | None = None
+    provenance: frozenset[str] = frozenset()
+
+
+def visible_provenance(source: str | Path) -> frozenset[str]:
+    """Vendor keys that the file's local metadata confirms, the evidence that drives
+    the ``auto`` sensitivity (relaxing a corroborated mark's detection trust gate).
+
+    Mapping: a Google/Gemini C2PA issuer -> ``"gemini"``; a China-AIGC (TC260) label
+    -> ``"doubao"``/``"jimeng"``; a ``samsung_genai`` marker -> ``"samsung"``.
+    Best-effort: any read error yields an empty set (no relaxation). Metadata-only, so
+    it never loads cv2/torch.
+    """
+    import contextlib
+
+    path = Path(source)
+    with contextlib.suppress(Exception):
+        from remove_ai_watermarks import identify
+
+        rep = identify.identify(path, check_visible=False, check_invisible=False)
+        signal_names = {signal.name for signal in rep.signals}
+        keys: set[str] = set()
+        platform = (rep.platform or "").lower()
+        if "google" in platform or "gemini" in platform:
+            keys.add("gemini")
+        if "aigc" in signal_names:
+            keys |= {"doubao", "jimeng"}
+        if "samsung_genai" in signal_names:
+            keys.add("samsung")
+        return frozenset(keys)
+    return frozenset()
+
+
+def _load_visible_input(source: str | Path | NDArray[Any]) -> _VisibleInput:
+    """Normalize a path/array source without making the public operation stateful."""
+    if not isinstance(source, (str, Path)):
+        return _VisibleInput(source)
+
+    from remove_ai_watermarks import image_io
+
+    path = Path(source)
+    bgr, alpha = image_io.read_bgr_and_alpha(path)
+    if bgr is None:
+        raise ValueError(f"Could not read image: {source}")
+    return _VisibleInput(bgr=bgr, alpha=alpha, path=path, provenance=visible_provenance(path))
+
+
+def _write_visible_result(
+    loaded: _VisibleInput,
+    result: NDArray[Any],
+    removed: list[str],
+    output: str | Path,
+    *,
+    strip_metadata: bool,
+    write_noop: bool,
+) -> None:
+    """Write one visible-removal result while preserving a true no-op losslessly."""
+    if not removed and not write_noop:
+        return
+
+    from remove_ai_watermarks import image_io
+
+    out_path = Path(output)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    source_path = loaded.path
+    if not removed and source_path is not None and source_path.suffix.lower() == out_path.suffix.lower():
+        # Copy the ORIGINAL bytes instead of lossily re-encoding a no-op. An in-place
+        # call needs no copy and would otherwise raise shutil.SameFileError.
+        if source_path.resolve() != out_path.resolve():
+            import shutil
+
+            shutil.copyfile(source_path, out_path)
+    else:
+        # imwrite is contractually NON-RAISING, so this bool is the only signal the file
+        # was not created. Unchecked, the metadata strip below ran on a nonexistent path
+        # and surfaced as a confusing "cannot read image <INPUT>" naming the OUTPUT path
+        # (Tier E, 2026-07-20). Raise here so a library caller and the CLI both get an
+        # accurate message about the write.
+        if not image_io.write_bgr_with_alpha(out_path, result, loaded.alpha):
+            raise OSError(f"failed to write output (is the destination writable?): {out_path}")
+
+    if strip_metadata:
+        from remove_ai_watermarks import metadata
+
+        metadata.remove_ai_metadata(out_path, out_path)
+
+
+def remove_visible(
+    source: str | Path | NDArray[Any],
+    output: str | Path | None = None,
+    *,
+    sensitivity: Sensitivity = "auto",
+    backend: Backend = "auto",
+    strip_metadata: bool = True,
+    write_noop: bool = True,
+) -> tuple[NDArray[Any], list[str]]:
+    """Remove every detected known visible AI mark (Gemini sparkle, Doubao/Jimeng/
+    Samsung text, the Jimeng pill) via localize -> fill, returning ``(result_bgr,
+    [labels removed])``.
+
+    ``source`` is a file path OR a BGR ndarray. For a PATH, metadata provenance is read
+    automatically (so ``sensitivity="auto"`` recovers a moved/faint mark whenever the
+    file still carries its provenance) and the alpha channel is preserved on write; for
+    an ARRAY there is no metadata to read and no separate alpha plane. When ``output``
+    is given the cleaned image is written there (alpha rejoined for a path source); the
+    array is always returned as well, so an empty ``removed`` list tells a caller nothing
+    known was found (e.g. route to the diffusion ``all`` path or ``erase``).
+
+    ``sensitivity`` (``auto``/``strict``) and ``backend``
+    (``auto``/``cv2``/``migan``/``lama``) are the same knobs as the CLI. Pass
+    corner if the guess is wrong).
+
+    ``strip_metadata`` (default True, matching the CLI ``visible --strip-metadata``)
+    also strips AI provenance metadata (C2PA/EXIF/XMP/IPTC) from the written output via
+    the lossless :func:`metadata.remove_ai_metadata`, so a library call does exactly
+    what the CLI does. Only applies when ``output`` is given.
+
+    ``write_noop`` (default True) controls whether ``output`` is written when NOTHING was
+    removed: True writes a clean passthrough copy (an idempotent clean); False leaves the
+    output path untouched, so a caller that treats "no mark" as "produce nothing" (the CLI
+    ``visible`` no-mark contract) does not clobber a pre-existing file at that path.
+    """
+    from remove_ai_watermarks import watermark_registry
+
+    # Reject a removed sensitivity loudly; `Sensitivity` is a Literal and not enforced
+    # at runtime, so a 0.15 caller would otherwise get `auto` behaviour in silence.
+    watermark_registry.validate_sensitivity(sensitivity)
+    loaded = _load_visible_input(source)
+    result, removed = watermark_registry.remove_auto_marks(
+        loaded.bgr,
+        sensitivity=sensitivity,
+        provenance=loaded.provenance,
+        backend=backend,
+    )
+    if output is not None:
+        _write_visible_result(
+            loaded,
+            result,
+            removed,
+            output,
+            strip_metadata=strip_metadata,
+            write_noop=write_noop,
+        )
+    return result, removed

src/remove_ai_watermarks/baidu_engine.py

@@ -0,0 +1,203 @@
+"""Baidu visible watermark detector/localizer.
+
+Baidu stamps its generations with a white bold "百度" text run plus a separate
+white rounded tag carrying dark "AI生成", bottom-right -- the China TC260
+explicit AIGC label. Detection keys on the **百度 text run only**: a
+two-component template (text + pill tag) was measured and REJECTED -- the solid
+white pill is a bright-blob magnet and both front-ends scored the clean arm at
+cohort levels (tophat clean p95 0.445 / gray clean p95 0.487 vs cohort ~0.5,
+2026-07-22). The text-only silhouette separates cleanly (below). The white tag
+is still removed with the mark: the fill blob covers both bright components in
+the corner box.
+
+Removal is the shared **localize -> fill** (:meth:`footprint_mask` ->
+``region_eraser``). This module supplies only Baidu's tuned
+:class:`TextMarkConfig` (``assets/baidu_alpha.png`` -- a font-rendered
+synthetic silhouette from ``scripts/render_vendor_silhouettes.py``, never cut
+from an upload).
+
+Measured on the vendor cohort (16 TC260 carriers whose producer USCC
+91110000802100433B names Baidu, harvested 2026-07-22 by
+``scripts/vendor_cohort_harvest.py``), NOT inherited from Doubao:
+
+  * The 百度 text run is 0.090 of the SHORT side wide (measured on 720/768/
+    1024-px frames), with its right edge ~0.099 of short off the right edge
+    (the pill tag sits between the text and the corner), bottom margin
+    ~0.006; the locate box below covers the whole mark (text + tag).
+  * Gate 0.43 (tophat front-end): on 278 hand-labelled clean frames
+    (cohort-contamination-guarded) the max is 0.352 / p99 0.314, and the
+    visibly-marked cohort frames score 0.386-0.65. Picked over the clean-arm
+    0.37 after a full-corpus check on the 741-frame blind-labelled eval set
+    surfaced 13 cross-fires at 0.38-0.43 (12 Qwen marks + one 抖音 mark) --
+    see DETECT_NCC_THRESHOLD below. At 0.43 the cohort keeps 7 detections
+    (0.61-0.65) and the whole 741 set fires only on the true Baidu frame.
+  * STRICT ONLY (``provenance_ncc_factor`` 1.0): the cohort is small (16) and
+    the sub-gate band is unmeasured, so no provenance relaxation exists.
+"""
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+# Locate geometry as a fraction of the image SHORT side (measured basis). The
+# box covers the text run AND the pill tag to its right (tag right edge ~0.002
+# off the frame edge, text run left edge ~0.19 off).
+WM_WIDTH_FRAC = 0.25
+WM_HEIGHT_FRAC = 0.07
+MARGIN_RIGHT_FRAC = 0.002
+MARGIN_BOTTOM_FRAC = 0.002
+
+# Glyph appearance: white bold text on a usually-darker background (white
+# top-hat), same overlay class as Doubao -- inherited, harmless because the
+# tophat front-end turns these gates into weights.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+TOPHAT_DELTA = 12
+
+DETECT_MIN_COVERAGE = 0.04  # unused by the tophat front-end (kept for config parity)
+# Calibrated 2026-07-22 on the vendor cohort vs 278 hand-labelled clean frames
+# (clean p99 0.314 / max 0.352), THEN raised 0.37 -> 0.43 after a full-corpus
+# check: on the 741-frame blind-labelled eval set the 0.37 gate fired 14 times
+# outside the cohort, and only ONE was the vendor -- 12 were 千问AI生成 (Qwen)
+# marks (the 百/千 first glyphs are near-identical after binarization) and one
+# was a 抖音 AI创作 mark at 0.425. The Qwen fires are handled by the rival
+# margin (Qwen scores 0.58-0.76 there, beating Baidu by 0.17-0.35), but the
+# 抖音 one named no registered rival, so the gate moved above it. Cost: the
+# cohort's low trio at 0.386 (3 genuine marks) -- precision over recall on a
+# small cohort. Raised again 0.43 -> 0.48 after the full-corpus sweep
+# (2026-07-22): outside-cohort true Baidu carriers score 0.50-0.66 while the
+# false fires (大众点评 UI, a math blackboard, an 80s banner, a checkerboard)
+# top out at 0.47. Remaining cohort detections: 7 at 0.61-0.65, plus the 6
+# metadata-stripped true carriers the cohort cannot see.
+DETECT_NCC_THRESHOLD = 0.48
+
+# Detection-silhouette geometry (fraction of the short side): the 百度 text run
+# only, measured 0.090 wide with aspect 0.51.
+_ALPHA_WIDTH_FRAC = 0.090
+_ALPHA_HEIGHT_FRAC = 0.046
+
+# Tight ladder: the NCC comb is sharp in size (see runninghub_engine), so the
+# nominal sits exactly on the measured 0.090 with +-5% rungs.
+_LADDER = (0.95, 1.0, 1.05)
+
+_CONFIG = TextMarkConfig(
+    name="Baidu",
+    asset_name="baidu_alpha.png",
+    corner="br",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_RIGHT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    detect_frontend="tophat",
+    scale_basis="short",
+    ladder=_LADDER,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    min_gw=8,
+    # Load-bearing rival margins (crossfire measured 2026-07-22): the 百度 and
+    # 豆包 silhouettes share their second glyph and a similar first, and 百度 vs
+    # 千问 are near-identical after binarization -- at the 0.37 gate this
+    # template fires on 45.8% of 400 Doubao-marked frames AND on Qwen-marked
+    # frames at 0.38-0.43. Doubao's template beats it by ~0.56 on Doubao marks,
+    # Qwen's by 0.17-0.35 on Qwen marks, so the 0.10 margin suppresses all of
+    # that crossfire at zero genuine-Baidu cost (cohort fire+m == fire).
+    rivals=("doubao_alpha.png", "qwen_alpha.png"),
+    # STRICT ONLY: small cohort, the relaxed band is unmeasured.
+    provenance_ncc_factor=1.0,
+)
+
+BaiduDetection = TextMarkDetection
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled Baidu alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "百度" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
+
+
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
+    """TM_CCOEFF_NORMED of the Baidu glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
+
+
+class BaiduEngine(TextMarkEngine):
+    """Detect/localize the visible Baidu "百度 AI生成" mark (bottom-right; localize -> fill)."""
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)
+
+    def footprint_mask(
+        self, image: NDArray[Any] | None, *, force: bool = False, dilate: int | None = None
+    ) -> NDArray[Any] | None:
+        """Full-frame mask of the WHOLE mark (text run + the pill tag to its right).
+
+        The base class's blob-bbox footprint UNDERCOVERS this mark: the white tag's
+        flat interior gives no top-hat response (a top-hat answers edges, not flats),
+        so the blob ends at the text run and the fill leaves the tag's right half as
+        a ghost (measured 2026-07-22 on the 768x1024 cohort frame: blob bbox x
+        632..746 vs the tag ending ~758). The layout is measured and fixed -- the
+        text run is at the left of the locate box, the tag runs to the corner -- so
+        the footprint is the detector's match box extended RIGHT to the corner.
+        """
+        if image is None or image.size == 0:
+            return None
+
+        from remove_ai_watermarks import image_io, region_eraser
+
+        image = image_io.to_bgr(image)
+        h, w = image.shape[:2]
+        if h < 32 or w < 64:
+            return None
+        loc = self.locate(image)
+        bx, by, bw, bh = loc.bbox
+        if force:
+            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
+        else:
+            if not self.detect(image).detected:
+                return None
+            _, box = self._tophat_best(image, loc)
+            if box is None:
+                return None
+            gx0, gy0, _gx1, gy1 = box
+            pad = max(4, int(0.15 * bh))
+            rx1 = max(0, bx + gx0 - pad)
+            ry1 = max(0, by + gy0 - pad)
+            rx2 = min(w, bx + bw)  # the tag runs to the corner end of the box
+            ry2 = min(h, by + gy1 + 1 + pad)
+        if rx1 >= rx2 or ry1 >= ry2:
+            return None
+        d = dilate if dilate is not None else max(3, int(0.02 * bw))
+        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/doubao_engine.py

@@ -1,16 +1,17 @@
-"""Doubao visible watermark removal engine.
+"""Doubao visible watermark detector/localizer.
 
 Doubao (ByteDance) stamps every generated image with a visible "豆包AI生成"
 (Doubao AI generated) text strip in the bottom-right corner -- the explicit AIGC
 label mandated by China's TC260 standard, a near-white semi-transparent overlay.
 
-Removal is **reverse-alpha blending** against a captured alpha map
-(``original = (wm - a*logo)/(1-a)``), always NCC-aligned to the actual mark plus a
-thin residual inpaint over the glyph footprint. This is one of the three text-mark
-engines that share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`;
-this module supplies only Doubao's tuned :class:`TextMarkConfig` (bottom-right corner,
-``assets/doubao_alpha.png`` rebuilt by ``scripts/visible_alpha_solve.py``). Arbitrary-
-region inpainting still lives in ``region_eraser`` / the ``erase`` command.
+Detection matches the bundled glyph silhouette against the corner candidate; removal
+is the shared **localize -> fill** (the glyph-bbox :meth:`footprint_mask` feeds
+``region_eraser``), NOT reverse-alpha. This is one of the three text-mark engines that
+share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
+supplies only Doubao's tuned :class:`TextMarkConfig` (bottom-right corner,
+``assets/doubao_alpha.png`` -- the detection silhouette, rebuilt by
+``scripts/visible_alpha_solve.py``). Arbitrary-region inpainting still lives in
+``region_eraser`` / the ``erase`` command.
 """
 # The module-level _alpha_template / _glyph_silhouette / _template_match_score below
 # are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
@@ -46,21 +47,28 @@ TOPHAT_DELTA = 12  # glyph must exceed the local background by this many levels
 # Shape-consistent detection: match the bundled alpha glyph silhouette against the
 # corner candidate via TM_CCOEFF_NORMED (keys on glyph SHAPE, not coverage; #23).
 DETECT_MIN_COVERAGE = 0.04
-DETECT_NCC_THRESHOLD = 0.4
+# NOTE: this gate is FRONT-END SPECIFIC. The continuous top-hat front-end scores higher
+# overall than the binary one (mean 0.809 vs 0.723 on the same 90 positives), so the
+# binary-era 0.40 left the provenance-relaxed gate (x0.7) far too low and admitted false
+# fires. Calibrated on the 240-image unbiased recall sample, full auto path:
+#
+#   gate   relaxed   recall   precision   true   false
+#   0.40     0.280      96%         91%     86       8
+#   0.45     0.315      94%         93%     85       6
+#   0.50     0.350      92%         99%     83       1   <- chosen
+#   0.60     0.420      87%         99%     78       1
+#
+# 0.50 beats the binary front-end on recall (92% vs 89%) at identical precision (99%),
+# which is the only reason the front-end switch is worth it. Do not port this number to
+# a binary-front-end mark; re-calibrate per front-end.
+DETECT_NCC_THRESHOLD = 0.50
 
-# Reverse-alpha geometry, emitted by scripts/visible_alpha_solve.py at the captured
-# width. Removal always tries fixed AND NCC-aligned placement and keeps the lower
-# residual, then a thin footprint inpaint clears the leftover edges.
+# Detection-silhouette geometry, emitted by scripts/visible_alpha_solve.py at the
+# captured width. Sizes the glyph silhouette for the TM_CCOEFF_NORMED detection match
+# (removal is the template-free glyph-bbox footprint mask, not this template).
 _ALPHA_NATIVE_WIDTH = 2048
-_ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
-_ALPHA_WIDTH_FRAC = 0.1636  # asset width / image width -- the alignment scale seed
+_ALPHA_WIDTH_FRAC = 0.1636  # asset width / image width -- sizes the detection silhouette
 _ALPHA_HEIGHT_FRAC = 0.0405
-_ALPHA_MARGIN_RIGHT_FRAC = 0.0132
-_ALPHA_MARGIN_BOTTOM_FRAC = 0.0166
-_ALPHA_ALIGN_SEARCH = (0.88, 1.12, 25)
-_RESIDUAL_ALPHA_FLOOR = 0.05
-_RESIDUAL_DILATE = 5
-_RESIDUAL_INPAINT_RADIUS = 2
 
 _CONFIG = TextMarkConfig(
     name="Doubao",
@@ -77,16 +85,15 @@ _CONFIG = TextMarkConfig(
     morph_open_size=5,
     detect_min_coverage=DETECT_MIN_COVERAGE,
     detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    detect_frontend="tophat",
+    scale_basis="short",  # measured: recovers 56% of landscape misses (see scale_base)
+    # No rival margin: measured 2026-07-18, the symmetric gate cost Doubao 7 genuine
+    # detections to prevent 5 false ones (1.4:1 against). Doubao's absolute detector
+    # is already 86% precise, so it has nothing to buy; Jimeng's is 38% and gains 25pp
+    # for free. The confusion is asymmetric, so the remedy is too.
     alpha_width_frac=_ALPHA_WIDTH_FRAC,
     alpha_height_frac=_ALPHA_HEIGHT_FRAC,
-    alpha_margin_x_frac=_ALPHA_MARGIN_RIGHT_FRAC,
-    alpha_margin_bottom_frac=_ALPHA_MARGIN_BOTTOM_FRAC,
-    alpha_align_search=_ALPHA_ALIGN_SEARCH,
     min_gw=8,
-    alpha_logo_bgr=_ALPHA_LOGO_BGR,
-    residual_alpha_floor=_RESIDUAL_ALPHA_FLOOR,
-    residual_dilate=_RESIDUAL_DILATE,
-    residual_inpaint_radius=_RESIDUAL_INPAINT_RADIUS,
 )
 
 # Doubao-specific aliases for the shared detection result/engine.
@@ -103,13 +110,13 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
     """TM_CCOEFF_NORMED of the Doubao glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, image_width, _CONFIG)
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
 
 
 class DoubaoEngine(TextMarkEngine):
-    """Remove the visible Doubao "豆包AI生成" watermark (locate -> mask -> reverse-alpha)."""
+    """Detect/localize the visible Doubao "豆包AI生成" watermark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)

src/remove_ai_watermarks/gemini_engine.py

@@ -1,16 +1,17 @@
-"""Gemini visible watermark removal engine.
+"""Gemini visible-sparkle detector and localizer (cv2/numpy, no GPU).
 
-Port of the GeminiWatermarkTool reverse-alpha-blending algorithm from C++ to Python.
-Original author: Allen Kuo (allenk) — https://github.com/allenk/GeminiWatermarkTool
+Locates the Google Gemini / Nano Banana sparkle so the shared fill (region_eraser)
+can inpaint it. Detection is a multi-scale NCC search against the captured sparkle
+alpha template (ported from GeminiWatermarkTool's Snap Engine; original author
+Allen Kuo (allenk), https://github.com/allenk/GeminiWatermarkTool), scored by a
+spatial + gradient + variance fusion with a false-positive gate. ``footprint_mask``
+returns the sparkle footprint (captured alpha thresholded low to include the halo,
+then dilated) as a full-frame mask for the fill.
 
-The Gemini AI watermark is applied using alpha blending:
-    watermarked = a * logo + (1 - a) * original
-
-We reverse this to recover the original:
-    original = (watermarked - a * logo) / (1 - a)
-
-The alpha maps are derived from background captures of the Gemini watermark
-on pure-black backgrounds (48x48 for small images, 96x96 for large images).
+The captured alpha maps are background captures of the sparkle on pure-black
+backgrounds (48x48 for small images, 96x96 for large). NB: they are used here only
+to DETECT and to shape the removal mask -- the old reverse-alpha pixel recovery
+(``original = (watermarked - a*logo)/(1-a)``) is gone; removal is localize -> fill.
 """
 
 # cv2/numpy boundary: cv2 and numpy ship no usable type info for the array ops
@@ -19,11 +20,12 @@ on pure-black backgrounds (48x48 for small images, 96x96 for large images).
 # pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false, reportOptionalMemberAccess=false, reportOptionalCall=false, reportOptionalSubscript=false, reportOptionalOperand=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false, reportPrivateUsage=false, reportInvalidTypeForm=false, reportConstantRedefinition=false, reportUnnecessaryComparison=false
 from __future__ import annotations
 
+import functools
 import logging
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any
 
 import cv2
 import numpy as np
@@ -125,52 +127,23 @@ def _load_embedded_asset(name: str) -> NDArray[Any]:
     return img
 
 
-class GeminiEngine:
-    """Engine for removing visible Gemini watermarks via reverse alpha blending.
+# Single source of truth for the multi-scale template ladder (aggressively downscaled to
+# slightly upscaled): the precomputed `_tmpl_cache` and the `_scan_scales` loop must use
+# the SAME scales or a scan scale would miss the cache and KeyError.
+_TEMPLATE_SCALES: tuple[int, ...] = tuple(range(16, 120, 2))
 
-    This is a Python port of the GeminiWatermarkTool C++ engine.
+
+class GeminiEngine:
+    """Detects and localizes the visible Gemini sparkle for the shared fill removal.
+
+    The multi-scale NCC detection is a Python port of the GeminiWatermarkTool C++
+    Snap Engine; ``footprint_mask`` turns a detection into a removal mask.
     """
 
-    # Footprint pixels with alpha at/above this are the sparkle body; below it the
-    # mark barely affects the pixel, so those are excluded from both the
-    # over-subtraction test and the inpaint mask.
-    _FOOTPRINT_ALPHA = 0.1
-    # If more than this fraction of footprint pixels over-subtract (numerator < 0),
-    # the fixed alpha does not match this image's sparkle and reverse-alpha would
-    # punch a dark pit -- inpaint instead. demo_banana measures 0.0 (reverse-alpha
-    # kept), the issue #30 dark-grass image measures ~0.61 (inpaint), so the 0.05
-    # gate separates them with a wide margin.
-    _OVERSUB_FOOTPRINT_FRAC = 0.05
-
-    # Mid-tone over-subtraction (2026-06-18 prod "the color just changed, not removed"
-    # report). The numerator fraction above only trips when reverse-alpha drives a
-    # footprint pixel fully NEGATIVE -- the dark-background black-pit case. On a MID-TONE
-    # background a sparkle fainter than the captured alpha is over-subtracted into a
-    # visibly DARKER-than-background diamond while no pixel ever crosses zero, so the
-    # numerator gate misses it and ships the dark mark. Predict the reverse-alpha output
-    # at the bright core, (core - a*logo)/(1-a); when it lands more than this many gray
-    # levels BELOW the local background ring, reverse-alpha would leave a dark diamond --
-    # inpaint instead. Calibrated wide: clean removals predict within ~12 of background
-    # (demo_banana ~-1, a bright-bg sparkle ~-12), the prod regression predicts ~-40 and
-    # the issue #30 dark case ~-82, so 25 separates keep-vs-inpaint with margin.
-    _OVERSUB_DARK_MARGIN = 25.0
-
-    # Per-image alpha gain (under-subtraction fix). The captured alpha peaks ~0.51
-    # (a ~51%-opaque sparkle). Some real Gemini sparkles are rendered MORE opaque,
-    # so the fixed alpha under-subtracts and reverse-alpha leaves a bright residual
-    # the detector still fires on (~11% of marks on the spaces corpus). Estimate
-    # this image's effective sparkle opacity from the bright core vs the local
-    # background and scale the alpha to match, capped so alpha stays < 0.99. The
-    # gain is clamped to >= 1.0 so it only ever STRENGTHENS removal: ~1.0 when the
-    # sparkle matches the capture (working cases unchanged), >1 when more opaque.
-    # On the spaces corpus the gain cleanly separates -- under-removed marks ~1.47,
-    # cleanly-removed ~1.00. 1.94 is the cap that reaches alpha 0.99 from 0.51.
-    _ALPHA_GAIN_MAX = 1.94
-    _ALPHA_GAIN_CORE_FRAC = 0.8  # body pixels at >= this * peak alpha define the core
-    # Deadband: apply the gain only above this, so a sparkle that already matches the
-    # capture (estimated gain ~1.0-1.04 from background noise) stays byte-identical to
-    # the pre-fix output. Under-removed marks estimate >= 1.26, well clear of the band.
-    _ALPHA_GAIN_DEADBAND = 1.05
+    # Body pixels at >= this fraction of the peak captured alpha define the sparkle
+    # "core", sampled by the detection FP-gate's core-vs-ring brightness margin
+    # (:meth:`_core_and_bg`).
+    _CORE_ALPHA_FRAC = 0.8
 
     # Sparkle false-positive gate. A real Gemini sparkle is a bright WHITE overlay,
     # so its core sits above the local background; a shape-only NCC match on ornate
@@ -201,22 +174,20 @@ class GeminiEngine:
     # confidence >= 0.65, above the gate).
     _SPARKLE_FP_GRAD = 0.55
 
-    # Self-verify fallback. The gain estimate corrects most under-subtractions, but
-    # on the spaces corpus a tail of strong sparkles still survived reverse-alpha
-    # (a few px of position jitter or a gain estimate the [1.0, 1.94] clamp could
-    # not fully reach). After the reverse blend, re-detect; if a sparkle this strong
-    # remains, inpaint the footprint and keep that ONLY when it lowers the re-detect
-    # confidence. Purely additive: the common clean removal re-detects below this and
-    # is returned untouched. Threshold matches the registry's real fail line (0.5),
-    # so it triggers exactly on the cases that would otherwise read as not-removed
-    # (rescued 4 of 15 corpus fails, 0 regressions). An offset+scale alignment search
-    # was prototyped on the remaining 11 but REJECTED: it only lowered the shape-NCC by
-    # moving the reverse-alpha to a different placement that left the sparkle as bright
-    # or brighter (NCC-gaming, not removal), so a brightness sanity check rejected every
-    # one. The footprint inpaint physically reconstructs the slot from its surroundings,
-    # so its rescues are genuine; the survivors are near-white ill-conditioning or
-    # detector false positives that no reverse-alpha placement fixes.
-    _VERIFY_FALLBACK_CONF = 0.5
+    # White-core rescue for the gate above. A real but FAINT sparkle -- a soft white
+    # star on a bright/textured background -- has a high core-ring margin but low
+    # gradient fidelity, the SAME signature the grad gate uses to demote the smooth
+    # colored-corner FP, so faint real sparkles get demoted with it. The separator the
+    # grad gate discards is the CORE COLOR: a real Gemini sparkle core is near-WHITE
+    # (low saturation), while a clean bright corner that shape-matches (sky, sun, a warm
+    # light) is COLORED. So do NOT demote a low-grad match that already clears the trust
+    # confidence (_SPARKLE_KEEP_CONF -- the registry's 0.5 sparkle gate plus a small
+    # margin so the ~0.51 bright-background FPs the grad gate was added for stay demoted)
+    # AND has a bright (margin) near-neutral core (_core_saturation <= _SPARKLE_WHITE_SAT).
+    # Corpus-measured on metadata-stripped faint sparkles: recovers ~14/20 the low-grad
+    # demotion would drop, at ~0.8% clean false-fire vs the ~0.55% baseline.
+    _SPARKLE_KEEP_CONF = 0.52
+    _SPARKLE_WHITE_SAT = 0.20
 
     # Corner promotion (issue #36): the size weight that suppresses tiny-patch
     # false positives also buries a small, near-perfect sparkle when a larger,
@@ -278,6 +249,16 @@ class GeminiEngine:
         self._alpha_small = _calculate_alpha_map(bg_small)
         self._alpha_large = _calculate_alpha_map(bg_large)
 
+        # Per-scale resized templates are constant (``_alpha_large`` never changes),
+        # so precompute the whole fixed 16..118 ladder once: ``_scan_scales`` runs it on
+        # every image (twice -- global + corner), and re-``resize``-ing the 96x96 source
+        # each time is pure repeated work. Prebuilt (not lazy) so the dict is read-only
+        # after construction and safe to share across threads via the module singleton.
+        self._tmpl_cache: dict[int, NDArray[Any]] = {
+            scale: cv2.resize(self._alpha_large, (scale, scale), interpolation=cv2.INTER_AREA)
+            for scale in _TEMPLATE_SCALES
+        }
+
         logger.debug(
             "Alpha maps loaded: small=%s, large=%s",
             self._alpha_small.shape,
@@ -311,11 +292,10 @@ class GeminiEngine:
         ``_alpha_large`` is the high-quality source downscaled per scale; the range
         covers aggressively downscaled to slightly upscaled logos.
         """
-        for scale in range(16, 120, 2):
+        for scale in _TEMPLATE_SCALES:
             if scale > gray.shape[0] or scale > gray.shape[1]:
                 continue
-            tmpl = cv2.resize(self._alpha_large, (scale, scale), interpolation=cv2.INTER_AREA)
-            match_res = cv2.matchTemplate(gray, tmpl, cv2.TM_CCOEFF_NORMED)
+            match_res = cv2.matchTemplate(gray, self._tmpl_cache[scale], cv2.TM_CCOEFF_NORMED)
             _, max_val, _, max_loc = cv2.minMaxLoc(match_res)
             yield scale, float(max_val), max_loc
 
@@ -323,8 +303,18 @@ class GeminiEngine:
         self,
         image: NDArray[Any],
         force_size: WatermarkSize | None = None,
+        *,
+        trust_provenance: bool = False,
     ) -> DetectionResult:
-        """Detect Gemini watermark using multi-scale Snap Engine logic (ported from C++ vendor algorithm)."""
+        """Detect Gemini watermark using multi-scale Snap Engine logic (ported from C++ vendor algorithm).
+
+        ``trust_provenance`` signals that external metadata already proves this is a
+        Google generation (C2PA issuer "Google"/"Gemini"). The false-positive gate
+        exists only to reject content that shape-matches the sparkle on NON-Google
+        images (Doubao text, ornate corners); when provenance confirms Google, that
+        gate would demote a genuine sparkle the vendor moved/re-rendered (bigger,
+        lighter, shifted), so it is skipped. The caller (registry) still applies the
+        relaxed provenance trust gate to the returned confidence."""
         result = DetectionResult()
 
         if image is None or image.size == 0:
@@ -387,6 +377,12 @@ class GeminiEngine:
         if promoted is not None:
             candidates.append(promoted)
 
+        # No candidate at any scale: the search region is smaller than the 16px template
+        # floor (an image whose short side is < 16px), so nothing is detectable. Return
+        # the empty (detected=False) result rather than dereferencing candidates[0].
+        if not candidates:
+            return result
+
         # Select the candidate with the highest full-fusion confidence (pre-FP-gate).
         best_scale, pos_x, pos_y, best_raw_ncc = candidates[0]
         grad_score, var_score, best_fused = 0.0, 0.0, -1.0
@@ -421,19 +417,27 @@ class GeminiEngine:
         # incl. bright). Demote when both are weak -- this catches the dark/mid no-core
         # FP (low margin) AND the bright-background smooth-blob FP (high margin but low
         # gradient), which the margin check alone misses. See _SPARKLE_FP_GRAD.
-        if confidence < self._SPARKLE_FP_CONF:
-            margin = self._core_ring_margin(image, self.get_interpolated_alpha(best_scale), (pos_x, pos_y))
+        if confidence < self._SPARKLE_FP_CONF and not trust_provenance:
+            alpha = self.get_interpolated_alpha(best_scale)
+            pos = (pos_x, pos_y)
+            margin = self._core_ring_margin(image, alpha, pos)
             low_margin = margin is not None and margin < self._SPARKLE_FP_MARGIN
             low_grad = grad_score < self._SPARKLE_FP_GRAD
             if low_margin or low_grad:
-                logger.debug(
-                    "Sparkle FP gate: conf=%.3f, core-ring margin=%s, grad=%.3f < %.2f; demoting.",
-                    confidence,
-                    f"{margin:.1f}" if margin is not None else "n/a",
-                    grad_score,
-                    self._SPARKLE_FP_GRAD,
-                )
-                confidence = min(confidence, 0.30)
+                # White-core rescue: a real faint sparkle clears the trust confidence,
+                # has a bright core (not low_margin), and a near-WHITE core -- unlike the
+                # colored-corner FP the low-grad demotion targets. See _SPARKLE_WHITE_SAT.
+                core_sat = self._core_saturation(image, alpha, pos)
+                white_core = not low_margin and core_sat is not None and core_sat <= self._SPARKLE_WHITE_SAT
+                if not (confidence >= self._SPARKLE_KEEP_CONF and white_core):
+                    logger.debug(
+                        "Sparkle FP gate: conf=%.3f, margin=%s, grad=%.3f, core_sat=%s; demoting.",
+                        confidence,
+                        f"{margin:.1f}" if margin is not None else "n/a",
+                        grad_score,
+                        f"{core_sat:.2f}" if core_sat is not None else "n/a",
+                    )
+                    confidence = min(confidence, 0.30)
 
         result.confidence = float(max(0.0, min(1.0, confidence)))
         result.detected = result.confidence >= 0.35
@@ -530,146 +534,68 @@ class GeminiEngine:
 
     # ── Removal ──────────────────────────────────────────────────────
 
-    def remove_watermark(
+    # Footprint mask for the localize -> fill removal path. The mask must cover the
+    # WHOLE sparkle including its faint semi-transparent halo, not just the bright
+    # core, or the fill leaves a visible ring. Threshold the captured alpha low
+    # (>_MASK_ALPHA catches the halo the core-only 0.10 misses) then dilate by a
+    # sparkle-relative margin so alignment slop and the outermost halo are absorbed.
+    _MASK_ALPHA = 0.04
+    _MASK_DILATE_FRAC = 0.18  # dilation radius as a fraction of the sparkle scale
+
+    def footprint_mask(
         self,
         image: NDArray[Any],
-        force_size: WatermarkSize | None = None,
-    ) -> NDArray[Any]:
-        """Remove Gemini visible watermark from an image using reverse alpha blending.
-
-        No-op when the detector does not find a watermark: returns an unmodified
-        copy. Reverse alpha blending applied where no sparkle exists creates a
-        visible inverse artifact, so we refuse to touch pixels without a positive
-        detection. To bypass detection (e.g. you know the exact region), use
-        ``remove_watermark_custom``.
-
-        Args:
-            image: BGR image as numpy array (will NOT be modified in-place).
-            force_size: Force a specific watermark size (auto-detect if None).
-
-        Returns:
-            Cleaned BGR image as numpy array, or an unmodified copy when no
-            watermark is detected.
-        """
-        # Normalize to 3-channel BGR up front: 2D grayscale (no channel axis) and
-        # 4-channel BGRA both reach this public entry point and would otherwise
-        # crash on the channel-count checks / downstream 3-channel math.
-        result = image_io.to_bgr(image.copy())
-
-        size = force_size or get_watermark_size(result.shape[1], result.shape[0])
-
-        # Detect dynamic position & size (on the normalized 3-channel image so a
-        # grayscale/BGRA input does not crash the detector).
-        detection = self.detect_watermark(result, force_size=size)
-
-        if not detection.detected:
-            logger.debug(
-                "No watermark detected (conf=%.3f); returning image unchanged.",
-                detection.confidence,
-            )
-            return result
-
-        pos = (detection.region[0], detection.region[1])
-        alpha_map = self.get_interpolated_alpha(detection.region[2])
-        # Match the captured alpha to this image's sparkle opacity (under-subtraction
-        # fix): a more-opaque-than-captured sparkle would otherwise leave a bright
-        # residual. gain == 1.0 leaves the working cases byte-identical.
-        gain = self._estimate_alpha_gain(result, alpha_map, pos)
-        if gain > self._ALPHA_GAIN_DEADBAND:
-            alpha_map = np.clip(alpha_map * gain, 0.0, 0.99)
-        logger.debug(
-            "Removing watermark at (%d, %d) size %dx%d [conf=%.3f]",
-            pos[0],
-            pos[1],
-            detection.region[2],
-            detection.region[3],
-            detection.confidence,
-        )
-
-        # The captured alpha map (max ~0.51 = a ~50%-opaque white sparkle) is exact
-        # only when the real mark's effective opacity matches it. On a dark/textured
-        # background the sparkle's effective alpha is lower than the capture, so the
-        # fixed-alpha reverse blend OVER-subtracts and drives the footprint to black --
-        # the "white sparkle turns into a black pit" bug (issue #30). The signature is
-        # a large fraction of footprint pixels whose numerator (watermarked - a*logo)
-        # goes negative, which is physically impossible under a brightening overlay.
-        # In that case inpaint the small footprint from the surrounding pixels instead;
-        # on a bright background no pixel over-subtracts, so reverse-alpha is used and
-        # the result is byte-identical to before (verified on demo_banana: 0% vs 61%).
-        if self._reverse_alpha_oversubtracts(result, alpha_map, pos):
-            logger.debug("Reverse-alpha over-subtracts on this background; inpainting sparkle footprint.")
-            self._inpaint_footprint(result, alpha_map, pos)
-        else:
-            self._reverse_alpha_blend(result, alpha_map, pos)
-        return self._verify_and_repair(result, alpha_map, pos, size)
-
-    def footprint_mask(self, image: NDArray[Any], *, force: bool = False, dilate: int = 13) -> NDArray[Any] | None:
+        *,
+        force: bool = False,
+        dilate: int | None = None,
+        region: tuple[int, int, int, int] | None = None,
+    ) -> NDArray[Any] | None:
         """Full-frame uint8 mask (255 = sparkle) of the sparkle footprint, for the
-        inpaint-fallback removal path (LaMa / cv2), or None.
+        shared fill removal path (cv2 / MI-GAN / LaMa), or None.
 
-        The footprint is the interpolated captured alpha at the detected scale --
-        the same region reverse-alpha operates on. When ``force`` and nothing is
-        detected, falls back to the default sparkle slot for the image size (the
-        ``--no-detect`` path). The caller gates on the trust-confidence detection.
+        The footprint is the interpolated captured alpha at the detected scale,
+        thresholded LOW so the faint halo is included, then dilated by a
+        sparkle-relative margin. When ``force`` and nothing is detected, falls back to
+        the default sparkle slot for the image size (the ``--no-detect`` path).
+
+        ``region`` is the already-resolved ``(x, y, scale)`` from the caller's detection
+        (the registry passes the decision's provenance-aware region). When given, the
+        mask is built from it directly WITHOUT a second internal detect -- otherwise a
+        provenance/assume-relaxed sparkle would be re-demoted by the strict re-detect and
+        yield no mask (reported-removed-but-unchanged). Absent ``region``, direct callers
+        keep the detect-then-force behavior.
         """
+        if image is None or image.size == 0:
+            return None  # guard before to_bgr (cvtColor raises on an empty Mat); mirror detect_watermark
         image = image_io.to_bgr(image)
         h, w = image.shape[:2]
-        det = self.detect_watermark(image)
-        if det.detected:
-            x, y, scale = det.region[0], det.region[1], det.region[2]
-        elif force:
-            cfg = get_watermark_config(w, h)
-            x, y = cfg.get_position(w, h)
-            scale = cfg.logo_size
+        if region is not None:
+            x, y, scale = region[0], region[1], region[2]
         else:
-            return None
+            det = self.detect_watermark(image)
+            if det.detected:
+                x, y, scale = det.region[0], det.region[1], det.region[2]
+            elif force:
+                cfg = get_watermark_config(w, h)
+                x, y = cfg.get_position(w, h)
+                scale = cfg.logo_size
+            else:
+                return None
         alpha = self.get_interpolated_alpha(scale)
         fp = self._footprint_indices(alpha, (x, y), image.shape)
         if fp is None:
             return None
         aroi, (y1, y2, x1, x2) = fp
-        sil = (aroi > 0.10).astype(np.uint8) * 255
+        sil = (aroi > self._MASK_ALPHA).astype(np.uint8) * 255
         if int((sil > 0).sum()) == 0:
             return None
         mask = np.zeros((h, w), np.uint8)
         mask[y1:y2, x1:x2] = sil
-        if dilate > 0:
-            mask = cv2.dilate(mask, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * dilate + 1, 2 * dilate + 1)))
+        d = dilate if dilate is not None else max(13, int(scale * self._MASK_DILATE_FRAC))
+        if d > 0:
+            mask = cv2.dilate(mask, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * d + 1, 2 * d + 1)))
         return mask
 
-    def remove_watermark_custom(
-        self,
-        image: NDArray[Any],
-        region: tuple[int, int, int, int],
-    ) -> NDArray[Any]:
-        """Remove watermark from a custom region with interpolated alpha map.
-
-        Args:
-            image: BGR image (will NOT be modified in-place).
-            region: (x, y, width, height) of the watermark region.
-
-        Returns:
-            Cleaned BGR image.
-        """
-        # Same channel normalization as remove_watermark: the reverse-alpha blend
-        # assumes 3-channel BGR (a grayscale/BGRA input would mis-broadcast).
-        result = image_io.to_bgr(image.copy())
-        x, y, rw, rh = region
-
-        # Check standard sizes
-        if rw == 48 and rh == 48:
-            self._reverse_alpha_blend(result, self._alpha_small, (x, y))
-            return result
-        if rw == 96 and rh == 96:
-            self._reverse_alpha_blend(result, self._alpha_large, (x, y))
-            return result
-
-        # Interpolate alpha map for custom size
-        interp = cv2.INTER_LINEAR if rw > 96 else cv2.INTER_AREA
-        alpha = cv2.resize(self._alpha_large, (rw, rh), interpolation=interp)
-        self._reverse_alpha_blend(result, alpha, (x, y))
-        return result
-
     def _footprint_indices(
         self,
         alpha_map: NDArray[Any],
@@ -712,7 +638,7 @@ class GeminiEngine:
         a_cap = float(alpha_roi.max())
         if a_cap < 0.2:
             return None
-        core = alpha_roi >= a_cap * self._ALPHA_GAIN_CORE_FRAC
+        core = alpha_roi >= a_cap * self._CORE_ALPHA_FRAC
         if not bool(core.any()):
             return None
         # Convert only the footprint+ring crop to gray, not the whole image: every
@@ -749,278 +675,46 @@ class GeminiEngine:
         cb = self._core_and_bg(image, alpha_map, position)
         return None if cb is None else cb[0] - cb[1]
 
-    def _estimate_alpha_gain(
+    def _core_saturation(
         self,
         image: NDArray[Any],
         alpha_map: NDArray[Any],
         position: tuple[int, int],
-    ) -> float:
-        """Scale factor matching the captured alpha to this image's sparkle opacity.
-
-        The captured alpha (peak ~0.51) under-represents sparkles rendered more
-        opaque; reverse-alpha then leaves a bright residual. Estimate the effective
-        opacity at the sparkle core (observed brightness vs the local background
-        ring) and return ``a_eff / a_capture``, clamped to ``[1.0, _ALPHA_GAIN_MAX]``
-        so it only ever STRENGTHENS removal (1.0 = no change on a matching sparkle).
-        Returns 1.0 when the background cannot be estimated reliably.
-        """
-        cb = self._core_and_bg(image, alpha_map, position)
-        if cb is None:
-            return 1.0
-        core_obs, bg, a_cap = cb
-        if 255.0 - bg < 5.0:
-            return 1.0
-        a_eff = float(np.clip((core_obs - bg) / (255.0 - bg), 0.0, 0.99))
-        return float(np.clip(a_eff / a_cap, 1.0, self._ALPHA_GAIN_MAX))
-
-    def _reverse_alpha_oversubtracts(
-        self,
-        image: NDArray[Any],
-        alpha_map: NDArray[Any],
-        position: tuple[int, int],
-    ) -> bool:
-        """True when reverse-alpha would drive the footprint dark.
-
-        Two signatures of the captured alpha over-estimating this image's sparkle
-        opacity, either of which means reverse-alpha would leave a dark mark:
-
-        1. Dark-background black pit (issue #30): the numerator
-           ``watermarked - alpha*logo`` over the sparkle body. A brightening overlay
-           can never make it negative, so a large negative fraction means the fixed
-           alpha over-subtracts past black.
-        2. Mid-tone dark diamond (see ``_OVERSUB_DARK_MARGIN``): on a mid-tone
-           background the over-subtraction darkens the core well below the background
-           without any pixel crossing zero, so case 1 misses it. Predict the
-           reverse-alpha core output and trip when it lands far below the local ring.
+    ) -> float | None:
+        """Median color saturation of the sparkle core (0 = white/neutral, higher =
+        colored). A real Gemini sparkle is a white star, so its core is near-neutral;
+        a clean bright corner that shape-matches (sky, sun, a warm light) is colored,
+        so a high core saturation flags the false positive the brightness/gradient
+        gates miss. Samples the same high-alpha core pixels as :meth:`_core_and_bg`.
+        None when the footprint cannot be placed or the core is empty.
         """
         placed = self._footprint_indices(alpha_map, position, image.shape)
         if placed is None:
-            return False
+            return None
         alpha_roi, (y1, y2, x1, x2) = placed
-        body = alpha_roi >= self._FOOTPRINT_ALPHA
-        if not bool(body.any()):
-            return False
-        roi = image[y1:y2, x1:x2].astype(np.float32)
-        numerator = roi.mean(axis=2) - np.clip(alpha_roi, 0.0, 0.99) * self.logo_value
-        frac = float((numerator[body] < 0).sum()) / float(body.sum())
-        if frac > self._OVERSUB_FOOTPRINT_FRAC:
-            return True
+        a_cap = float(alpha_roi.max())
+        if a_cap < 0.2:
+            return None
+        core = alpha_roi >= a_cap * self._CORE_ALPHA_FRAC
+        box = image[y1:y2, x1:x2]
+        if box.shape[:2] != core.shape or not bool(core.any()):
+            return None
+        px = box[core].astype(np.float32)  # (N, 3) BGR core pixels
+        hi = px.max(axis=1)
+        lo = px.min(axis=1)
+        return float(np.median((hi - lo) / (hi + 1.0)))
 
-        # Mid-tone darkening: predict the reverse-alpha output at the bright core and
-        # compare to the local background ring (reuses the FP-gate / alpha-gain machinery).
-        cb = self._core_and_bg(image, alpha_map, position)
-        if cb is None:
-            return False
-        core_obs, bg, a_cap = cb
-        a = min(a_cap, 0.99)
-        predicted_core = (core_obs - a * self.logo_value) / (1.0 - a)
-        return predicted_core < bg - self._OVERSUB_DARK_MARGIN
 
-    def _inpaint_footprint(
-        self,
-        image: NDArray[Any],
-        alpha_map: NDArray[Any],
-        position: tuple[int, int],
-    ) -> None:
-        """Inpaint the sparkle body from surrounding pixels, in-place.
+@functools.lru_cache(maxsize=1)
+def _shared_engine() -> GeminiEngine:
+    """Process-wide default ``GeminiEngine`` singleton.
 
-        Fallback for backgrounds where reverse-alpha over-subtracts: a small mask of
-        the footprint (alpha >= threshold, dilated) is reconstructed by cv2 NS inpaint
-        from the continuous surroundings, so the sparkle is replaced by plausible
-        background instead of a black pit.
-        """
-        placed = self._footprint_indices(alpha_map, position, image.shape)
-        if placed is None:
-            return
-        alpha_roi, (y1, y2, x1, x2) = placed
-        # Inpaint only a padded crop around the footprint, not the whole image: the
-        # mask is zero outside a ~96x96 corner, so inpainting the full (multi-MP)
-        # image would be ~hundreds of times more work for an identical result. The
-        # padding gives cv2 enough surrounding context to reconstruct the sparkle.
-        ih, iw = image.shape[:2]
-        pad = 24
-        cy1, cy2 = max(0, y1 - pad), min(ih, y2 + pad)
-        cx1, cx2 = max(0, x1 - pad), min(iw, x2 + pad)
-        crop = image[cy1:cy2, cx1:cx2]
-        mask = np.zeros(crop.shape[:2], dtype=np.uint8)
-        mask[y1 - cy1 : y2 - cy1, x1 - cx1 : x2 - cx1] = (alpha_roi >= self._FOOTPRINT_ALPHA).astype(np.uint8) * 255
-        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
-        mask = cv2.dilate(mask, kernel, iterations=2)
-        image[cy1:cy2, cx1:cx2] = cv2.inpaint(crop, mask, 6, cv2.INPAINT_NS)
-
-    def _verify_and_repair(
-        self,
-        result: NDArray[Any],
-        alpha_map: NDArray[Any],
-        position: tuple[int, int],
-        size: WatermarkSize,
-    ) -> NDArray[Any]:
-        """Inpaint-repair a sparkle that survived reverse-alpha, keeping the better.
-
-        Re-detect on the reverse-alpha output; if a sparkle this strong remains (an
-        alpha mismatch the gain estimate could not fully correct), inpaint the
-        footprint and return that ONLY when it lowers the re-detect confidence. The
-        footprint inpaint reconstructs from the (darker) surroundings, so it physically
-        removes the bright sparkle rather than gaming the shape-NCC. Returns ``result``
-        unchanged when the removal is already clean (the common case) or when the
-        inpaint does not improve it, so it can never regress.
-        """
-        residual = self.detect_watermark(result, force_size=size).confidence
-        if residual < self._VERIFY_FALLBACK_CONF:
-            return result
-        candidate = result.copy()
-        self._inpaint_footprint(candidate, alpha_map, position)
-        if self.detect_watermark(candidate, force_size=size).confidence < residual:
-            logger.debug("Sparkle survived reverse-alpha (conf=%.3f); footprint inpaint improved it.", residual)
-            return candidate
-        return result
-
-    def _reverse_alpha_blend(
-        self,
-        image: NDArray[Any],
-        alpha_map: NDArray[Any],
-        position: tuple[int, int],
-    ) -> None:
-        """Apply reverse alpha blending in-place.
-
-        Formula: original = (watermarked - a * logo) / (1 - a)
-        """
-        placed = self._footprint_indices(alpha_map, position, image.shape)
-        if placed is None:
-            return
-        alpha_roi, (y1, y2, x1, x2) = placed
-        image_roi = image[y1:y2, x1:x2].astype(np.float32)
-
-        alpha_threshold = 0.002
-        max_alpha = 0.99
-
-        # Vectorized reverse alpha blending
-        alpha = alpha_roi.copy()
-        mask = alpha >= alpha_threshold
-        alpha = np.clip(alpha, 0.0, max_alpha)
-        one_minus_alpha = 1.0 - alpha
-
-        # Expand alpha for 3-channel broadcast
-        alpha_3d = alpha[:, :, np.newaxis]
-        one_minus_3d = one_minus_alpha[:, :, np.newaxis]
-        mask_3d = mask[:, :, np.newaxis]
-
-        # original = (watermarked - alpha * logo) / (1 - alpha)
-        restored = (image_roi - alpha_3d * self.logo_value) / one_minus_3d
-        restored = np.clip(restored, 0.0, 255.0)
-
-        # Apply only where alpha is significant
-        image_roi = np.where(mask_3d, restored, image_roi)
-        image[y1:y2, x1:x2] = image_roi.astype(np.uint8)
-
-    # ── Inpainting cleanup ───────────────────────────────────────────
-
-    def inpaint_residual(
-        self,
-        image: NDArray[Any],
-        region: tuple[int, int, int, int],
-        strength: float = 0.85,
-        method: Literal["gaussian", "telea", "ns"] = "ns",
-        inpaint_radius: int = 10,
-        padding: int = 32,
-    ) -> NDArray[Any]:
-        """Apply inpaint cleanup on residual artifacts after reverse alpha blend.
-
-        Uses a sparse mask derived from alpha map gradient to repair only
-        the sparkle-edge pixels where interpolation broke the math.
-
-        Args:
-            image: BGR image (will NOT be modified in-place).
-            region: (x, y, w, h) of the watermark region.
-            strength: Blend strength (0.0 = keep original, 1.0 = fully inpainted).
-            method: Inpaint method ("gaussian", "telea", or "ns").
-            inpaint_radius: Radius for cv2.inpaint.
-            padding: Context padding around region in pixels.
-
-        Returns:
-            Cleaned BGR image.
-        """
-        result = image.copy()
-        x, y, rw, rh = region
-
-        if rw < 4 or rh < 4:
-            return result
-
-        strength = max(0.0, min(1.0, strength))
-        if strength < 0.001:
-            return result
-
-        # Padded region
-        px1 = max(0, x - padding)
-        py1 = max(0, y - padding)
-        px2 = min(image.shape[1], x + rw + padding)
-        py2 = min(image.shape[0], y + rh + padding)
-
-        if (px2 - px1) < 8 or (py2 - py1) < 8:
-            return result
-
-        # Inner rect relative to padded
-        ix1 = x - px1
-        iy1 = y - py1
-
-        # Get alpha map (interpolated if needed)
-        source_alpha = self._alpha_large
-        interp = cv2.INTER_LINEAR if rw > source_alpha.shape[1] else cv2.INTER_AREA
-        alpha_resized = cv2.resize(source_alpha, (rw, rh), interpolation=interp)
-
-        # Compute gradient mask from alpha
-        grad_x = cv2.Sobel(alpha_resized, cv2.CV_32F, 1, 0, ksize=3)
-        grad_y = cv2.Sobel(alpha_resized, cv2.CV_32F, 0, 1, ksize=3)
-        grad_mag = cv2.magnitude(grad_x, grad_y)
-
-        grad_min, grad_max = grad_mag.min(), grad_mag.max()
-        if grad_max <= grad_min:
-            return result
-
-        # Normalize and apply gamma correction
-        grad_norm = (grad_mag - grad_min) / (grad_max - grad_min)
-        grad_weight = np.sqrt(grad_norm)
-
-        # Dilate the mask
-        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
-        grad_weight = cv2.dilate(grad_weight, kernel)
-
-        if method == "gaussian":
-            # Soft blend with Gaussian blur
-            padded_roi = result[py1:py2, px1:px2].copy()
-            blurred = cv2.GaussianBlur(padded_roi, (0, 0), sigmaX=2.0)
-
-            # Create weight mask on padded area (only inner region has weights)
-            weight_full = np.zeros((py2 - py1, px2 - px1), dtype=np.float32)
-            weight_full[iy1 : iy1 + rh, ix1 : ix1 + rw] = grad_weight * strength
-
-            weight_3d = weight_full[:, :, np.newaxis]
-            blended = padded_roi.astype(np.float32) * (1 - weight_3d) + blurred.astype(np.float32) * weight_3d
-            result[py1:py2, px1:px2] = blended.astype(np.uint8)
-        else:
-            # OpenCV inpainting (TELEA or NS)
-            inpaint_flag = cv2.INPAINT_TELEA if method == "telea" else cv2.INPAINT_NS
-
-            # Create binary mask from gradient weight
-            binary_mask = (grad_weight * 255).astype(np.uint8)
-            _, binary_mask = cv2.threshold(binary_mask, 30, 255, cv2.THRESH_BINARY)
-
-            # Expand mask to padded region
-            mask_full = np.zeros((py2 - py1, px2 - px1), dtype=np.uint8)
-            mask_full[iy1 : iy1 + rh, ix1 : ix1 + rw] = binary_mask
-
-            padded_roi = result[py1:py2, px1:px2].copy()
-            inpainted = cv2.inpaint(padded_roi, mask_full, inpaint_radius, inpaint_flag)
-
-            # Blend with strength
-            weight_full = np.zeros((py2 - py1, px2 - px1), dtype=np.float32)
-            weight_full[iy1 : iy1 + rh, ix1 : ix1 + rw] = grad_weight * strength
-            weight_3d = weight_full[:, :, np.newaxis]
-
-            blended = padded_roi.astype(np.float32) * (1 - weight_3d) + inpainted.astype(np.float32) * weight_3d
-            result[py1:py2, px1:px2] = blended.astype(np.uint8)
-
-        return result
+    The engine holds only constant assets (embedded captures, alpha maps, the
+    precomputed template ladder) and takes the image as a method argument, so one
+    instance is reused across every ``detect_sparkle_confidence`` call instead of
+    reloading assets + recomputing alpha maps + rebuilding the template cache on
+    each of the ~34k images an ``identify`` batch scans. Output is identical."""
+    return GeminiEngine()
 
 
 def detect_sparkle_confidence(image_path: Path, *, image: NDArray[Any] | None = None) -> float | None:
@@ -1040,4 +734,4 @@ def detect_sparkle_confidence(image_path: Path, *, image: NDArray[Any] | None =
     img = image if image is not None else image_io.imread(image_path)
     if img is None:
         return None
-    return float(GeminiEngine().detect_watermark(img).confidence)
+    return float(_shared_engine().detect_watermark(img).confidence)

src/remove_ai_watermarks/humanizer.py

@@ -41,11 +41,14 @@ def apply_analog_humanizer(image: NDArray, grain_intensity: float = 4.0, chromat
     # Shift R channel left, B channel right. np.roll is circular, so it wraps
     # the opposite edge into a thin colored fringe at the L/R borders; replicate
     # the original edge columns there to keep the intended offset interior-only.
-    if chromatic_shift > 0:
-        r = np.roll(r, -chromatic_shift, axis=1)
-        r[:, -chromatic_shift:] = r[:, -chromatic_shift - 1 : -chromatic_shift]
-        b = np.roll(b, chromatic_shift, axis=1)
-        b[:, :chromatic_shift] = b[:, chromatic_shift : chromatic_shift + 1]
+    # Clamp so the edge-replication slices below always have a source column: a shift
+    # >= width would leave them empty and crash the broadcast (r[:, -shift:] = (H, 0)).
+    shift = min(chromatic_shift, image.shape[1] - 1)
+    if shift > 0:
+        r = np.roll(r, -shift, axis=1)
+        r[:, -shift:] = r[:, -shift - 1 : -shift]
+        b = np.roll(b, shift, axis=1)
+        b[:, :shift] = b[:, shift : shift + 1]
 
     merged = cv2.merge((b, g, r))
 

src/remove_ai_watermarks/identify.py

@@ -41,7 +41,12 @@ from remove_ai_watermarks.metadata import (
     xai_signature,
 )
 from remove_ai_watermarks.noai.c2pa import cbor_text_after, extract_c2pa_info, soft_binding_vendors_in
-from remove_ai_watermarks.noai.constants import C2PA_AI_TOOLS, C2PA_AI_VENDORS, C2PA_ISSUERS
+from remove_ai_watermarks.noai.constants import (
+    C2PA_AI_TOOLS,
+    C2PA_AI_VENDORS,
+    C2PA_IDENTITY_AI_ORGS,
+    C2PA_ISSUERS,
+)
 from remove_ai_watermarks.watermark_registry import GEMINI_SPARKLE_TRUST_CONF
 
 if TYPE_CHECKING:
@@ -52,7 +57,7 @@ if TYPE_CHECKING:
 
     from remove_ai_watermarks.watermark_registry import MarkDetection
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 # How much of a non-PNG container to binary-scan for the C2PA issuer.
 _SCAN_BYTES = 1024 * 1024
@@ -294,6 +299,19 @@ _AI_VENDOR_TOKENS: tuple[tuple[str, str], ...] = (
     ("grok", "xAI"),
     ("aurora", "xAI"),
     ("xai", "xAI"),
+    # ByteDance family (all its brands normalize to one origin, mirroring constants.py):
+    # without these a transplanted ByteDance C2PA manifest next to an independent
+    # conflicting stamp went undetected by the clash check.
+    ("bytedance", "ByteDance"),
+    ("doubao", "ByteDance"),
+    ("jimeng", "ByteDance"),
+    ("dreamina", "ByteDance"),
+    ("volcengine", "ByteDance"),
+    ("volcano engine", "ByteDance"),
+    ("canva", "Canva"),
+    ("elevenlabs", "ElevenLabs"),
+    ("eleven labs", "ElevenLabs"),
+    ("black forest", "Black Forest Labs"),
 )
 
 
@@ -323,6 +341,17 @@ def _vendor_of(text: str | None) -> str | None:
 _C2PA_MANIFEST_SOURCE = "c2pa_manifest"
 _CLASH_SOURCE: dict[str, str] = {"c2pa": _C2PA_MANIFEST_SOURCE, "synthid": _C2PA_MANIFEST_SOURCE}
 
+# The generic China TC260 AIGC vendor label -- a COUNTRY-LEVEL regulatory "this is AI"
+# stamp any Chinese generator applies to its own output, naming no specific vendor.
+_GENERIC_AIGC_VENDOR = "China AIGC (TC260)"
+# Vendors that apply the TC260 label to their OWN output. When one is co-attributed with
+# the generic AIGC label, the label is that vendor's own stamp (not an independent
+# competing origin), so the clash check attributes the AIGC label to it -- else a legit
+# ByteDance/Doubao image (C2PA "ByteDance" + its own TC260 label) would false-clash once
+# ByteDance normalizes via _vendor_of. Chinese generators only (Canva/BFL/ElevenLabs,
+# also added to _vendor_of, are NOT TC260 appliers).
+_TC260_VENDORS: frozenset[str] = frozenset({"ByteDance"})
+
 
 def _integrity_clashes(
     ai_vendors: dict[str, str], camera_label: str | None, *, camera_has_ai_marker: bool
@@ -347,6 +376,18 @@ def _integrity_clashes(
     # families clash only when they belong to different provenance sources (see
     # _CLASH_SOURCE) AND name different vendors -- so multiple vendors named within
     # one C2PA manifest (c2pa issuer + synthid proxy) do not flag.
+    # The generic TC260 AIGC label is a Chinese regulatory "this is AI" stamp. When a
+    # Chinese TC260-applying vendor (ByteDance) is ALSO attributed, the label is that
+    # vendor's own stamp on its own output, so attribute it to that vendor -- a legit
+    # Doubao image carries BOTH a ByteDance C2PA manifest and its own TC260 label and
+    # must not clash. Against a NON-TC260 vendor (OpenAI, Google, ...) the label stays
+    # generic and still clashes as a laundering tell (a foreign-vendor image carrying a
+    # Chinese TC260 label names two different origins).
+    if ai_vendors.get("aigc") == _GENERIC_AIGC_VENDOR:
+        own = next((v for f, v in ai_vendors.items() if f != "aigc" and v in _TC260_VENDORS), None)
+        if own:
+            ai_vendors = {**ai_vendors, "aigc": own}  # copy co-located with the relabel
+
     source = {fam: _CLASH_SOURCE.get(fam, fam) for fam in ai_vendors}
     independent_conflict = any(
         source[a] != source[b] and ai_vendors[a] != ai_vendors[b] for a, b in itertools.combinations(ai_vendors, 2)
@@ -393,7 +434,7 @@ def _visible_sparkle(image_path: Path, *, image: NDArray[Any] | None = None) ->
     try:
         from remove_ai_watermarks.gemini_engine import detect_sparkle_confidence
     except Exception as exc:  # cv2/engine assets missing
-        log.debug("visible-sparkle detector unavailable: %s", exc)
+        logger.debug("visible-sparkle detector unavailable: %s", exc)
         return None
     return detect_sparkle_confidence(image_path, image=image)
 
@@ -405,12 +446,17 @@ def _visible_sparkle(image_path: Path, *, image: NDArray[Any] | None = None) ->
 _VISIBLE_MARK_PLATFORM = {
     "doubao": "ByteDance Doubao (visible 豆包AI生成 mark detected)",
     "jimeng": "ByteDance Jimeng / Dreamina (visible 即梦AI mark detected)",
+    "qwen": "Alibaba Tongyi Qianwen (visible 千问AI生成 mark detected)",
+    "kling": "Kuaishou Kling (visible 可灵AI 3.0 mark detected)",
     "samsung": "Samsung Galaxy AI (visible 'Contenuti generati dall'AI' mark detected)",
+    "runninghub": "RunningHub (visible RunningHub AI生成 mark detected)",
+    "baidu": "Baidu (visible 百度 AI生成 mark detected)",
+    "liblib": "LibLibAI (visible LibLibAI mark detected)",
 }
 
 
 def _visible_text_marks(image_path: Path, *, image: NDArray[Any] | None = None) -> list[MarkDetection]:
-    """Detected visible Doubao/Jimeng marks (registry ``MarkDetection`` list).
+    """Detected visible text marks (registry ``MarkDetection`` list).
 
     The Gemini sparkle keeps its own ``_visible_sparkle`` path (file-level
     confidence); these two text marks reuse the registry detectors, which apply
@@ -424,7 +470,7 @@ def _visible_text_marks(image_path: Path, *, image: NDArray[Any] | None = None)
         from remove_ai_watermarks.image_io import imread
         from remove_ai_watermarks.watermark_registry import get_mark
     except Exception as exc:  # cv2/engine assets missing
-        log.debug("visible-mark detectors unavailable: %s", exc)
+        logger.debug("visible-mark detectors unavailable: %s", exc)
         return []
     if image is None:
         image = imread(image_path)
@@ -435,7 +481,7 @@ def _visible_text_marks(image_path: Path, *, image: NDArray[Any] | None = None)
         try:
             det = get_mark(key).detect(image)
         except Exception as exc:  # one engine failing must not break identify
-            log.debug("visible-mark %s detector failed: %s", key, exc)
+            logger.debug("visible-mark %s detector failed: %s", key, exc)
             continue
         if det.detected:
             detections.append(det)
@@ -464,6 +510,42 @@ def _trustmark(image_path: Path) -> str | None:
     return detect_trustmark(image_path)
 
 
+def _collect_visible_signals(
+    image_path: Path,
+    signals: list[Signal],
+    watermarks: list[str],
+    platform: str | None,
+) -> str | None:
+    """Decode once, append every trusted visible-mark signal, and return platform.
+
+    Keeping this stage separate from metadata aggregation makes the optional cv2
+    boundary explicit and guarantees that all visible detectors share one decoded
+    BGR array. A decode failure preserves the detectors' historical fallback/no-op
+    behavior.
+    """
+    image: NDArray[Any] | None = None
+    try:
+        from remove_ai_watermarks.image_io import imread
+
+        image = imread(image_path)
+    except Exception as exc:  # cv2 missing - detectors fall back / no-op
+        logger.debug("visible-mark decode unavailable: %s", exc)
+
+    sparkle_conf = _visible_sparkle(image_path, image=image)
+    if sparkle_conf is not None and sparkle_conf >= _SPARKLE_THRESHOLD:
+        signals.append(Signal("visible_sparkle", f"NCC confidence {sparkle_conf:.2f}", "medium"))
+        watermarks.append(f"Visible Gemini sparkle (confidence {sparkle_conf:.2f})")
+        if platform is None:
+            platform = "Google Gemini family (visible sparkle detected)"
+
+    for detection in _visible_text_marks(image_path, image=image):
+        signals.append(Signal(f"visible_{detection.key}", f"NCC confidence {detection.confidence:.2f}", "medium"))
+        watermarks.append(f"Visible {detection.label} (confidence {detection.confidence:.2f})")
+        if platform is None:
+            platform = _VISIBLE_MARK_PLATFORM[detection.key]
+    return platform
+
+
 def identify(image_path: Path, *, check_visible: bool = True, check_invisible: bool = True) -> ProvenanceReport:
     """Identify an image's origin platform and watermark inventory.
 
@@ -515,7 +597,14 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
             c2pa_source_kind = "generated"
         elif b"compositeWithTrainedAlgorithmicMedia" in head:
             c2pa_source_kind = "enhanced"
-    c2pa_is_ai = c2pa_source_kind is not None
+    # An identity-AI issuer (a pure-generator brand like Dreamina) asserts AI even
+    # without a digitalSourceType -- some ByteDance/Dreamina manifests ship no
+    # trainedAlgorithmicMedia, so the registered generator name is the only signal.
+    # Restricted to the ``asserts_ai`` vendors (distinctive brand strings), so it
+    # does not reopen the incidental-mention problem the common-word issuers have.
+    issuer_blob = " ".join(issuers)
+    c2pa_identity_ai = has_c2pa and any(org in issuer_blob for org in C2PA_IDENTITY_AI_ORGS)
+    c2pa_is_ai = c2pa_source_kind is not None or c2pa_identity_ai
     # Generator string (for the signal detail): structured for PNG, CBOR-scanned
     # for other containers. Best-effort -- some manifests key it as
     # `claim_generator_info` (Pixel), so this can be None even when a device is
@@ -613,7 +702,7 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         watermarks.append("China AIGC label (TC260 standard)")
         if platform is None:
             platform = "China AIGC-labeled generator (TC260; e.g. Doubao)"
-        ai_vendor_claims["aigc"] = "China AIGC (TC260)"
+        ai_vendor_claims["aigc"] = _GENERIC_AIGC_VENDOR
 
     # ── Local diffusion parameters (Stable Diffusion / ComfyUI) ──────
     local_keys = sorted(k for k in meta if k.lower() in _LOCAL_GEN_KEYS)
@@ -707,36 +796,8 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         or xai_sig
     )
 
-    # Decode the file ONCE for every visible-mark detector. The sparkle and the
-    # text-mark detectors both consume a BGR array; letting each re-read the file
-    # was two full cv2 decodes of the same bitmap, which spikes memory on a small
-    # worker. None (cv2 missing / unreadable container) makes each detector fall
-    # back to its own read, preserving the old behavior.
-    vis_image: NDArray[Any] | None = None
     if check_visible:
-        try:
-            from remove_ai_watermarks.image_io import imread
-
-            vis_image = imread(image_path)
-        except Exception as exc:  # cv2 missing - detectors fall back / no-op
-            log.debug("visible-mark decode unavailable: %s", exc)
-
-    # ── Visible Gemini sparkle (fallback for stripped-metadata case) ─
-    sparkle_conf = _visible_sparkle(image_path, image=vis_image) if check_visible else None
-    if sparkle_conf is not None and sparkle_conf >= _SPARKLE_THRESHOLD:
-        signals.append(Signal("visible_sparkle", f"NCC confidence {sparkle_conf:.2f}", "medium"))
-        watermarks.append(f"Visible Gemini sparkle (confidence {sparkle_conf:.2f})")
-        if platform is None:
-            platform = "Google Gemini family (visible sparkle detected)"
-
-    # ── Visible Doubao / Jimeng text marks (registry; same stripped-metadata
-    #    fallback role as the Gemini sparkle above) ─
-    if check_visible:
-        for det in _visible_text_marks(image_path, image=vis_image):
-            signals.append(Signal(f"visible_{det.key}", f"NCC confidence {det.confidence:.2f}", "medium"))
-            watermarks.append(f"Visible {det.label} (confidence {det.confidence:.2f})")
-            if platform is None:
-                platform = _VISIBLE_MARK_PLATFORM[det.key]
+        platform = _collect_visible_signals(image_path, signals, watermarks, platform)
 
     visible_only = any(s.name.startswith("visible_") for s in signals) and not ai_from_metadata
     hf_only = bool(hf_job) and not ai_from_metadata
@@ -798,6 +859,6 @@ def has_invisible_target(image_path: Path) -> bool:
     try:
         report = identify(image_path, check_visible=False, check_invisible=True)
     except Exception:  # unreadable / detector error -> do not skip the removal
-        log.debug("has_invisible_target: identify failed, defaulting to run", exc_info=True)
+        logger.debug("has_invisible_target: identify failed, defaulting to run", exc_info=True)
         return True
     return report.ai_from_metadata

src/remove_ai_watermarks/image_io.py

@@ -29,11 +29,17 @@ if TYPE_CHECKING:
 
 
 def imread(path: str | Path, flags: int | None = None) -> NDArray[Any] | None:
-    """Unicode-safe ``cv2.imread``.
+    """Unicode-safe ``cv2.imread`` with a Pillow fallback for HEIC/AVIF.
 
     ``flags`` defaults to ``cv2.IMREAD_COLOR`` (same as ``cv2.imread``). Returns
-    ``None`` when the file is missing or cannot be decoded, matching
-    ``cv2.imread`` semantics so existing ``if img is None`` checks keep working.
+    ``None`` when the file is missing or cannot be decoded, matching ``cv2.imread``
+    semantics so existing ``if img is None`` checks keep working.
+
+    OpenCV cannot decode HEIC/AVIF (and some other containers), so when its decode
+    returns None we fall back to Pillow (:func:`_pil_read`): AVIF is native in modern
+    Pillow, HEIC works when the optional ``pillow-heif`` plugin is installed. This lets
+    the pixel path (visible removal) read the same formats the metadata path already
+    scans; normal PNG/JPEG/WebP never reach the fallback, so they are unaffected.
     """
     import cv2
     import numpy as np
@@ -46,16 +52,50 @@ def imread(path: str | Path, flags: int | None = None) -> NDArray[Any] | None:
         return None
     if data.size == 0:
         return None
-    return cv2.imdecode(data, flags)
+    img = cv2.imdecode(data, flags)
+    # cv2.imdecode returns None on an undecodable container (HEIC/AVIF); the type stub
+    # omits that, hence the ignore.
+    if img is not None:  # pyright: ignore[reportUnnecessaryComparison]
+        return img
+    return _pil_read(path, flags)
+
+
+_heif_registered = False
+
+
+def _pil_read(path: str | Path, flags: int) -> NDArray[Any] | None:
+    """Decode via Pillow (HEIC/AVIF and any other Pillow-readable container) into the
+    cv2 layout ``flags`` implies: grayscale, 3-channel BGR, or BGRA when the source has
+    alpha and ``IMREAD_UNCHANGED`` was requested. Returns None if Pillow (with the
+    optional HEIF plugin) still cannot open it. No EXIF auto-rotation, matching cv2."""
+    import cv2
+    import numpy as np
+
+    try:
+        from PIL import Image
+    except Exception:
+        return None
+    _register_heif()
+    try:
+        with Image.open(path) as im:
+            im.load()
+            if flags == cv2.IMREAD_GRAYSCALE:
+                return np.asarray(im.convert("L"))
+            has_alpha = im.mode in ("RGBA", "LA", "PA") or "transparency" in im.info
+            if flags == cv2.IMREAD_UNCHANGED and has_alpha:
+                return cv2.cvtColor(np.asarray(im.convert("RGBA")), cv2.COLOR_RGBA2BGRA)
+            return cv2.cvtColor(np.asarray(im.convert("RGB")), cv2.COLOR_RGB2BGR)
+    except Exception:
+        return None
 
 
 def to_bgr(image: NDArray[Any]) -> NDArray[Any]:
     """Return a 3-channel BGR view of ``image``, promoting grayscale and BGRA.
 
-    The cv2-based engines (sparkle + the reverse-alpha text marks) assume a
-    3-channel BGR array for their channel reductions (``mean(axis=2)``, the
-    per-pixel logo subtraction). A 2D grayscale or 4-channel BGRA input -- a real
-    Gemini-app export is opaque RGBA -- would otherwise crash or mis-broadcast.
+    The cv2-based engines (sparkle + the text-mark detectors/localizers) assume a
+    3-channel BGR array for their channel reductions (``mean(axis=2)``, the top-hat
+    glyph extraction). A 2D grayscale or 4-channel BGRA input -- a real Gemini-app
+    export is opaque RGBA -- would otherwise crash or mis-broadcast.
     Centralizes the shape coercion that was inlined across the engines. A 3-channel
     input is returned unchanged (no copy).
     """
@@ -68,18 +108,87 @@ def to_bgr(image: NDArray[Any]) -> NDArray[Any]:
     return image
 
 
-def imwrite(path: str | Path, img: NDArray[Any]) -> bool:
-    """Unicode-safe ``cv2.imwrite``.
+def _register_heif() -> None:
+    """Register the HEIF+AVIF Pillow opener/saver via libheif (idempotent, best-effort)."""
+    global _heif_registered
+    if _heif_registered:
+        return
+    _heif_registered = True
+    import contextlib
 
-    The output format is taken from the path extension (e.g. ``.png``), exactly
-    like ``cv2.imwrite``. Returns ``True`` on success, ``False`` if the codec
-    rejects the image or the path cannot be written (matching ``cv2.imwrite``,
-    which returns ``False`` rather than raising on an unwritable path).
-    """
+    with contextlib.suppress(Exception):
+        import pillow_heif  # pyright: ignore[reportMissingImports]
+
+        pillow_heif.register_heif_opener()
+
+
+# Containers cv2 cannot encode -> written via Pillow (pillow-heif).
+_HEIF_WRITE_EXTS = {".heic", ".heif", ".avif"}
+
+
+def _encode_params(ext: str) -> list[int]:
+    """cv2 encode params that PRESERVE quality. The removal only touches the mark's
+    footprint, so the container re-encode must not degrade the untouched pixels:
+    JPEG at quality 100 with 4:4:4 chroma (no subsampling), WebP at max. Lossless
+    containers (PNG/BMP/TIFF) need no params. getattr-guarded so an older OpenCV
+    build without the chroma/subsampling flags still gets quality 100."""
     import cv2
 
-    ext = Path(path).suffix or ".png"
-    ok, buf = cv2.imencode(ext, img)
+    if ext in (".jpg", ".jpeg"):
+        params = [cv2.IMWRITE_JPEG_QUALITY, 100]
+        cq = getattr(cv2, "IMWRITE_JPEG_CHROMA_QUALITY", None)
+        if cq is not None:
+            params += [cq, 100]
+        sf = getattr(cv2, "IMWRITE_JPEG_SAMPLING_FACTOR", None)
+        sf444 = getattr(cv2, "IMWRITE_JPEG_SAMPLING_FACTOR_444", None)
+        if sf is not None and sf444 is not None:
+            params += [sf, sf444]
+        return params
+    if ext == ".webp":
+        # cv2 WebP: quality 1-100 is LOSSY; a value > 100 selects LOSSLESS mode.
+        # "work with originals" requires lossless so a mark-removal re-encode does not
+        # degrade the untouched pixels the fill composites over (regression: q100
+        # round-tripped a random image at maxdiff ~230, q101 at 0).
+        return [cv2.IMWRITE_WEBP_QUALITY, 101]
+    return []
+
+
+def _pil_write(path: str | Path, img: NDArray[Any]) -> bool:
+    """Encode HEIC/AVIF via Pillow (+pillow-heif) at high quality -- cv2 has no encoder
+    for them. BGR / BGRA in; returns False if Pillow (with the plugin) cannot save."""
+    import cv2
+    import numpy as np
+    from PIL import Image
+
+    _register_heif()
+    if img.ndim == 3 and img.shape[2] == 4:
+        arr, mode = cv2.cvtColor(img, cv2.COLOR_BGRA2RGBA), "RGBA"
+    else:
+        arr, mode = cv2.cvtColor(to_bgr(img), cv2.COLOR_BGR2RGB), "RGB"
+    try:
+        Image.fromarray(np.ascontiguousarray(arr), mode).save(str(path), quality=100)
+        return True
+    except Exception:
+        return False
+
+
+def imwrite(path: str | Path, img: NDArray[Any]) -> bool:
+    """Unicode-safe image write that PRESERVES the input format at max quality.
+
+    Format is taken from the path extension. HEIC/AVIF (which cv2 cannot encode) go
+    through Pillow; everything else through cv2 with quality-preserving params (see
+    :func:`_encode_params`) so a lossy re-encode of the untouched pixels stays near-
+    lossless. Returns ``True`` on success, ``False`` if the codec rejects the image or
+    the path cannot be written (matching ``cv2.imwrite``, never raising)."""
+    import cv2
+
+    ext = (Path(path).suffix or ".png").lower()
+    if ext in _HEIF_WRITE_EXTS:
+        return _pil_write(path, img)
+    try:
+        ok, buf = cv2.imencode(ext, img, _encode_params(ext))
+    except cv2.error:
+        return False
     if not ok:
         return False
     try:
@@ -87,3 +196,49 @@ def imwrite(path: str | Path, img: NDArray[Any]) -> bool:
     except OSError:
         return False
     return True
+
+
+# Container extensions that carry an alpha channel (for read/write-with-alpha).
+ALPHA_FORMATS = {".png", ".webp", ".heic", ".heif", ".avif"}
+
+
+def read_bgr_and_alpha(path: str | Path) -> tuple[NDArray[Any] | None, NDArray[Any] | None]:
+    """Read an image preserving its alpha channel separately.
+
+    Returns ``(bgr, alpha)`` where ``alpha`` is a single-channel ndarray when the
+    source has transparency, else ``None``. Grayscale inputs are promoted to BGR.
+    Returns ``(None, None)`` if the image cannot be decoded.
+    """
+    import cv2
+
+    image = imread(path, cv2.IMREAD_UNCHANGED)
+    if image is None:
+        return None, None
+    if image.ndim == 2:
+        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGR), None
+    if image.shape[2] == 4:
+        return image[:, :, :3].copy(), image[:, :, 3].copy()
+    return image, None
+
+
+def write_bgr_with_alpha(path: str | Path, bgr: NDArray[Any], alpha: NDArray[Any] | None) -> bool:
+    """Write BGR (with optional alpha) to ``path``. Returns ``imwrite``'s success flag.
+
+    When ``alpha`` is provided and the output extension supports it, the original
+    alpha plane is rejoined unchanged. The watermark region is NOT made transparent:
+    the fill reconstructs real pixels there, so zeroing alpha would punch a
+    transparent hole that renders as a white box on any non-transparent viewer
+    (issue #30). Preserving the input alpha keeps genuinely transparent backgrounds
+    intact without inventing new holes.
+
+    Returning the flag is load-bearing: :func:`imwrite` is contractually non-raising, so
+    this is the ONLY signal a caller gets that the file was not created. Discarding it let
+    a failed write (read-only directory, full disk) run on to ``output.stat()`` and die
+    with a bare ``FileNotFoundError`` traceback instead of a readable error.
+    Regression: ``tests/test_cli_robustness.py::TestFailedWriteIsReported``.
+    """
+    import numpy as np
+
+    if alpha is None or Path(path).suffix.lower() not in ALPHA_FORMATS:
+        return imwrite(path, bgr)
+    return imwrite(path, np.dstack([bgr, alpha]))

src/remove_ai_watermarks/invisible_engine.py

@@ -229,6 +229,12 @@ class InvisibleEngine:
         # SDXL img2img runs near its ~1024 training size instead of distorting on a
         # tiny latent (a 381x512 portrait wrecks at native -- issue #36 follow-up).
         # The output is restored to orig_size below, so the floor is transparent.
+        # Register the HEIF/AVIF opener so a .heic/.avif input (now a SUPPORTED_FORMAT)
+        # decodes here too. The --force skip path bypasses image_io.imread, which is
+        # what would otherwise register it, so a bare Image.open would fail on HEIC.
+        from remove_ai_watermarks import image_io
+
+        image_io._register_heif()
         image = Image.open(image_path)
         image = ImageOps.exif_transpose(image)
         orig_size = image.size  # (width, height)
@@ -256,10 +262,14 @@ class InvisibleEngine:
 
         # Always persist to a temp file, even without downscaling: WatermarkRemover
         # reloads by path, so the EXIF-transposed pixels must be saved or rotation
-        # is lost. Cleaned up in the finally block via _tmp_path.
-        _tmp_fd, _tmp_str = tempfile.mkstemp(suffix=image_path.suffix)
+        # is lost. Written as PNG (lossless) regardless of the input format, so a JPEG
+        # input does not feed a re-compressed copy into the diffusion pass.
+        # Cleaned up in the finally block via _tmp_path.
+        _tmp_fd, _tmp_str = tempfile.mkstemp(suffix=".png")
         _tmp_path = Path(_tmp_str)
-        image.save(_tmp_path)
+        # Convert to RGB before the PNG temp: the diffusion pass is RGB anyway, and a
+        # non-RGB source mode (e.g. a CMYK JPEG) cannot be written as PNG and would raise.
+        image.convert("RGB").save(_tmp_path)
         os.close(_tmp_fd)
         image_path = _tmp_path
 

src/remove_ai_watermarks/invisible_watermark.py

@@ -31,7 +31,7 @@ from typing import TYPE_CHECKING, cast
 if TYPE_CHECKING:
     from pathlib import Path
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 # Known 48-bit ``bits`` watermarks (dwtDct, no key), name -> message integer.
 _BITS_48: dict[str, int] = {
@@ -96,7 +96,7 @@ def detect_invisible_watermark(image_path: Path) -> str | None:
             if _bits_match(value, ref) >= _MATCH_48:
                 return name
     except Exception as exc:  # decode can fail on tiny images
-        log.debug("48-bit watermark decode failed for %s: %s", image_path, exc)
+        logger.debug("48-bit watermark decode failed for %s: %s", image_path, exc)
 
     # 136-bit default string watermark (SD 1.x / 2.x).
     try:
@@ -104,6 +104,6 @@ def detect_invisible_watermark(image_path: Path) -> str | None:
         if _bytes_match_frac(raw, _SD1_STRING) >= _MATCH_SD1_FRAC:
             return "Stable Diffusion 1.x / 2.x"
     except Exception as exc:
-        log.debug("string watermark decode failed for %s: %s", image_path, exc)
+        logger.debug("string watermark decode failed for %s: %s", image_path, exc)
 
     return None

src/remove_ai_watermarks/jimeng_engine.py

@@ -1,17 +1,18 @@
-"""Jimeng / Dreamina visible watermark removal engine.
+"""Jimeng / Dreamina visible watermark detector/localizer.
 
 Jimeng (即梦AI, ByteDance) stamps generated images with a visible "★ 即梦AI" wordmark
 in the bottom-right corner -- a near-white semi-transparent overlay, the same overlay
 class as the Doubao text strip.
 
-Removal is **reverse-alpha blending** against a captured alpha map
-(``original = (wm - a*logo)/(1-a)``), always NCC-aligned to the actual mark plus a thin
-residual inpaint over the glyph footprint. This is one of the three text-mark engines
-that share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
+Detection matches the bundled glyph silhouette against the corner; removal is the
+shared **localize -> fill** (the glyph-bbox :meth:`footprint_mask` feeds
+``region_eraser``), NOT reverse-alpha. This is one of the three text-mark engines that
+share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
 supplies only Jimeng's tuned :class:`TextMarkConfig` (bottom-right corner,
-``assets/jimeng_alpha.png`` rebuilt by ``scripts/visible_alpha_solve.py`` from the gray
-capture). Jimeng images are also caught by the China TC260 AIGC metadata label, so this
-is the visible-mark *removal* path, not a new ``identify`` signal.
+``assets/jimeng_alpha.png`` -- the detection silhouette, rebuilt by
+``scripts/visible_alpha_solve.py`` from the gray capture). Jimeng images are also caught
+by the China TC260 AIGC metadata label, so this is the visible-mark *removal* path, not
+a new ``identify`` signal.
 """
 # The module-level _alpha_template / _glyph_silhouette / _template_match_score below
 # are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
@@ -41,21 +42,27 @@ TOPHAT_DELTA = 12
 
 # Shape-consistent detection. Threshold 0.45 cleanly separates real Jimeng marks
 # (>=0.81) from the Doubao strip (0.21), so the two ByteDance marks do not cross-fire.
+#
+# That separation holds at the STRICT threshold ONLY. Relaxed under provenance it
+# collapses: at the old shared 0.7 factor (gate 0.315) the arm ran at 17% precision
+# and 33 of its 68 false additions were Doubao marks (corpus-measured 2026-07-18 --
+# full table at _DEFAULT_PROVENANCE_NCC_FACTOR). That was patched with a tighter 0.85
+# factor at the time; the competitive rival margin replaced it -- see below.
 DETECT_MIN_COVERAGE = 0.02
 DETECT_NCC_THRESHOLD = 0.45
 
-# Reverse-alpha geometry, emitted by scripts/visible_alpha_solve.py from the gray
-# capture at the captured width.
+# Back to the 0.70 default. The 0.85 patch (2026-07-18) existed only to blunt the
+# Doubao cross-fire by sacrificing recall; the competitive RIVAL MARGIN below
+# discriminates directly and passes real wordmarks at 100%, so the recall the patch
+# gave up is no longer the price of precision. See _rival_margin_ok.
+PROVENANCE_NCC_FACTOR = 0.7
+
+# Detection-silhouette geometry, emitted by scripts/visible_alpha_solve.py from the
+# gray capture at the captured width (sizes the silhouette for the detection match;
+# removal is the template-free glyph-bbox footprint mask).
 _ALPHA_NATIVE_WIDTH = 2048
-_ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
-_ALPHA_WIDTH_FRAC = 0.2021  # asset width / image width -- the alignment scale seed
+_ALPHA_WIDTH_FRAC = 0.2021  # asset width / image width -- sizes the detection silhouette
 _ALPHA_HEIGHT_FRAC = 0.0576
-_ALPHA_MARGIN_RIGHT_FRAC = 0.0288
-_ALPHA_MARGIN_BOTTOM_FRAC = 0.0288
-_ALPHA_ALIGN_SEARCH = (0.90, 1.12, 23)
-_RESIDUAL_ALPHA_FLOOR = 0.05
-_RESIDUAL_DILATE = 5
-_RESIDUAL_INPAINT_RADIUS = 2
 
 _CONFIG = TextMarkConfig(
     name="Jimeng",
@@ -72,16 +79,11 @@ _CONFIG = TextMarkConfig(
     morph_open_size=5,
     detect_min_coverage=DETECT_MIN_COVERAGE,
     detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    provenance_ncc_factor=PROVENANCE_NCC_FACTOR,
+    rivals=("doubao_alpha.png",),
     alpha_width_frac=_ALPHA_WIDTH_FRAC,
     alpha_height_frac=_ALPHA_HEIGHT_FRAC,
-    alpha_margin_x_frac=_ALPHA_MARGIN_RIGHT_FRAC,
-    alpha_margin_bottom_frac=_ALPHA_MARGIN_BOTTOM_FRAC,
-    alpha_align_search=_ALPHA_ALIGN_SEARCH,
     min_gw=8,
-    alpha_logo_bgr=_ALPHA_LOGO_BGR,
-    residual_alpha_floor=_RESIDUAL_ALPHA_FLOOR,
-    residual_dilate=_RESIDUAL_DILATE,
-    residual_inpaint_radius=_RESIDUAL_INPAINT_RADIUS,
 )
 
 JimengDetection = TextMarkDetection
@@ -97,13 +99,13 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
     """TM_CCOEFF_NORMED of the Jimeng glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, image_width, _CONFIG)
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
 
 
 class JimengEngine(TextMarkEngine):
-    """Remove the visible Jimeng "★ 即梦AI" watermark (locate -> mask -> reverse-alpha)."""
+    """Detect/localize the visible Jimeng "★ 即梦AI" watermark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)

src/remove_ai_watermarks/kling_engine.py

@@ -0,0 +1,149 @@
+"""Kling (可灵, Kuaishou) visible watermark detector/localizer.
+
+Kling stamps its generations with a thin, light-gray "可灵AI 3.0" text strip in the
+bottom-right corner, preceded by the vendor's spiral logo (not part of the detection
+silhouette -- logos vary between releases, the text run is what discriminates).
+Known variants: an "Omni" suffix release, a latin "KlingAI 3.0" release, and a
+version-less "可灵AI" -- the silhouette targets the common "可灵AI 3.0" core, so the
+suffix variants are only caught when the core run is bold enough (measured below).
+
+Detection matches the bundled glyph silhouette against the corner; removal is the
+shared **localize -> fill** (the glyph-bbox :meth:`footprint_mask` feeds
+``region_eraser``), NOT reverse-alpha. This module supplies only Kling's tuned
+:class:`TextMarkConfig` (``assets/kling_alpha.png`` -- a font-rendered synthetic
+silhouette from ``scripts/render_vendor_silhouettes.py``, never cut from an
+upload). It also feeds ``identify`` as the medium-confidence ``visible_kling``
+signal via the registry.
+
+EVERY tuned number below was measured on the vendor cohort (30 TC260 carriers whose
+producer USCC 91110108335469089C names the entity, 2026-07-21; harness
+``scripts/vendor_mark_calibrate.py``), NOT inherited from Doubao:
+
+  * The mark scales with the SHORT side at ~0.12 of it (mark_w/short measured
+    0.118-0.122 across portrait AND landscape carriers -- unimodal, so the shipped
+    3-rung ladder covers it) and sits ~0.03 off the right/bottom edges; the locate
+    box fractions below are fitted from the measured absolute mark rects.
+  * ``alpha_height_frac`` comes from the silhouette aspect (0.239) at the fitted
+    width, matching the aspect the fit converged on (0.25).
+  * Gate 0.35, one step above the clean arm's max: on the cohort-vs-clean run
+    (cohort-contamination-guarded, 286 hand-labelled clean frames) the clean arm
+    scored p99 0.304 / max 0.320, and every cohort frame >= 0.35 carries a visible
+    可灵AI 3.0 mark (9 of ~19 eyeballed visible marks fire = ~47% recall of visible
+    marks; the misses are the faint "Omni"-suffix release, the latin "KlingAI"
+    release and the version-less "可灵AI", which score 0.17-0.25 and cannot be
+    reached without engulfing the clean arm).
+  * STRICT ONLY (``provenance_ncc_factor`` 1.0): the sub-gate band holds real Kling
+    variants AND the clean arm's top (clean p90 0.220 vs variant marks at 0.17-0.25
+    -- they overlap), so a provenance-relaxed arm cannot separate them. No
+    provenance relaxation exists for this mark.
+  * No rival margin: at the shipped gate the template fires on 1 of 400
+    Doubao-marked frames (0.2%, a 豆包 frame sitting INSIDE the Kling cohort, still
+    below the gate), 0 of 298 Jimeng-marked frames and 0 of 286 hand-labelled clean
+    frames, and a 0.10 rival margin costs zero genuine Kling detections -- so it is
+    simply unnecessary (same conclusion shape as Qwen).
+"""
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+# Locate geometry as a fraction of the image SHORT side (measured basis -- see
+# scale_base). The box is fitted to the measured mark rects: the mark's right
+# margin is ~0.034 of the short side and its bottom margin ~0.027; width/height
+# cover the mark plus NCC slack.
+WM_WIDTH_FRAC = 0.19
+WM_HEIGHT_FRAC = 0.05
+MARGIN_RIGHT_FRAC = 0.03
+MARGIN_BOTTOM_FRAC = 0.023
+
+# Glyph appearance: a light, low-saturation gray rendered brighter than the local
+# background (white top-hat), same overlay class as Doubao -- inherited, and
+# harmless because the tophat front-end turns these gates into weights.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+TOPHAT_DELTA = 12
+
+DETECT_MIN_COVERAGE = 0.04  # unused by the tophat front-end (kept for config parity)
+# Calibrated 2026-07-21 on the vendor cohort vs 286 hand-labelled clean frames
+# (cohort-contamination-guarded): clean p99 0.304 / max 0.320, and every cohort
+# frame scoring >= 0.35 carries a visible 可灵AI 3.0 mark. 0.35 was picked over
+# 0.33 (also zero clean fires) for margin against unseen clean content at a cost
+# of zero measured cohort detections.
+DETECT_NCC_THRESHOLD = 0.35
+
+# Detection-silhouette geometry (fraction of the short side), fitted on the
+# cohort: the mark's width (0.12, unimodal) and the silhouette aspect (0.239).
+_ALPHA_WIDTH_FRAC = 0.12
+_ALPHA_HEIGHT_FRAC = 0.0287
+
+_CONFIG = TextMarkConfig(
+    name="Kling",
+    asset_name="kling_alpha.png",
+    corner="br",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_RIGHT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    detect_frontend="tophat",
+    scale_basis="short",  # measured: mark_w/short 0.118-0.122 across orientations
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    min_gw=8,
+    # STRICT ONLY: the sub-gate band (real Kling variants at 0.17-0.25) overlaps
+    # the clean arm's top (p90 0.220), so provenance relaxation is disabled
+    # outright (factor 1.0 = never relaxed).
+    provenance_ncc_factor=1.0,
+)
+
+KlingDetection = TextMarkDetection
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled Kling alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "可灵AI 3.0" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
+
+
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
+    """TM_CCOEFF_NORMED of the Kling glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
+
+
+class KlingEngine(TextMarkEngine):
+    """Detect/localize the visible Kling "可灵AI 3.0" watermark (locate -> mask; mask feeds the fill)."""
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/liblib_engine.py

@@ -0,0 +1,189 @@
+"""LibLibAI visible watermark detector/localizer.
+
+LibLibAI (哩布哩布AI, USCC 91110105MACJ6K1C8A) stamps its generations with a
+white triangle logo + "LibLibAI" latin wordmark at **bottom-center** (not a
+corner -- the locate box is horizontally centered). Detection matches the
+bundled font-rendered "LibLibAI" silhouette (the triangle logo is NOT rendered
+-- logos vary, the wordmark discriminates); removal is the shared **localize ->
+fill** (the glyph blob covers logo + wordmark, both bright).
+
+This module supplies only LibLibAI's tuned :class:`TextMarkConfig`
+(``assets/liblib_alpha.png`` from ``scripts/render_vendor_silhouettes.py``,
+never cut from an upload).
+
+Measured on the vendor cohort (15 TC260 carriers, harvested 2026-07-22 by
+``scripts/vendor_cohort_harvest.py``), NOT inherited from Doubao:
+
+  * The wordmark is ~0.10 of the frame WIDTH wide, centered horizontally, its
+    baseline ~0.94-0.95 of the height; consistent across 768..2240-px frames.
+  * The silhouette font is Arial, NOT the STHeiti the CJK marks use: the real
+    wordmark is a grotesque, and measured across 7 candidate fonts Arial lifts
+    the cohort positives from 0.31-0.47 to 0.42-0.73 while the full-corpus
+    false arm (latin UI text) drops to max 0.398. A 200x200 icon false-fired
+    at 0.444, so a per-mark size floor (``_MIN_SHORT_SIDE``) backs the gate.
+  * Gate 0.42 (tophat front-end): false arm max 0.398, cohort 0.43-0.59.
+  * STRICT ONLY (``provenance_ncc_factor`` 1.0): small cohort, the relaxed band
+    is unmeasured.
+"""
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+# Locate geometry as a fraction of the image WIDTH (measured basis). The box is
+# horizontally centered (corner="bc") and covers the logo + wordmark with NCC
+# slack around the measured 0.10 width.
+WM_WIDTH_FRAC = 0.20
+WM_HEIGHT_FRAC = 0.09
+MARGIN_BOTTOM_FRAC = 0.02
+
+# Glyph appearance: white wordmark on a usually-darker background (white
+# top-hat), same overlay class as Doubao -- inherited, harmless because the
+# tophat front-end turns these gates into weights.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+TOPHAT_DELTA = 12
+
+DETECT_MIN_COVERAGE = 0.04  # unused by the tophat front-end (kept for config parity)
+# Calibrated 2026-07-22 on the vendor cohort vs 286 hand-labelled clean frames
+# (clean p99 0.315 / max 0.367) and re-measured after the font fix: the wordmark
+# is set in an Arial-class grotesque, and the Arial silhouette lifts the cohort
+# positives to 0.43-0.59 while the full-corpus false arm (latin UI text bands,
+# website screenshots) drops to max 0.398 -- generic latin text matches the
+# wrong font less, which is exactly where the discrimination comes from. Gate
+# 0.42 keeps all 8 marked cohort frames with a 0.022 margin over the false arm.
+DETECT_NCC_THRESHOLD = 0.42
+
+# Detection-silhouette geometry (fraction of the frame width): the wordmark,
+# measured 0.10 wide with aspect 0.26.
+_ALPHA_WIDTH_FRAC = 0.10
+_ALPHA_HEIGHT_FRAC = 0.026
+
+# Tight ladder: the NCC comb is sharp in size (see runninghub_engine).
+_LADDER = (0.9, 1.0, 1.1)
+
+_CONFIG = TextMarkConfig(
+    name="LibLibAI",
+    asset_name="liblib_alpha.png",
+    corner="bc",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=0.0,  # unused for corner="bc" (horizontally centered)
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    detect_frontend="tophat",
+    scale_basis="width",
+    ladder=_LADDER,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    min_gw=8,
+    # STRICT ONLY: small cohort, the relaxed band is unmeasured.
+    provenance_ncc_factor=1.0,
+)
+
+LibLibDetection = TextMarkDetection
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled LibLibAI alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "LibLibAI" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
+
+
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
+    """TM_CCOEFF_NORMED of the LibLibAI glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
+
+
+class LibLibEngine(TextMarkEngine):
+    """Detect/localize the visible LibLibAI wordmark (bottom-center; localize -> fill)."""
+
+    # Per-mark size floor: the wordmark template is 0.10 of the frame width, so
+    # below ~480px short side it degrades under ~48px -- the one full-corpus
+    # false fire with the final Arial template was a 200x200 icon (0.444, above
+    # the gate, on a 20px template; measured 2026-07-22). The smallest true
+    # carrier in the cohort is 768px.
+    _MIN_SHORT_SIDE = 480
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)
+
+    def detect(self, image: NDArray[Any] | None, *, provenance: bool = False) -> TextMarkDetection:
+        if image is None or not image.size or min(image.shape[:2]) < self._MIN_SHORT_SIDE:
+            return TextMarkDetection()
+        return super().detect(image, provenance=provenance)
+
+    def footprint_mask(
+        self, image: NDArray[Any] | None, *, force: bool = False, dilate: int | None = None
+    ) -> NDArray[Any] | None:
+        """Full-frame mask of the logo + wordmark, bounded by the detector's match box.
+
+        The base class's blob-bbox footprint is wrong in both directions here: the
+        blob bleeds UP into bright background structure (on the 768x1024 cohort
+        frame it reached y 931 and the fill ate the shirt's own print) and it does
+        not own the triangle logo anyway. The match box bounds the wordmark exactly
+        (that is what the NCC localized); the logo sits its own height to the LEFT
+        of the text (measured on the cohort zoom: logo ~1.0x the glyph height, gap
+        ~0.3x), so the footprint is the match box extended left by ~1.3 heights.
+        """
+        if image is None or image.size == 0:
+            return None
+        from remove_ai_watermarks import image_io, region_eraser
+
+        image = image_io.to_bgr(image)
+        h, w = image.shape[:2]
+        if h < 32 or w < 64:
+            return None
+        loc = self.locate(image)
+        bx, by, bw, bh = loc.bbox
+        if force:
+            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
+        else:
+            if not self.detect(image).detected:
+                return None
+            _, box = self._tophat_best(image, loc)
+            if box is None:
+                return None
+            gx0, gy0, gx1, gy1 = box
+            gh = gy1 - gy0 + 1
+            pad = max(3, int(0.25 * gh))
+            rx1 = max(0, bx + gx0 - int(1.3 * gh))  # the triangle logo, left of the text
+            ry1 = max(0, by + gy0 - pad)
+            rx2 = min(w, bx + gx1 + 1 + pad)
+            ry2 = min(h, by + gy1 + 1 + pad)
+        if rx1 >= rx2 or ry1 >= ry2:
+            return None
+        d = dilate if dilate is not None else max(3, int(0.02 * bw))
+        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/metadata.py

@@ -93,9 +93,17 @@ def c2pa_marker_in(data: bytes) -> bool:
 IPTC_AI_MARKERS: tuple[bytes, ...] = (
     b"trainedAlgorithmicMedia",
     b"compositeSynthetic",
-    b"algorithmicMedia",
     b"compositeWithTrainedAlgorithmicMedia",
 )
+# NOTE: bare ``algorithmicMedia`` is deliberately NOT here. That IPTC digitalSourceType
+# means "created purely by an algorithm, NOT from sampled training data" (procedural /
+# generative-code art) -- it is NOT AI/ML generation. Real "Made with AI" labels
+# (Meta / Instagram / MidJourney) use ``trainedAlgorithmicMedia``. Including the bare
+# token flagged clean procedural images as AI (is_ai=high + has_invisible_target=True ->
+# a diffusion scrub of clean content), contradicting the c2pa layer, which sets
+# source_type without ai_source for it (tests/test_noai.py::test_plain_algorithmic_media_not_flagged_ai).
+# It is not a substring of the trained/composite tokens, so its removal does not affect
+# their detection.
 
 # IPTC Photo Metadata 2025.1 (published 2025-11-27) added explicit AI-disclosure
 # XMP properties in the Iptc4xmpExt namespace. Their mere presence is an AI
@@ -137,6 +145,7 @@ AIGC_MARKERS: tuple[bytes, ...] = (
 # label even when the namespaced XMP element is absent.
 _TC260_FIELDS: frozenset[str] = frozenset(
     {
+        # Producer-side schema (Doubao and most China-served generators).
         "Label",
         "ContentProducer",
         "ProduceID",
@@ -144,6 +153,12 @@ _TC260_FIELDS: frozenset[str] = frozenset(
         "PropagateID",
         "ReservedCode1",
         "ReservedCode2",
+        # Service-provider schema (Tencent Cloud's AIGC variant, mined from the
+        # retained corpus 2026-07): the same ``{"AIGC":{...}}`` wrapper but keyed
+        # ``ServiceProvider`` / ``ServiceUser`` (+ generic ``Time`` / ``ContentId``,
+        # not gated on), embedded in EXIF ``ImageDescription``.
+        "ServiceProvider",
+        "ServiceUser",
     }
 )
 
@@ -332,7 +347,7 @@ def has_ai_metadata(image_path: Path) -> bool:
         return True
     # China TC260 AIGC label as a PNG text chunk (the byte scan above catches
     # only the XMP form; the raw-JSON tEXt chunk needs the PIL-based parse).
-    if aigc_label(image_path):
+    if aigc_label(image_path) is not None:
         return True
     # HuggingFace-hosted job marker (hf-job-id PNG text chunk).
     if huggingface_job(image_path):
@@ -514,18 +529,45 @@ _SAMSUNG_GENAI_RE = re.compile(rb'genAIType"\s*:\s*(-?\d+)')
 _SAMSUNG_EDITOR_MARKER = b"PhotoEditor_Re_Edit_Data"
 
 
+def _read_file_tail(image_path: Path, size: int) -> bytes:
+    """Return the last ``size`` bytes of the file (or the whole file if smaller)."""
+    try:
+        file_size = image_path.stat().st_size
+        with open(image_path, "rb") as f:
+            if file_size > size:
+                f.seek(file_size - size)
+            return f.read()
+    except OSError:
+        return b""
+
+
 def samsung_genai(image_path: Path) -> int | None:
     """Return Samsung's non-zero ``genAIType`` value if the image carries the
     Galaxy AI editing marker, else None.
 
     See the module note above ``_SAMSUNG_GENAI_RE``: detection is empirical and
     gated on the ``PhotoEditor_Re_Edit_Data`` container so an incidental
-    ``genAIType`` token cannot false-positive.
+    ``genAIType`` token cannot false-positive. Galaxy AI appends the marker as a
+    trailer AFTER the JPEG EOI, so on a multi-MB phone photo it sits past the quick-
+    scan window; when the head misses it, also read the file tail (else detection
+    and removal disagree -- the strip reads the whole file and would drop a marker
+    detection never reported).
     """
-    head = scan_head(image_path, _QUICK_SCAN_BYTES)
-    if _SAMSUNG_EDITOR_MARKER not in head:
+    data = scan_head(image_path, _QUICK_SCAN_BYTES)
+    if _SAMSUNG_EDITOR_MARKER not in data:
+        # The marker is a post-EOI trailer, so only a file LARGER than the quick-scan
+        # window can hide it past the head (`scan_head` already read a smaller file
+        # whole). Gate the extra tail read on that — `samsung_genai` is on the identify
+        # hot path, so a redundant 512 KB re-read per small image is not free.
+        try:
+            oversize = image_path.stat().st_size > _QUICK_SCAN_BYTES
+        except OSError:
+            oversize = False
+        if oversize:
+            data = _read_file_tail(image_path, _QUICK_SCAN_BYTES)
+    if _SAMSUNG_EDITOR_MARKER not in data:
         return None
-    m = _SAMSUNG_GENAI_RE.search(head)
+    m = _SAMSUNG_GENAI_RE.search(data)
     if m is None:
         return None
     return int(m.group(1)) or None
@@ -702,47 +744,90 @@ def xai_signature(image_path: Path) -> bool:
     )
 
 
-def _scrub_ai_exif(exif_dict: dict[str, Any]) -> list[str]:
-    """Delete AI-provenance tags from a piexif dict's ``0th`` IFD, in place.
+def _is_aigc_exif_value(raw: object) -> bool:
+    """Whether an EXIF tag value carries a China TC260 AIGC producer/service block.
 
-    Removes (a) the xAI/Grok signature pair (``ImageDescription`` "Signature: ..."
-    + UUID ``Artist``) and (b) any ``Software`` / ``Make`` / ``Artist`` /
-    ``ImageDescription`` tag whose value carries an ``AI_GENERATOR_TOKENS`` token
-    (Ideogram's ``Make``, Firefly's ``Software``, etc.). Mirrors the detection in
-    ``xai_signature`` / ``exif_generator`` so removal scrubs exactly what
-    ``identify`` flags, while leaving genuine camera/editor EXIF intact. Returns
-    the names of the removed tags (for logging).
+    Mirrors ``aigc_label``'s EXIF path: the ``{"AIGC":{...}}`` wrapper embedded in
+    ``UserComment`` / ``ImageDescription`` by China-served generators (Doubao's
+    producer schema AND Tencent Cloud's service-provider schema, both keyed under
+    ``_TC260_FIELDS``). Gated on both the ``AIGC`` marker and a TC260 field so a
+    coincidental token cannot false-drop a genuine caption/comment. Accepts a ``str``
+    too (a PNG ``tEXt``/``iTXt`` value), not only EXIF bytes.
+    """
+    if isinstance(raw, str):
+        raw = raw.encode("latin-1", "ignore")
+    if not isinstance(raw, (bytes, bytearray)):
+        return False
+    if b"AIGC" not in raw:
+        return False
+    text = bytes(raw).decode("latin-1", "ignore")
+    return any(field in text for field in _TC260_FIELDS)
+
+
+def _ai_exif_targets(loaded: dict[str, Any]) -> list[tuple[str, int, bytes, str]]:
+    """The SINGLE AI-EXIF rule set, as ``(ifd_key, tag, value_bytes, name)`` entries.
+
+    Shared by both EXIF scrubbers so their coverage cannot drift: the JPEG-path
+    :func:`_scrub_ai_exif` pops each tag, and the ISOBMFF-path
+    ``isobmff.blank_ai_exif_tokens`` blanks each value's bytes in place. Covers
+    (a) the xAI/Grok ``Signature:`` + UUID-``Artist`` pair, (b) any ``Software`` /
+    ``Make`` / ``Artist`` / ``ImageDescription`` tag carrying an ``AI_GENERATOR_TOKENS``
+    token, and (c) the China TC260 ``{"AIGC":{...}}`` block in ``ImageDescription``
+    (0th) or ``UserComment`` (Exif). De-duplicated by ``(ifd_key, tag)`` so a value
+    flagged by two rules is removed and named once. Mirrors the detection in
+    ``xai_signature`` / ``exif_generator`` / ``aigc_label``; adding a new AI EXIF
+    placement here reaches BOTH containers.
     """
     import piexif
 
     from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
 
-    ifd = exif_dict.get("0th")
-    if not ifd:
-        return []
+    ifd0: dict[int, Any] = loaded.get("0th") or {}
+    ifde: dict[int, Any] = loaded.get("Exif") or {}
+    seen: set[tuple[str, int]] = set()
+    targets: list[tuple[str, int, bytes, str]] = []
 
-    drop: dict[int, str] = {}
+    def add(ifd_key: str, ifd: dict[int, Any], tag: int, name: str) -> None:
+        value = ifd.get(tag)
+        if isinstance(value, bytes) and (ifd_key, tag) not in seen:
+            seen.add((ifd_key, tag))
+            targets.append((ifd_key, tag, value, name))
 
     # (a) xAI / Grok: the Signature blob and the UUID Artist go together.
     if _is_xai_signature_pair(
-        _exif_text(ifd, piexif.ImageIFD.ImageDescription), _exif_text(ifd, piexif.ImageIFD.Artist)
+        _exif_text(ifd0, piexif.ImageIFD.ImageDescription), _exif_text(ifd0, piexif.ImageIFD.Artist)
     ):
-        drop[piexif.ImageIFD.ImageDescription] = "ImageDescription"
-        drop[piexif.ImageIFD.Artist] = "Artist"
-
-    # (b) Known AI generator token in any of the text tags.
+        add("0th", ifd0, piexif.ImageIFD.ImageDescription, "ImageDescription")
+        add("0th", ifd0, piexif.ImageIFD.Artist, "Artist")
+    # (b) known AI generator token in a 0th text tag.
     for tag, name in (
         (piexif.ImageIFD.Software, "Software"),
         (piexif.ImageIFD.Make, "Make"),
         (piexif.ImageIFD.Artist, "Artist"),
         (piexif.ImageIFD.ImageDescription, "ImageDescription"),
     ):
-        if any(token in _exif_text(ifd, tag).lower() for token in AI_GENERATOR_TOKENS):
-            drop[tag] = name
+        if any(token in _exif_text(ifd0, tag).lower() for token in AI_GENERATOR_TOKENS):
+            add("0th", ifd0, tag, name)
+    # (c) TC260 AIGC block in ImageDescription (0th) or UserComment (Exif sub-IFD).
+    if _is_aigc_exif_value(ifd0.get(piexif.ImageIFD.ImageDescription)):
+        add("0th", ifd0, piexif.ImageIFD.ImageDescription, "ImageDescription")
+    if _is_aigc_exif_value(ifde.get(piexif.ExifIFD.UserComment)):
+        add("Exif", ifde, piexif.ExifIFD.UserComment, "UserComment")
 
-    for tag in drop:
-        ifd.pop(tag, None)
-    return list(drop.values())
+    return targets
+
+
+def _scrub_ai_exif(exif_dict: dict[str, Any]) -> list[str]:
+    """Delete the AI-provenance EXIF tags (`_ai_exif_targets`) from a piexif dict's
+    ``0th`` / ``Exif`` IFDs in place; return the removed tag names (for logging).
+    Genuine camera/editor EXIF is left intact."""
+    removed: list[str] = []
+    for ifd_key, tag, _value, name in _ai_exif_targets(exif_dict):
+        ifd = exif_dict.get(ifd_key)
+        if ifd is not None:
+            ifd.pop(tag, None)
+            removed.append(name)
+    return removed
 
 
 def get_ai_metadata(image_path: Path) -> dict[str, str]:
@@ -802,7 +887,7 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
             result["soft_binding"] = ", ".join(vendors)
 
     # China TC260 AI-content label (Doubao and other China-served generators).
-    if aigc := aigc_label(image_path):
+    if (aigc := aigc_label(image_path)) is not None:
         producer = aigc.get("ContentProducer", "")
         result["aigc_label"] = f"China AIGC label (TC260){f'; producer {producer}' if producer else ''}"
 
@@ -864,6 +949,154 @@ def _strip_with_ffmpeg(source_path: Path, output_path: Path) -> Path:
     return output_path
 
 
+def _jpeg_app_carries_ai(marker: int, payload: bytes) -> bool:
+    """Whether a JPEG APPn segment carries AI provenance to drop wholesale (C2PA in
+    APP11, an AI XMP packet in APP1, an IPTC "Made with AI" record in APP13). EXIF
+    (APP1 ``Exif``) is NOT dropped here -- it is scrubbed tag-by-tag via piexif so
+    genuine camera EXIF survives."""
+    if not (0xE0 <= marker <= 0xEF):  # only APPn segments carry these
+        return False
+    # C2PA / JUMBF manifest (APP11).
+    if marker == 0xEB and (c2pa_marker_in(payload) or b"jumb" in payload[:256].lower()):
+        return True
+    # AI XMP packet (APP1): C2PA, a China-AIGC token, or an IPTC digitalSourceType /
+    # 2025.1 AI-disclosure marker (which live in XMP, not only the APP13 IIM record).
+    if (
+        marker == 0xE1
+        and payload.startswith(b"http://ns.adobe.com/xap/")
+        and (
+            c2pa_marker_in(payload)
+            or any(m in payload for m in AIGC_MARKERS)
+            or any(m in payload for m in IPTC_AI_MARKERS)
+            or any(m in payload for m in IPTC_AI_FIELD_MARKERS)
+        )
+    ):
+        return True
+    # IPTC "Made with AI" record (APP13).
+    if marker == 0xED and (
+        any(m in payload for m in IPTC_AI_MARKERS) or any(m in payload for m in IPTC_AI_FIELD_MARKERS)
+    ):
+        return True
+    # A bare / wrapped China TC260 AIGC block (``AIGC{...}`` or ``{"AIGC":{...}}``) glued
+    # into ANY APP segment -- some China gens use APP11, APP1, or a near-JFIF APPn. This
+    # runs for every APP marker the specific checks above did NOT already claim, so a bare
+    # AIGC in APP11 (not a C2PA manifest) is no longer missed by the 0xEB C2PA-only check.
+    # ``aigc_label`` detects it anywhere, so removal must drop the carrying segment too
+    # (detection<->removal parity). Skip APP1-EXIF (0xE1 ``Exif``): its camera tags are
+    # scrubbed tag-by-tag via piexif, not dropped wholesale.
+    if not (marker == 0xE1 and payload.startswith(b"Exif")):
+        return _is_aigc_exif_value(payload)
+    return False
+
+
+def _strip_samsung_trailer(scan_and_tail: bytes) -> bytes:
+    """Drop a Samsung Galaxy AI editing trailer appended AFTER the JPEG EOI.
+
+    Galaxy AI records its ``PhotoEditor_Re_Edit_Data`` (``genAIType``) blob as a
+    proprietary trailer past the final ``FFD9`` end-of-image, so the verbatim
+    scan copy in :func:`_strip_jpeg_metadata_lossless` would carry it through. If
+    the marker is present in the post-EOI trailer, truncate at EOI (the coded scan
+    is untouched, pixels stay bit-identical). A JPEG with no such trailer -- or a
+    non-Samsung trailer (e.g. an MPF multi-picture block) -- is returned unchanged.
+    """
+    if _SAMSUNG_EDITOR_MARKER not in scan_and_tail:
+        return scan_and_tail
+    eoi = scan_and_tail.rfind(b"\xff\xd9")
+    if eoi == -1 or _SAMSUNG_EDITOR_MARKER not in scan_and_tail[eoi:]:
+        return scan_and_tail  # marker not in the post-EOI trailer; leave the scan alone
+    return scan_and_tail[: eoi + 2]
+
+
+def _strip_jpeg_metadata_lossless(source_path: Path, output_path: Path) -> bool:
+    """Remove AI metadata from a JPEG WITHOUT re-encoding the DCT scan, so the pixels
+    stay bit-identical (the point of "work with originals" -- a metadata strip must not
+    degrade the image). Walks the marker segments up to SOS, drops the AI-bearing APP
+    segments (:func:`_jpeg_app_carries_ai`), copies the entropy-coded scan verbatim
+    (minus a Samsung Galaxy AI trailer past EOI, via :func:`_strip_samsung_trailer`),
+    then scrubs AI EXIF tags in place via piexif (which rewrites only the APP1 EXIF,
+    leaving genuine camera EXIF and the scan untouched). Returns False if the bytes are
+    not a parseable JPEG, so the caller falls back to the near-lossless PIL re-save."""
+    import piexif
+
+    data = source_path.read_bytes()
+    if not data.startswith(b"\xff\xd8"):
+        return False
+    out = bytearray(b"\xff\xd8")
+    i, n = 2, len(data)
+    while i + 1 < n:
+        if data[i] != 0xFF:
+            return False  # malformed marker boundary: defer to the PIL re-encode fallback
+        marker = data[i + 1]
+        if marker in (0xDA, 0xD9):  # SOS / EOI -> the coded scan follows; copy verbatim
+            out += _strip_samsung_trailer(data[i:])
+            break
+        if 0xD0 <= marker <= 0xD7 or marker == 0x01:  # standalone markers carry no length
+            out += data[i : i + 2]
+            i += 2
+            continue
+        if i + 4 > n:
+            return False  # truncated segment header: defer to the PIL re-encode fallback
+        seg_len = int.from_bytes(data[i + 2 : i + 4], "big")
+        seg_end = i + 2 + seg_len
+        if seg_len < 2 or seg_end > n:
+            return False  # malformed segment length: defer to the PIL re-encode fallback
+        if not _jpeg_app_carries_ai(marker, data[i + 4 : seg_end]):
+            out += data[i:seg_end]
+        i = seg_end
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_bytes(bytes(out))
+    try:
+        exif = piexif.load(str(output_path))
+        if _scrub_ai_exif(exif):
+            piexif.insert(piexif.dump(exif), str(output_path))
+    except Exception:
+        logger.debug("piexif EXIF scrub skipped on %s", output_path, exc_info=True)
+    return True
+
+
+# Fallback extension -> PIL save format, used only when the content sniff is
+# inconclusive (never for JPEG re-encode of lossless content).
+_EXT_TO_PIL_FORMAT = {".jpg": "JPEG", ".jpeg": "JPEG", ".webp": "WEBP", ".png": "PNG"}
+
+
+def _sniff_image_format(head: bytes) -> str | None:
+    """Actual raster format from a file's leading magic bytes (>= 12 bytes), as a PIL
+    format name ("JPEG"/"PNG"/"WEBP"), or None when unrecognized. The file EXTENSION is
+    unreliable: ~2% of real uploads carry a mismatched one (a PNG served as ``.jpg`` is
+    common). Choosing the save format by extension re-encodes a lossless PNG/WebP into a
+    real JPEG, silently degrading the pixels -- so the strip routes on content instead.
+    ISOBMFF/GIF are handled before this point or fall through to PNG; only the
+    lossy-vs-lossless distinction that matters here is resolved."""
+    if head[:2] == b"\xff\xd8":
+        return "JPEG"
+    if head[:8] == b"\x89PNG\r\n\x1a\n":
+        return "PNG"
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "WEBP"
+    return None
+
+
+def strip_and_verify(
+    source_path: Path,
+    output_path: Path | None = None,
+    *,
+    keep_standard: bool = True,
+) -> tuple[Path, dict[str, str]]:
+    """Strip AI metadata, then RE-SCAN the output and report what survived.
+
+    :func:`remove_ai_metadata` is deliberately fail-safe: a file PIL cannot decode is
+    copied through UNCHANGED rather than crashing a caller, and the path it returns is
+    indistinguishable from a real strip. Any caller that reports an outcome to a user
+    therefore cannot tell a no-op from a success -- corpus-observed on real Samsung
+    Galaxy S22 C2PA PNGs, where `metadata --remove` printed "stripped" and exited 0 while
+    the output still read as AI (2026-07-19 parity audit).
+
+    Returns ``(output_path, surviving_markers)``; an empty mapping means a real strip.
+    """
+    out = remove_ai_metadata(source_path, output_path, keep_standard=keep_standard)
+    return out, get_ai_metadata(out)
+
+
 def remove_ai_metadata(
     source_path: Path,
     output_path: Path | None = None,
@@ -931,14 +1164,55 @@ def remove_ai_metadata(
     if source_path.suffix.lower() in _FFMPEG_STRIP_EXTS:
         return _strip_with_ffmpeg(source_path, output_path)
 
+    # Route on the ACTUAL content format, not the extension (which lies on ~2% of real
+    # uploads -- a PNG served as .jpg, etc.). Trusting the extension would push a
+    # lossless PNG/WebP through the lossy JPEG re-encode below just because its name
+    # ends .jpg, breaking the "work with originals" invariant.
+    true_fmt = _sniff_image_format(head)  # reuse the 12 bytes already read above
+
+    # JPEG: strip AI metadata at the byte level so the DCT scan (the pixels) is NOT
+    # re-encoded. The PIL open+save path below is lossy for JPEG (a q95 re-encode that
+    # would undo the quality-preserving writes of the removal pipelines); this keeps a
+    # JPEG bit-identical outside its APP metadata segments. Falls through on a
+    # non-parseable JPEG. Only when keep_standard: the lossless walk drops AI segments
+    # but preserves standard ones, so a keep_standard=False caller (strip EVERYTHING)
+    # must use the full re-encode path below instead.
+    if keep_standard and true_fmt == "JPEG" and _strip_jpeg_metadata_lossless(source_path, output_path):
+        return output_path
+
+    # Fail-safe for a truncated / corrupt image: PIL raises OSError when it decodes a
+    # partial file (`img.copy()` / `img.save()` below), which would crash a direct
+    # library caller (a web worker 500s on a partial upload). Probe decodability first;
+    # if it fails, copy the input through unchanged and return -- we cannot strip what we
+    # cannot parse, but we never raise (mirrors strip_c2pa_boxes' fail-safe).
+    try:
+        with Image.open(source_path) as _probe:
+            _probe.load()
+    except Exception:
+        logger.warning("Could not decode %s to strip metadata (truncated/corrupt); copied through", source_path)
+        if output_path != source_path:
+            import shutil
+
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(source_path, output_path)
+        return output_path
+
     # Read image and filter metadata
     with Image.open(source_path) as img:
         img = img.copy()
-        fmt = output_path.suffix.lower()
+        # Pick the save format. Honor the caller's output extension (so a deliberate
+        # source.png -> output.jpg conversion still works) UNLESS the SOURCE is misnamed
+        # -- a lossless PNG/WebP whose extension lies (served as .jpg). There the output
+        # extension only inherited the source's wrong name, so re-encoding to JPEG would
+        # silently degrade an original; preserve the true content format instead.
+        source_ext_fmt = _EXT_TO_PIL_FORMAT.get(source_path.suffix.lower())
+        if true_fmt is not None and true_fmt != source_ext_fmt:
+            fmt = true_fmt  # misnamed source: never let a lying extension force a re-encode
+        else:
+            fmt = _EXT_TO_PIL_FORMAT.get(output_path.suffix.lower()) or true_fmt or "PNG"
 
-        save_kwargs: dict[str, Any] = {}
-        if fmt in (".jpg", ".jpeg"):
-            save_kwargs["format"] = "JPEG"
+        save_kwargs: dict[str, Any] = {"format": fmt}
+        if fmt == "JPEG":
             # JPEG output is unavoidably lossy, so minimize the loss: high quality
             # and no chroma subsampling (4:4:4). Without these PIL defaults to
             # quality 75 + 4:2:0, which visibly degrades a re-saved image.
@@ -946,15 +1220,12 @@ def remove_ai_metadata(
             save_kwargs["subsampling"] = 0
             if img.mode in ("RGBA", "P"):
                 img = img.convert("RGB")
-        elif fmt == ".webp":
+        elif fmt == "WEBP":
             # Preserve the WebP container losslessly instead of silently rewriting
             # it as PNG (which changes the format and bloats the file).
-            save_kwargs["format"] = "WEBP"
             save_kwargs["lossless"] = True
             if img.mode == "P":  # WebP cannot encode palette mode
                 img = img.convert("RGBA" if "transparency" in img.info else "RGB")
-        else:
-            save_kwargs["format"] = "PNG"
 
         # Collect non-AI metadata
         kept_meta: dict[str, str] = {}
@@ -965,10 +1236,12 @@ def remove_ai_metadata(
                 continue
             if _is_ai_key(key):
                 continue
-            # Drop a generic text chunk whose VALUE names an AI generator (NovelAI
-            # writes its stamp into Title/Source under non-AI keys) -- keeps removal
-            # in parity with exif_generator's value-based detection.
-            if isinstance(value, str) and _is_ai_value(value):
+            # Drop a text chunk whose VALUE names an AI generator (NovelAI writes its
+            # stamp into Title/Source under non-AI keys) OR carries a China TC260 AIGC
+            # block (some China gens put `{"AIGC":{...}}` in a STANDARD chunk like
+            # Description, which _is_ai_key would keep) -- keeps removal in parity with
+            # exif_generator / aigc_label's value-based detection.
+            if isinstance(value, str) and (_is_ai_value(value) or _is_aigc_exif_value(value)):
                 continue
             if key == "exif":
                 with contextlib.suppress(Exception):

src/remove_ai_watermarks/noai/__init__.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from remove_ai_watermarks.noai.cleaner import remove_ai_metadata
+    from remove_ai_watermarks.metadata import remove_ai_metadata
     from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover, remove_watermark
 
 __all__ = ["WatermarkRemover", "remove_ai_metadata", "remove_watermark"]
@@ -26,7 +26,9 @@ __all__ = ["WatermarkRemover", "remove_ai_metadata", "remove_watermark"]
 def __getattr__(name: str) -> object:
     """Resolve the public API on first access (PEP 562), not at package import."""
     if name == "remove_ai_metadata":
-        from remove_ai_watermarks.noai.cleaner import remove_ai_metadata
+        # Re-export the single, robust stripper (byte-level, lossless-for-JPEG, all
+        # containers); the old noai.cleaner implementation is retired.
+        from remove_ai_watermarks.metadata import remove_ai_metadata
 
         return remove_ai_metadata
     if name in ("WatermarkRemover", "remove_watermark"):

src/remove_ai_watermarks/noai/c2pa.py

@@ -41,7 +41,7 @@ from remove_ai_watermarks.noai.constants import (
     SYNTHID_C2PA_ISSUERS,
 )
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 # Official C2PA reader (c2pa-python, a core dependency). It is the primary,
 # spec-tracking manifest parser; the hand-rolled caBX/CBOR scanner below stays as
@@ -96,7 +96,7 @@ def _read_manifest_store_impl(path_str: str) -> str | None:
     try:
         reader = _C2paReader.try_create(path_str)
     except Exception as exc:  # malformed manifest, unsupported container, etc.
-        log.debug("c2pa Reader could not parse %s: %s", path_str, exc)
+        logger.debug("c2pa Reader could not parse %s: %s", path_str, exc)
         return None
     if reader is None:
         return None
@@ -104,7 +104,7 @@ def _read_manifest_store_impl(path_str: str) -> str | None:
         with reader:
             return reader.json()
     except Exception as exc:  # pragma: no cover - reader opened but json() failed
-        log.debug("c2pa Reader.json() failed on %s: %s", path_str, exc)
+        logger.debug("c2pa Reader.json() failed on %s: %s", path_str, exc)
         return None
 
 
@@ -374,12 +374,15 @@ def _populate_registry_fields(buf: bytes, c2pa_info: dict[str, Any]) -> bool:
         c2pa_info["source_type"] = "trainedAlgorithmicMedia (AI-generated)"
         c2pa_info["ai_source_kind"] = "generated"
         ai_source = True
-    elif b"algorithmicMedia" in buf:
-        c2pa_info["source_type"] = "algorithmicMedia"
     elif b"compositeWithTrainedAlgorithmicMedia" in buf:
+        # Checked BEFORE bare ``algorithmicMedia``: a manifest can carry both tokens
+        # (an AI-enhanced composite with a procedural ingredient), and the bare-token
+        # branch would otherwise fire first and misclassify the AI composite as non-AI.
         c2pa_info["source_type"] = "compositeWithTrainedAlgorithmicMedia (AI-enhanced)"
         c2pa_info["ai_source_kind"] = "enhanced"
         ai_source = True
+    elif b"algorithmicMedia" in buf:
+        c2pa_info["source_type"] = "algorithmicMedia"
 
     # SynthID pixel-watermark proxy: a C2PA manifest from a SynthID-using
     # vendor (Google/OpenAI) on AI-generated content implies an invisible

src/remove_ai_watermarks/noai/cleaner.py

@@ -1,180 +0,0 @@
-"""AI metadata cleaning and removal.
-
-Provides functions to identify and strip AI-generation metadata from
-PNG and JPEG images while optionally preserving standard fields like
-Author, Title, and Copyright.
-
-The removal pipeline:
-1. Opens the image and iterates over all metadata keys.
-2. Classifies each key as AI-related (using ``constants.AI_METADATA_KEYS``
-   and ``constants.AI_KEYWORDS``) or standard.
-3. Rebuilds the image with only the desired metadata retained.
-"""
-
-from __future__ import annotations
-
-import contextlib
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-import piexif
-from PIL import Image
-from PIL.PngImagePlugin import PngInfo
-
-from remove_ai_watermarks.noai.constants import AI_KEYWORDS, AI_METADATA_KEYS, PNG_METADATA_KEYS
-from remove_ai_watermarks.noai.utils import get_image_format
-
-# Pre-compute a lowercase set for O(1) key lookups.
-_AI_KEYS_LOWER: frozenset[str] = frozenset(k.lower() for k in AI_METADATA_KEYS)
-
-
-def remove_ai_metadata(
-    source_path: Path,
-    output_path: Path | None = None,
-    keep_standard: bool = True,
-) -> Path:
-    """
-    Remove all AI-generated metadata from an image.
-
-    Removes:
-    - AI parameters (Stable Diffusion, ComfyUI, etc.)
-    - C2PA metadata (Google Imagen, OpenAI, etc.)
-    - Any metadata with AI-related keywords
-
-    Args:
-        source_path: Path to the source image file.
-        output_path: Optional output path. If not provided, modifies source in place.
-        keep_standard: If True, keeps standard metadata (Author, Title, etc.).
-
-    Returns:
-        Path to the output file with AI metadata removed.
-    """
-    if output_path is None:
-        output_path = source_path
-
-    cleaned_metadata = _extract_non_ai_metadata(source_path, keep_standard)
-
-    with Image.open(source_path) as img:
-        img = img.copy()
-
-        output_format = get_image_format(output_path)
-        save_kwargs: dict[str, Any] = {"format": output_format}
-
-        # Handle EXIF data (keep it, just don't include AI-related fields)
-        if "exif" in cleaned_metadata:
-            save_kwargs["exif"] = cleaned_metadata["exif"]
-
-        if output_format == "PNG":
-            save_kwargs = _prepare_clean_png_kwargs(save_kwargs, cleaned_metadata)
-        elif output_format == "JPEG":
-            save_kwargs = _prepare_clean_jpeg_kwargs(save_kwargs, cleaned_metadata)
-
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-
-        if output_format == "JPEG" and img.mode in ("RGBA", "P"):
-            img = img.convert("RGB")
-
-        img.save(output_path, **save_kwargs)
-
-    return output_path
-
-
-def _extract_non_ai_metadata(source_path: Path, keep_standard: bool) -> dict[str, Any]:
-    """Extract metadata excluding AI-related fields."""
-    cleaned_metadata: dict[str, Any] = {}
-
-    with Image.open(source_path) as img:
-        # Handle EXIF data
-        if "exif" in img.info:
-            with contextlib.suppress(Exception):
-                exif_dict = piexif.load(img.info["exif"])
-                cleaned_metadata["exif"] = exif_dict
-
-        # Extract non-AI metadata
-        for key, value in img.info.items():
-            if not isinstance(key, str):
-                continue
-            if _is_ai_metadata_key(key):
-                continue
-
-            is_standard = keep_standard and key in PNG_METADATA_KEYS
-            is_nonstandard = not keep_standard and key not in ["exif", "dpi", "gamma"] and key not in PNG_METADATA_KEYS
-            if is_standard or is_nonstandard:
-                cleaned_metadata[key] = value
-
-        # Keep DPI and gamma
-        if "dpi" in img.info:
-            cleaned_metadata["dpi"] = img.info["dpi"]
-        if "gamma" in img.info:
-            cleaned_metadata["gamma"] = img.info["gamma"]
-
-    return cleaned_metadata
-
-
-def _is_ai_metadata_key(key: str) -> bool:
-    """Return True if *key* is an AI-generation metadata field.
-
-    Detection uses two layers:
-    1. Exact match against the canonical ``AI_METADATA_KEYS`` list.
-    2. Substring match against ``AI_KEYWORDS`` (covers partial hits
-       like ``"stable_diffusion_model"``).
-    """
-    key_lower = key.lower()
-    if key_lower in _AI_KEYS_LOWER:
-        return True
-    return any(kw in key_lower for kw in AI_KEYWORDS)
-
-
-def _prepare_clean_png_kwargs(save_kwargs: dict[str, Any], metadata: dict[str, Any]) -> dict[str, Any]:
-    """Prepare save kwargs for clean PNG."""
-    pnginfo: dict[str, Any] = {}
-    exclude_keys = ["exif", "exif_raw", "dpi", "gamma"]
-
-    for key, value in metadata.items():
-        if key not in exclude_keys:
-            pnginfo[key] = value
-
-    if pnginfo:
-        pnginfo_obj = PngInfo()
-        for key, value in pnginfo.items():
-            if isinstance(value, str):
-                pnginfo_obj.add_text(key, value)
-            elif isinstance(value, bytes):
-                pnginfo_obj.add_text(key, value.decode("utf-8", errors="replace"))
-        save_kwargs["pnginfo"] = pnginfo_obj
-
-    if "dpi" in metadata:
-        save_kwargs["dpi"] = metadata["dpi"]
-
-    return save_kwargs
-
-
-def _prepare_clean_jpeg_kwargs(save_kwargs: dict[str, Any], metadata: dict[str, Any]) -> dict[str, Any]:
-    """Prepare save kwargs for clean JPEG."""
-    exif_dict = metadata.get("exif", {"0th": {}, "Exif": {}, "1st": {}, "GPS": {}, "Interop": {}})
-
-    with contextlib.suppress(Exception):
-        exif_bytes = piexif.dump(exif_dict)
-        save_kwargs["exif"] = exif_bytes
-
-    if "dpi" in metadata:
-        save_kwargs["dpi"] = metadata["dpi"]
-
-    return save_kwargs
-
-
-def has_ai_content(image_path: Path) -> bool:
-    """
-    Check if an image has any AI-generated content or metadata.
-
-    Args:
-        image_path: Path to the image file.
-
-    Returns:
-        True if the image contains AI metadata.
-    """
-    from remove_ai_watermarks.noai.extractor import has_ai_metadata
-
-    return has_ai_metadata(image_path)

src/remove_ai_watermarks/noai/constants.py

@@ -6,8 +6,12 @@ so adding a new AI tool or metadata key requires updating only this file.
 
 from typing import NamedTuple
 
-# Supported image formats
-SUPPORTED_FORMATS = {".png", ".jpg", ".jpeg", ".webp"}
+# Supported image formats for the pixel/removal path (CLI input validation + batch
+# discovery). PNG/JPEG/WebP decode+encode via cv2; HEIC/HEIF/AVIF via the core
+# pillow-heif dep (image_io.imread Pillow fallback + imwrite _pil_write), so batch
+# now picks them up and the CLI no longer warns on an iPhone HEIC. JPEG-XL is left
+# out on purpose -- it is metadata/strip-only (no pixel decoder without pillow-jxl).
+SUPPORTED_FORMATS = {".png", ".jpg", ".jpeg", ".webp", ".heic", ".heif", ".avif"}
 
 # AI-generated image metadata keys (Stable Diffusion, ComfyUI, Midjourney, etc.)
 AI_METADATA_KEYS = [
@@ -96,6 +100,13 @@ class C2paAiVendor(NamedTuple):
     # (usually a shorter form of org, e.g. "Google" for "Google LLC"); None when platform is.
     needle: str | None
     synthid: bool = False  # vendor pairs an invisible SynthID pixel watermark with its C2PA manifest
+    # The vendor's mere presence in the manifest asserts AI generation even without
+    # a digitalSourceType (``trainedAlgorithmicMedia``) assertion. Set ONLY for a
+    # pure-generator brand whose issuer/generator byte string is unambiguous (e.g.
+    # "Dreamina"). Do NOT set for common-word issuers (Adobe/Google/OpenAI/Microsoft):
+    # those appear incidentally in unrelated XMP/trust-chain bytes, so they stay
+    # source-type-gated in identify._attribute_platform.
+    asserts_ai: bool = False
 
 
 # C2PA known vendors, ORDERED for first-match-wins platform attribution: when a
@@ -145,6 +156,24 @@ C2PA_AI_VENDORS: tuple[C2paAiVendor, ...] = (
     # earlier row's label wins anyway -- they normalize together for clash
     # detection. Verified on real signed files in production traffic, 2026-06-19.
     C2paAiVendor(b"Byteplus", "BytePlus (ByteDance)", "ByteDance (Doubao / Jimeng / Volcano Engine)", "ByteDance"),
+    # Dreamina (ByteDance's international Jimeng brand) signs C2PA as "Bytedance
+    # Pte. Ltd." with a "Dreamina/x.y" claim generator and, unlike the Volcano
+    # Engine output, NO digitalSourceType assertion -- so the generator name is the
+    # only AI signal. It is registered by that generator token (which the caBX /
+    # store-JSON byte scan sees across active + ingredient manifests, where the
+    # active manifest is often a plain c2pa-tool transcode). ``asserts_ai`` lets the
+    # issuer alone flag AI without trainedAlgorithmicMedia; "Dreamina" is a
+    # distinctive brand string, so it does not risk the incidental-mention problem
+    # the common-word issuers have. Verified on real signed files in the retained
+    # corpus, 2026-07. Normalizes to the same "ByteDance" needle/platform as the
+    # volcengine row (they collapse together for clash detection).
+    C2paAiVendor(
+        b"Dreamina",
+        "ByteDance (Dreamina)",
+        "ByteDance (Doubao / Jimeng / Volcano Engine)",
+        "ByteDance",
+        asserts_ai=True,
+    ),
     # Canva Magic Media signs AI-generated images as "Canva" with a generic
     # c2pa-rs claim generator + trainedAlgorithmicMedia; without this entry the
     # source read AI but no platform was attributed. Verified on real signed files
@@ -177,6 +206,12 @@ C2PA_AI_VENDORS: tuple[C2paAiVendor, ...] = (
 # C2PA issuer signature -> resolved org name, for the manifest byte-scan.
 C2PA_ISSUERS: dict[bytes, str] = {v.issuer: v.org for v in C2PA_AI_VENDORS}
 
+# Resolved org names of the vendors whose presence asserts AI generation on its
+# own (no digitalSourceType needed) -- see the ``asserts_ai`` field. identify uses
+# this to lift the AI verdict for an identity-AI issuer (e.g. Dreamina) that ships
+# no trainedAlgorithmicMedia. Derived from the flag -- set it on the vendor, not here.
+C2PA_IDENTITY_AI_ORGS: frozenset[str] = frozenset(v.org for v in C2PA_AI_VENDORS if v.asserts_ai)
+
 # C2PA issuers whose signed outputs also carry an invisible SynthID pixel
 # watermark -- a metadata proxy for "SynthID is in the pixels":
 #   - Google (Imagen/Gemini): embeds SynthID, long-standing (DeepMind docs).

src/remove_ai_watermarks/noai/isobmff.py

@@ -33,7 +33,7 @@ from remove_ai_watermarks.metadata import (
     IPTC_AI_MARKERS,
 )
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 # Top-level box types that may carry AI provenance. ``uuid`` boxes are checked
 # against ``C2PA_UUID`` / AI-label markers before being stripped; ``jumb`` boxes
@@ -188,7 +188,7 @@ def strip_c2pa_boxes(data: bytes) -> tuple[bytes, int]:
     # would silently truncate the file from the bad box to EOF -- worse than not
     # stripping. If the walk did not consume the whole input, return it unchanged.
     if consumed != len(data):
-        log.warning(
+        logger.warning(
             "ISOBMFF box walk stopped at offset %d of %d (malformed box); "
             "returning input unchanged to avoid truncation",
             consumed,
@@ -246,42 +246,39 @@ def blank_ai_exif_tokens(data: bytes) -> tuple[bytes, int]:
     ``remove_ai_metadata`` (a documented gap). This locates EXIF TIFF blocks by
     their byte-order header, **validates each with piexif** (so a coincidental
     II/MM run in pixel data is ignored -- it will not parse as a TIFF IFD), and
-    overwrites any value carrying an ``AI_GENERATOR_TOKENS`` token with spaces of
-    the SAME length. Because the replacement is same-length, every box size and
-    ``iloc`` offset stays valid and the coded image is untouched -- only the AI tag
-    content is destroyed; camera/editor EXIF without an AI token is left intact
-    (mirrors ``metadata._scrub_ai_exif`` and ``blank_ai_xmp_packets``).
+    overwrites any AI value with spaces of the SAME length. Because the replacement
+    is same-length, every box size and ``iloc`` offset stays valid and the coded image
+    is untouched -- only the AI tag content is destroyed; camera/editor EXIF without an
+    AI token is left intact. This mirrors ``metadata._scrub_ai_exif`` in what it removes
+    -- generator tokens (``Software``/``Make``/``Artist``/``ImageDescription``), the
+    China TC260 ``{"AIGC":{...}}`` block (``ImageDescription``/``UserComment``), and the
+    xAI/Grok ``Signature:`` + UUID-``Artist`` pair -- since on the ISOBMFF path this is
+    the ONLY EXIF scrubber (``_scrub_ai_exif`` never runs there), so without parity a
+    HEIC/AVIF AIGC/xAI tag is detected but not removed.
     """
     import piexif
 
-    from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
+    # The AI-EXIF rule set is defined ONCE in metadata._ai_exif_targets and shared by both
+    # EXIF scrubbers (the JPEG _scrub_ai_exif pops the tag; here we blank the value bytes),
+    # so their coverage cannot drift. Imported lazily to avoid import-order coupling with
+    # metadata (which imports this module); a deliberate cross-module use, not an API leak.
+    from remove_ai_watermarks.metadata import _ai_exif_targets  # pyright: ignore[reportPrivateUsage]
 
-    ai_tags = (
-        piexif.ImageIFD.Software,
-        piexif.ImageIFD.Make,
-        piexif.ImageIFD.Artist,
-        piexif.ImageIFD.ImageDescription,
-    )
     out = bytearray(data)
     blanked = 0
     for header in _TIFF_HEADERS:
         pos = data.find(header)
         while pos != -1:
             window = bytes(out[pos : pos + _EXIF_WINDOW])
-            ifd: dict[int, Any] = {}
             try:
-                ifd = piexif.load(window).get("0th", {})
+                loaded: dict[str, Any] = piexif.load(window)
             except Exception:
-                ifd = {}
-            for tag in ai_tags:
-                value = ifd.get(tag)
-                if not isinstance(value, bytes):
-                    continue
-                if any(token in value.decode("latin1", "replace").lower() for token in AI_GENERATOR_TOKENS):
-                    # Blank the value bytes in place, within this EXIF block only.
-                    vpos = out.find(value, pos, pos + _EXIF_WINDOW)
-                    if vpos != -1:
-                        out[vpos : vpos + len(value)] = b" " * len(value)
-                        blanked += 1
+                loaded = {}
+            for _ifd_key, _tag, value, _name in _ai_exif_targets(loaded):
+                # Blank the value bytes in place, within this EXIF block only.
+                vpos = out.find(value, pos, pos + _EXIF_WINDOW)
+                if vpos != -1:
+                    out[vpos : vpos + len(value)] = b" " * len(value)
+                    blanked += 1
             pos = data.find(header, pos + len(header))
     return bytes(out), blanked

src/remove_ai_watermarks/noai/tiling.py

@@ -81,7 +81,7 @@ def feather_weights(width: int, height: int, overlap: int) -> NDArray[Any]:
 
     Separable linear taper over ``overlap`` pixels from every edge (capped at
     half the tile so short tiles still taper symmetrically). Strictly positive
-    everywhere, so the normalised blend is well-defined even at an image corner
+    everywhere, so the normalized blend is well-defined even at an image corner
     that only one tile covers.
     """
     import numpy as np

src/remove_ai_watermarks/noai/watermark_profiles.py

@@ -5,6 +5,7 @@ Pure configuration and lookup functions with no ML dependencies.
 
 from __future__ import annotations
 
+import math
 from typing import TYPE_CHECKING, Literal
 
 if TYPE_CHECKING:
@@ -137,6 +138,30 @@ def resolve_strength(strength: float | None, vendor: str | None = None, pipeline
     return _VENDOR_STRENGTH.get(vendor or "", UNKNOWN_STRENGTH)
 
 
+def viable_steps(num_inference_steps: int, strength: float) -> int:
+    """The smallest step count >= ``num_inference_steps`` that actually denoises.
+
+    diffusers derives its img2img timesteps as ``int(steps * strength)``. When that
+    rounds to ZERO the pipeline builds an empty latent and dies deep inside attention
+    with ``cannot reshape tensor of 0 elements into shape [0, -1, 1, 512]`` -- an opaque
+    torch error for what is really "these two options cannot work together".
+
+    The combination is reachable with entirely valid CLI arguments: at the default
+    strength 0.15 every ``--steps`` below 7 crashed, and nothing told the user that
+    ``--steps`` and ``--strength`` interact (found by the release smoke matrix,
+    2026-07-19). Raising the count to the minimum that denoises keeps the caller's intent
+    -- they asked for "few steps", not "zero" -- and the engine logs the adjustment.
+
+    A non-positive ``strength`` cannot denoise at any step count; return the caller's
+    value unchanged rather than dividing by zero.
+    """
+    if strength <= 0:
+        return num_inference_steps
+    if int(num_inference_steps * strength) >= 1:
+        return num_inference_steps
+    return math.ceil(1 / strength)
+
+
 def vendor_for_strength(image_path: Path) -> Literal["openai", "google"] | None:
     """Detect the SynthID vendor for strength selection: ``"openai"`` / ``"google"`` / None.
 

src/remove_ai_watermarks/noai/watermark_remover.py

@@ -49,6 +49,7 @@ from remove_ai_watermarks.noai.watermark_profiles import (
     QWEN_MODEL_ID,
     normalize_profile,
     resolve_strength,
+    viable_steps,
 )
 
 logger = logging.getLogger(__name__)
@@ -447,6 +448,19 @@ class WatermarkRemover:
             self._set_progress("Loading fp16-fixed SDXL VAE (avoids black output)...")
             load_kwargs["vae"] = AutoencoderKL.from_pretrained(_SDXL_FP16_VAE_ID, torch_dtype=torch.float16)
 
+    @staticmethod
+    def _disable_sdxl_watermarker(load_kwargs: dict[str, Any]) -> None:
+        """Turn off the diffusers default invisible watermarker on an SDXL pipeline.
+
+        diffusers embeds an open "Stable Diffusion XL" DWT-DCT invisible watermark on
+        EVERY SDXL output whenever ``invisible-watermark`` is installed (the ``detect``
+        extra). A watermark REMOVER must not re-stamp a detectable AI watermark, or the
+        cleaned output re-reads as AI (``identify`` -> "Open invisible watermark: Stable
+        Diffusion XL"). Shared by both SDXL loaders; the ``ControlNetModel`` sub-model
+        and the Qwen loader never call it (only the pipeline accepts the kwarg).
+        """
+        load_kwargs["add_watermarker"] = False
+
     def _move_to_device_and_optimize(self, pipeline: Any) -> Any:
         """Move a freshly-loaded pipeline to ``self.device`` + enable memory opts.
 
@@ -520,6 +534,7 @@ class WatermarkRemover:
             load_kwargs = self._base_load_kwargs()
             load_kwargs["safety_checker"] = None
             load_kwargs["requires_safety_checker"] = False
+            self._disable_sdxl_watermarker(load_kwargs)
             self._maybe_add_fp16_vae(load_kwargs)
 
             pipeline = self._load_from_pretrained(AutoImg2ImgPipeline, self.model_id, **load_kwargs)  # type: ignore
@@ -549,6 +564,7 @@ class WatermarkRemover:
 
             load_kwargs = self._base_load_kwargs()
             load_kwargs["controlnet"] = controlnet
+            self._disable_sdxl_watermarker(load_kwargs)
             self._maybe_add_fp16_vae(load_kwargs)
 
             self._set_progress(f"Loading model weights: {self.model_id}")
@@ -675,6 +691,20 @@ class WatermarkRemover:
             self._set_progress(f"Setting reproducible seed: {seed}")
             generator = _make_seed_generator(self.device, seed)
 
+        # A step count whose product with strength rounds to zero kills the pipeline
+        # inside attention with an opaque reshape error, so raise it to the minimum that
+        # denoises. Must be applied to the value HANDED TO THE PIPELINE -- the old
+        # max(1, ...) below only clamped the number in the log line.
+        adjusted = viable_steps(num_inference_steps, strength)
+        if adjusted != num_inference_steps:
+            logger.warning(
+                "steps=%s at strength=%s denoises 0 steps and would crash; using steps=%s (1 effective)",
+                num_inference_steps,
+                strength,
+                adjusted,
+            )
+            num_inference_steps = adjusted
+
         effective_steps = max(1, int(num_inference_steps * strength))
         self._set_progress(
             f"Config: strength={strength}, steps={num_inference_steps} "
@@ -738,12 +768,24 @@ class WatermarkRemover:
             self._set_progress(f"Encoding as JPEG → {output_path.name}...")
         else:
             self._set_progress(f"Encoding as PNG → {output_path.name}...")
-        cleaned_image.save(output_path)
+        # Encode through image_io so the regenerated image gets the same quality-
+        # preserving write as the visible path (JPEG q100 / 4:4:4, HEIC/AVIF via Pillow)
+        # instead of PIL's default JPEG quality 75, which would crush the diffusion
+        # output further for no reason.
+        import numpy as np
+
+        from remove_ai_watermarks import image_io
+
+        rgb = np.asarray(cleaned_image.convert("RGB"))[:, :, ::-1]  # PIL RGB -> cv2 BGR
+        if not image_io.imwrite(str(output_path), np.ascontiguousarray(rgb)):
+            cleaned_image.save(output_path)  # fallback for a container image_io/cv2 cannot encode
 
         if output_path.exists():
             self._set_progress("Stripping AI metadata from output...")
             try:
-                from remove_ai_watermarks.noai.cleaner import remove_ai_metadata
+                # The single, robust stripper (byte-level: lossless for JPEG, handles
+                # every container) -- not the legacy PIL-re-encoding noai.cleaner one.
+                from remove_ai_watermarks.metadata import remove_ai_metadata
 
                 remove_ai_metadata(output_path, output_path, keep_standard=True)
             except Exception:
@@ -952,8 +994,9 @@ def remove_watermark(
     """Convenience function to remove watermark from an image.
 
     ``strength=None`` lets the profile pick its vendor-adaptive default
-    (0.20 OpenAI / 0.30 Google / 0.30 unknown, from the C2PA SynthID proxy on the
-    input; same ladder for the controlnet and sdxl pipelines). Pass a value to override.
+    (0.10 OpenAI / 0.15 Google / 0.15 unknown, from the C2PA SynthID proxy on the
+    input; same ladder for the controlnet and sdxl pipelines -- the single source of
+    truth is ``watermark_profiles.py``). Pass a value to override.
 
     ``region=(x, y, w, h)`` restricts the regeneration to that box and preserves the
     real photo elsewhere -- for AI-enhanced composites (see

src/remove_ai_watermarks/pill_engine.py

@@ -1,9 +1,9 @@
 """Jimeng-basic 'AI生成' pill: a CAPTURE-LESS visible mark (issue #54).
 
 The Jimeng free-tier TC260 label is a rounded pill with 'AI生成' in the TOP-LEFT
-corner -- distinct from the reverse-alpha ``jimeng`` "★ 即梦AI" mark (bottom-right).
-No flat capture / alpha map exists for it, so it is removed by INPAINT, not
-reverse-alpha:
+corner -- distinct from the ``jimeng`` "★ 即梦AI" wordmark (bottom-right). It has no
+captured alpha map, so unlike the other marks it is detected purely by a synthetic
+silhouette; like every mark it is then removed by the shared localize -> fill:
 
   * Detect: edge-NCC of a font-rendered SILHOUETTE (``assets/jimeng_pill.png``,
     synthetic, data-safe -- see ``scripts/render_pill_silhouette.py``) against the
@@ -89,7 +89,7 @@ def _grad(gray: NDArray[Any]) -> NDArray[Any]:
 
 
 class PillEngine:
-    """Detect + inpaint-mask the top-left 'AI生成' pill (edge-NCC, no reverse-alpha)."""
+    """Detect + build the removal mask for the top-left 'AI生成' pill (edge-NCC of a synthetic silhouette)."""
 
     def _match(self, image: NDArray[Any]) -> tuple[float, tuple[int, int, int, int]] | None:
         sil = _load_silhouette()
@@ -98,7 +98,7 @@ class PillEngine:
         h, w = image.shape[:2]
         if h < 64 or w < 64:
             return None
-        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        gray = cv2.cvtColor(image_io.to_bgr(image), cv2.COLOR_BGR2GRAY)
         rh, rw = int(h * _ROI_H_FRAC), int(w * _ROI_W_FRAC)
         roi = gray[0:rh, 0:rw]
         tw = max(24, int(_WIDTH_FRAC * w))
@@ -138,7 +138,7 @@ class PillEngine:
             return 0.0
         x0, y0, x1, y1 = box
         crop = image[y0:y1, x0:x1]
-        gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY) if crop.ndim == 3 else crop
+        gray = cv2.cvtColor(image_io.to_bgr(crop), cv2.COLOR_BGR2GRAY)
         tw = 220
         gray = cv2.resize(gray, (tw, max(1, int(gray.shape[0] * tw / gray.shape[1])))).astype(np.float32)
         gx = cv2.Sobel(gray, cv2.CV_32F, 1, 0, ksize=3)

src/remove_ai_watermarks/qwen_engine.py

@@ -0,0 +1,157 @@
+"""Qwen (Tongyi Qianwen, Alibaba) visible watermark detector/localizer.
+
+Qwen stamps its generations with a visible "千问AI生成" text strip in the
+bottom-right corner -- the explicit AIGC label mandated by China's GB 45438-2025
+(the same 6-glyph house style as Doubao's "豆包AI生成": a 2-glyph vendor prefix
+plus the shared `AI生成` tail), preceded by the vendor's tri-lobe logo (not part
+of the detection silhouette -- logos vary between releases, the CJK run is what
+discriminates).
+
+Detection matches the bundled glyph silhouette against the corner; removal is the
+shared **localize -> fill** (the glyph-bbox :meth:`footprint_mask` feeds
+``region_eraser``), NOT reverse-alpha. This module supplies only Qwen's tuned
+:class:`TextMarkConfig` (``assets/qwen_alpha.png`` -- a font-rendered synthetic
+silhouette from ``scripts/render_vendor_silhouettes.py``, never cut from an
+upload). It also feeds ``identify`` as the medium-confidence ``visible_qwen``
+signal via the registry.
+
+EVERY tuned number below was measured on the vendor cohort (117 TC260 carriers
+whose producer USCC 91440101MA9Y9T4H7A names the entity, 2026-07-21; harness
+``scripts/vendor_mark_calibrate.py``), NOT inherited from Doubao:
+
+  * The mark sits in TWO size modes (frac of the short side ~0.124 and ~0.203,
+    ratio 1.64 -- wider than the shared 3-rung ladder's 1.5625 span), so a single
+    fraction on the shared ladder covers ~75% of marks and the rest land in the
+    comb's collapse zone. Qwen therefore carries its OWN 2-rung ladder
+    (``TextMarkConfig.ladder``), one rung centred on each mode; the shared
+    default is untouched for every other mark.
+  * The mark also sits FARTHER off the corner than Doubao's box assumes (right
+    margin ~0.025 vs 0.004 of the short side), so Doubao's locate box clipped the
+    first glyph and collapsed an exact-size template to 0.26; the box fractions
+    below are fitted from the measured absolute mark rects.
+  * ``alpha_height_frac`` comes from the aspect fit at the winning width (p50
+    aspect 0.26), not from the silhouette's own aspect (0.2219) and not from
+    Doubao's ratio.
+  * STRICT ONLY (``provenance_ncc_factor`` 1.0): the score band just below the
+    gate is dominated by non-Qwen banners on same-cohort frames (a 夸克
+    anti-forgery strip at 0.274, a 造点 mark at 0.253), so a provenance-relaxed
+    arm would be mostly false fills. No provenance relaxation exists for this
+    mark.
+  * No rival margin: at the shipped gate the template fires on 0 of 400
+    Doubao-marked frames, 0 of 298 Jimeng-marked frames and 0 of 286 hand-labelled
+    clean frames (the shared tail correlates at ~0.22, far below the gate), while
+    a 0.10 rival margin would have suppressed ~10% of genuine Qwen detections.
+"""
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+# Locate geometry as a fraction of the image SHORT side (measured basis -- see
+# scale_base). The box is fitted to the measured mark rects: the mark's right
+# margin is ~0.025 of the short side (not Doubao's 0.004), so the box anchor is
+# wider off the corner; width/height cover the big size mode plus NCC slack.
+WM_WIDTH_FRAC = 0.231
+WM_HEIGHT_FRAC = 0.074
+MARGIN_RIGHT_FRAC = 0.0203
+MARGIN_BOTTOM_FRAC = 0.0218
+
+# Glyph appearance: a light, low-saturation gray rendered brighter than the local
+# background (white top-hat), same overlay class as Doubao -- inherited, and
+# harmless because the tophat front-end turns these gates into weights.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+TOPHAT_DELTA = 12
+
+DETECT_MIN_COVERAGE = 0.04  # unused by the tophat front-end (kept for config parity)
+# Calibrated 2026-07-21 on the vendor cohort vs 286 hand-labelled clean frames
+# (cohort-contamination-guarded): clean p99 0.301 / max 0.316, and every cohort
+# frame scoring >= 0.45 carries a visible 千问AI生成 mark (86% of the eyeballed
+# visible marks fire, the misses being white-on-near-white contrast losses).
+# 0.45 was picked over 0.32 (identical clean fire) for margin against unseen
+# clean content at zero measured recall cost.
+DETECT_NCC_THRESHOLD = 0.45
+
+# Detection-silhouette geometry (fraction of the short side), fitted on the
+# cohort: the mark's width modes and its aspect (0.26) at the winning width.
+_ALPHA_WIDTH_FRAC = 0.160
+_ALPHA_HEIGHT_FRAC = 0.0416
+
+# The two measured size modes as scale rungs: 0.124 and 0.203 of the short side,
+# expressed against the 0.160 nominal. Measured, not rounded: off-mode rungs drop
+# NCC from ~0.73 to ~0.37 on real marks (the comb), and a 4-rung variant scored
+# strictly worse (the extra rungs cover nothing and the big mode lands 4.6% off
+# its nearest rung).
+_LADDER = (0.78, 1.27)
+
+_CONFIG = TextMarkConfig(
+    name="Qwen",
+    asset_name="qwen_alpha.png",
+    corner="br",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_RIGHT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    detect_frontend="tophat",
+    scale_basis="short",  # measured: frac_short CV 0.189 vs width 0.273
+    ladder=_LADDER,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    min_gw=8,
+    # STRICT ONLY: the sub-gate band is dominated by non-Qwen banners, so
+    # provenance relaxation is disabled outright (factor 1.0 = never relaxed).
+    provenance_ncc_factor=1.0,
+)
+
+QwenDetection = TextMarkDetection
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled Qwen alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "千问AI生成" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
+
+
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
+    """TM_CCOEFF_NORMED of the Qwen glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
+
+
+class QwenEngine(TextMarkEngine):
+    """Detect/localize the visible Qwen "千问AI生成" watermark (locate -> mask; mask feeds the fill)."""
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/region_eraser.py

@@ -2,7 +2,7 @@
 
 Position- and content-agnostic. You supply the rectangle(s); the eraser inpaints
 whatever is inside, so it removes any visible logo / watermark / object regardless
-of colour, style, or location. Localisation is the user's responsibility (pass the
+of color, style, or location. Localization is the user's responsibility (pass the
 box); restoration runs on CPU. This is the universal fallback for marks the
 deterministic per-generator engines (Gemini sparkle, Doubao) do not cover.
 
@@ -10,9 +10,12 @@ Backends:
   - ``cv2`` (default): ``cv2.inpaint`` (Telea / Navier-Stokes). Instant, no extra
     dependencies, lower quality on large or textured regions.
   - ``migan`` (optional, extra ``migan``): MI-GAN via onnxruntime
-    (``andraniksargsyan/migan``, MIT). CPU, ~28 MB model, ~700-950 MB peak RAM,
-    ~0.19 s/call -- the droplet-friendly tier: near-big-LaMa quality on small
-    marks at ~5x less RAM and ~8x faster. Model downloaded on first use.
+    (``andraniksargsyan/migan``, MIT). CPU, ~28 MB model, ~0.19 s/call -- the
+    droplet-friendly tier: near-big-LaMa quality on small marks. Model downloaded
+    on first use. Like ``lama`` it crops a padded region around the mask before
+    inference (at native resolution -- MI-GAN takes arbitrary dims), so peak RAM is
+    bounded by the mark size (~0.6-0.9 GB) rather than scaling with the image, which
+    is what lets a memory-tight host run it on a large upload.
   - ``lama`` (optional, extra ``lama``): big-LaMa via onnxruntime
     (``Carve/LaMa-ONNX``, Apache-2.0). CPU, resolution-robust, best quality on
     texture but ~200 MB model and ~4.7 GB peak RAM (too heavy for a small host).
@@ -69,6 +72,26 @@ def boxes_to_mask(
     return mask
 
 
+def _padded_crop_box(
+    mask: NDArray[Any], h: int, w: int, *, pad_frac: float, pad_min: int
+) -> tuple[int, int, int, int] | None:
+    """Bounding box of the set mask pixels, padded and clamped to the image.
+
+    Returns ``(x0, y0, x1, y1)`` or ``None`` when the mask is empty. Both learned
+    backends crop to this box so the ONNX working set is bounded by the mark size
+    rather than the whole image; ``pad_frac``/``pad_min`` tune how much surrounding
+    context the inpainter sees (LaMa then resizes the crop to its fixed square,
+    MI-GAN feeds it at native resolution).
+    """
+    ys, xs = np.where(mask > 0)
+    if len(xs) == 0:
+        return None
+    pad = max(pad_min, int(pad_frac * max(xs.max() - xs.min() + 1, ys.max() - ys.min() + 1)))
+    x0, y0 = max(0, int(xs.min()) - pad), max(0, int(ys.min()) - pad)
+    x1, y1 = min(w, int(xs.max()) + 1 + pad), min(h, int(ys.max()) + 1 + pad)
+    return x0, y0, x1, y1
+
+
 def erase_cv2(
     image_bgr: NDArray[Any],
     mask: NDArray[Any],
@@ -139,19 +162,15 @@ def erase_lama(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
     size = next((d for d in reversed(dims) if isinstance(d, int) and d > 1), 512)
 
     h, w = image_bgr.shape[:2]
-    ys, xs = np.where(mask > 0)
-    if len(xs) == 0:
+    box = _padded_crop_box(mask, h, w, pad_frac=0.4, pad_min=16)
+    if box is None:
         return image_bgr.copy()
-
-    # Padded crop around the mask (context for the inpainter).
-    pad = max(16, int(0.4 * max(xs.max() - xs.min() + 1, ys.max() - ys.min() + 1)))
-    cx0, cy0 = max(0, int(xs.min()) - pad), max(0, int(ys.min()) - pad)
-    cx1, cy1 = min(w, int(xs.max()) + 1 + pad), min(h, int(ys.max()) + 1 + pad)
+    cx0, cy0, cx1, cy1 = box
     crop = image_bgr[cy0:cy1, cx0:cx1]
     crop_mask = mask[cy0:cy1, cx0:cx1]
     ch, cw = crop.shape[:2]
 
-    # Resize crop + mask to the model size, normalise to [0,1] RGB CHW.
+    # Resize crop + mask to the model size, normalize to [0,1] RGB CHW.
     crop_rs = cv2.resize(crop, (size, size), interpolation=cv2.INTER_AREA)
     mask_rs = cv2.resize(crop_mask, (size, size), interpolation=cv2.INTER_NEAREST)
     img_in = cv2.cvtColor(crop_rs, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
@@ -201,16 +220,25 @@ def _get_migan_session() -> object:
 def erase_migan(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
     """Inpaint ``mask`` (255 = erase) with MI-GAN via onnxruntime (CPU).
 
-    The MI-GAN ONNX pipeline crops around the mask bbox internally and re-composites,
-    so the full image is fed at native resolution. Only the masked pixels are pasted
-    back, so untouched areas stay pixel-exact.
+    Like ``erase_lama``, we crop a padded region around the mask, feed only that crop
+    to the ONNX model, and paste only the masked pixels back -- so untouched areas stay
+    pixel-exact and the ONNX working set is bounded by the MARK size, not the whole
+    image. MI-GAN accepts arbitrary spatial dims, so (unlike LaMa's fixed 512 square)
+    the crop is fed at NATIVE resolution -- no resize, so the mark is seen at full
+    scale. Feeding the whole frame instead made peak RAM scale with the image
+    (~0.6 GB at 4 MP up to ~2.4 GB at 25 MP, measured 2026-07); cropping holds the
+    inpaint working set roughly constant, so a memory-tight host (e.g. a 1-2 GB web
+    worker) can run MI-GAN on a 25 MP upload. Cropping does not degrade the fill:
+    a small mark only needs local context, and on real marks the cropped fill is on
+    par with -- sometimes cleaner than -- the full-frame fill (a tighter view gives
+    the GAN less room to hallucinate large background structure).
 
     Mask polarity: the shipped ``andraniksargsyan/migan`` ONNX expects 0 = hole
     (inpaint) / 255 = known (keep) -- the INVERSE of this package's 255-erase
     convention -- so the mask is inverted before feeding the model (corpus-validated
     2026-07; feeding 255=hole regenerates the whole frame into stripes).
 
-    Like ``erase_lama``, accepts 1-channel (grayscale) and 4-channel (BGRA) input.
+    Accepts 1-channel (grayscale) and 4-channel (BGRA) input.
     """
     if image_bgr.ndim == 2:
         bgr = erase_migan(cv2.cvtColor(image_bgr, cv2.COLOR_GRAY2BGR), mask)
@@ -219,26 +247,40 @@ def erase_migan(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
         bgr = erase_migan(np.ascontiguousarray(image_bgr[:, :, :3]), mask)
         return np.dstack([bgr, image_bgr[:, :, 3]])
 
+    h, w = image_bgr.shape[:2]
+    # 2x the mark size (min 256 px) gives ample local context while a small corner
+    # mask keeps the crop small regardless of the full image resolution; the crop is
+    # clamped to the image, so a mark already spanning the frame degrades to the
+    # whole image (the old behavior) rather than erroring.
+    box = _padded_crop_box(mask, h, w, pad_frac=2.0, pad_min=256)
+    if box is None:
+        return image_bgr.copy()
+    cx0, cy0, cx1, cy1 = box
+    crop = np.ascontiguousarray(image_bgr[cy0:cy1, cx0:cx1])
+    crop_mask = mask[cy0:cy1, cx0:cx1]
+    ch, cw = crop.shape[:2]
+
     session = _get_migan_session()
     inp = session.get_inputs()  # type: ignore[attr-defined]
     img_name, mask_name = inp[0].name, inp[1].name
-    h, w = image_bgr.shape[:2]
 
-    rgb = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB)
-    img_in = np.transpose(rgb, (2, 0, 1))[None].astype(np.uint8)  # (1,3,H,W)
+    rgb = cv2.cvtColor(crop, cv2.COLOR_BGR2RGB)
+    img_in = np.transpose(rgb, (2, 0, 1))[None].astype(np.uint8)  # (1,3,ch,cw)
     # invert to MI-GAN polarity: 255 where KNOWN (keep), 0 where hole (erase)
-    known = (mask <= 127).astype(np.uint8) * 255
-    mask_in = known[None, None]  # (1,1,H,W)
+    known = (crop_mask <= 127).astype(np.uint8) * 255
+    mask_in = known[None, None]  # (1,1,ch,cw)
 
     out = session.run(None, {img_name: img_in, mask_name: mask_in})[0]  # type: ignore[attr-defined]
-    res = np.transpose(np.asarray(out)[0], (1, 2, 0)).astype(np.uint8)  # (H',W',3) RGB
-    if res.shape[:2] != (h, w):
-        res = cv2.resize(res, (w, h), interpolation=cv2.INTER_LINEAR)
+    res = np.transpose(np.asarray(out)[0], (1, 2, 0)).astype(np.uint8)  # (ch',cw',3) RGB
+    if res.shape[:2] != (ch, cw):
+        res = cv2.resize(res, (cw, ch), interpolation=cv2.INTER_LINEAR)
     out_bgr = cv2.cvtColor(res, cv2.COLOR_RGB2BGR)
 
     result = image_bgr.copy()
-    hole = mask > 127
-    result[hole] = out_bgr[hole]
+    region = result[cy0:cy1, cx0:cx1]
+    hole = crop_mask > 127
+    region[hole] = out_bgr[hole]
+    result[cy0:cy1, cx0:cx1] = region
     return result
 
 

src/remove_ai_watermarks/runninghub_engine.py

@@ -0,0 +1,180 @@
+"""RunningHub visible watermark detector/localizer.
+
+RunningHub (a hosted ComfyUI platform, USCC 91340100MAEB4N8H76) stamps its
+generations with a faint light-gray "RunningHub AI生成" text mark in the
+**top-left** corner -- the China TC260 explicit AIGC label, but placed top-left
+(unlike the GB 45438-2025 house style bottom-right of Doubao/Qwen/Kling) and
+rendered in a mid-gray that the white top-hat front-end suppresses to clean-arm
+levels.
+
+Detection therefore uses the ``gray`` front-end (raw-grayscale silhouette NCC,
+see ``TextMarkConfig.detect_frontend``); removal is the shared **localize ->
+fill** (the detector's best-match box feeds :meth:`footprint_mask` ->
+``region_eraser``). This module supplies only RunningHub's tuned
+:class:`TextMarkConfig` (``assets/runninghub_alpha.png`` -- a font-rendered
+synthetic silhouette from ``scripts/render_vendor_silhouettes.py``, never cut
+from an upload).
+
+EVERY tuned number below was measured on the vendor cohort (73 TC260 carriers
+whose producer USCC names the entity, harvested 2026-07-22 by
+``scripts/vendor_cohort_harvest.py``), NOT inherited from Doubao:
+
+  * Only ~4 of the 73 cohort frames carry a visible mark (the rest are
+    metadata-only TC260 carriers -- the platform labels frames it does not
+    stamp), so recall of visible marks is 4/4 but the cohort fire rate is not
+    a recall estimate. Positions/geometry are consistent across the positives.
+  * The mark's width is ~0.32 of the frame WIDTH (0.319 measured on 832/1080/
+    1536-wide frames) at ~0.008/0.006 x/y margins; the locate box below covers
+    it with NCC slack.
+  * ``alpha_height_frac`` comes from the silhouette aspect (0.128) at the
+    measured width (0.27 * 1.25 rung ~= 0.3375 >= 0.32), per the standing rule
+    that it is measured, not inherited.
+  * STRICT ONLY (``provenance_ncc_factor`` 1.0): raw gray NCC is
+    contrast-DEPENDENT and the sub-gate band of a corner-anchored gray match is
+    unmeasured beyond the clean arm, so no provenance relaxation exists.
+  * Gate 0.34: on 283 hand-labelled clean frames (cohort-contamination-guarded)
+    corner-anchored gray NCC p99 is 0.264 / max 0.304, while the 4 positives
+    score 0.38-0.54. 0.34 sits above the clean max with a small margin; the
+    positives are few, so the margin is deliberately thin on the recall side.
+"""
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+# Locate geometry as a fraction of the image WIDTH (the measured basis: every
+# positive is portrait, where width == short side). The mark hugs the top-left
+# corner (~0.008 of width off the left edge, ~0.006 of height off the top).
+WM_WIDTH_FRAC = 0.45
+WM_HEIGHT_FRAC = 0.10
+MARGIN_LEFT_FRAC = 0.002
+MARGIN_TOP_FRAC = 0.002
+
+# Glyph appearance fields are unused by the gray front-end (it never binarizes)
+# and kept only for config parity with the other text marks.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+TOPHAT_DELTA = 12
+
+DETECT_MIN_COVERAGE = 0.04  # unused by the gray front-end (kept for config parity)
+# Calibrated 2026-07-22 on the vendor cohort vs 283 hand-labelled clean frames:
+# corner-anchored gray NCC, clean p99 0.264 / max 0.304; positives 0.38-0.54.
+DETECT_NCC_THRESHOLD = 0.34
+
+# Detection-silhouette geometry (fraction of the image width), measured on the
+# positives: mark width is ~0.320 of width on all three frame sizes (266px at 832,
+# 345px at 1080, 491px at 1536), and the NCC is razor-sharp in size (0.537 on-size,
+# 0.223 at +5.6% -- the same comb behaviour Qwen measured), so the nominal sits
+# exactly on the measured size with a TIGHT ladder around it, not the shared 3 rungs
+# (whose nearest rung landed 5.6% off and collapsed the match to 0.22).
+_ALPHA_WIDTH_FRAC = 0.32
+_ALPHA_HEIGHT_FRAC = 0.04
+_LADDER = (0.95, 1.0, 1.05)
+
+_CONFIG = TextMarkConfig(
+    name="RunningHub",
+    asset_name="runninghub_alpha.png",
+    corner="tl",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_LEFT_FRAC,
+    margin_bottom_frac=MARGIN_TOP_FRAC,  # top margin for corner="tl"
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    detect_frontend="gray",
+    scale_basis="width",  # measured: mark width tracks the frame width (0.32)
+    ladder=_LADDER,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    min_gw=8,
+    # STRICT ONLY: contrast-dependent gray NCC; the relaxed band is unmeasured.
+    provenance_ncc_factor=1.0,
+)
+
+RunningHubDetection = TextMarkDetection
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled RunningHub alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "RunningHub AI生成" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
+
+
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
+    """TM_CCOEFF_NORMED of the RunningHub glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
+
+
+class RunningHubEngine(TextMarkEngine):
+    """Detect/localize the visible RunningHub "RunningHub AI生成" mark (top-left; localize -> fill)."""
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)
+
+    # Anchor window for the match position, as a fraction of the FRAME: the true
+    # mark hugs the corner (measured x 0.008-0.014, y 0.005-0.007 of the frame on
+    # every cohort positive), while the full-corpus false fires (hair, shelves,
+    # window frames, CJK banners -- 37 of 42009 outside-cohort frames at the 0.34
+    # gate, 2026-07-22 sweep) match off-anchor at x 0.013-0.150 / y 0.009-0.045.
+    # No NCC gate separates them (false max 0.384 vs two positives at 0.381), but
+    # position does: every false fire sits outside this window, every positive
+    # inside. Contrast-dependent raw-gray NCC keys on "some text-like structure
+    # anywhere in the box"; the anchor is what makes it about THIS mark.
+    _ANCHOR_MAX_X = 0.025
+    _ANCHOR_MAX_Y = 0.015
+
+    def detect(self, image: NDArray[Any], *, provenance: bool = False) -> TextMarkDetection:
+        det = super().detect(image, provenance=provenance)
+        if not det.detected:
+            return det
+        loc = self.locate(image)
+        _, box = self._gray_best(image, loc)
+        if box is None:
+            det.detected = False
+            return det
+        h, w = image.shape[:2]
+        ax = (loc.x + box[0]) / w
+        ay = (loc.y + box[1]) / h
+        if ax > self._ANCHOR_MAX_X or ay > self._ANCHOR_MAX_Y:
+            logger.debug(
+                "RunningHub detect: score %.3f but match off-anchor (x=%.3f y=%.3f); demoting.",
+                det.confidence,
+                ax,
+                ay,
+            )
+            det.detected = False
+        return det
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/samsung_engine.py

@@ -1,19 +1,22 @@
-"""Samsung Galaxy AI visible watermark removal engine.
+"""Samsung Galaxy AI visible watermark detector/localizer.
 
 Samsung's on-device Generative AI photo edits burn a visible "✦ Contenuti generati
 dall'AI" wordmark into the bottom-LEFT corner (the Italian locale variant calibrated
-here; the string is locale-specific). It is a faint, near-white semi-transparent
-overlay, the same overlay class as the Doubao/Jimeng marks but bottom-left.
+here; the string is locale-specific -- DETECTION only matches this locale's silhouette,
+so other locales are not yet detected, though the fill mask itself is locale-agnostic).
+It is a faint, near-white semi-transparent overlay, the same overlay class as the
+Doubao/Jimeng marks but bottom-left.
 
-Removal is **reverse-alpha blending** against a captured alpha map
-(``original = (wm - a*logo)/(1-a)``), always NCC-aligned to the actual mark plus a thin
-residual inpaint over the glyph footprint. This is one of the three text-mark engines
-that share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
+Detection matches the bundled glyph silhouette against the corner; removal is the
+shared **localize -> fill** (the glyph-bbox :meth:`footprint_mask` feeds
+``region_eraser``), NOT reverse-alpha. This is one of the three text-mark engines that
+share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
 supplies only Samsung's tuned :class:`TextMarkConfig` (bottom-LEFT corner, a lower glyph
-luma since the mark is faint, ``assets/samsung_alpha.png`` solved from the flat captures
-by ``scripts/visible_alpha_solve.py``). Samsung Galaxy AI edits are also caught by C2PA
-+ the ``genAIType`` marker, so this is the visible-mark *removal* path; it also feeds
-``identify`` as the medium-confidence ``visible_samsung`` signal via the registry.
+luma since the mark is faint, ``assets/samsung_alpha.png`` -- the detection silhouette,
+solved from the flat captures by ``scripts/visible_alpha_solve.py``). Samsung Galaxy AI
+edits are also caught by C2PA + the ``genAIType`` marker, so this is the visible-mark
+*removal* path; it also feeds ``identify`` as the medium-confidence ``visible_samsung``
+signal via the registry.
 """
 # The module-level _alpha_template / _glyph_silhouette / _template_match_score below
 # are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
@@ -48,21 +51,13 @@ TOPHAT_DELTA = 8
 DETECT_MIN_COVERAGE = 0.01
 DETECT_NCC_THRESHOLD = 0.40
 
-# Reverse-alpha geometry, solved by scripts/visible_alpha_solve.py from the flat gray
-# capture (native width 1086). Real photos are ~2958 wide, so the captured glyph is
-# upscaled; width-scale + NCC-align removes it cleanly (a flat capture at the real
-# resolution would make the alpha pixel-sharp -- an open quality upgrade).
+# Detection-silhouette geometry, solved by scripts/visible_alpha_solve.py from the flat
+# gray capture (native width 1086). Real photos are ~2958 wide, so the captured glyph is
+# upscaled; width-scale + NCC-align sizes the silhouette for the detection match (removal
+# is the template-free glyph-bbox footprint mask).
 _ALPHA_NATIVE_WIDTH = 1086
-_ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
-_ALPHA_WIDTH_FRAC = 0.3195  # asset width / image width -- the alignment scale seed
+_ALPHA_WIDTH_FRAC = 0.3195  # asset width / image width -- sizes the detection silhouette
 _ALPHA_HEIGHT_FRAC = 0.0378
-_ALPHA_MARGIN_LEFT_FRAC = 0.0110
-_ALPHA_MARGIN_BOTTOM_FRAC = 0.0064
-# Wider scale search: the flat capture is far off the real-photo width.
-_ALPHA_ALIGN_SEARCH = (0.85, 1.18, 23)
-_RESIDUAL_ALPHA_FLOOR = 0.05
-_RESIDUAL_DILATE = 5
-_RESIDUAL_INPAINT_RADIUS = 2
 
 _CONFIG = TextMarkConfig(
     name="Samsung Galaxy AI",
@@ -81,14 +76,7 @@ _CONFIG = TextMarkConfig(
     detect_ncc_threshold=DETECT_NCC_THRESHOLD,
     alpha_width_frac=_ALPHA_WIDTH_FRAC,
     alpha_height_frac=_ALPHA_HEIGHT_FRAC,
-    alpha_margin_x_frac=_ALPHA_MARGIN_LEFT_FRAC,
-    alpha_margin_bottom_frac=_ALPHA_MARGIN_BOTTOM_FRAC,
-    alpha_align_search=_ALPHA_ALIGN_SEARCH,
     min_gw=16,
-    alpha_logo_bgr=_ALPHA_LOGO_BGR,
-    residual_alpha_floor=_RESIDUAL_ALPHA_FLOOR,
-    residual_dilate=_RESIDUAL_DILATE,
-    residual_inpaint_radius=_RESIDUAL_INPAINT_RADIUS,
 )
 
 SamsungDetection = TextMarkDetection
@@ -104,13 +92,13 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
+def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
     """TM_CCOEFF_NORMED of the Samsung glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, image_width, _CONFIG)
+    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
 
 
 class SamsungEngine(TextMarkEngine):
-    """Remove the visible Samsung Galaxy AI text mark (locate -> mask -> reverse-alpha)."""
+    """Detect/localize the visible Samsung Galaxy AI text mark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)

src/remove_ai_watermarks/trustmark_detector.py

@@ -28,7 +28,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from pathlib import Path
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 # Adobe ships Variant P in production (com.adobe.trustmark.P).
 _MODEL_TYPE = "P"
@@ -94,10 +94,10 @@ def detect_trustmark(image_path: Path) -> str | None:
         if not wm_present:
             return None
         if not _survives_reencode(decoder, cover, wm_schema):
-            log.debug("TrustMark decode for %s did not survive re-encode; treating as false positive", image_path)
+            logger.debug("TrustMark decode for %s did not survive re-encode; treating as false positive", image_path)
             return None
     except Exception as exc:  # model download / decode failure / unreadable image
-        log.debug("TrustMark decode failed for %s: %s", image_path, exc)
+        logger.debug("TrustMark decode failed for %s: %s", image_path, exc)
         return None
     return f"Adobe TrustMark (variant {_MODEL_TYPE}, schema {wm_schema})"
 

src/remove_ai_watermarks/watermark_registry.py

@@ -5,29 +5,33 @@ A single catalog that ties each known visible mark to (a) where it usually sits,
 registry detects every known mark in its usual place and removes the ones
 present.
 
-**Reverse-alpha based.** A known mark is a fixed semi-transparent overlay, so it
-is removed by inverting the alpha blend against a captured alpha map
-(``original = (wm - a*logo)/(1-a)``) -- recovering the true pixels rather than
-inpainting a guess. Gemini and Doubao recover exactly with no inpaint at native on
-bright/flat backgrounds (Gemini falls back to inpainting the sparkle footprint when
-reverse-alpha would over-subtract on a dark background -- issue #30, see gemini_engine);
-Jimeng adds a thin residual inpaint over the glyph footprint to clear the outline
-its per-image render variation leaves behind (still seeded by the reverse-alpha
-recovery, not a blind inpaint). Detection is consistent with that: each mark is
-recognized by matching its known shape/template (the thing we invert), not by
-heuristics. A mark is therefore listed here only once a real alpha map has been
-captured for it; everything else (arbitrary logos/objects) is the user-directed
-``erase --region`` tool, not this catalog.
+**Localize -> fill.** A known mark is removed by LOCALIZING it (a template-free,
+version-robust detector that returns a binary footprint MASK) and then handing
+that mask to ONE shared, swappable fill backend (``region_eraser``: cv2 Telea/NS,
+MI-GAN, or big-LaMa). No mark carries a reverse-alpha step any more: the old
+``original = (wm - a*logo)/(1-a)`` recovery depended on a fixed captured alpha map
+at a fixed position, broke whenever a vendor re-rendered or moved its mark, and was
+not color-lossless even with the right map (it amplifies quantization/JPEG-chroma
+error by ``1/(1-a)`` -- the "the color just changed, not removed" reports). The
+localizer stays cheap (cv2/numpy, CPU) so a memory-tight caller can run it on a
+small worker; the heavy fill (MI-GAN / LaMa) is opt-in and chosen by the caller.
 
 Entries:
   - ``gemini`` -- Google Gemini / Nano Banana sparkle, bottom-right.
   - ``doubao`` -- ByteDance Doubao "豆包AI生成" text strip, bottom-right.
   - ``jimeng`` -- ByteDance Jimeng / Dreamina "★ 即梦AI" wordmark, bottom-right.
+  - ``qwen`` -- Alibaba Tongyi Qianwen "千问AI生成" text strip, bottom-right.
+  - ``kling`` -- Kuaishou Kling "可灵AI 3.0" text strip, bottom-right.
   - ``samsung`` -- Samsung Galaxy AI "Contenuti generati dall'AI" strip, bottom-left.
+  - ``jimeng_pill`` -- Jimeng-basic "AI生成" pill, top-left (capture-less).
+  - ``runninghub`` -- RunningHub "RunningHub AI生成" text, top-left (gray front-end).
+  - ``baidu`` -- Baidu "百度 AI生成" text + white tag, bottom-right.
+  - ``liblib`` -- LibLibAI "LibLibAI" wordmark, bottom-center.
 """
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
@@ -36,15 +40,87 @@ if TYPE_CHECKING:
 
     from numpy.typing import NDArray
 
-# cv2 method for the Gemini reverse-alpha edge-residual cleanup (not a standalone
-# remover): "ns" / "telea".
-InpaintMethod = Literal["telea", "ns"]
+logger = logging.getLogger(__name__)
+
 Region = tuple[int, int, int, int]
 
-# Removal method selection for the visible pass. ``auto`` prefers the inpaint
-# fallback (LaMa footprint) when the ``lama`` extra is installed, else reverse-alpha
-# for marks with a captured alpha map (cv2 inpaint for capture-less marks).
-RemovalMethod = Literal["auto", "reverse-alpha", "inpaint"]
+# Fill backend for the shared removal path. ``auto`` resolves best-first to the highest
+# quality installed model -- LaMa, else MI-GAN, else cv2 (see ``resolve_backend``); the
+# others force a specific backend (mirrors the ``erase`` command's ``--backend``).
+Backend = Literal["auto", "cv2", "migan", "lama"]
+
+# Detection sensitivity for the removal path -- how much to trust a borderline mark.
+#   * ``strict``: high-precision visual gate only; never relaxed, so a clean image is
+#     never touched (the gate demotes a sparkle-shaped content match, so it never fills
+#     a clean corner). Lowest recall on faint/moved marks.
+#   * ``auto`` (default): relax a mark's gate ONLY when the image carries same-product
+#     evidence the mark is there -- metadata provenance for that vendor, or a confidently
+#     detected sibling mark of the same product (see ``resolve_trust``). No evidence ->
+#     stays strict. Safe: it only escalates where the mark is corroborated.
+#
+# REMOVED 2026-07-19: ``assume_ai`` relaxed every mark's gate on the caller's bare
+# assertion that the image is AI. It was a statistical gamble, not an instruction:
+# "this image is AI" says nothing about WHICH vendor or WHERE, which is exactly what a
+# gate bypass needs, so it took a confidence floor to be tolerable at all (before that
+# floor it filled a phantom sparkle on 59.8% of genuine camera photos). It also had no
+# place in the product's own model -- detector finds a mark, remove it; detector finds
+# nothing, leave the image alone; the USER sees a mark and says so, act on that. A user
+# who can see the mark is better served by pointing at it (``erase --region``) or naming
+# it (``--mark X --no-detect`` for a text mark), both of which execute an instruction
+# instead of guessing. Removing it also collapsed the trust ladder from three levels to
+# two. See docs/module-internals.md for the measurements.
+Sensitivity = Literal["auto", "strict"]
+
+# The trust level a mark's detection gate is resolved to (see ``resolve_trust``).
+# ``confirmed`` bypasses the engine's false-positive gate, and that bypass is documented
+# to require evidence naming THIS vendor (see GeminiEngine.detect_watermark's
+# ``trust_provenance`` contract) -- so it is only ever reached from same-product evidence.
+# A third ``assumed`` level existed for ``assume_ai`` and went with it (2026-07-19).
+Trust = Literal["strict", "confirmed"]
+
+# Product family per mark, for the ``auto`` cross-mark corroboration: a confidently
+# detected mark relaxes only OTHER marks of the SAME product (different corners, one
+# product -- the Jimeng wordmark + the Jimeng pill). Doubao and Jimeng are BOTH ByteDance
+# but distinct products in the SAME bottom-right corner, so they must NOT cross-relax
+# (relaxing Doubao on a Jimeng wordmark would spuriously fire Doubao on it).
+_PRODUCT_OF: dict[str, str] = {
+    "gemini": "gemini",
+    "doubao": "doubao",
+    "jimeng": "jimeng",
+    "jimeng_pill": "jimeng",  # same product as the Jimeng wordmark
+    "qwen": "qwen",
+    "kling": "kling",
+    "samsung": "samsung",
+    "runninghub": "runninghub",
+    "baidu": "baidu",
+    "liblib": "liblib",
+}
+
+
+# Marks whose own detection is too weak to serve as EVIDENCE for a sibling of the
+# same product, even though they share one. Sibling corroboration grants ``confirmed``
+# trust, which bypasses the sibling's false-positive gate outright -- so a detector
+# that false-fires often must not be able to hand that bypass to anyone.
+#
+# The pill qualifies on its own documented numbers: ~7% raw false-fire (5.5% measured
+# on 578 vendor negatives, 2026-07-18). Letting it corroborate produced a closed loop
+# on the DEFAULT auto path, no user flag involved:
+#   pill false-fires on a clean non-ByteDance image
+#     -> _PRODUCT_OF maps it to "jimeng", so jimeng resolves to `confirmed`
+#     -> jimeng's NCC gate drops 0.45 -> 0.3825 and it false-fires too
+#     -> _keep_pill now sees "jimeng" in keys and takes the WORDMARK arm, which
+#        removes the pill unrestricted -- skipping the flatness guard that exists
+#        precisely to stop the fill smearing a textured corner.
+# Measured on the corpus: 3 of 578 negatives ran the full loop, one of them with
+# footprint_flat=0 (the exact case the guard was written to block). Cutting the pill
+# out of corroboration removed all 3 and cost NOTHING on 4417 TC260 carriers
+# (jimeng fires 398 -> 398), so this is a defect fix, not a recall trade.
+#
+# `_keep_pill` already encodes the same distrust for the pill's own ACTION; this
+# closes the gap that its TESTIMONY was never gated.
+# Regression: tests/test_watermark_registry.py::TestArbiter::
+#   test_weak_pill_detection_does_not_confirm_the_jimeng_wordmark
+_CANNOT_CORROBORATE: frozenset[str] = frozenset({"jimeng_pill"})
 
 
 @dataclass(frozen=True)
@@ -59,56 +135,162 @@ class MarkDetection:
     region: Region
 
 
+@dataclass(frozen=True)
+class Localization:
+    """A located mark: its detection verdict plus the full-frame removal mask.
+
+    ``mask`` is a full-frame uint8 array (255 = remove) sized to the image, or None
+    when nothing should be removed (no detection and not forced, or the footprint
+    could not be placed). ``region`` is the mark's bbox (for logging / residual
+    positioning)."""
+
+    detected: bool
+    confidence: float
+    region: Region
+    mask: NDArray[Any] | None
+
+
+_REMOVED_SENSITIVITIES = {
+    "assume_ai": (
+        "sensitivity='assume_ai' was removed in 0.16: it relaxed EVERY mark's detection "
+        "gate on the bare assertion that an image is AI, which says nothing about which "
+        "vendor made it or where the mark is. If you can see a mark the detector missed, "
+        "act on what you see: erase(image, region=(x, y, w, h)), or the CLI "
+        "`--mark <name> --no-detect` for a known text mark. Use sensitivity='auto' for "
+        "the default evidence-driven behaviour."
+    )
+}
+
+
+def validate_sensitivity(value: str) -> Sensitivity:
+    """Reject a removed sensitivity LOUDLY instead of silently falling back to ``auto``.
+
+    ``Sensitivity`` is a ``Literal``, which is not enforced at runtime, so a caller
+    upgrading from 0.15 would pass ``"assume_ai"`` and quietly get ``auto`` behaviour --
+    a silent semantic change on the one release where they most need to be told.
+    """
+    if value in _REMOVED_SENSITIVITIES:
+        raise ValueError(_REMOVED_SENSITIVITIES[value])
+    if value not in ("auto", "strict"):
+        raise ValueError(f"unknown sensitivity {value!r}; expected 'auto' or 'strict'")
+    return value  # type: ignore[return-value]
+
+
+@dataclass(frozen=True)
+class Context:
+    """The evidence + policy the removal arbiter decides against (perception is
+    kept separate from this decision). ``sensitivity`` is the caller's intent
+    (see :data:`Sensitivity`); ``provenance`` is the vendor keys local metadata
+    confirms, the evidence that drives ``auto``. Bundling them into one object is
+    why the arbiter can be a pure function of ``(candidates, context)``."""
+
+    sensitivity: Sensitivity = "auto"
+    provenance: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        validate_sensitivity(self.sensitivity)
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """One mark's PERCEPTION output -- what the engine sees, with NO policy applied.
+
+    Carries the mark's verdict at BOTH trust levels (``detected_strict`` = the
+    conservative gate, ``detected_relaxed`` = the gate the engine relaxes to under
+    provenance), so the arbiter can pick per mark without re-running detection.
+
+    ``features`` is a generic bag of physical measurements a mark's gate may need (the
+    mark owns which it reports via ``KnownMark._features``); e.g. the pill supplies
+    ``footprint_flat`` (0/1). Empty for marks whose gate needs no extra evidence."""
+
+    key: str
+    label: str
+    detected_strict: bool
+    detected_relaxed: bool
+    features: dict[str, float]  # generic; both construction sites always supply it (empty when none)
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The arbiter's verdict for one fired mark: remove it, at the resolved trust
+    level (``relax`` feeds the mark's mask build so the fill footprint matches the
+    level the mark was accepted at)."""
+
+    candidate: Candidate
+    relax: bool
+
+
 @dataclass(frozen=True)
 class KnownMark:
-    """A known visible watermark: where it lives, how to find and remove it."""
+    """A known visible watermark: where it lives, how to find and mask it.
+
+    Removal is uniform (:meth:`remove`): localize the mark to a mask, then fill that
+    mask with the chosen backend. Each mark supplies two cheap cv2/numpy callables --
+    ``_detect`` (verdict + bbox, no mask; used by the identify scan) and ``_mask``
+    (the full-frame footprint mask; used by removal)."""
 
     key: str
     label: str
     location: str  # usual place, human-readable ("bottom-right")
     in_auto: bool  # participate in `--mark auto` scanning
-    recovery: str  # default removal strategy label ("reverse-alpha")
-    _detect: Callable[[NDArray[Any]], MarkDetection]
-    _remove: Callable[..., tuple[NDArray[Any], Region | None]]
-    has_capture: bool = True  # a captured alpha map exists (reverse-alpha possible)
+    _detect: Callable[..., MarkDetection]
+    _mask: Callable[..., NDArray[Any] | None]
+    # Optional physical-feature probe: the mark's OWN measurements its gate needs
+    # (e.g. the pill's footprint flatness), so the perception pass stays uniform and
+    # does not special-case any mark. None = the mark's gate needs no extra evidence.
+    _features: Callable[..., dict[str, float]] | None = None
 
-    def detect(self, image: NDArray[Any]) -> MarkDetection:
-        return self._detect(image)
+    def features(self, image: NDArray[Any]) -> dict[str, float]:
+        """Physical features the mark reports for the arbiter's gate (empty if none)."""
+        return self._features(image) if self._features is not None else {}
+
+    def detect(self, image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
+        """Detect the mark (verdict + bbox, no mask). ``provenance`` signals that
+        external metadata already confirms this vendor, so the engine may relax its
+        trust threshold (a mark it would otherwise demote as a content false positive
+        is trusted when provenance says the vendor is present)."""
+        return self._detect(image, provenance=provenance)
+
+    def localize(self, image: NDArray[Any], *, provenance: bool = False, force: bool = False) -> Localization:
+        """Detect and build the removal mask in one call. Returns a
+        :class:`Localization`; ``mask`` is None unless the mark is detected (or
+        ``force`` bypasses detection for the mark's usual footprint)."""
+        det = self.detect(image, provenance=provenance)
+        if not (det.detected or force):
+            return Localization(det.detected, det.confidence, det.region, None)
+        # Pass the (provenance-aware) detection to the mask builder so it does NOT
+        # re-detect at a different trust level -- a relaxed sparkle must not be
+        # re-demoted into a None mask (reported-removed-but-unchanged).
+        mask = self._mask(image, force=force, detection=det)
+        return Localization(det.detected, det.confidence, det.region, mask)
 
     def remove(
         self,
         image: NDArray[Any],
         *,
-        method: RemovalMethod = "auto",
-        inpaint_method: InpaintMethod = "ns",
-        inpaint: bool = True,
-        inpaint_strength: float = 0.85,
+        backend: Backend = "auto",
+        provenance: bool = False,
         force: bool = False,
     ) -> tuple[NDArray[Any], Region | None]:
-        """Remove this mark; returns ``(result, region)`` where ``region`` is the
-        removed mark's bbox (for residual-inpaint positioning), or None if nothing
-        was removed. NB: the CLI does NOT use ``region`` to clear alpha on save --
-        that zeroing caused the issue-#30 white box.
+        """Remove this mark by localize -> fill; returns ``(result, region)`` where
+        ``region`` is the removed mark's bbox, or None if nothing was removed.
 
-        ``method`` selects the removal path: ``reverse-alpha`` recovers the true
-        pixels from the captured alpha map (lighter, exact, better on structured
-        backgrounds); ``inpaint`` erases the footprint with LaMa (or cv2 when the
-        ``lama`` extra is absent), needing no capture; ``auto`` (default) prefers
-        inpaint when LaMa is installed and falls back to reverse-alpha otherwise
-        (cv2 inpaint for capture-less marks). ``inpaint``/``inpaint_strength``/
-        ``inpaint_method`` tune the Gemini reverse-alpha edge-residual cleanup only.
-        ``force`` removes at the mark's usual location even without a positive
-        detection (the ``--no-detect`` path).
-        """
-        if resolve_removal_method(method, self.has_capture) == "inpaint":
-            return _inpaint_remove(self, image, force)
-        return self._remove(image, inpaint_method, inpaint, inpaint_strength, force)
+        ``backend`` picks the fill (``auto`` = LaMa > MI-GAN > cv2, best available; or force
+        ``cv2``/``migan``/``lama``). ``provenance`` relaxes the detector's trust gate
+        when metadata already confirms the vendor. ``force`` removes at the mark's
+        usual footprint even without a positive detection (the ``--no-detect`` path).
+        NB: the CLI does NOT use ``region`` to clear alpha on save -- that zeroing
+        caused the issue-#30 white box."""
+        loc = self.localize(image, provenance=provenance, force=force)
+        if loc.mask is None or not loc.mask.any():
+            return image.copy(), None
+        return fill(image, loc.mask, backend=backend), (loc.region if loc.detected else None)
 
 
 # Single source of truth for the Gemini-sparkle "trust this as a real mark"
-# confidence, shared by BOTH the removal arbitration here (`best_auto_mark` /
-# `_gemini_detect`) and the provenance detector in `identify` (which imports it
-# as its sparkle threshold). Defining it once removes the detect-vs-remove
+# confidence, shared by BOTH the removal arbitration here (`_gemini_detect`) and
+# the provenance detector in `identify` (which imports it as its sparkle threshold).
+# Defining it once removes the detect-vs-remove
 # threshold drift the retained-corpus mining surfaced (2026-06-20): identify
 # would report a sparkle while removal declined it, or vice versa, whenever the
 # two independently-maintained 0.5 constants fell out of step. Now they cannot.
@@ -119,14 +301,49 @@ class KnownMark:
 # and its core-ring brightness margin is HIGHER than a genuine faint sparkle's,
 # so neither confidence nor the brightness gate separates them in the [0.35, 0.5)
 # band. Lowering this gate to recover faint sparkles was evaluated against that
-# band (2026-06-20) and REJECTED: it cannot be done without re-admitting the
-# Doubao-text / content false positives, trading a rare miss for false-positive
-# removals on clean images. The band below the gate is therefore intentionally
-# left to the higher-strength / metadata paths. 0.5 gives 0 false positives on
-# the corpus.
+# band (2026-06-20) and REJECTED for the no-provenance case: it cannot be done
+# without re-admitting the Doubao-text / content false positives. The band below
+# the gate is therefore left to the metadata-confirmed path below.
 GEMINI_SPARKLE_TRUST_CONF = 0.5
 _GEMINI_AUTO_MIN_CONF = GEMINI_SPARKLE_TRUST_CONF
 
+# Provenance-confirmed Gemini trust gate. When external metadata already proves the
+# image is a Google generation (C2PA issuer "Google"/"Gemini"), the [gate, 0.5) band
+# that the no-provenance gate leaves out is no longer ambiguous with Doubao text: a
+# Doubao image carries ByteDance provenance, not Google, so it never reaches this
+# relaxed gate. The vendor moving/re-rendering the sparkle (bigger, lighter, shifted
+# north-west) drops a real sparkle into this band, and the fixed-slot detector demotes
+# it -- provenance is exactly the extra evidence that lets us trust it.
+#
+# The gate was originally the engine's own `detected` floor (0.35). Raised to 0.42
+# on 2026-07-18 after measuring what this arm actually admits, because the Doubao
+# argument above -- while correct -- is not the binding constraint. Google C2PA is
+# carried by Imagen, API generations and NotebookLM exports, none of which stamp a
+# visible sparkle at all, so the relaxed gate spends most of its budget on images
+# that never had a mark rather than on moved ones.
+#
+# Measured blind on 954 unique Google-metadata uploads (detector never saw the
+# metadata), hand-labelled against a two-sided control (labeller sensitivity ~88%,
+# specificity 100%). "Additions" = accepted with provenance but not without:
+#
+#   band         precision   95% CI    population
+#   0.35-0.42          13%    5-30%           120
+#   0.42-0.46          35%   19-54%            47
+#   0.46-0.50          27%   14-46%            44
+#   0.50-0.54          40%   20-64%            15
+#
+# Precision is flat above 0.42 and collapses below it, and that bottom band alone is
+# half the arm's volume -- so this is a step, not a gradient, and 0.42 is where it
+# sits. Raising the gate here drops ~16 genuine recoveries to prevent ~104 false
+# fills (6.5:1), cutting false fills from 18.7% to 7.8% of Google-metadata uploads.
+# A false fill is the worse error: it destroys pixels AND makes the caller report a
+# removal that did not happen, while a miss leaves the image untouched.
+#
+# NOTE: even at 0.42 this arm runs at ~33% precision (two false fills per genuine
+# recovery). Whether an arm that inaccurate should exist at all is a product call,
+# not a tuning one -- do not read this constant as "now correct".
+_GEMINI_PROVENANCE_MIN_CONF = 0.42
+
 # ── Engine adapters (lazy singletons; engines are cv2-only, no model load) ──
 
 _engines: dict[str, Any] = {}
@@ -146,6 +363,14 @@ def _engine(key: str) -> Any:
             from remove_ai_watermarks.jimeng_engine import JimengEngine
 
             _engines[key] = JimengEngine()
+        elif key == "qwen":
+            from remove_ai_watermarks.qwen_engine import QwenEngine
+
+            _engines[key] = QwenEngine()
+        elif key == "kling":
+            from remove_ai_watermarks.kling_engine import KlingEngine
+
+            _engines[key] = KlingEngine()
         elif key == "samsung":
             from remove_ai_watermarks.samsung_engine import SamsungEngine
 
@@ -154,6 +379,18 @@ def _engine(key: str) -> Any:
             from remove_ai_watermarks.pill_engine import PillEngine
 
             _engines[key] = PillEngine()
+        elif key == "runninghub":
+            from remove_ai_watermarks.runninghub_engine import RunningHubEngine
+
+            _engines[key] = RunningHubEngine()
+        elif key == "baidu":
+            from remove_ai_watermarks.baidu_engine import BaiduEngine
+
+            _engines[key] = BaiduEngine()
+        elif key == "liblib":
+            from remove_ai_watermarks.liblib_engine import LibLibEngine
+
+            _engines[key] = LibLibEngine()
         else:  # pragma: no cover - guarded by the registry keys
             raise KeyError(key)
     return _engines[key]
@@ -166,148 +403,142 @@ def inpaint_model_available() -> bool:
     return region_eraser.migan_available() or region_eraser.lama_available()
 
 
-def preferred_inpaint_backend() -> str:
-    """Backend used by the inpaint fallback: MI-GAN (light, droplet-friendly, the
-    default) when its ONNX runtime is available, else cv2. big-LaMa is NOT auto-
-    selected -- it is a heavier explicit opt-in via ``erase --backend lama`` (both
-    models run on onnxruntime, so availability alone cannot express the user's
-    intent; the light model is the safe default)."""
+_warned_cv2_fallback = False
+
+
+def preferred_inpaint_backend() -> Literal["lama", "migan", "cv2"]:
+    """Backend the ``auto`` fill resolves to, best-first: LaMa > MI-GAN > cv2.
+
+    LaMa is the highest-quality inpaint (it recovers the textured/structured backgrounds
+    the classical fill smears), so ``auto`` prefers it whenever a learned backend can run
+    (onnxruntime present). MI-GAN is the lighter learned model; both currently share the
+    SAME onnxruntime availability check, so ``auto`` cannot tell them apart and always
+    prefers the better one -- a memory-tight deployment that cannot afford LaMa's ~4.7 GB
+    peak pins MI-GAN explicitly via ``--backend migan`` / ``backend="migan"`` (that is the
+    deployment's call, not the library's). cv2 is the classical no-deps floor and the last
+    resort: it smears textured/structured backgrounds, so a one-time quality warning fires
+    when ``auto`` falls back to it."""
     from remove_ai_watermarks import region_eraser
 
-    return "migan" if region_eraser.migan_available() else "cv2"
+    if region_eraser.lama_available():
+        return "lama"
+    if region_eraser.migan_available():
+        return "migan"
+    global _warned_cv2_fallback
+    if not _warned_cv2_fallback:
+        _warned_cv2_fallback = True
+        logger.warning(
+            "No learned-inpaint backend available (onnxruntime not installed); falling back "
+            "to the cv2 classical inpaint, which can smear textured or structured backgrounds. "
+            "Install the 'lama' (best) or 'migan' (lighter) extra for higher-quality fills."
+        )
+    return "cv2"
 
 
-def resolve_removal_method(method: RemovalMethod, has_capture: bool) -> Literal["reverse-alpha", "inpaint"]:
-    """Resolve the requested method to a concrete one. A capture-less mark has no
-    alpha map, so it can only be inpainted -- even explicit ``reverse-alpha`` falls
-    back to inpaint there.
-
-    ``auto`` uses **reverse-alpha for capture marks** and **inpaint for capture-less**.
-    Reverse-alpha recovers the true pixels under the mark (measured cleaner than
-    MI-GAN inpaint on the capture marks -- doubao/gemini/jimeng -- especially on
-    structured backgrounds, and it needs no model / RAM), so it stays the default
-    where a capture exists; inpaint is reserved for marks that have no alpha map
-    (the Jimeng pill). ``--method inpaint`` still forces inpaint for anyone who
-    wants it."""
-    # A capture-less mark can only be inpainted; a capture mark inpaints only when
-    # explicitly asked (auto + reverse-alpha both recover the true pixels).
-    if method == "inpaint" or not has_capture:
-        return "inpaint"
-    return "reverse-alpha"
+def resolve_backend(backend: Backend) -> Literal["cv2", "migan", "lama"]:
+    """Resolve ``auto`` to the preferred installed backend; pass the rest through."""
+    if backend == "auto":
+        return preferred_inpaint_backend()
+    return backend
 
 
-def _inpaint_remove(mark: KnownMark, image: NDArray[Any], force: bool) -> tuple[NDArray[Any], Region | None]:
-    """Remove ``mark`` by inpainting its footprint: the NCC-aligned captured
-    silhouette (:meth:`footprint_mask`), erased with MI-GAN when its extra is
-    installed, else cv2 (see :func:`preferred_inpaint_backend`). No-op (returns a
-    copy) on a clean corner unless ``force``. Gated on the mark's trust-confidence
-    detection, so a clean image is never touched."""
+def fill(image: NDArray[Any], mask: NDArray[Any], *, backend: Backend = "auto") -> NDArray[Any]:
+    """The ONE shared, mark-agnostic removal: erase ``mask`` (255 = remove) via the
+    chosen inpaint backend. Delegates to :func:`region_eraser.erase`; ``auto``
+    resolves to MI-GAN when installed else cv2 (see :func:`resolve_backend`)."""
     from remove_ai_watermarks import region_eraser
 
-    det = mark.detect(image)
-    if not (det.detected or force):
-        return image.copy(), None
-    engine = _engine(mark.key)
-    fm = engine.footprint_mask(image, force=force)  # uniform signature; text/pill ignore force
-    if fm is None or not fm.any():
-        return image.copy(), None
-    if preferred_inpaint_backend() == "migan":
-        result = region_eraser.erase_migan(image, fm)
-    else:
-        result = region_eraser.erase_cv2(image, fm, radius=6)
-    return result, (det.region if det.detected else None)
+    return region_eraser.erase(image, mask=mask, backend=resolve_backend(backend))
 
 
-def _gemini_detect(image: NDArray[Any]) -> MarkDetection:
-    d = _engine("gemini").detect_watermark(image)
-    detected = bool(d.detected) and d.confidence >= _GEMINI_AUTO_MIN_CONF
+# ── Detection adapters (verdict + bbox; no mask work on this path) ──
+# The identify scan calls `detect_marks`, which must stay cheap (it runs every
+# detector on the memory-tight identify host), so detection never builds a mask.
+
+
+def _gemini_detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
+    d = _engine("gemini").detect_watermark(image, trust_provenance=provenance)
+    gate = _GEMINI_PROVENANCE_MIN_CONF if provenance else _GEMINI_AUTO_MIN_CONF
+    detected = bool(d.detected) and d.confidence >= gate
     return MarkDetection("gemini", "Google Gemini sparkle", "bottom-right", detected, d.confidence, d.region)
 
 
-def _gemini_remove(
-    image: NDArray[Any], inpaint_method: InpaintMethod, inpaint: bool, strength: float, force: bool
-) -> tuple[NDArray[Any], Region | None]:
-    engine = _engine("gemini")
-    det = engine.detect_watermark(image)
-    if not det.detected:
-        if not force:
-            return image.copy(), None
-        # Forced (--no-detect): remove at the default sparkle slot for the size.
-        from remove_ai_watermarks.gemini_engine import get_watermark_config
-
-        h, w = image.shape[:2]
-        cfg = get_watermark_config(w, h)
-        px, py = cfg.get_position(w, h)
-        region = (px, py, cfg.logo_size, cfg.logo_size)
-        result = engine.remove_watermark_custom(image, region)
-        if inpaint:
-            result = engine.inpaint_residual(result, region, strength=strength, method=inpaint_method)
-        return result, region
-    result = engine.remove_watermark(image)
-    # Reverse-alpha leaves a faint residual at the sparkle edge; the engine's
-    # own residual inpaint cleans that seam (part of its reverse-alpha pipeline).
-    if inpaint:
-        result = engine.inpaint_residual(result, det.region, strength=strength, method=inpaint_method)
-    return result, det.region
+def _gemini_mask(
+    image: NDArray[Any], *, force: bool = False, detection: MarkDetection | None = None
+) -> NDArray[Any] | None:
+    # Reuse the decision's provenance-aware region (skip the strict re-detect that would
+    # otherwise re-demote a relaxed sparkle to None); None region -> footprint_mask
+    # falls back to its own detect-then-force path (direct/--no-detect callers).
+    region = detection.region if (detection is not None and detection.detected) else None
+    return _engine("gemini").footprint_mask(image, force=force, region=region)
 
 
 # The three text-mark engines (Doubao/Jimeng/Samsung) share the TextMarkEngine
 # interface, so one parameterized adapter pair drives all of them -- a new
-# reverse-alpha text mark is one `_text_mark(...)` row below, not another copy-paste
-# of these bodies. Removal is reverse-alpha only: applied when the mark is detected
-# (or forced) and the alpha asset loads, otherwise skipped (no hallucination on a
-# clean corner).
-def _text_mark_detect(key: str, label: str, location: str) -> Callable[[NDArray[Any]], MarkDetection]:
-    def detect(image: NDArray[Any]) -> MarkDetection:
-        d = _engine(key).detect(image)
+# text mark is one `_text_mark(...)` row below, not another copy-paste of these
+# bodies. Detection matches the glyph silhouette; the mask is the template-free
+# glyph-bbox footprint (see TextMarkEngine.footprint_mask).
+def _text_mark_detect(key: str, label: str, location: str) -> Callable[..., MarkDetection]:
+    def detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
+        d = _engine(key).detect(image, provenance=provenance)
         return MarkDetection(key, label, location, d.detected, d.confidence, d.region)
 
     return detect
 
 
-def _text_mark_remove(key: str) -> Callable[..., tuple[NDArray[Any], Region | None]]:
-    def remove(
-        image: NDArray[Any], _inpaint_method: InpaintMethod, _inpaint: bool, _strength: float, force: bool
-    ) -> tuple[NDArray[Any], Region | None]:
-        engine = _engine(key)
-        det = engine.detect(image)
-        if (det.detected or force) and engine.reverse_alpha_available(image):
-            return engine.remove_watermark_reverse_alpha(image), (det.region if det.detected else None)
-        return image.copy(), None
+def _text_mark_mask(key: str) -> Callable[..., NDArray[Any] | None]:
+    def mask(
+        image: NDArray[Any], *, force: bool = False, detection: MarkDetection | None = None
+    ) -> NDArray[Any] | None:
+        # Text masks rebuild the glyph blob template-free (no trust gate to re-apply), so
+        # the detection is not needed here; accepted for the uniform _mask signature.
+        del detection
+        return _engine(key).footprint_mask(image, force=force)
 
-    return remove
+    return mask
 
 
 def _text_mark(key: str, label: str, location: str) -> KnownMark:
-    """A reverse-alpha text-mark registry row (Doubao/Jimeng/Samsung)."""
-    return KnownMark(
-        key, label, location, True, "reverse-alpha", _text_mark_detect(key, label, location), _text_mark_remove(key)
-    )
+    """A text-mark registry row (Doubao/Jimeng/Samsung): glyph-silhouette detect +
+    template-free glyph-bbox mask."""
+    return KnownMark(key, label, location, True, _text_mark_detect(key, label, location), _text_mark_mask(key))
 
 
-# ── Capture-less mark: the Jimeng-basic "AI生成" pill (top-left, inpaint-only) ──
-# No alpha map exists, so removal is inpaint only (has_capture=False routes every
-# method to inpaint). Detection is edge-NCC of a synthetic silhouette; see pill_engine.
-def _pill_detect(image: NDArray[Any]) -> MarkDetection:
+# ── Capture-less mark: the Jimeng-basic "AI生成" pill (top-left) ──
+# Detection is edge-NCC of a synthetic silhouette; the mask is a fixed top-left
+# geometry box (see pill_engine). Removal is the same localize -> fill as the rest.
+def _pill_detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
+    del provenance  # the pill detector is provenance-independent; its relaxation lives entirely in _keep_pill
     d = _engine("jimeng_pill").detect(image)
     return MarkDetection("jimeng_pill", "Jimeng AI生成 pill", "top-left", d.detected, d.confidence, d.region)
 
 
-def _pill_noop_remove(
-    image: NDArray[Any], _im: InpaintMethod, _ip: bool, _st: float, _force: bool
-) -> tuple[NDArray[Any], Region | None]:
-    # Capture-less: reverse-alpha is impossible. resolve_removal_method routes every
-    # method to inpaint (_inpaint_remove), so this reverse-alpha slot is never reached;
-    # return an untouched copy defensively.
-    return image.copy(), None
+def _pill_mask(
+    image: NDArray[Any], *, force: bool = False, detection: MarkDetection | None = None
+) -> NDArray[Any] | None:
+    # The pill mask is a fixed top-left geometry box, independent of the detection;
+    # accepted for the uniform _mask signature.
+    del detection
+    return _engine("jimeng_pill").footprint_mask(image, force=force)
+
+
+def _pill_features(image: NDArray[Any]) -> dict[str, float]:
+    """The pill's own gate feature: top-left footprint flatness (1.0 = flat enough for
+    an invisible fill), read by the metadata arm of :func:`_keep_pill`."""
+    return {"footprint_flat": float(_engine("jimeng_pill").footprint_is_flat(image))}
 
 
 _REGISTRY: tuple[KnownMark, ...] = (
-    KnownMark("gemini", "Google Gemini sparkle", "bottom-right", True, "reverse-alpha", _gemini_detect, _gemini_remove),
+    KnownMark("gemini", "Google Gemini sparkle", "bottom-right", True, _gemini_detect, _gemini_mask),
     _text_mark("doubao", "Doubao 豆包AI生成 text", "bottom-right"),
     _text_mark("jimeng", "Jimeng 即梦AI wordmark", "bottom-right"),
+    _text_mark("qwen", "Qwen 千问AI生成 text", "bottom-right"),
+    _text_mark("kling", "Kling 可灵AI 3.0 text", "bottom-right"),
     _text_mark("samsung", "Samsung Galaxy AI text", "bottom-left"),
-    KnownMark("jimeng_pill", "Jimeng AI生成 pill", "top-left", True, "inpaint", _pill_detect, _pill_noop_remove, False),
+    _text_mark("runninghub", "RunningHub AI生成 text", "top-left"),
+    _text_mark("baidu", "Baidu 百度 AI生成 text", "bottom-right"),
+    _text_mark("liblib", "LibLibAI wordmark", "bottom-center"),
+    KnownMark("jimeng_pill", "Jimeng AI生成 pill", "top-left", True, _pill_detect, _pill_mask, _pill_features),
 )
 
 
@@ -329,79 +560,151 @@ def get_mark(key: str) -> KnownMark:
     raise KeyError(key)
 
 
-def detect_marks(image: NDArray[Any], *, include_explicit: bool = True) -> list[MarkDetection]:
+def detect_marks(
+    image: NDArray[Any],
+    *,
+    include_explicit: bool = True,
+    provenance: frozenset[str] = frozenset(),
+) -> list[MarkDetection]:
     """Detect every known mark in its usual place.
 
     Returns one MarkDetection per scanned mark (``detected`` flags which fired).
     ``include_explicit=False`` scans only the ``in_auto`` marks -- the set used
-    by ``--mark auto``."""
-    return [m.detect(image) for m in _REGISTRY if include_explicit or m.in_auto]
+    by ``--mark auto``. ``provenance`` names the vendor keys that external metadata
+    already confirms, so each named mark's detector may relax its trust gate."""
+    return [m.detect(image, provenance=m.key in provenance) for m in _REGISTRY if include_explicit or m.in_auto]
 
 
-def best_auto_mark(image: NDArray[Any]) -> MarkDetection | None:
-    """The highest-confidence detected ``in_auto`` mark, or None if none fired."""
-    fired = [d for d in detect_marks(image, include_explicit=False) if d.detected]
-    return max(fired, key=lambda d: d.confidence) if fired else None
+def resolve_trust(
+    key: str,
+    *,
+    sensitivity: Sensitivity,
+    provenance: frozenset[str],
+    strict_keys: set[str],
+) -> Trust:
+    """The trust level mark ``key``'s detection gate is resolved to.
+
+    The single place that turns the ``sensitivity`` policy + evidence into a per-mark
+    level (which the engines consume as ``provenance = level != "strict"``). ``strict``
+    never relaxes. A mark is ``confirmed`` only on same-product evidence -- the vendor
+    confirmed by metadata (``key in provenance``) or a confidently strict-detected
+    sibling of the same product (``_PRODUCT_OF``, minus the marks too weak to vouch,
+    :data:`_CANNOT_CORROBORATE`). Without that evidence a mark stays ``strict``: there is
+    no path that relaxes a gate on anything less than same-product evidence."""
+    if sensitivity == "strict":
+        return "strict"
+    product = _PRODUCT_OF[key]
+    confirmed = key in provenance or any(
+        _PRODUCT_OF[k] == product for k in strict_keys if k != key and k not in _CANNOT_CORROBORATE
+    )
+    return "confirmed" if confirmed else "strict"
 
 
-def _keep_pill(image: NDArray[Any], keys: set[str], *, pill_metadata: bool) -> bool:
+def _keep_pill(keys: set[str], *, provenance: frozenset[str], footprint_flat: bool) -> bool:
     """Whether to auto-remove the capture-less 'AI生成' pill given the fired marks.
 
-    The pill detector is weak (~7% raw false-fire) and metadata confirms the platform,
-    not pill presence, so a naive metadata-OR-wordmark gate over-fires: on a 32k
-    real-upload corpus (2026-07) the metadata-only arm was only ~27% precise and its
-    false fires were textured ceilings/walls that inpaint visibly SMEARS. Two arms:
+    Pure decision (the flatness feature is precomputed at perception time and passed
+    in). The pill detector is weak (~7% raw false-fire) and metadata/intent confirms
+    the platform, not pill presence, so a naive confirmation-OR gate over-fires: on a
+    32k real-upload corpus (2026-07) the metadata-only arm was only ~27% precise and
+    its false fires were textured ceilings/walls that the fill visibly SMEARS. Arms:
       * bottom-right "★ 即梦AI" wordmark fired -> ~94% precise, and it survives
         metadata-STRIPPED uploads: remove the pill unrestricted;
-      * metadata only (TC260 AIGC, no wordmark) -> remove ONLY when the top-left
-        footprint is flat enough for an invisible inpaint (``footprint_is_flat``),
-        so real flat-scene pills (and harmless flat false fires) are cleaned while
-        the damaging textured false fires are left untouched.
+      * TC260 metadata confirms Jimeng (``"jimeng" in provenance``, no wordmark) -> remove ONLY when the
+        top-left footprint is flat enough for an invisible fill (``footprint_flat``),
+        so real flat-scene pills (and harmless flat false fires) are cleaned while the
+        damaging textured false fires are left untouched.
     A Doubao image is TC260 too but is not Jimeng-basic, so the pill never rides on a
-    Doubao detection. No confirmation at all -> never remove (blocks false fires on
-    non-Jimeng content)."""
-    if "doubao" in keys:
+    Doubao detection; a Qwen image likewise (another vendor's bottom-right mark naming
+    its own product), so a confident Qwen detection suppresses the pill the same way.
+    No confirmation at all -> never remove (blocks false fires on non-Jimeng content)."""
+    if "doubao" in keys or "qwen" in keys or "kling" in keys or "runninghub" in keys or "baidu" in keys:
         return False
     if "jimeng" in keys:
         return True
-    if pill_metadata:
-        return bool(_engine("jimeng_pill").footprint_is_flat(image))
+    if "jimeng" in provenance:
+        return footprint_flat
     return False
 
 
+def _build_candidates(image: NDArray[Any]) -> list[Candidate]:
+    """PERCEPTION pass: run every ``in_auto`` mark's detector at both trust levels and
+    package the raw verdicts + physical features into :class:`Candidate` objects. No
+    policy here -- the arbiter (:func:`decide`) makes every keep/drop call.
+
+    Each mark is detected at the strict AND the relaxed (``provenance=True``) level so
+    :func:`decide` can pick per mark without re-running detection; a relaxed gate is
+    monotonically more permissive, so this reproduces the old strict-then-relax pass
+    exactly. The loop is uniform -- it knows nothing about any specific mark: each mark
+    reports its own gate features via :meth:`KnownMark.features` (computed only when the
+    mark is detected, so a clean image pays nothing extra)."""
+    cands: list[Candidate] = []
+    for m in _REGISTRY:
+        if not m.in_auto:
+            continue
+        strict = m.detect(image, provenance=False)
+        relaxed = m.detect(image, provenance=True)
+        feats = m.features(image) if (strict.detected or relaxed.detected) else {}
+        cands.append(Candidate(m.key, m.label, strict.detected, relaxed.detected, feats))
+    return cands
+
+
+def decide(candidates: list[Candidate], context: Context) -> list[Decision]:
+    """The removal ARBITER: a pure function turning perception + context into the
+    ordered list of marks to remove (and the trust level each was accepted at).
+
+    All policy lives here, in one place: per-mark trust resolution (:func:`resolve_trust`,
+    which needs the strict-detected siblings for ``auto`` cross-mark corroboration) and
+    the capture-less pill gate (:func:`_keep_pill`). No image, no I/O -- so it is unit-testable in isolation and
+    the same decision drives every caller."""
+    strict_keys = {c.key for c in candidates if c.detected_strict}
+    fired: list[Decision] = []
+    for c in candidates:
+        trust = resolve_trust(
+            c.key, sensitivity=context.sensitivity, provenance=context.provenance, strict_keys=strict_keys
+        )
+        relax = trust != "strict"
+        ok = c.detected_relaxed if relax else c.detected_strict
+        if ok:
+            fired.append(Decision(c, relax))
+    keys = {d.candidate.key for d in fired}
+    if "jimeng_pill" in keys:
+        pill = next(d for d in fired if d.candidate.key == "jimeng_pill")
+        flat = bool(pill.candidate.features.get("footprint_flat", 0.0))
+        if not _keep_pill(keys, provenance=context.provenance, footprint_flat=flat):
+            fired = [d for d in fired if d.candidate.key != "jimeng_pill"]
+    return fired
+
+
 def remove_auto_marks(
     image: NDArray[Any],
     *,
-    pill_metadata: bool = False,
-    method: RemovalMethod = "auto",
-    inpaint_method: InpaintMethod = "ns",
-    inpaint: bool = True,
-    inpaint_strength: float = 0.85,
+    sensitivity: Sensitivity = "auto",
+    provenance: frozenset[str] = frozenset(),
+    backend: Backend = "auto",
 ) -> tuple[NDArray[Any], list[str]]:
-    """Remove EVERY detected ``in_auto`` mark in one pass, chaining the result.
+    """Remove EVERY decided ``in_auto`` mark in one pass, chaining the result.
 
-    Marks coexist in different corners -- a Jimeng-basic image carries BOTH the
-    top-left "AI生成" pill AND the bottom-right "★ 即梦AI" wordmark -- and their
-    confidences are on different scales, so ``best_auto_mark`` (single strongest)
-    would clean only one and leave the other (issue #54). Each mark re-detects at
-    its own corner on the progressively-cleaned image, so order does not matter.
+    The three stages are separated: PERCEPTION (:func:`_build_candidates` -- engines
+    report what they see, no policy), DECISION (:func:`decide` -- the pure arbiter over
+    ``(candidates, Context)``), ACTION (localize -> :func:`fill` per winner). Marks
+    coexist in different corners -- a Jimeng-basic image carries BOTH the top-left pill
+    AND the bottom-right wordmark -- so every decided mark is removed, chained on the
+    progressively-cleaned image (order does not matter, each re-localizes its corner).
 
-    The capture-less ``jimeng_pill`` has a weak edge-NCC detector (~7% raw
-    false-fire), so its removal is gated by ``_keep_pill`` (Jimeng-class confirmation
-    + a safe-inpaint check on the metadata-only arm; see that helper). Returns
-    ``(result, [labels removed])``; an empty list means nothing fired."""
-    fired = [d for d in detect_marks(image, include_explicit=False) if d.detected]
-    keys = {d.key for d in fired}
-    if "jimeng_pill" in keys and not _keep_pill(image, keys, pill_metadata=pill_metadata):
-        fired = [d for d in fired if d.key != "jimeng_pill"]
+    Three orthogonal knobs: ``sensitivity`` (how hard to trust a borderline mark --
+    see :data:`Sensitivity`), ``provenance`` (vendor keys external metadata confirms,
+    the evidence that drives ``auto``; the TC260 label maps to ``jimeng``/``doubao``),
+    and ``backend`` (the shared fill). Returns ``(result, [labels removed])``; empty
+    means nothing fired."""
+    context = Context(sensitivity=sensitivity, provenance=provenance)
     result = image
-    for det in fired:
-        result, _ = get_mark(det.key).remove(
-            result,
-            method=method,
-            inpaint_method=inpaint_method,
-            inpaint=inpaint,
-            inpaint_strength=inpaint_strength,
-            force=False,
-        )
-    return result, [d.label for d in fired]
+    labels: list[str] = []
+    for d in decide(_build_candidates(image), context):
+        result, region = get_mark(d.candidate.key).remove(result, backend=backend, provenance=d.relax, force=False)
+        # Only report the mark as removed when a fill actually happened: remove() returns
+        # a None region when the localized mask came back empty, and reporting it anyway
+        # would claim a removal that left the pixels unchanged.
+        if region is not None:
+            labels.append(d.candidate.label)
+    return result, labels

tests/test_api.py

@@ -0,0 +1,146 @@
+"""High-level convenience API (remove_visible / visible_provenance) and the lazy
+top-level re-exports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+import remove_ai_watermarks as raiw
+from remove_ai_watermarks import api
+
+SAMPLES = Path(__file__).resolve().parents[1] / "data" / "samples"
+DOUBAO = SAMPLES / "doubao-1.png"
+CHATGPT = SAMPLES / "chatgpt-1.png"
+
+
+class TestTopLevelExports:
+    def test_lazy_reexports_resolve(self):
+        assert raiw.remove_visible is api.remove_visible
+        assert raiw.visible_provenance is api.visible_provenance
+
+    def test_unknown_attribute_raises(self):
+        with pytest.raises(AttributeError):
+            _ = raiw.does_not_exist
+
+    def test_bare_import_is_light(self):
+        # importing the package must not pull the heavy cv2/torch stack (PEP 562 lazy).
+        # Checked in a FRESH interpreter -- another test in this process may already
+        # have imported cv2, so an in-process sys.modules check would be flaky.
+        import subprocess
+        import sys
+
+        code = "import remove_ai_watermarks, sys; print(int(any(m in sys.modules for m in ('cv2','torch'))))"
+        out = subprocess.run(  # noqa: S603  -- fixed sys.executable + literal code, no untrusted input
+            [sys.executable, "-c", code], check=True, capture_output=True, text=True
+        )
+        assert out.stdout.strip() == "0", f"bare import pulled a heavy module: {out.stdout!r}"
+
+
+class TestRemoveVisibleArray:
+    def test_array_no_mark_is_noop_copy(self):
+        arr = np.zeros((256, 256, 3), np.uint8)
+        result, removed = raiw.remove_visible(arr, backend="cv2")
+        assert removed == []
+        assert result.shape == arr.shape
+        assert np.array_equal(result, arr)
+
+    def test_array_accepts_knobs(self):
+        arr = np.zeros((256, 256, 3), np.uint8)
+        result, removed = raiw.remove_visible(arr, sensitivity="strict", backend="cv2")
+        assert removed == []
+        assert result.shape == arr.shape
+
+    def test_bad_source_raises(self, tmp_path):
+        with pytest.raises(ValueError, match="Could not read image"):
+            raiw.remove_visible(tmp_path / "nope.png")
+
+
+@pytest.mark.skipif(not DOUBAO.exists(), reason="doubao sample not present")
+class TestRemoveVisiblePath:
+    def test_path_removes_and_writes(self, tmp_path):
+        out = tmp_path / "clean.png"
+        result, removed = raiw.remove_visible(DOUBAO, out, backend="cv2")
+        assert out.exists()
+        assert any("Doubao" in lbl for lbl in removed)
+        assert result.shape[2] == 3
+
+    def test_path_no_output_returns_without_writing(self, tmp_path):
+        # output=None returns the array but writes nothing
+        result, _ = raiw.remove_visible(DOUBAO, backend="cv2")
+        assert result.ndim == 3
+
+
+class TestNoOpPreservesOriginal:
+    def test_no_mark_copies_original_bytes(self, tmp_path):
+        # A clean image (no mark) same-format-out must be copied VERBATIM, not
+        # re-encoded -- so a no-op never degrades the original ("work with originals").
+        import filecmp
+
+        from PIL import Image
+
+        src = tmp_path / "clean.jpg"
+        Image.fromarray(np.full((40, 40, 3), 120, np.uint8), "RGB").save(src, quality=90)
+        out = tmp_path / "clean_out.jpg"
+        _, removed = raiw.remove_visible(str(src), str(out), sensitivity="strict", backend="cv2")
+        assert removed == []
+        assert filecmp.cmp(str(src), str(out), shallow=False)  # byte-identical
+
+
+class TestVisibleProvenance:
+    @pytest.mark.skipif(not DOUBAO.exists(), reason="doubao sample not present")
+    def test_doubao_tc260_maps_to_bytedance(self):
+        prov = raiw.visible_provenance(DOUBAO)
+        # TC260 label -> ByteDance family (both doubao and jimeng)
+        assert {"doubao", "jimeng"} <= prov
+
+    @pytest.mark.skipif(not CHATGPT.exists(), reason="chatgpt sample not present")
+    def test_openai_image_has_no_visible_vendor(self):
+        # OpenAI C2PA is not one of the visible-mark vendors -> empty provenance
+        assert raiw.visible_provenance(CHATGPT) == frozenset()
+
+    def test_unreadable_path_is_empty(self, tmp_path):
+        assert raiw.visible_provenance(tmp_path / "missing.png") == frozenset()
+
+    def test_uses_report_signals_for_falsy_metadata_values(self, monkeypatch, tmp_path):
+        """An empty TC260 object and Samsung genAIType=0 are still present signals.
+
+        The report has already normalized those values, so the public API must not
+        re-read the file and accidentally discard them by truthiness.
+        """
+        from types import SimpleNamespace
+
+        from remove_ai_watermarks import identify
+
+        report = SimpleNamespace(
+            platform=None,
+            signals=[SimpleNamespace(name="aigc"), SimpleNamespace(name="samsung_genai")],
+        )
+        monkeypatch.setattr(identify, "identify", lambda *args, **kwargs: report)
+
+        assert raiw.visible_provenance(tmp_path / "synthetic.png") == frozenset({"doubao", "jimeng", "samsung"})
+
+
+class TestRemoveVisibleOutputPath:
+    """Output-path robustness: in-place clean (#3) and a missing output dir (#4)."""
+
+    def _write_clean(self, p: Path) -> None:
+        from remove_ai_watermarks import image_io
+
+        image_io.imwrite(str(p), np.full((128, 128, 3), 200, np.uint8))
+
+    def test_inplace_clean_no_crash(self, tmp_path: Path):
+        p = tmp_path / "clean.png"
+        self._write_clean(p)
+        _, removed = raiw.remove_visible(str(p), str(p), backend="cv2")
+        assert removed == []
+        assert p.exists()
+
+    def test_creates_missing_output_dir(self, tmp_path: Path):
+        src = tmp_path / "in.png"
+        self._write_clean(src)
+        out = tmp_path / "sub" / "out.png"
+        raiw.remove_visible(str(src), str(out), backend="cv2")
+        assert out.exists()

tests/test_baidu_engine.py

@@ -0,0 +1,133 @@
+"""Tests for the Baidu ("百度 AI生成") visible-watermark engine.
+
+Every tuned constant in ``baidu_engine`` was measured on the 16-frame vendor
+cohort (2026-07-22); these tests pin the load-bearing ones: detection keys on
+the 百度 text run ONLY (the text+pill template was a measured bright-blob
+magnet), the load-bearing Doubao rival margin, the strict-only gate, and the
+corner-extended footprint (the tag's flat white interior gives no top-hat
+response, so a blob-bbox mask leaves the tag as a ghost).
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from remove_ai_watermarks import watermark_registry as registry
+from remove_ai_watermarks.baidu_engine import (
+    _ALPHA_HEIGHT_FRAC,
+    _ALPHA_WIDTH_FRAC,
+    BaiduEngine,
+    _alpha_template,
+)
+
+_TEXT_FRAC = 0.090  # measured 百度 text-run width, fraction of the short side
+_TEXT_RIGHT = 0.099  # measured right margin of the text run (the tag is right of it)
+_TAG_FRAC = 0.075  # the white tag's width, approx (text-right to corner)
+
+
+def _compose(w: int, h: int, bg: float = 100.0):
+    """Composite the 百度 text run + a solid white tag at the measured layout."""
+    img = np.full((h, w, 3), bg, np.float32)
+    at = _alpha_template()
+    short = min(w, h)
+    gw = int(_TEXT_FRAC * short)
+    gh = max(4, int(_TEXT_FRAC * (_ALPHA_HEIGHT_FRAC / _ALPHA_WIDTH_FRAC) * short))
+    margin_b = int(0.006 * short)
+    ax = w - int(_TEXT_RIGHT * short) - gw
+    ay = h - margin_b - gh
+    amap = np.zeros((h, w), np.float32)
+    amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+    # the white rounded tag between the text and the corner
+    tx0 = w - int(0.015 * short) - int(_TAG_FRAC * short)
+    amap[ay - gh // 8 : ay + gh + gh // 8, tx0 : w - int(0.015 * short)] = 1.0
+    a3 = amap[:, :, None]
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return wm, (ax, ay, gw, gh, tx0)
+
+
+class TestLocate:
+    def test_box_anchored_bottom_right(self):
+        eng = BaiduEngine()
+        img = np.zeros((2048, 2048, 3), np.uint8)
+        loc = eng.locate(img)
+        assert 2048 - (loc.x + loc.w) < 40
+        assert 2048 - (loc.y + loc.h) < 40
+
+    def test_box_scales_with_short_side(self):
+        eng = BaiduEngine()
+        landscape = eng.locate(np.zeros((640, 1280, 3), np.uint8))
+        wider = eng.locate(np.zeros((640, 2560, 3), np.uint8))
+        assert wider.w == landscape.w
+
+
+class TestConfig:
+    def test_tophat_frontend(self):
+        assert BaiduEngine().config.detect_frontend == "tophat"
+
+    def test_doubao_rival_margin(self):
+        # 百度 vs 豆包 share a glyph and a corner: the candidate fires on 45.8% of
+        # Doubao-marked frames at the gate, and the 0.10 margin suppresses ALL of
+        # it at zero genuine-detection cost (crossfire, 2026-07-22).
+        assert "doubao_alpha.png" in BaiduEngine().config.rivals
+
+    def test_strict_only_no_provenance_relaxation(self):
+        assert BaiduEngine().config.provenance_ncc_factor == 1.0
+
+    def test_gate_above_clean_arm_max(self):
+        # Clean arm scored p99 0.314 / max 0.352 on 278 hand-labelled frames;
+        # the 741-frame eval set surfaced cross-fires up to 0.426 (a 抖音
+        # AI创作 mark no rival can suppress), and the full-corpus sweep put the
+        # outside-cohort false arm at 0.47 max vs true carriers at 0.50-0.66,
+        # so the gate sits at 0.48.
+        assert BaiduEngine().config.detect_ncc_threshold >= 0.48
+
+    def test_qwen_is_a_rival(self):
+        # 百度 vs 千问 are near-identical after binarization: 12 of 14 full-corpus
+        # cross-fires at the 0.37 gate were Qwen marks (Qwen's template beats
+        # Baidu's there by 0.17-0.35, so the margin suppresses them).
+        assert "qwen_alpha.png" in BaiduEngine().config.rivals
+
+    def test_registry_row(self):
+        mark = registry.get_mark("baidu")
+        assert mark.location == "bottom-right"
+        assert mark.in_auto
+
+
+class TestDetectAndMask:
+    def test_detects_composed_mark(self):
+        eng = BaiduEngine()
+        wm, _ = _compose(1024, 1024)
+        det = eng.detect(wm)
+        assert det.detected, f"composed mark missed (conf={det.confidence:.3f})"
+
+    def test_clean_frame_stays_quiet(self):
+        eng = BaiduEngine()
+        img = np.full((1024, 1024, 3), 100, np.uint8)
+        assert not eng.detect(img).detected
+
+    def test_mask_extends_to_the_corner_tag(self):
+        """Regression (2026-07-22): the tag's flat white interior gives no top-hat
+        response, so a blob-bbox mask ended at the text run and the fill left the
+        tag as a ghost. The footprint must extend right to the corner."""
+        eng = BaiduEngine()
+        wm, (ax, _ay, gw, _gh, tx0) = _compose(1024, 1024)
+        mask = eng.footprint_mask(wm)
+        assert mask is not None
+        _ys, xs = np.where(mask > 0)
+        assert xs.min() <= ax + int(0.1 * gw)  # covers the text run's left edge
+        assert xs.max() >= tx0 + 10  # covers the white tag right of the text
+
+    def test_no_mask_on_clean_frame(self):
+        eng = BaiduEngine()
+        img = np.full((1024, 1024, 3), 100, np.uint8)
+        assert eng.footprint_mask(img) is None
+
+
+class TestPillInteraction:
+    def test_confident_baidu_detection_suppresses_the_jimeng_pill(self):
+        # A Baidu image is TC260 too but is not Jimeng-basic: like Doubao/Qwen/
+        # Kling, a confident Baidu detection must veto the pill (``_keep_pill``).
+        from remove_ai_watermarks.watermark_registry import _keep_pill
+
+        assert not _keep_pill({"baidu"}, provenance=frozenset({"jimeng"}), footprint_flat=1.0)

tests/test_cli.py

@@ -172,7 +172,9 @@ class TestVisibleCommand:
         expected = sample_png.with_stem(sample_png.stem + "_clean")
         assert expected.exists()
 
-    def test_visible_no_inpaint(self, runner, sample_png, tmp_path):
+    def test_visible_backend_cv2(self, runner, sample_png, tmp_path):
+        # The old --inpaint/--no-inpaint flags are gone; the fill backend is picked
+        # with --backend (localize -> fill). cv2 needs no ONNX model.
         output = tmp_path / "clean.png"
         result = runner.invoke(
             main,
@@ -181,7 +183,8 @@ class TestVisibleCommand:
                 str(sample_png),
                 "-o",
                 str(output),
-                "--no-inpaint",
+                "--backend",
+                "cv2",
                 "--no-detect",
             ],
         )
@@ -570,6 +573,41 @@ class TestMetadataCommand:
         assert result.exit_code == 0
         assert "stripped" in result.output
 
+    def test_metadata_remove_reports_failure_when_the_strip_was_a_no_op(self, runner, tmp_path):
+        """A file PIL cannot decode is copied through UNCHANGED by the fail-safe.
+
+        That is correct (never crash a worker on a partial upload) but the command used
+        to print "AI metadata stripped ->" and exit 0 for it, so a caller could not tell
+        a real strip from a no-op and the output still read as AI. Found on real Samsung
+        Galaxy S22 C2PA PNGs during the corpus parity audit, 2026-07-19.
+        """
+        # PNG signature + a C2PA (caBX) chunk, then garbage: the byte scanner sees the
+        # marker, PIL cannot decode it.
+        src = tmp_path / "undecodable.png"
+        payload = b"c2pa" + b"\x00" * 32
+        chunk = len(payload).to_bytes(4, "big") + b"caBX" + payload + b"\x00\x00\x00\x00"
+        src.write_bytes(b"\x89PNG\r\n\x1a\n" + chunk + b"NOTAPNG" * 8)
+        out = tmp_path / "cleaned.png"
+
+        result = runner.invoke(main, ["metadata", str(src), "--remove", "-o", str(out)])
+
+        from remove_ai_watermarks.metadata import get_ai_metadata
+
+        if not get_ai_metadata(src):
+            pytest.skip("fixture does not register as an AI-metadata carrier")
+        assert result.exit_code != 0, "a no-op strip must not report success"
+        assert "stripped ->" not in result.output
+
+    def test_metadata_remove_in_place(self, runner, tmp_png_with_ai_metadata):
+        """With ``-o`` omitted, the strip overwrites the source in place (default
+        output_path=None). Previously every test passed an explicit ``-o``."""
+        from remove_ai_watermarks.metadata import has_ai_metadata
+
+        assert has_ai_metadata(tmp_png_with_ai_metadata)  # precondition
+        result = runner.invoke(main, ["metadata", str(tmp_png_with_ai_metadata), "--remove"])
+        assert result.exit_code == 0, result.output
+        assert not has_ai_metadata(tmp_png_with_ai_metadata)  # source overwritten, AI metadata gone
+
 
 class TestIdentifyCommand:
     """Tests for the 'identify' subcommand."""
@@ -597,6 +635,18 @@ class TestIdentifyCommand:
         assert "AI-generated" in result.output
         assert "Stable Diffusion" in result.output
 
+    def test_identify_reports_generated_source_kind(self, runner):
+        """The C2PA trainedAlgorithmicMedia source type sharpens the verdict to
+        'AI-generated (fully synthetic)' at the CLI (the ai_source_kind branch)."""
+        from pathlib import Path
+
+        sample = Path(__file__).resolve().parent.parent / "data" / "samples" / "chatgpt-1.png"
+        if not sample.exists():
+            pytest.skip("chatgpt sample not present")
+        result = runner.invoke(main, ["identify", str(sample), "--no-visible"])
+        assert result.exit_code == 0
+        assert "AI-generated (fully synthetic)" in result.output
+
     def test_identify_json_is_valid(self, runner, tmp_png_with_ai_metadata):
         result = runner.invoke(main, ["identify", str(tmp_png_with_ai_metadata), "--no-visible", "--json"])
         assert result.exit_code == 0
@@ -771,6 +821,34 @@ class TestBatchCommand:
         expected_dir = tmp_path / "input_clean"
         assert expected_dir.exists()
 
+    def test_batch_errors_exit_nonzero(self, runner, tmp_path):
+        """Regression: batch used to always exit 0 even when every image errored,
+        hiding failure from a wrapping service. A corrupt image must yield a non-zero
+        exit and an error count."""
+        input_dir = tmp_path / "input"
+        input_dir.mkdir()
+        (input_dir / "corrupt.png").write_bytes(b"this is not a PNG at all" * 50)
+        result = runner.invoke(main, ["batch", str(input_dir), "--mode", "visible"])
+        assert result.exit_code != 0, result.output
+        assert "error" in result.output.lower()
+
+    def test_batch_invisible_gpu_missing_writes_output_and_exits_nonzero(self, runner, tmp_path):
+        """Regression: batch --mode invisible with a signal-bearing image but no GPU
+        deps used to write NO output for that image and still exit 0, silently dropping
+        the files that most needed processing. It must now copy the input through (so the
+        output dir is complete), warn about the retained SynthID watermark, and exit
+        non-zero -- mirroring the single ``all`` command."""
+        input_dir = _make_batch_dir_with_metadata(tmp_path, count=3)  # SD params = invisible signal
+        output_dir = tmp_path / "output"
+        with patch("remove_ai_watermarks.invisible_engine.is_available", return_value=False):
+            result = runner.invoke(
+                main,
+                ["batch", str(input_dir), "-o", str(output_dir), "--mode", "invisible"],
+            )
+        assert result.exit_code != 0, result.output
+        assert "NOT removed" in result.output
+        assert len(list(output_dir.glob("*.png"))) == 3  # every input copied through, none dropped
+
 
 class TestGpuHintMarkup:
     """The GPU-extra install hint must reach the user with the ``[gpu]`` token
@@ -863,3 +941,54 @@ class TestEraseCommand:
         assert result.exit_code != 0
         assert "onnxruntime" in result.output.lower()
         assert not output.exists()
+
+
+def test_visible_backend_runtime_error_exits_cleanly(runner, tmp_path, monkeypatch):
+    # A backend whose extra is missing raises RuntimeError in region_eraser.erase;
+    # the visible --mark auto path must surface it cleanly, not as a raw traceback (#9).
+    from pathlib import Path
+
+    from remove_ai_watermarks import region_eraser
+
+    doubao = Path(__file__).resolve().parent.parent / "data" / "samples" / "doubao-1.png"
+    if not doubao.exists():
+        pytest.skip("doubao sample not present")
+
+    def boom(*_a, **_k):
+        raise RuntimeError("MI-GAN backend requires onnxruntime. Install the extra: ...")
+
+    monkeypatch.setattr(region_eraser, "erase", boom)
+    out = tmp_path / "out.png"
+    result = runner.invoke(main, ["visible", str(doubao), "-o", str(out), "--backend", "migan"])
+    assert result.exit_code == 1
+    assert not isinstance(result.exception, RuntimeError), "RuntimeError leaked as a traceback"
+
+
+@pytest.mark.parametrize(
+    ("name", "content"),
+    [
+        ("empty.png", b""),
+        ("notimage.jpg", b"plain text, not an image at all " * 20),
+        ("truncated.png", b"\x89PNG\r\n\x1a\n" + b"\x00" * 40),
+    ],
+)
+@pytest.mark.parametrize("cmd", [["metadata", "--remove"], ["visible", "--backend", "cv2"]])
+def test_unreadable_input_exits_cleanly(runner, tmp_path, name, content, cmd):
+    """Regression: a corrupt / empty / non-image file (real prod uploads include ~0.2%
+    truncated files) must NEVER leak a raw PIL/OSError/ValueError traceback. `metadata
+    --remove` is fail-safe -- an undecodable file is copied through unchanged (exit 0),
+    a strip that cannot parse the file is a no-op, not a crash; `visible` must decode to
+    remove a mark, so it is a clean error (exit 1). Found by the runtime mode fuzz."""
+    bad = tmp_path / name
+    bad.write_bytes(content)
+    out = tmp_path / "out.png"
+    result = runner.invoke(main, [cmd[0], str(bad), "-o", str(out), *cmd[1:]])
+    assert result.exception is None or isinstance(result.exception, SystemExit), (
+        f"leaked a raw traceback: {result.exception!r}"
+    )
+    if cmd[0] == "metadata":
+        assert result.exit_code == 0, result.output  # fail-safe copy-through
+        assert out.read_bytes() == content  # input passed through unchanged
+    else:
+        assert result.exit_code == 1, result.output  # cannot remove a mark from unreadable input
+        assert "Error" in result.output

tests/test_cli_robustness.py

@@ -0,0 +1,114 @@
+"""A failed write and a directory input must REPORT, not raise a traceback.
+
+Both found 2026-07-20 by the Tier E adversarial sweep (`scripts/robustness_suite.py`),
+which drives the real CLI over degenerate inputs. Neither was reachable from the 849-test
+suite, because unit tests feed well-formed fixtures into writable directories.
+
+1. READ-ONLY OUTPUT DIRECTORY. `image_io.imwrite` is contractually non-raising -- it
+   returns False when the codec rejects the image or the path cannot be written. But
+   `write_bgr_with_alpha` discarded that bool and returned None, so no caller could tell a
+   failed write from a successful one. `cmd_erase` then ran `output.stat()` on a file that
+   was never created and died with `FileNotFoundError`. The signal existed the whole way
+   down and was thrown away by the wrapper.
+
+2. A DIRECTORY PASSED WHERE A FILE IS EXPECTED. `click.Path(exists=True)` accepts
+   directories unless told otherwise, so `identify <dir>` reached the metadata scanner and
+   raised `IsADirectoryError` from `open()`. (`batch` was already correct: it declares
+   `file_okay=False`.)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from click.testing import CliRunner
+
+from remove_ai_watermarks import image_io
+from remove_ai_watermarks.cli import main
+
+
+@pytest.fixture
+def bgr() -> np.ndarray:
+    return np.full((60, 80, 3), 128, np.uint8)
+
+
+class TestFailedWriteIsReported:
+    def test_write_bgr_with_alpha_reports_failure(self, tmp_path, bgr):
+        """The wrapper must PROPAGATE imwrite's failure signal, not swallow it.
+
+        Uses a nonexistent directory rather than `chmod`: CI runs windows-latest, where
+        `os.chmod` cannot make a DIRECTORY unwritable, so a chmod-based assertion would be
+        a platform-dependent flake. `write_bgr_with_alpha` does no mkdir of its own, so a
+        missing parent is a genuine write failure on every platform.
+        """
+        assert image_io.write_bgr_with_alpha(tmp_path / "no-such-dir" / "x.png", bgr, None) is False
+
+    def test_write_bgr_with_alpha_reports_success(self, tmp_path, bgr):
+        """The other direction, so the assertion above cannot pass by always being False."""
+        assert image_io.write_bgr_with_alpha(tmp_path / "ok.png", bgr, None) is True
+
+    def test_erase_reports_a_failed_write_without_a_traceback(self, tmp_path, bgr, monkeypatch):
+        """The CLI must exit non-zero with a readable message, not raise FileNotFoundError.
+
+        The write is forced to fail by patching, not by `chmod`: the CLI mkdirs the parent,
+        so a missing directory would not reproduce it, and chmod on a directory is a no-op
+        on Windows. Patching states the condition under test directly -- "the write failed".
+        """
+        src = tmp_path / "in.png"
+        image_io.imwrite(src, bgr)
+        monkeypatch.setattr(image_io, "write_bgr_with_alpha", lambda *a, **k: False)
+        result = CliRunner().invoke(main, ["erase", str(src), "--region", "5,5,20,10", "-o", str(tmp_path / "x.png")])
+        assert result.exit_code != 0
+        assert not isinstance(result.exception, FileNotFoundError), "write failure escaped as a traceback"
+        assert "write" in result.output.lower() or "failed" in result.output.lower()
+
+    def test_batch_counts_a_failed_write_instead_of_exiting_zero(self, tmp_path, bgr, monkeypatch):
+        """The worst shape of this bug: no output files AND a success exit code.
+
+        Corpus-reproduced 2026-07-20 -- `batch --mode visible` into a read-only directory
+        wrote ZERO files for 2 inputs and exited 0, so a wrapping service would treat an
+        empty output directory as a completed run. The batch loop counts per-image
+        exceptions, so the write must RAISE there, never `SystemExit` (which would abort
+        the whole run instead of failing one image).
+        """
+        indir = tmp_path / "in"
+        indir.mkdir()
+        for i in range(2):
+            image_io.imwrite(indir / f"img{i}.png", bgr)
+        monkeypatch.setattr(image_io, "write_bgr_with_alpha", lambda *a, **k: False)
+        result = CliRunner().invoke(main, ["batch", str(indir), "-o", str(tmp_path / "out"), "--mode", "visible"])
+        assert result.exit_code != 0, "a batch that wrote nothing must not exit 0"
+
+
+class TestApiReportsFailedWrite:
+    """The same bug lived one layer down, in the library API, with a misleading message.
+
+    `api._write_visible_result` also discarded the write flag, then ran the metadata strip
+    on a file that was never created. The resulting `FileNotFoundError` surfaced through
+    the CLI as `cannot read image <INPUT>: ... <OUTPUT path>` -- it blamed the input while
+    quoting the output. A library caller got the same confusing error with no CLI at all.
+    """
+
+    def test_remove_visible_raises_a_clear_error_on_unwritable_output(self, tmp_path, bgr, monkeypatch):
+        """Patched rather than chmod'd: `_write_visible_result` mkdirs the parent, so a
+        missing directory would not reproduce it, and chmod on a directory is a no-op on
+        the Windows CI runner."""
+        from remove_ai_watermarks.api import remove_visible
+
+        monkeypatch.setattr(image_io, "write_bgr_with_alpha", lambda *a, **k: False)
+        with pytest.raises(OSError, match="failed to write output"):
+            remove_visible(bgr, tmp_path / "out.png", strip_metadata=False)
+
+
+class TestDirectoryInputIsRejected:
+    @pytest.mark.parametrize("cmd", ["identify", "visible", "erase", "metadata", "invisible", "all"])
+    def test_directory_as_source_is_a_clean_usage_error(self, tmp_path, cmd):
+        """A directory must be refused by argument parsing, never reach the scanners."""
+        args = [cmd, str(tmp_path)]
+        if cmd == "erase":
+            args += ["--region", "1,1,5,5"]
+        if cmd == "metadata":
+            args += ["--check"]
+        result = CliRunner().invoke(main, args)
+        assert result.exit_code != 0
+        assert not isinstance(result.exception, IsADirectoryError), "directory reached the file reader"

tests/test_doubao_engine.py

@@ -1,4 +1,4 @@
-"""Tests for the Doubao visible-watermark engine (reverse-alpha only)."""
+"""Tests for the Doubao visible-watermark engine (localize -> fill)."""
 
 from __future__ import annotations
 
@@ -8,11 +8,9 @@ import cv2
 import numpy as np
 import pytest
 
+from remove_ai_watermarks import watermark_registry as registry
 from remove_ai_watermarks.doubao_engine import (
     _ALPHA_HEIGHT_FRAC,
-    _ALPHA_LOGO_BGR,
-    _ALPHA_MARGIN_BOTTOM_FRAC,
-    _ALPHA_MARGIN_RIGHT_FRAC,
     _ALPHA_NATIVE_WIDTH,
     _ALPHA_WIDTH_FRAC,
     DETECT_NCC_THRESHOLD,
@@ -26,6 +24,22 @@ from remove_ai_watermarks.doubao_engine import (
 SAMPLE = Path(__file__).resolve().parents[1] / "data" / "samples" / "doubao-1.png"
 
 
+def _compose(w: int, h: int, bg: float = 100.0):
+    """Composite the real alpha (scaled to width ``w``) onto a flat bg.
+    Returns ``(watermarked_uint8, mark_bool_mask)``."""
+    img = np.full((h, w, 3), bg, np.float32)
+    at = _alpha_template()
+    gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
+    margin = int(0.015 * w)
+    ax = w - margin - gw
+    ay = h - margin - gh
+    amap = np.zeros((h, w), np.float32)
+    amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+    a3 = amap[:, :, None]
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return wm, amap > 0.2
+
+
 class TestLocate:
     def test_box_anchored_bottom_right(self):
         eng = DoubaoEngine()
@@ -81,15 +95,7 @@ class TestDetect:
         the CJK silhouette (2026-06-26 FP: a 48x48 app-icon chevron scored 0.41). The
         size guard suppresses detection there. Bracket it: a real mark is detected at
         native size, but the same content downscaled below the guard is not."""
-        w = h = _ALPHA_NATIVE_WIDTH
-        at = _alpha_template()
-        gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-        ax = w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw
-        ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh
-        amap = np.zeros((h, w), np.float32)
-        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
-        a3 = amap[:, :, None]
-        wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * 100.0).clip(0, 255).astype(np.uint8)
+        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
         eng = DoubaoEngine()
         assert eng.detect(wm).detected  # native: real mark detected
         assert not eng.detect(cv2.resize(wm, (150, 150))).detected  # below guard: suppressed
@@ -102,25 +108,25 @@ class TestRealSample:
         assert det.detected
         assert det.confidence >= DETECT_NCC_THRESHOLD
 
-    def test_reverse_alpha_removes_mark(self):
-        eng = DoubaoEngine()
+    def test_fill_lowers_confidence(self):
         img = load_image_bgr(SAMPLE)
-        assert eng.reverse_alpha_available(img)  # sample is at the captured width
-        out = eng.remove_watermark_reverse_alpha(img)
-        assert not eng.detect(out).detected  # mark gone after recovery
+        before = DoubaoEngine().detect(img)
+        assert before.detected
+        out, region = registry.get_mark("doubao").remove(img, backend="cv2")
+        assert region is not None
+        assert DoubaoEngine().detect(out).confidence < before.confidence
 
     def test_far_region_untouched(self):
-        eng = DoubaoEngine()
         img = load_image_bgr(SAMPLE)
-        out = eng.remove_watermark_reverse_alpha(img)
+        out, _ = registry.get_mark("doubao").remove(img, backend="cv2")
         h, w = img.shape[:2]
         assert np.array_equal(img[: h // 2, : w // 2], out[: h // 2, : w // 2])
 
 
-# ── Reverse-alpha (exact recovery) ──────────────────────────────────
+# ── Alpha asset + footprint mask + localize -> fill removal ─────────
 
 
-class TestReverseAlpha:
+class TestAlphaAsset:
     def test_alpha_asset_loads(self):
         at = _alpha_template()
         assert at is not None
@@ -128,104 +134,90 @@ class TestReverseAlpha:
         assert float(at.min()) >= 0.0
         assert float(at.max()) <= 1.0
 
-    def test_available_whenever_asset_present(self):
-        # NCC alignment generalizes to any resolution, so availability is just
-        # "asset loadable" (any non-empty image); the caller gates on detect.
-        eng = DoubaoEngine()
-        assert eng.reverse_alpha_available(np.zeros((1024, 1024, 3), np.uint8))
-        assert eng.reverse_alpha_available(np.zeros((1773, 1535, 3), np.uint8))
-        assert not eng.reverse_alpha_available(np.zeros((0, 0, 3), np.uint8))
 
-    @staticmethod
-    def _compose(w: int, h: int, bg: float = 100.0):
-        """Composite the real alpha (scaled to width ``w``) onto a flat bg.
-        Returns ``(watermarked_uint8, mark_bool_mask)``."""
-        img = np.full((h, w, 3), bg, np.float32)
-        at = _alpha_template()
-        gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-        ax = w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw
-        ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh
-        amap = np.zeros((h, w), np.float32)
-        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
-        a3 = amap[:, :, None]
-        wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * img).clip(0, 255).astype(np.uint8)
-        return wm, amap > 0.2
+class TestFootprintMaskAndRemoval:
+    def test_footprint_mask_in_bottom_right(self):
+        """A composed mark yields a footprint mask localized to the bottom-right."""
+        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
+        mask = DoubaoEngine().footprint_mask(wm)
+        assert mask is not None
+        assert mask.shape == wm.shape[:2]
+        ys, xs = np.where(mask > 0)
+        assert ys.mean() > wm.shape[0] / 2
+        assert xs.mean() > wm.shape[1] / 2
 
     def test_removes_synthetic_mark(self):
-        """Reverse-alpha + thin residual inpaint clears a mark composed from the
-        real alpha (re-detect no longer fires)."""
-        eng = DoubaoEngine()
-        wm, _mark = self._compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
-        assert eng.detect(wm).detected
-        out = eng.remove_watermark_reverse_alpha(wm)
-        assert not eng.detect(out).detected
+        """localize -> cv2 fill clears a mark composed from the real alpha
+        (re-detect no longer fires)."""
+        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
+        assert DoubaoEngine().detect(wm).detected
+        out, region = registry.get_mark("doubao").remove(wm, backend="cv2")
+        assert region is not None
+        assert not DoubaoEngine().detect(out).detected
 
     @pytest.mark.parametrize(
-        ("w", "h", "max_err"),
+        ("w", "h"),
         [
-            (_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH, 5.0),  # captured width
-            (1773, 2364, 8.0),  # 3:4 portrait -> NCC alignment generalizes the single capture
+            (_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH),  # captured width
+            (1773, 2364),  # 3:4 portrait -> template-free footprint generalizes
         ],
     )
-    def test_recovers_flat_background(self, w, h, max_err):
-        """Recovers the flat background at the captured width AND a non-native
-        resolution (NCC alignment generalizes the single capture)."""
-        eng = DoubaoEngine()
-        wm, mark = self._compose(w, h)
+    def test_fill_removes_and_leaves_far_region(self, w, h):
+        """The fill lowers re-detect confidence and leaves the far corner exact."""
+        wm, mark = _compose(w, h)
         assert float(np.abs(wm.astype(np.float32)[mark] - 100.0).mean()) > 15  # mark visible
-        out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-        assert float(np.abs(out[mark] - 100.0).mean()) < max_err
-
-    @staticmethod
-    def _textured_bg(w: int, h: int):
-        yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
-        base = 120 + 40 * np.sin(xx / 90.0) + 30 * np.cos(yy / 70.0)
-        return np.clip(np.stack([base, base * 0.95, base * 1.05], axis=-1), 0, 255)
-
-    def test_recovers_shifted_mark_on_texture(self):
-        """A real mark is re-rasterized a few px off its fixed slot, so removal
-        must NCC-align to it. Regression guard for the issue-#13 follow-up defect:
-        a too-tight locate box let a corner-ward shift fall outside the alignment
-        search, leaving a readable outline that the detector did not flag. Composes
-        the real alpha SHIFTED on a known texture and asserts the texture is
-        recovered (a misaligned removal would leave the bright glyph outline)."""
-        eng = DoubaoEngine()
-        w = h = _ALPHA_NATIVE_WIDTH
-        at = _alpha_template()
-        gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-        ax = w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw + 12  # shift toward the corner
-        ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh + 8
-        amap = np.zeros((h, w), np.float32)
-        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
-        a3 = amap[:, :, None]
-        bg = self._textured_bg(w, h)
-        wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * bg).clip(0, 255).astype(np.uint8)
-        mark = amap > 0.15
-        assert float(np.abs(wm.astype(np.float32)[mark] - bg[mark]).mean()) > 30  # mark clearly visible
-        out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-        assert float(np.abs(out[mark] - bg[mark]).mean()) < 8.0  # texture recovered, no outline
+        before = DoubaoEngine().detect(wm)
+        out, _ = registry.get_mark("doubao").remove(wm, backend="cv2")
+        assert DoubaoEngine().detect(out).confidence < before.confidence
+        assert np.array_equal(out[: h // 2, : w // 2], wm[: h // 2, : w // 2])
 
 
 class TestDegenerateAndChannelInputs:
-    """Removal must not crash on degenerate sizes or non-3-channel inputs."""
+    """footprint_mask must not crash on degenerate sizes or non-3-channel inputs."""
 
     @pytest.mark.parametrize(("w", "h"), [(2048, 1), (1, 2048), (2048, 8)])
     def test_wide_short_does_not_raise(self, w, h):
         """A wide/short image at native width makes the width-derived glyph box
-        taller than the image; the slice assignment must not ValueError."""
+        taller than the image; masking must not ValueError."""
         eng = DoubaoEngine()
         img = np.zeros((h, w, 3), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(img)
-        assert out.shape == img.shape
+        mask = eng.footprint_mask(img, force=True)
+        assert mask is None or mask.shape == (h, w)
 
     def test_grayscale_2d_does_not_raise(self):
         eng = DoubaoEngine()
         gray = np.zeros((2048, 2048), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(gray)
-        assert out.shape == (2048, 2048, 3)
+        mask = eng.footprint_mask(gray, force=True)
+        assert mask is None or mask.shape == (2048, 2048)
 
     def test_bgra_4channel_does_not_raise(self):
         eng = DoubaoEngine()
         bgra = np.zeros((2048, 2048, 4), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(bgra)
-        assert out.shape == (2048, 2048, 3)
+        mask = eng.footprint_mask(bgra, force=True)
+        assert mask is None or mask.shape == (2048, 2048)
+
+    def test_template_match_score_guards_return_zero(self):
+        # Guards return 0.0 (never a false positive) for a mask that cannot hold a
+        # glyph: empty, narrower than min_gw, or shorter than the 4-px floor.
+        assert _template_match_score(np.zeros((0, 5), np.uint8), 1000) == 0.0
+        assert _template_match_score(np.zeros((10, 3), np.uint8), 1000) == 0.0  # width-1 < min_gw
+        assert _template_match_score(np.zeros((3, 200), np.uint8), 1000) == 0.0  # height-1 < 4
+
+    @pytest.mark.parametrize("shape", [(20, 20, 3), (10, 400, 3), (400, 10, 3), (1, 1, 3), (2000, 2000, 3)])
+    def test_locate_box_stays_in_bounds(self, shape):
+        """locate() must clamp its geometry box inside the image for ANY size/aspect --
+        wide-short, tall-narrow, 1x1, huge -- for both bottom corners (br + bl)."""
+        from remove_ai_watermarks._text_mark_engine import TextMarkEngine
+        from remove_ai_watermarks.doubao_engine import _CONFIG as BR_CONFIG
+        from remove_ai_watermarks.samsung_engine import _CONFIG as BL_CONFIG
+
+        h, w = shape[:2]
+        img = np.zeros(shape, np.uint8)
+        for cfg in (BR_CONFIG, BL_CONFIG):
+            loc = TextMarkEngine(cfg).locate(img)
+            assert loc.x >= 0
+            assert loc.y >= 0
+            assert loc.x + loc.w <= w
+            assert loc.y + loc.h <= h
+            assert loc.w > 0
+            assert loc.h > 0

tests/test_gemini_engine.py

@@ -102,28 +102,6 @@ class TestGeminiEngine:
         assert small.shape == (48, 48)
         assert large.shape == (96, 96)
 
-    def test_remove_watermark_returns_same_shape(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.remove_watermark(image)
-        assert result.shape == image.shape
-        assert result.dtype == np.uint8
-
-    def test_remove_watermark_does_not_modify_input(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        original = image.copy()
-        self.engine.remove_watermark(image)
-        np.testing.assert_array_equal(image, original)
-
-    def test_remove_watermark_large_image(self, tmp_large_image_path):
-        image = cv2.imread(str(tmp_large_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.remove_watermark(image)
-        assert result.shape == image.shape
-
-    def test_remove_watermark_custom_region(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.remove_watermark_custom(image, (10, 10, 48, 48))
-        assert result.shape == image.shape
-
     def test_detect_on_grayscale_does_not_crash(self):
         # A 2D grayscale array reaching detect_watermark (registry adapter / library
         # API) must not crash the FP-gate's axis=2 reduction; it is normalized to BGR.
@@ -131,26 +109,59 @@ class TestGeminiEngine:
         result = self.engine.detect_watermark(gray)
         assert result is not None
 
-    def test_remove_on_bgra_returns_3_channel(self):
+
+# ── Removal: localize -> fill ───────────────────────────────────────
+
+
+def _composite_sparkle(engine, bg_value: int = 160, size: int = 1400):
+    """Composite the captured sparkle at the configured position on a textured
+    mid-tone image (texture so the filled footprint no longer NCC-matches the
+    template). Returns ``(watermarked_uint8, (x, y, w, h))``."""
+    yy, xx = np.mgrid[0:size, 0:size].astype(np.float32)
+    base = bg_value + 18 * np.sin(xx / 40.0) + 14 * np.cos(yy / 55.0)
+    img = np.clip(np.stack([base, base * 0.97, base * 1.03], axis=-1), 0, 255)
+    config = get_watermark_config(size, size)
+    x, y = config.get_position(size, size)
+    alpha = engine.get_interpolated_alpha(config.logo_size)
+    ah, aw = alpha.shape[:2]
+    a = alpha[:, :, None]
+    roi = img[y : y + ah, x : x + aw]
+    img[y : y + ah, x : x + aw] = a * 255.0 + (1.0 - a) * roi
+    return np.clip(img, 0, 255).astype(np.uint8), (x, y, aw, ah)
+
+
+class TestRemovalLocalizeFill:
+    """Removal is localize (footprint_mask) -> fill (shared inpaint backend)."""
+
+    @pytest.fixture(autouse=True)
+    def _setup_engine(self):
+        self.engine = GeminiEngine()
+
+    def test_footprint_mask_covers_detected_sparkle(self):
+        img, (x, y, w, h) = _composite_sparkle(self.engine)
+        assert self.engine.detect_watermark(img).detected
+        mask = self.engine.footprint_mask(img)
+        assert mask is not None
+        assert mask.shape == img.shape[:2]
+        # The mask mass overlaps the sparkle footprint box.
+        assert int(mask[y : y + h, x : x + w].sum()) > 0
+
+    def test_fill_lowers_confidence(self):
+        import remove_ai_watermarks.watermark_registry as registry
+
+        img, _ = _composite_sparkle(self.engine)
+        before = self.engine.detect_watermark(img).confidence
+        mask = self.engine.footprint_mask(img)
+        assert mask is not None
+        out = registry.fill(img, mask, backend="cv2")
+        assert self.engine.detect_watermark(out).confidence < before
+
+    def test_footprint_mask_bgra_input(self):
+        # A 4-channel input is normalized before masking; no crash, right shape.
         bgra = np.zeros((300, 300, 4), dtype=np.uint8)
         bgra[..., 3] = 255
-        result = self.engine.remove_watermark(bgra)
-        assert result.shape == (300, 300, 3)
-
-    def test_remove_watermark_custom_large_region(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.remove_watermark_custom(image, (10, 10, 96, 96))
-        assert result.shape == image.shape
-
-    def test_remove_watermark_custom_arbitrary_region(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.remove_watermark_custom(image, (5, 5, 60, 60))
-        assert result.shape == image.shape
-
-    def test_force_size(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.remove_watermark(image, force_size=WatermarkSize.LARGE)
-        assert result.shape == image.shape
+        mask = self.engine.footprint_mask(bgra, force=True)
+        assert mask is None or mask.shape == (300, 300)
 
 
 # ── Detection ───────────────────────────────────────────────────────
@@ -203,239 +214,6 @@ class TestDetectSparkleConfidence:
         assert detect_sparkle_confidence(bogus) is None
 
 
-# ── Inpainting ──────────────────────────────────────────────────────
-
-
-class TestInpainting:
-    """Tests for residual inpainting."""
-
-    @pytest.fixture(autouse=True)
-    def _setup_engine(self):
-        self.engine = GeminiEngine()
-
-    def test_inpaint_ns(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.inpaint_residual(image, (150, 150, 48, 48), method="ns")
-        assert result.shape == image.shape
-
-    def test_inpaint_telea(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.inpaint_residual(image, (150, 150, 48, 48), method="telea")
-        assert result.shape == image.shape
-
-    def test_inpaint_gaussian(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.inpaint_residual(image, (150, 150, 48, 48), method="gaussian")
-        assert result.shape == image.shape
-
-    def test_inpaint_zero_strength(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.inpaint_residual(image, (150, 150, 48, 48), strength=0.0)
-        np.testing.assert_array_equal(result, image)
-
-    def test_inpaint_tiny_region_returns_unchanged(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        result = self.engine.inpaint_residual(image, (10, 10, 2, 2))
-        np.testing.assert_array_equal(result, image)
-
-    def test_inpaint_does_not_modify_input(self, tmp_image_path):
-        image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
-        original = image.copy()
-        self.engine.inpaint_residual(image, (150, 150, 48, 48))
-        np.testing.assert_array_equal(image, original)
-
-
-class TestOverSubtractionGuard:
-    """Issue #30: reverse-alpha must not turn the sparkle into a black pit.
-
-    On a dark background the captured alpha over-estimates the real sparkle opacity,
-    so the fixed-alpha reverse blend over-subtracts and drives the footprint to black.
-    The engine detects this and inpaints the footprint instead.
-    """
-
-    # Composite the mark at ~60% of the captured opacity: the engine's alpha maxes at
-    # ~0.51, real dark-background sparkles sit nearer ~0.31, so 0.6x reproduces the
-    # capture-over-estimates-reality mismatch that triggers the bug.
-    _REALISTIC_ALPHA_SCALE = 0.6
-
-    @pytest.fixture(autouse=True)
-    def _setup_engine(self):
-        self.engine = GeminiEngine()
-
-    def _composite_sparkle(self, bg_value: int, size: int = 1400, alpha_scale: float = _REALISTIC_ALPHA_SCALE):
-        """Build a flat BGR image of ``bg_value`` with the sparkle composited in.
-
-        The mark is composited at a LOWER effective opacity than the engine's captured
-        alpha map (``alpha_scale`` < 1), reproducing the real-world mismatch behind
-        issue #30: the captured alpha (~0.51) over-estimates a real sparkle whose
-        effective opacity is lower, so the fixed-alpha reverse blend over-subtracts.
-        Placed at the configured large-image position so the detector locates it.
-        """
-        img = np.full((size, size, 3), bg_value, dtype=np.float32)
-        config = get_watermark_config(size, size)
-        x, y = config.get_position(size, size)
-        alpha = self.engine.get_alpha_map(WatermarkSize.LARGE)
-        ah, aw = alpha.shape[:2]
-        a = (alpha * alpha_scale)[:, :, None]
-        roi = img[y : y + ah, x : x + aw]
-        img[y : y + ah, x : x + aw] = a * 255.0 + (1.0 - a) * roi
-        return np.clip(img, 0, 255).astype(np.uint8), (x, y, aw, ah)
-
-    def test_dark_background_does_not_leave_black_pit(self):
-        image, (x, y, w, h) = self._composite_sparkle(bg_value=60)
-        out = self.engine.remove_watermark(image)
-        footprint = out[y : y + h, x : x + w]
-        # The recovered footprint must read like the dark background, not a black hole.
-        assert footprint.min() > 25, f"black pit: min={footprint.min()}"
-        assert abs(float(footprint.mean()) - 60.0) < 25.0
-
-    def test_bright_background_keeps_reverse_alpha(self):
-        """A bright background does not over-subtract, so reverse-alpha is used."""
-        bright, pos = self._composite_sparkle(bg_value=230)
-        alpha = self.engine.get_interpolated_alpha(pos[2])
-        assert self.engine._reverse_alpha_oversubtracts(bright, alpha, (pos[0], pos[1])) is False
-        dark, dpos = self._composite_sparkle(bg_value=60)
-        dalpha = self.engine.get_interpolated_alpha(dpos[2])
-        assert self.engine._reverse_alpha_oversubtracts(dark, dalpha, (dpos[0], dpos[1])) is True
-
-    def test_midtone_background_does_not_leave_dark_diamond(self):
-        """2026-06-18 prod report: a faint sparkle on a MID-TONE background was
-        over-subtracted into a darker-than-background diamond ("the color just
-        changed, not removed"). No footprint pixel crosses zero there, so the
-        numerator gate misses it -- the dark-margin gate must catch it and inpaint.
-        """
-        image, (x, y, w, h) = self._composite_sparkle(bg_value=160)
-        footprint = image[y : y + h, x : x + w]
-        # The numerator (black-pit) gate alone does NOT fire on a mid-tone background.
-        alpha = self.engine.get_interpolated_alpha(w)
-        roi = footprint.astype(np.float32).mean(axis=2)
-        body = alpha[:h, :w] >= self.engine._FOOTPRINT_ALPHA
-        numerator = roi - np.clip(alpha[:h, :w], 0.0, 0.99) * self.engine.logo_value
-        assert float((numerator[body] < 0).sum()) / float(body.sum()) <= self.engine._OVERSUB_FOOTPRINT_FRAC
-        # ...but the over-subtraction guard still trips (via the dark-margin path) and
-        # removal leaves the footprint reading like the mid-tone background, not darker.
-        assert self.engine._reverse_alpha_oversubtracts(image, alpha, (x, y)) is True
-        out = self.engine.remove_watermark(image)
-        cleaned = out[y : y + h, x : x + w]
-        assert abs(float(cleaned.mean()) - 160.0) < 15.0, f"dark diamond: mean={cleaned.mean()}"
-        assert int(cleaned.min()) > 160 - 30, f"dark pit: min={cleaned.min()}"
-
-
-class TestUnderSubtractionGain:
-    """Under-subtraction fix: a sparkle MORE opaque than the captured alpha must not
-    survive removal. The captured alpha (~0.51) under-represents such marks, so the
-    fixed-alpha reverse blend leaves a bright residual; the per-image gain scales the
-    alpha up to match this image's opacity. Mirror of TestOverSubtractionGuard.
-    """
-
-    @pytest.fixture(autouse=True)
-    def _setup_engine(self):
-        self.engine = GeminiEngine()
-
-    def _composite_sparkle(self, bg_value: int, alpha_scale: float, size: int = 1400):
-        """Flat ``bg_value`` image with the sparkle composited at ``alpha_scale`` opacity.
-
-        ``alpha_scale`` > 1 makes the mark MORE opaque than the engine's captured alpha,
-        reproducing the under-subtraction case (real under-removed marks estimate ~1.47).
-        """
-        img = np.full((size, size, 3), bg_value, dtype=np.float32)
-        config = get_watermark_config(size, size)
-        x, y = config.get_position(size, size)
-        alpha = self.engine.get_alpha_map(WatermarkSize.LARGE)
-        ah, aw = alpha.shape[:2]
-        a = np.clip(alpha * alpha_scale, 0.0, 1.0)[:, :, None]
-        roi = img[y : y + ah, x : x + aw]
-        img[y : y + ah, x : x + aw] = a * 255.0 + (1.0 - a) * roi
-        return np.clip(img, 0, 255).astype(np.uint8), (x, y, aw, ah)
-
-    def test_more_opaque_sparkle_estimates_gain_above_deadband(self):
-        image, pos = self._composite_sparkle(bg_value=80, alpha_scale=1.3)
-        alpha = self.engine.get_interpolated_alpha(pos[2])
-        gain = self.engine._estimate_alpha_gain(image, alpha, (pos[0], pos[1]))
-        assert gain > self.engine._ALPHA_GAIN_DEADBAND, f"gain {gain} did not exceed deadband"
-
-    def test_matching_sparkle_estimates_unit_gain(self):
-        """A sparkle that matches the captured opacity gets ~1.0 (no scaling)."""
-        image, pos = self._composite_sparkle(bg_value=80, alpha_scale=1.0)
-        alpha = self.engine.get_interpolated_alpha(pos[2])
-        gain = self.engine._estimate_alpha_gain(image, alpha, (pos[0], pos[1]))
-        assert gain <= self.engine._ALPHA_GAIN_DEADBAND, f"matching sparkle scaled by {gain}"
-
-    def test_more_opaque_sparkle_is_removed(self):
-        """The gain-scaled removal clears a more-opaque sparkle without a black pit.
-
-        Asserted on the footprint PIXELS, not the detector: the detector's NCC is
-        degenerate on a perfectly flat synthetic background (zero-variance regions
-        spuriously match), so a re-detect conf is meaningless here -- on real textured
-        images the same removal drops the detector from ~0.80 to ~0.27 (spaces corpus).
-        """
-        image, (x, y, w, h) = self._composite_sparkle(bg_value=80, alpha_scale=1.3)
-        assert self.engine.detect_watermark(image).detected
-        before_max = int(image[y : y + h, x : x + w].max())  # bright sparkle present
-        assert before_max > 150
-        out = self.engine.remove_watermark(image)
-        footprint = out[y : y + h, x : x + w]
-        # Sparkle gone: no bright residual, no black pit, footprint reads like the bg.
-        assert int(footprint.max()) < 80 + 30, f"bright residual: max={footprint.max()}"
-        assert int(footprint.min()) > 25, f"black pit: min={footprint.min()}"
-        assert abs(float(footprint.mean()) - 80.0) < 20.0
-
-
-class TestVerifyAndRepair:
-    """Self-verify fallback: a sparkle that survives reverse-alpha is inpaint-repaired,
-    but only when that lowers the re-detect confidence (so it can never regress).
-
-    The detector NCC is degenerate on flat synthetic backgrounds, so the keep-best
-    control flow is driven through a stubbed ``detect_watermark`` rather than a real
-    re-detect (mirroring the reasoning in TestUnderSubtractionGain).
-    """
-
-    @pytest.fixture(autouse=True)
-    def _setup_engine(self):
-        self.engine = GeminiEngine()
-        self.alpha = self.engine.get_interpolated_alpha(96)
-        self.pos = (200, 200)
-
-    def _stub_detect(self, confidences):
-        """detect_watermark stub yielding the given confidences in order."""
-        seq = iter(confidences)
-
-        def fake(image, force_size=None):
-            return DetectionResult(detected=True, confidence=next(seq))
-
-        return fake
-
-    def _repair(self, result):
-        return self.engine._verify_and_repair(result, self.alpha, self.pos, WatermarkSize.LARGE)
-
-    def test_clean_removal_returned_untouched(self, monkeypatch):
-        """Below the fallback threshold, the input is returned byte-identical."""
-        img = np.full((600, 600, 3), 90, dtype=np.uint8)
-        monkeypatch.setattr(self.engine, "detect_watermark", self._stub_detect([0.2]))
-        out = self._repair(img)
-        assert out is img  # no copy, no inpaint
-
-    def test_keeps_footprint_inpaint_when_it_helps(self, monkeypatch):
-        """A surviving sparkle is footprint-inpainted when that re-detects lower; the
-        footprint pixels change."""
-        img = np.full((600, 600, 3), 90, dtype=np.uint8)
-        # Bright residual block over the footprint so the inpaint visibly changes it.
-        img[self.pos[1] : self.pos[1] + 96, self.pos[0] : self.pos[0] + 96] = 240
-        # residual 0.7 (>= 0.5 triggers), candidate re-detects 0.2 (< residual -> keep).
-        monkeypatch.setattr(self.engine, "detect_watermark", self._stub_detect([0.7, 0.2]))
-        out = self._repair(img)
-        assert out is not img
-        assert not np.array_equal(out, img)  # footprint was inpainted from surroundings
-
-    def test_repair_rejected_when_inpaint_does_not_help(self, monkeypatch):
-        """When the inpaint does not lower the re-detect confidence, keep the original."""
-        img = np.full((600, 600, 3), 90, dtype=np.uint8)
-        # residual 0.7, candidate re-detects 0.75 (>= residual -> reject the inpaint).
-        monkeypatch.setattr(self.engine, "detect_watermark", self._stub_detect([0.7, 0.75]))
-        out = self._repair(img)
-        assert out is img
-
-
 class TestSparkleFalsePositiveGate:
     """False-positive gate: a low-confidence shape match whose core is NOT brighter
     than its surroundings (ornate/flat content, not a white sparkle overlay) is
@@ -514,14 +292,15 @@ class TestSparkleFalsePositiveGate:
         assert det.confidence < 0.5
         assert not det.detected
 
-    def test_bright_background_low_gradient_match_demoted(self):
-        """Bright-background content FP (2026-06-26 landing-page reports: a snow+sky
-        photo and a white product render scored ~0.51). A bright background gives the
-        match a HIGH core-ring margin, so the margin gate cannot demote it -- but the
-        smooth blob lacks the crisp star edges of a real sparkle, so its GRADIENT NCC
-        is low. The gradient gate (``_SPARKLE_FP_GRAD``) demotes it. Reproduces the
-        regime with a heavily-blurred bright sparkle: high margin, low gradient, and a
-        pre-gate fusion above the 0.5 promote bar (so it WOULD have been detected).
+    def test_bright_white_blurred_sparkle_rescued(self):
+        """A strong, bright, WHITE blurred sparkle is now KEPT (white-core rescue). A
+        faint / re-compressed real sparkle has soft edges (low gradient) like a smooth
+        blob, but its core is bright AND near-WHITE and its fused confidence clears the
+        trust gate, so the rescue (``_SPARKLE_WHITE_SAT`` / ``_SPARKLE_KEEP_CONF``) keeps
+        it -- recovering the metadata-stripped faint sparkles the grad gate used to drop.
+        The weaker (~0.51) bright-background FPs the grad gate was added for still get
+        demoted, because they fall below ``_SPARKLE_KEEP_CONF`` (0.52); the colored-blob
+        case below is demoted on core saturation.
         """
         size = 1400
         config = get_watermark_config(size, size)
@@ -533,16 +312,28 @@ class TestSparkleFalsePositiveGate:
         img[y : y + ah, x : x + aw] = a * 255.0 + (1.0 - a) * img[y : y + ah, x : x + aw]
         img = cv2.GaussianBlur(np.clip(img, 0, 255).astype(np.uint8), (39, 39), 0)
         det = self.engine.detect_watermark(img)
-        # Pre-gate fusion clears the 0.5 promote bar (would have been detected)...
-        pre = det.spatial_score * 0.5 + det.gradient_score * 0.3 + det.variance_score * 0.2
-        assert pre > 0.5
-        # ...the OLD margin gate cannot catch it (bright background -> high margin)...
-        margin = self.engine._core_ring_margin(img, self.engine.get_interpolated_alpha(det.region[2]), det.region[:2])
-        assert margin is not None
-        assert margin >= self.engine._SPARKLE_FP_MARGIN
-        # ...but the gradient is low (smooth blob, not a crisp star)...
+        assert det.gradient_score < self.engine._SPARKLE_FP_GRAD  # soft edges, low gradient
+        assert det.confidence >= self.engine._SPARKLE_KEEP_CONF  # strong white-core match, kept
+        assert det.detected
+
+    def test_bright_colored_blob_still_demoted(self):
+        """The white-core rescue must NOT re-admit a COLORED bright-corner FP (sky, sun,
+        a warm light): its core saturation is high, so the rescue does not apply and the
+        gradient gate still demotes it. Same blurred construction as the white sparkle
+        above, but tinted -- proving the discriminator is core color, not just brightness.
+        """
+        size = 1400
+        config = get_watermark_config(size, size)
+        x, y = config.get_position(size, size)
+        alpha = self.engine.get_alpha_map(WatermarkSize.LARGE)
+        ah, aw = alpha.shape[:2]
+        img = np.full((size, size, 3), 110, dtype=np.float32)
+        a = np.clip(alpha * 1.6, 0.0, 1.0)[:, :, None]
+        color = np.array([40.0, 140.0, 235.0])  # BGR warm/orange -> saturated (non-white) core
+        img[y : y + ah, x : x + aw] = a * color + (1.0 - a) * img[y : y + ah, x : x + aw]
+        img = cv2.GaussianBlur(np.clip(img, 0, 255).astype(np.uint8), (39, 39), 0)
+        det = self.engine.detect_watermark(img)
         assert det.gradient_score < self.engine._SPARKLE_FP_GRAD
-        # ...so the gradient gate demotes it below the detection bar.
         assert det.confidence < 0.5
         assert not det.detected
 

tests/test_humanizer.py

@@ -1,4 +1,5 @@
 import numpy as np
+import pytest
 
 from remove_ai_watermarks.humanizer import apply_analog_humanizer, unsharp_mask
 
@@ -72,6 +73,15 @@ def test_chromatic_shift_does_not_wrap_opposite_edge():
     assert result[:, -shift:, 2].min() > 195
 
 
+@pytest.mark.parametrize(("width", "shift"), [(1, 1), (3, 3), (3, 5), (5, 10)])
+def test_chromatic_shift_wider_than_image_no_crash(width: int, shift: int):
+    """Regression: a chromatic_shift >= image width left the edge-replication slices
+    empty and crashed the broadcast (ValueError). The shift must clamp to width-1."""
+    img = np.full((4, width, 3), 120, np.uint8)
+    result = apply_analog_humanizer(img, grain_intensity=0.0, chromatic_shift=shift)
+    assert result.shape == img.shape
+
+
 def test_unsharp_disabled_returns_unchanged_copy():
     img = np.full((20, 20, 3), 128, dtype=np.uint8)
     img[10, 10] = [100, 150, 200]
@@ -147,3 +157,19 @@ class TestAdaptivePolish:
         a = adaptive_polish(soft, reference, seed=7)
         b = adaptive_polish(soft, reference, seed=7)
         assert np.array_equal(a, b)
+
+    def test_all_edges_reference_grain_mask_near_zero(self):
+        # An all-high-frequency target: _smooth_grain_mask suppresses edges, so the grain
+        # mask is ~all-zero (grain adds nothing) -- adaptive_polish must still return a
+        # valid same-shape image, not crash on the empty-mask branch.
+        import cv2
+
+        from remove_ai_watermarks.humanizer import _smooth_grain_mask, adaptive_polish
+
+        rng = np.random.default_rng(5)
+        edges = rng.integers(0, 256, (120, 120, 3), dtype=np.uint8)  # all high-frequency
+        assert _smooth_grain_mask(edges).mean() < _smooth_grain_mask(np.full((120, 120, 3), 128, np.uint8)).mean()
+        soft = cv2.GaussianBlur(edges, (0, 0), sigmaX=3.0)
+        out = adaptive_polish(soft, edges, seed=0)
+        assert out.shape == soft.shape
+        assert out.dtype == np.uint8

tests/test_identify.py

@@ -152,6 +152,18 @@ class TestIdentifyNonPng:
         assert r.is_ai_generated is True
         assert "ByteDance" in (r.platform or "")
 
+    def test_dreamina_attributed_without_source_type(self, tmp_path: Path):
+        # Dreamina (ByteDance's international Jimeng brand) signs C2PA as
+        # "Bytedance Pte. Ltd." with a "Dreamina/x.y" claim generator and NO
+        # digitalSourceType assertion -- the generator name is the only AI signal.
+        # It is an identity-AI vendor (a pure generator), so attribution must not
+        # depend on trainedAlgorithmicMedia the way the incidental-mention-prone
+        # common-word issuers (Adobe/Google/OpenAI) do.
+        path = self._c2pa_jpeg(tmp_path, b"Bytedance Pte. Ltd. Dreamina/7.5.0 c2pa.created")
+        r = identify(path, check_visible=False, check_invisible=False)
+        assert r.is_ai_generated is True
+        assert "ByteDance" in (r.platform or "")
+
     def test_elevenlabs_attributed(self, tmp_path: Path):
         path = self._c2pa_jpeg(tmp_path, b"Eleven Labs Inc. ... trainedAlgorithmicMedia")
         r = identify(path, check_visible=False, check_invisible=False)
@@ -493,7 +505,7 @@ _DEMO_AFTER = REPO_ROOT / "demo_banana_after.png"
 
 @pytest.mark.skipif(not (_DEMO_BEFORE.exists() and _DEMO_AFTER.exists()), reason="demo banana pair not present")
 class TestSparkleDetectRemoveAlignment:
-    """Detect (identify) and remove (registry.best_auto_mark) must agree on the
+    """Detect (identify) and remove (registry.detect_marks) must agree on the
     same image -- the retained-corpus desync where identify reported a sparkle the
     removal arbitration declined (or vice versa). Both gate on the single shared
     GEMINI_SPARKLE_TRUST_CONF, so a sparkle just over the line is taken by BOTH
@@ -520,8 +532,8 @@ class TestSparkleDetectRemoveAlignment:
 
         conf = detect_sparkle_confidence(path) or 0.0
         identify_fires = conf >= GEMINI_SPARKLE_TRUST_CONF
-        best = watermark_registry.best_auto_mark(image_io.imread(path))
-        remove_takes_gemini = best is not None and best.key == "gemini"
+        dets = watermark_registry.detect_marks(image_io.imread(path), include_explicit=False)
+        remove_takes_gemini = any(d.key == "gemini" and d.detected for d in dets)
         return identify_fires, remove_takes_gemini, conf
 
     def test_above_threshold_both_fire(self, tmp_path: Path):
@@ -687,6 +699,16 @@ class TestOpenAiCaveatVendorScoped:
         assert any("SynthID watermark, inferred from C2PA metadata (likely present (OpenAI" in w for w in r.watermarks)
         assert any("before the rollout" in c for c in r.caveats)
 
+    def test_dreamina_png_cabx_without_source_type(self, tmp_path: Path):
+        # Real Dreamina PNGs carry the "Dreamina/x.y" generator in an ingredient
+        # manifest (the active one is often a c2pa-tool transcode), so the caBX
+        # byte-scan -- which sees the whole store -- is the reliable detector, and
+        # there is no trainedAlgorithmicMedia to lean on.
+        png = self._png(tmp_path, "dreamina.png", self._png_chunk(b"caBX", b"jumbc2pa Dreamina/7.5.0 c2pa.created"))
+        r = identify(png, check_visible=False, check_invisible=False)
+        assert r.is_ai_generated is True
+        assert "ByteDance" in (r.platform or "")
+
 
 class TestReportSerializable:
     def test_report_is_json_serializable(self, tmp_png_with_ai_metadata: Path):
@@ -904,6 +926,15 @@ class TestVendorOf:
         assert _vendor_of("a regular photo") is None
         assert _vendor_of(None) is None
 
+    def test_registered_vendors_normalize(self):
+        # Regression: these registered C2PA vendors returned None, so their claims never
+        # entered clash detection (a coverage hole). They now normalize to one origin.
+        assert _vendor_of("ByteDance (Doubao / Jimeng / Volcano Engine)") == "ByteDance"
+        assert _vendor_of("Dreamina/1.2") == "ByteDance"
+        assert _vendor_of("Canva (Magic Media)") == "Canva"
+        assert _vendor_of("Black Forest Labs (FLUX)") == "Black Forest Labs"
+        assert _vendor_of("Eleven Labs Inc.") == "ElevenLabs"
+
 
 class TestIntegrityClashesHelper:
     def test_two_ai_vendors_clash(self):
@@ -927,6 +958,31 @@ class TestIntegrityClashesHelper:
                 == []
             )
 
+    def test_bytedance_c2pa_plus_own_aigc_no_clash(self):
+        # A legit ByteDance/Doubao image carries BOTH a ByteDance C2PA manifest and its
+        # own China TC260 AIGC label. The label is ByteDance's own regulatory stamp, so
+        # it must be attributed to ByteDance and NOT read as a competing origin.
+        assert (
+            _integrity_clashes({"c2pa": "ByteDance", "aigc": "China AIGC (TC260)"}, None, camera_has_ai_marker=True)
+            == []
+        )
+
+    def test_foreign_vendor_plus_aigc_still_clashes(self):
+        # But a NON-Chinese vendor's C2PA next to a China TC260 label names two different
+        # origins -- a laundering tell that must still fire (the generic label stays generic).
+        clashes = _integrity_clashes({"c2pa": "OpenAI", "aigc": "China AIGC (TC260)"}, None, camera_has_ai_marker=True)
+        assert len(clashes) == 1
+        assert "Conflicting AI-origin" in clashes[0]
+
+    def test_bytedance_c2pa_plus_foreign_generator_clashes(self):
+        # Coverage win: a transplanted ByteDance C2PA manifest next to an independent
+        # foreign generator stamp is a laundering tell that went undetected before
+        # ByteDance was added to _vendor_of.
+        clashes = _integrity_clashes({"c2pa": "ByteDance", "exif_generator": "OpenAI"}, None, camera_has_ai_marker=True)
+        assert len(clashes) == 1
+        assert "ByteDance" in clashes[0]
+        assert "OpenAI" in clashes[0]
+
     def test_manifest_vendor_vs_independent_signal_clashes(self):
         # A vendor named only inside the manifest still clashes with a genuinely
         # independent stamp (here an EXIF/XMP generator tag) naming a third vendor.

tests/test_image_io.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import io
 from typing import TYPE_CHECKING
 
 import cv2
 import numpy as np
+import pytest
 
 from remove_ai_watermarks import image_io
 
@@ -103,3 +105,105 @@ class TestFailureSemantics:
         # An unwritable path must return False (cv2.imwrite contract), not raise.
         path = tmp_path / "no-such-dir" / "out.png"
         assert image_io.imwrite(path, _make_bgr()) is False
+
+
+def _avif_writable() -> bool:
+    """True when the installed Pillow can ENCODE AVIF (needed to synthesize a fixture);
+    read support is what we test, but we need a writer to make the sample."""
+    from PIL import Image, features
+
+    if not (hasattr(features, "check") and features.check("avif")):
+        return False
+    try:
+        Image.fromarray(np.zeros((8, 8, 3), np.uint8)).save(io.BytesIO(), format="AVIF")
+        return True
+    except Exception:
+        return False
+
+
+_HAS_AVIF_WRITE = _avif_writable()
+
+
+class TestPillowFallback:
+    """OpenCV cannot decode HEIC/AVIF; :func:`imread` falls back to Pillow (with the
+    pillow-heif plugin) so the pixel/removal path reads them. Uses a synthetic AVIF
+    (no corpus files); HEIC is exercised the same way in production."""
+
+    @pytest.mark.skipif(not _HAS_AVIF_WRITE, reason="Pillow AVIF encoder unavailable")
+    def test_avif_decodes_via_fallback(self, tmp_path: Path) -> None:
+        from PIL import Image
+
+        path = tmp_path / "x.avif"
+        Image.fromarray(np.full((32, 48, 3), (10, 20, 200), np.uint8), "RGB").save(path)
+        img = image_io.imread(path)  # cv2 fails on AVIF -> Pillow fallback
+        assert img is not None
+        assert img.shape == (32, 48, 3)
+        # Source RGB (R=10, G=20, B=200) -> BGR, so blue [...,0] is high, red [...,2] low
+        # (thresholds loose for AVIF's lossy compression).
+        assert int(img[0, 0, 0]) > 150
+        assert int(img[0, 0, 2]) < 70
+
+    @pytest.mark.skipif(not _HAS_AVIF_WRITE, reason="Pillow AVIF encoder unavailable")
+    def test_avif_alpha_survives_read_bgr_and_alpha(self, tmp_path: Path) -> None:
+        from PIL import Image
+
+        path = tmp_path / "x.avif"
+        rgba = np.dstack([np.full((20, 20, 3), 80, np.uint8), np.full((20, 20), 128, np.uint8)])
+        Image.fromarray(rgba, "RGBA").save(path)
+        bgr, alpha = image_io.read_bgr_and_alpha(path)
+        assert bgr is not None
+        assert bgr.shape == (20, 20, 3)
+        assert alpha is not None  # the source alpha plane survives the fallback
+        assert alpha.shape == (20, 20)
+
+
+def _heif_writable(fmt: str) -> bool:
+    try:
+        image_io._register_heif()
+        from PIL import Image
+
+        Image.fromarray(np.zeros((8, 8, 3), np.uint8), "RGB").save(io.BytesIO(), format=fmt, quality=100)
+        return True
+    except Exception:
+        return False
+
+
+class TestQualityPreservingWrite:
+    """The removal only touches the mark footprint, so the container re-encode must
+    not degrade the untouched pixels: JPEG/WebP are written at max quality, HEIC/AVIF
+    (which cv2 cannot encode) via Pillow instead of crashing."""
+
+    def test_jpeg_written_near_lossless(self, tmp_path: Path) -> None:
+        # a smooth gradient -> JPEG at quality 100 / 4:4:4 is near-lossless
+        g = np.tile(np.linspace(30, 210, 64, dtype=np.uint8), (48, 1))
+        img = np.dstack([g, g, g])
+        p = tmp_path / "x.jpg"
+        assert image_io.imwrite(p, img) is True
+        back = image_io.imread(p)
+        assert back is not None
+        assert float(np.abs(img.astype(int) - back.astype(int)).mean()) < 1.0
+
+    def test_webp_written_lossless(self, tmp_path: Path) -> None:
+        # Regression: cv2 WebP quality 1-100 is LOSSY; lossless needs > 100. A
+        # mark-removal .webp re-encode must NOT degrade the untouched pixels, so
+        # a full-frame round-trip of random data must be bit-identical.
+        img = np.random.default_rng(0).integers(0, 256, (80, 80, 3), dtype=np.uint8)
+        p = tmp_path / "x.webp"
+        assert image_io.imwrite(p, img) is True
+        back = image_io.imread(p)
+        assert back is not None
+        assert np.array_equal(back, img), "WebP re-encode was lossy"
+
+    @pytest.mark.skipif(not _heif_writable("HEIF"), reason="no HEIC encoder in this env")
+    def test_heic_write_roundtrips(self, tmp_path: Path) -> None:
+        # cv2 cannot encode HEIC (used to raise); imwrite must route through Pillow.
+        img = np.full((32, 48, 3), (30, 140, 200), np.uint8)
+        p = tmp_path / "x.heic"
+        assert image_io.imwrite(p, img) is True
+        back = image_io.imread(p)
+        assert back is not None
+        assert back.shape == (32, 48, 3)
+
+    def test_unencodable_ext_returns_false_not_raises(self, tmp_path: Path) -> None:
+        # a bogus extension cv2 can't encode returns False (never raises the cv2.error).
+        assert image_io.imwrite(tmp_path / "x.zzz", _make_bgr()) is False

tests/test_inpaint_fallback.py

@@ -1,55 +1,60 @@
-"""Inpaint-fallback visible removal: method resolution, footprint masks, dispatch.
+"""Visible removal via localize -> fill: backend resolution, footprint masks, dispatch.
 
-The inpaint path erases the mark footprint (MI-GAN when the ``migan`` extra is
-installed, else cv2) instead of reverse-alpha, so a mark needs no captured alpha
-map for removal (only for the footprint silhouette). ``auto`` is deterministic:
-reverse-alpha for capture marks, inpaint for capture-less. These tests avoid any
-ONNX model download by pinning the backend to cv2 via ``preferred_inpaint_backend``;
-only pure cv2/numpy paths run.
+Every known mark is removed by LOCALIZING it to a full-frame footprint mask and
+handing that mask to ONE shared fill backend (MI-GAN when the ``migan`` extra is
+installed, else cv2). These tests avoid any ONNX model download by pinning the
+backend to cv2; only pure cv2/numpy paths run.
 """
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+import cv2
 import numpy as np
-import pytest
 
 from remove_ai_watermarks import watermark_registry as registry
+from remove_ai_watermarks._text_mark_engine import load_alpha_template
 from remove_ai_watermarks.doubao_engine import DoubaoEngine
 from remove_ai_watermarks.gemini_engine import GeminiEngine
 
+if TYPE_CHECKING:
+    import pytest
+
 
 def _compose_textmark(engine, bg: float = 120.0, w: int = 1024, h: int = 1024):
     """Composite the engine's captured mark onto a flat ``bg`` at full opacity so
     the mark is detectable. Returns ``(watermarked_uint8, (ax, ay, gw, gh))``."""
+    c = engine.config
+    at = load_alpha_template(c.asset_name)
+    gw = max(c.min_gw, int(c.alpha_width_frac * w))
+    gh = max(4, int(c.alpha_height_frac * w))
+    margin = int(0.015 * w)
+    ax = (w - margin - gw) if c.corner == "br" else margin
+    ay = h - margin - gh
+    block = cv2.resize(at, (gw, gh))
     img = np.full((h, w, 3), float(bg), np.float32)
-    block, (ax, ay, gw, gh) = engine._fixed_alpha_map(img)
     a = np.clip(block, 0.0, 0.99)[:, :, None]
-    logo = np.array(engine.config.alpha_logo_bgr, np.float32)
-    img[ay : ay + gh, ax : ax + gw] = img[ay : ay + gh, ax : ax + gw] * (1 - a) + logo * a
+    img[ay : ay + gh, ax : ax + gw] = img[ay : ay + gh, ax : ax + gw] * (1 - a) + 255.0 * a
     return np.clip(img, 0, 255).astype(np.uint8), (ax, ay, gw, gh)
 
 
-class TestResolveMethod:
-    @pytest.mark.parametrize("explicit", ["reverse-alpha", "inpaint"])
-    def test_explicit_passthrough(self, explicit: str) -> None:
-        # capture mark: the explicit method passes through unchanged
-        assert registry.resolve_removal_method(explicit, True) == explicit  # type: ignore[arg-type]
-        # capture-less: reverse-alpha is impossible, so it collapses to inpaint
-        expected = "inpaint" if explicit == "reverse-alpha" else explicit
-        assert registry.resolve_removal_method(explicit, False) == expected  # type: ignore[arg-type]
+class TestResolveBackend:
+    def test_auto_resolves_to_available_backend(self) -> None:
+        # auto picks the best available model (LaMa > MI-GAN) or cv2; any is fine.
+        assert registry.resolve_backend("auto") in {"cv2", "migan", "lama"}
 
-    def test_auto_uses_reverse_alpha_for_capture_marks(self) -> None:
-        # auto is deterministic and model-independent: reverse-alpha where a capture
-        # exists (cleaner + lighter than inpaint), inpaint only where it does not.
-        assert registry.resolve_removal_method("auto", True) == "reverse-alpha"
+    def test_cv2_passthrough(self) -> None:
+        assert registry.resolve_backend("cv2") == "cv2"
 
-    def test_auto_uses_inpaint_for_capture_less(self) -> None:
-        assert registry.resolve_removal_method("auto", False) == "inpaint"
+    def test_lama_passthrough(self) -> None:
+        assert registry.resolve_backend("lama") == "lama"
 
 
 class TestFootprintMask:
     def test_textmark_footprint_geometry(self) -> None:
-        mask = DoubaoEngine().footprint_mask(np.full((1024, 1024, 3), 120, np.uint8))
+        # A clean flat corner has no glyph, so force=True yields the geometry box.
+        mask = DoubaoEngine().footprint_mask(np.full((1024, 1024, 3), 120, np.uint8), force=True)
         assert mask is not None
         assert mask.shape == (1024, 1024)
         assert mask.dtype == np.uint8
@@ -71,57 +76,56 @@ class TestFootprintMask:
         assert forced.any()
 
 
-class TestInpaintDispatch:
-    """Force the cv2 backend (patch preferred_inpaint_backend) so no ONNX model
-    downloads; the dispatch/gating logic is backend-agnostic."""
+class TestFillDispatch:
+    """Force the cv2 backend so no ONNX model downloads; the dispatch/gating logic
+    is backend-agnostic."""
 
-    def test_clean_image_is_untouched(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.setattr(registry, "preferred_inpaint_backend", lambda: "cv2")
+    def test_clean_image_is_untouched(self) -> None:
         img = np.full((1024, 1024, 3), 120, np.uint8)
-        out, region = registry.get_mark("doubao").remove(img, method="inpaint")
+        out, region = registry.get_mark("doubao").remove(img, backend="cv2")
         assert region is None
         assert np.array_equal(out, img)  # not detected, not forced -> no-op
 
-    def test_forced_inpaint_edits_only_footprint(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.setattr(registry, "preferred_inpaint_backend", lambda: "cv2")
+    def test_forced_fill_edits_only_footprint(self) -> None:
         img, (ax, ay, gw, gh) = _compose_textmark(DoubaoEngine())
-        out, _ = registry.get_mark("doubao").remove(img, method="inpaint", force=True)
+        out, _ = registry.get_mark("doubao").remove(img, backend="cv2", force=True)
         assert not np.array_equal(out[ay : ay + gh, ax : ax + gw], img[ay : ay + gh, ax : ax + gw])
         assert np.array_equal(out[:200, :200], img[:200, :200])  # far corner untouched
 
-    def test_detected_inpaint_lowers_confidence(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.setattr(registry, "preferred_inpaint_backend", lambda: "cv2")
+    def test_detected_fill_lowers_confidence(self) -> None:
         mark = registry.get_mark("doubao")
         img, _ = _compose_textmark(DoubaoEngine())
         before = mark.detect(img)
         assert before.detected  # the composed mark is detectable
-        out, region = mark.remove(img, method="inpaint")
+        out, region = mark.remove(img, backend="cv2")
         assert region is not None
         assert mark.detect(out).confidence < before.confidence
 
-    def test_reverse_alpha_method_still_selectable(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.setattr(registry, "inpaint_model_available", lambda: True)  # would be inpaint on auto
-        img, _ = _compose_textmark(DoubaoEngine())
-        # explicit reverse-alpha bypasses the inpaint fallback even with a model present
-        out, region = registry.get_mark("doubao").remove(img, method="reverse-alpha")
-        assert region is not None
-        assert not np.array_equal(out, img)
-
 
 class TestBackendSelection:
-    """MI-GAN is the preferred inpaint backend (light, droplet-friendly); big-LaMa
-    is NOT auto-selected. cv2 is the floor when no ONNX model is present."""
+    """auto resolves to the best available inpaint backend: LaMa > MI-GAN > cv2.
+    cv2 is the floor when no learned ONNX model is present (and warns once)."""
 
-    def test_prefers_migan_when_available(self, monkeypatch: pytest.MonkeyPatch) -> None:
+    def test_prefers_lama_when_available(self, monkeypatch: pytest.MonkeyPatch) -> None:
         from remove_ai_watermarks import region_eraser
 
+        monkeypatch.setattr(region_eraser, "lama_available", lambda: True)
+        monkeypatch.setattr(region_eraser, "migan_available", lambda: True)
+        assert registry.preferred_inpaint_backend() == "lama"
+
+    def test_migan_when_only_migan(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from remove_ai_watermarks import region_eraser
+
+        monkeypatch.setattr(region_eraser, "lama_available", lambda: False)
         monkeypatch.setattr(region_eraser, "migan_available", lambda: True)
         assert registry.preferred_inpaint_backend() == "migan"
 
     def test_cv2_when_no_model(self, monkeypatch: pytest.MonkeyPatch) -> None:
         from remove_ai_watermarks import region_eraser
 
+        monkeypatch.setattr(region_eraser, "lama_available", lambda: False)
         monkeypatch.setattr(region_eraser, "migan_available", lambda: False)
+        monkeypatch.setattr(registry, "_warned_cv2_fallback", True)
         assert registry.preferred_inpaint_backend() == "cv2"
 
     def test_inpaint_model_available_reflects_either(self, monkeypatch: pytest.MonkeyPatch) -> None:

tests/test_invisible_engine.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from types import SimpleNamespace
 
+import pytest
 from PIL import Image
 
 from remove_ai_watermarks.invisible_engine import InvisibleEngine, _target_size, is_available
@@ -195,3 +196,24 @@ class TestEsrganUpscale:
         out = InvisibleEngine._esrgan_upscale(self._fake_engine(), img, (512, 341))
         assert out.size == (512, 341)
         assert np.array_equal(np.asarray(out), np.asarray(img.resize((512, 341), Image.Resampling.LANCZOS)))
+
+
+class TestCannyControlImage:
+    """The ControlNet canny conditioning image builder (pure cv2/numpy; behind the gpu
+    extra since it lives on WatermarkRemover). Skips when torch/diffusers are absent."""
+
+    def test_edge_map_is_3channel_rgb(self):
+        if not is_available():
+            pytest.skip("gpu extra (torch/diffusers) not installed")
+        import numpy as np
+
+        from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
+
+        rng = np.random.default_rng(0)
+        img = Image.fromarray(rng.integers(0, 256, (64, 80, 3), dtype=np.uint8))
+        # The method uses no instance state, so call it unbound with a dummy self.
+        out = WatermarkRemover._build_canny_control_image(None, img)  # type: ignore[arg-type]
+        arr = np.array(out)
+        assert out.mode == "RGB"
+        assert arr.shape == (64, 80, 3)
+        assert arr.max() <= 255

tests/test_jimeng_engine.py

@@ -11,11 +11,9 @@ import cv2
 import numpy as np
 import pytest
 
+from remove_ai_watermarks import watermark_registry as registry
 from remove_ai_watermarks.jimeng_engine import (
     _ALPHA_HEIGHT_FRAC,
-    _ALPHA_LOGO_BGR,
-    _ALPHA_MARGIN_BOTTOM_FRAC,
-    _ALPHA_MARGIN_RIGHT_FRAC,
     _ALPHA_NATIVE_WIDTH,
     _ALPHA_WIDTH_FRAC,
     DETECT_NCC_THRESHOLD,
@@ -32,12 +30,13 @@ def _compose(w: int, h: int, bg: float = 100.0):
     img = np.full((h, w, 3), bg, np.float32)
     at = _alpha_template()
     gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-    ax = w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw
-    ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh
+    margin = int(0.015 * w)
+    ax = w - margin - gw
+    ay = h - margin - gh
     amap = np.zeros((h, w), np.float32)
     amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
     a3 = amap[:, :, None]
-    wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
     return wm, amap > 0.2
 
 
@@ -105,7 +104,7 @@ class TestDetect:
         assert det.confidence >= DETECT_NCC_THRESHOLD
 
 
-class TestReverseAlpha:
+class TestAlphaAssetAndRemoval:
     def test_alpha_asset_loads(self):
         at = _alpha_template()
         assert at is not None
@@ -113,89 +112,57 @@ class TestReverseAlpha:
         assert float(at.min()) >= 0.0
         assert float(at.max()) <= 1.0
 
-    def test_logo_is_white(self):
-        assert _ALPHA_LOGO_BGR == (255.0, 255.0, 255.0)
-
-    def test_available_whenever_asset_present(self):
-        eng = JimengEngine()
-        assert eng.reverse_alpha_available(np.zeros((1024, 1024, 3), np.uint8))
-        assert eng.reverse_alpha_available(np.zeros((1440, 2560, 3), np.uint8))
-        assert not eng.reverse_alpha_available(np.zeros((0, 0, 3), np.uint8))
+    def test_footprint_mask_in_bottom_right(self):
+        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
+        mask = JimengEngine().footprint_mask(wm)
+        assert mask is not None
+        assert mask.shape == wm.shape[:2]
+        ys, xs = np.where(mask > 0)
+        assert ys.mean() > wm.shape[0] / 2
+        assert xs.mean() > wm.shape[1] / 2
 
     def test_removes_synthetic_mark(self):
-        """Reverse-alpha + residual inpaint clears the composed mark (re-detect
-        no longer fires)."""
-        eng = JimengEngine()
+        """localize -> cv2 fill clears the composed mark (re-detect no longer fires)."""
         wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
-        assert eng.detect(wm).detected
-        out = eng.remove_watermark_reverse_alpha(wm)
-        assert not eng.detect(out).detected
+        assert JimengEngine().detect(wm).detected
+        out, region = registry.get_mark("jimeng").remove(wm, backend="cv2")
+        assert region is not None
+        assert not JimengEngine().detect(out).detected
 
     @pytest.mark.parametrize(
-        ("w", "h", "max_err"),
+        ("w", "h"),
         [
-            (_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH, 4.0),  # captured width
-            (1440, 2560, 8.0),  # off-native -> NCC alignment generalizes the capture
+            (_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH),  # captured width
+            (1440, 2560),  # off-native -> template-free footprint generalizes
         ],
     )
-    def test_recovers_flat_background(self, w, h, max_err):
-        eng = JimengEngine()
+    def test_fill_removes_and_leaves_far_region(self, w, h):
         wm, mark = _compose(w, h)
         assert float(np.abs(wm.astype(np.float32)[mark] - 100.0).mean()) > 15  # mark visible
-        out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-        assert float(np.abs(out[mark] - 100.0).mean()) < max_err
-
-    def test_far_region_untouched(self):
-        """The residual inpaint only touches the bottom-right footprint; the
-        opposite corner stays pixel-identical."""
-        eng = JimengEngine()
-        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
-        out = eng.remove_watermark_reverse_alpha(wm)
-        h, w = wm.shape[:2]
-        assert np.array_equal(wm[: h // 2, : w // 2], out[: h // 2, : w // 2])
-
-    def test_recovers_shifted_mark_on_texture(self):
-        """A real mark is re-rasterized a few px off its fixed slot, so removal
-        must NCC-align to it (a too-tight locate box would let a corner-ward shift
-        escape the search and leave a readable outline). Composes the real alpha
-        SHIFTED on a known texture and asserts the texture is recovered."""
-        eng = JimengEngine()
-        w = h = _ALPHA_NATIVE_WIDTH
-        at = _alpha_template()
-        gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-        ax = w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw + 12  # shift toward the corner
-        ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh + 8
-        amap = np.zeros((h, w), np.float32)
-        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
-        a3 = amap[:, :, None]
-        yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
-        base = 120 + 40 * np.sin(xx / 90.0) + 30 * np.cos(yy / 70.0)
-        bg = np.clip(np.stack([base, base * 0.95, base * 1.05], axis=-1), 0, 255)
-        wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * bg).clip(0, 255).astype(np.uint8)
-        mark = amap > 0.15
-        assert float(np.abs(wm.astype(np.float32)[mark] - bg[mark]).mean()) > 30  # mark clearly visible
-        out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-        assert float(np.abs(out[mark] - bg[mark]).mean()) < 8.0  # texture recovered, no outline
+        before = JimengEngine().detect(wm)
+        out, _ = registry.get_mark("jimeng").remove(wm, backend="cv2")
+        assert JimengEngine().detect(out).confidence < before.confidence
+        assert np.array_equal(out[: h // 2, : w // 2], wm[: h // 2, : w // 2])
 
 
 class TestDegenerateAndChannelInputs:
-    """Removal must not crash on degenerate sizes or non-3-channel inputs."""
+    """footprint_mask must not crash on degenerate sizes or non-3-channel inputs."""
 
     @pytest.mark.parametrize(("w", "h"), [(2048, 1), (1, 2048), (2048, 8)])
     def test_wide_short_does_not_raise(self, w, h):
         eng = JimengEngine()
         img = np.zeros((h, w, 3), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(img)
-        assert out.shape == img.shape
+        mask = eng.footprint_mask(img, force=True)
+        assert mask is None or mask.shape == (h, w)
 
     def test_grayscale_2d_does_not_raise(self):
         eng = JimengEngine()
         gray = np.zeros((2048, 2048), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(gray)
-        assert out.shape == (2048, 2048, 3)
+        mask = eng.footprint_mask(gray, force=True)
+        assert mask is None or mask.shape == (2048, 2048)
 
     def test_bgra_4channel_does_not_raise(self):
         eng = JimengEngine()
         bgra = np.zeros((2048, 2048, 4), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(bgra)
-        assert out.shape == (2048, 2048, 3)
+        mask = eng.footprint_mask(bgra, force=True)
+        assert mask is None or mask.shape == (2048, 2048)

tests/test_kling_engine.py

@@ -0,0 +1,149 @@
+"""Tests for the Kling (可灵AI 3.0) visible-watermark engine (localize -> fill).
+
+Every tuned constant in ``kling_engine`` was measured on the 30-frame vendor
+cohort (2026-07-21, ``scripts/vendor_mark_calibrate.py``); these tests pin the
+load-bearing ones so a later "cleanup" cannot silently re-inherit Doubao's
+geometry or relax the measured strict-only gate.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+import pytest
+
+from remove_ai_watermarks import watermark_registry as registry
+from remove_ai_watermarks.kling_engine import (
+    _ALPHA_HEIGHT_FRAC,
+    _ALPHA_WIDTH_FRAC,
+    KlingEngine,
+    _alpha_template,
+    _glyph_silhouette,
+)
+
+_MARK_FRAC = 0.12  # measured mark width, fraction of the short side (unimodal)
+_MARGIN = 0.03  # measured right/bottom margin of the real mark
+
+
+def _compose(w: int, h: int, mode: float = _MARK_FRAC, bg: float = 100.0):
+    """Composite the Kling silhouette at the measured size onto a flat bg."""
+    img = np.full((h, w, 3), bg, np.float32)
+    at = _alpha_template()
+    short = min(w, h)
+    gw = int(mode * short)
+    gh = max(4, int(mode * (_ALPHA_HEIGHT_FRAC / _ALPHA_WIDTH_FRAC) * short))
+    margin = int(_MARGIN * short)
+    ax = w - margin - gw
+    ay = h - margin - gh
+    amap = np.zeros((h, w), np.float32)
+    amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+    a3 = amap[:, :, None]
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return wm, amap > 0.2
+
+
+class TestLocate:
+    def test_box_anchored_bottom_right(self):
+        eng = KlingEngine()
+        img = np.zeros((2048, 2048, 3), np.uint8)
+        loc = eng.locate(img)
+        assert 2048 - (loc.x + loc.w) == pytest.approx(2048 * 0.03, rel=0.15)
+        assert 2048 - (loc.y + loc.h) == pytest.approx(2048 * 0.023, rel=0.15)
+
+    def test_box_scales_with_short_side_not_width(self):
+        # scale_basis="short" (measured: mark_w/short 0.118-0.122 across orientations).
+        eng = KlingEngine()
+        landscape = eng.locate(np.zeros((640, 1280, 3), np.uint8))
+        wider = eng.locate(np.zeros((640, 2560, 3), np.uint8))
+        assert wider.w == landscape.w  # same short side -> same box
+        bigger = eng.locate(np.zeros((1280, 1920, 3), np.uint8))  # 2x the short side
+        assert bigger.w == pytest.approx(landscape.w * 2, rel=0.05)
+
+
+class TestConfig:
+    def test_shared_ladder_default(self):
+        # The mark is unimodal at 0.12 of the short side, so Kling keeps the shared
+        # 3-rung ladder (Qwen's per-mark ladder is the measured exception, not a norm).
+        assert KlingEngine().config.ladder == (0.8, 1.0, 1.25)
+
+    def test_strict_only_no_provenance_relaxation(self):
+        # The sub-gate band (real Kling variants at 0.17-0.25) overlaps the clean
+        # arm's top (p90 0.220), so a relaxed arm cannot separate: factor pinned 1.0.
+        assert KlingEngine().config.provenance_ncc_factor == 1.0
+
+    def test_gate_above_clean_arm_max(self):
+        # Clean arm scored p99 0.304 / max 0.320 on 286 hand-labelled frames; the
+        # gate must sit above that with margin.
+        assert KlingEngine().config.detect_ncc_threshold > 0.32
+
+    def test_registry_row(self):
+        mark = registry.get_mark("kling")
+        assert mark.location == "bottom-right"
+        assert "可灵AI" in mark.label
+        assert mark.in_auto
+
+    def test_confident_kling_detection_suppresses_the_jimeng_pill(self):
+        # A Kling image is TC260 too but is not Jimeng-basic: like Doubao and Qwen,
+        # a confident Kling detection must veto the pill (``_keep_pill``).
+        from remove_ai_watermarks.watermark_registry import _keep_pill
+
+        assert not _keep_pill({"kling"}, provenance=frozenset({"jimeng"}), footprint_flat=1.0)
+
+
+class TestDetect:
+    def test_clean_gradient_not_detected(self):
+        eng = KlingEngine()
+        ramp = np.tile(np.linspace(0, 255, 1024, dtype=np.uint8), (1024, 1))
+        img = cv2.cvtColor(ramp, cv2.COLOR_GRAY2BGR)
+        assert not eng.detect(img).detected
+
+    def test_solid_blob_corner_not_detected(self):
+        eng = KlingEngine()
+        img = np.zeros((1024, 1024, 3), np.uint8)
+        x, y, bw, bh = eng.locate(img).bbox
+        img[y + bh // 4 : y + bh * 3 // 4, x : x + bw // 2] = 200
+        assert not eng.detect(img).detected
+
+    def test_silhouette_loads(self):
+        sil = _glyph_silhouette()
+        assert sil is not None
+        assert set(np.unique(sil)).issubset({0, 255})
+
+    def test_composed_mark_detected(self):
+        # The registration's core claim: a mark at the measured size scores over the
+        # gate. The floor is deliberately far above the gate: the synthetic mark is
+        # clean, so it scores high when the geometry is right.
+        wm, _ = _compose(853, 640)
+        det = KlingEngine().detect(wm)
+        assert det.detected
+        assert det.confidence >= 0.80
+
+    def test_small_image_guarded(self):
+        wm, _ = _compose(853, 640)
+        eng = KlingEngine()
+        assert eng.detect(wm).detected
+        assert not eng.detect(cv2.resize(wm, (150, 112))).detected
+
+
+class TestFootprintMaskAndRemoval:
+    def test_removes_composed_mark(self):
+        wm, mark = _compose(853, 640)
+        assert float(np.abs(wm.astype(np.float32)[mark] - 100.0).mean()) > 15  # mark visible
+        assert KlingEngine().detect(wm).detected
+        out, region = registry.get_mark("kling").remove(wm, backend="cv2")
+        assert region is not None
+        assert not KlingEngine().detect(out).detected
+        h, w = wm.shape[:2]
+        assert np.array_equal(out[: h // 2, : w // 2], wm[: h // 2, : w // 2])  # far region exact
+
+    def test_footprint_mask_in_bottom_right(self):
+        wm, _ = _compose(853, 640)
+        mask = KlingEngine().footprint_mask(wm)
+        assert mask is not None
+        ys, xs = np.where(mask > 0)
+        assert ys.mean() > wm.shape[0] / 2
+        assert xs.mean() > wm.shape[1] / 2
+
+    def test_clean_frame_produces_no_mask(self):
+        clean = cv2.GaussianBlur(np.full((640, 853, 3), 120, np.uint8), (5, 5), 0)
+        assert KlingEngine().footprint_mask(clean, force=False) is None

tests/test_liblib_engine.py

@@ -0,0 +1,114 @@
+"""Tests for the LibLibAI ("LibLibAI" wordmark) visible-watermark engine.
+
+Every tuned constant in ``liblib_engine`` was measured on the 15-frame vendor
+cohort (2026-07-22); these tests pin the load-bearing ones: the bottom-CENTER
+anchor, the strict-only gate, and the match-box footprint (the blob bbox both
+bled into background structure and did not own the triangle logo).
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+import pytest
+
+from remove_ai_watermarks import watermark_registry as registry
+from remove_ai_watermarks.liblib_engine import (
+    _ALPHA_HEIGHT_FRAC,
+    _ALPHA_WIDTH_FRAC,
+    LibLibEngine,
+    _alpha_template,
+)
+
+_MARK_FRAC = 0.10  # measured wordmark width, fraction of the frame WIDTH
+
+
+def _compose(w: int, h: int, bg: float = 100.0):
+    """Composite a triangle logo + the LibLibAI wordmark, bottom-center."""
+    img = np.full((h, w, 3), bg, np.float32)
+    at = _alpha_template()
+    gw = int(_MARK_FRAC * w)
+    gh = max(4, int(_MARK_FRAC * (_ALPHA_HEIGHT_FRAC / _ALPHA_WIDTH_FRAC) * w))
+    ax = (w - gw) // 2
+    ay = int(0.94 * h) - gh
+    amap = np.zeros((h, w), np.float32)
+    amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+    # the triangle logo, its own height to the LEFT of the wordmark
+    lx1 = ax - int(0.3 * gh)
+    lx0 = lx1 - gh
+    cv2.fillPoly(amap, [np.array([(lx0, ay + gh), (lx1, ay + gh), (lx1, ay)])], 1.0)
+    a3 = amap[:, :, None]
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return wm, (ax, ay, gw, gh, lx0)
+
+
+class TestLocate:
+    def test_box_horizontally_centered(self):
+        eng = LibLibEngine()
+        img = np.zeros((2048, 1536, 3), np.uint8)
+        loc = eng.locate(img)
+        assert (1536 - loc.w) // 2 == pytest.approx(loc.x, abs=2)  # corner="bc"
+        assert 2048 - (loc.y + loc.h) > 0  # bottom-anchored
+
+    def test_box_scales_with_width(self):
+        eng = LibLibEngine()
+        narrow = eng.locate(np.zeros((2048, 1024, 3), np.uint8))
+        wide = eng.locate(np.zeros((2048, 2048, 3), np.uint8))
+        assert wide.w == pytest.approx(narrow.w * 2, rel=0.05)
+
+
+class TestConfig:
+    def test_tophat_frontend(self):
+        assert LibLibEngine().config.detect_frontend == "tophat"
+
+    def test_strict_only_no_provenance_relaxation(self):
+        assert LibLibEngine().config.provenance_ncc_factor == 1.0
+
+    def test_gate_above_clean_arm_max(self):
+        # With the Arial silhouette the full-corpus false arm (latin UI text)
+        # tops out at 0.398 while the cohort sits at 0.43-0.59; gate 0.42.
+        assert LibLibEngine().config.detect_ncc_threshold >= 0.42
+
+    def test_small_image_size_floor(self):
+        # The one full-corpus false fire with the final template was a 200x200
+        # icon on a 20px template; the engine refuses small images outright.
+        eng = LibLibEngine()
+        assert not eng.detect(np.full((200, 200, 3), 100, np.uint8)).detected
+        wm, _ = _compose(200, 200)
+        assert not eng.detect(wm).detected  # even a composed mark under the floor
+
+    def test_registry_row(self):
+        mark = registry.get_mark("liblib")
+        assert mark.location == "bottom-center"
+        assert mark.in_auto
+
+
+class TestDetectAndMask:
+    def test_detects_composed_mark(self):
+        eng = LibLibEngine()
+        wm, _ = _compose(1792, 2400)
+        det = eng.detect(wm)
+        assert det.detected, f"composed mark missed (conf={det.confidence:.3f})"
+
+    def test_clean_frame_stays_quiet(self):
+        eng = LibLibEngine()
+        img = np.full((2400, 1792, 3), 100, np.uint8)
+        assert not eng.detect(img).detected
+
+    def test_mask_covers_logo_and_wordmark(self):
+        """The footprint must cover the triangle logo LEFT of the wordmark while
+        staying bounded by the match box vertically (the blob bbox bled into
+        background structure and ate real content, 2026-07-22)."""
+        eng = LibLibEngine()
+        wm, (ax, ay, gw, gh, lx0) = _compose(1792, 2400)
+        mask = eng.footprint_mask(wm)
+        assert mask is not None
+        ys, xs = np.where(mask > 0)
+        assert xs.min() <= lx0 + gh // 2  # covers the logo
+        assert xs.max() >= ax + gw - int(0.05 * gw)  # covers the wordmark's right edge
+        assert ys.min() >= ay - gh  # does not bleed far above the mark
+
+    def test_no_mask_on_clean_frame(self):
+        eng = LibLibEngine()
+        img = np.full((2400, 1792, 3), 100, np.uint8)
+        assert eng.footprint_mask(img) is None

tests/test_metadata.py

@@ -156,6 +156,128 @@ class TestHasAiMetadata:
         path.write_bytes(b"\xff\xd8\xff\xe1" + xmp + b"\xff\xd9")
         assert has_ai_metadata(path)
 
+    @pytest.mark.skipif(not SAMPLES_DIR.exists(), reason="data/samples not present")
+    def test_jpeg_metadata_strip_is_pixel_lossless(self, tmp_path: Path):
+        """A JPEG metadata strip must NOT re-encode the DCT scan: pixels stay
+        bit-identical, only the AI provenance APP segments are removed. Verified on real
+        committed fixtures -- grok-1.jpg (EXIF signature), flux-1.jpg (C2PA APP11)."""
+        import numpy as np
+
+        from remove_ai_watermarks import image_io
+        from remove_ai_watermarks.metadata import remove_ai_metadata
+
+        for name in ("grok-1.jpg", "flux-1.jpg"):
+            src = SAMPLES_DIR / name
+            if not src.exists():
+                continue
+            before = image_io.imread(str(src))
+            out = tmp_path / name
+            remove_ai_metadata(src, out)
+            after = image_io.imread(str(out))
+            assert before is not None
+            assert after is not None
+            assert np.array_equal(before, after), f"{name}: pixels changed (DCT was re-encoded)"
+            assert not has_ai_metadata(out), f"{name}: AI metadata survived the strip"
+
+    def test_strip_preserves_lossless_content_with_mismatched_extension(self, tmp_path: Path):
+        """F1 regression: the save format is chosen by CONTENT, not the file extension.
+        A PNG served with a .jpg name (common on real uploads -- ~1% of the corpus is a
+        PNG/WebP under a .jpg extension) must be stripped losslessly as PNG, NOT
+        re-encoded into a real JPEG. The extension-driven path silently degraded it,
+        breaking the 'work with originals' invariant."""
+        import numpy as np
+        from PIL import Image
+        from PIL.PngImagePlugin import PngInfo
+
+        from remove_ai_watermarks import image_io
+        from remove_ai_watermarks.metadata import remove_ai_metadata
+
+        # Random noise: JPEG (even q95 4:4:4) provably shifts it; PNG stays exact.
+        arr = np.random.default_rng(0).integers(0, 256, (64, 64, 3), dtype=np.uint8)
+        info = PngInfo()
+        info.add_text("parameters", "Stable Diffusion prompt")  # an AI-provenance key
+        src = tmp_path / "actually_png.jpg"  # PNG bytes under a .jpg name
+        Image.fromarray(arr).save(src, format="PNG", pnginfo=info)
+        assert has_ai_metadata(src)
+
+        out = tmp_path / "cleaned.jpg"
+        remove_ai_metadata(src, out)
+
+        before = image_io.imread(str(src))
+        after = image_io.imread(str(out))
+        assert before is not None
+        assert after is not None
+        assert np.array_equal(before, after), "misnamed PNG was lossily re-encoded to JPEG"
+        assert not has_ai_metadata(out), "AI metadata survived the strip"
+
+    @staticmethod
+    def _xmp_iptc_jpeg(tmp_path: Path, name: str, marker: bytes) -> Path:
+        """A real (decodable) JPEG carrying the IPTC AI marker in a well-formed APP1
+        XMP segment -- the layout Instagram/Facebook/X and MidJourney/Meta use, where
+        ``digitalSourceType`` lives in XMP rather than the APP13 IPTC-IIM record.
+        Synthetic (no corpus): a solid cv2 JPEG with the APP1 spliced in after SOI."""
+        import cv2
+        import numpy as np
+
+        real = tmp_path / f"real-{name}"
+        cv2.imwrite(str(real), np.full((32, 32, 3), 200, np.uint8), [cv2.IMWRITE_JPEG_QUALITY, 100])
+        data = real.read_bytes()
+        xmp = (
+            b"http://ns.adobe.com/xap/1.0/\x00"
+            b'<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF><rdf:Description>'
+            b"<Iptc4xmpExt:DigitalSourceType>http://cv.iptc.org/newscodes/digitalsourcetype/"
+            + marker
+            + b"</Iptc4xmpExt:DigitalSourceType></rdf:Description></rdf:RDF></x:xmpmeta>"
+        )
+        seg = b"\xff\xe1" + (len(xmp) + 2).to_bytes(2, "big") + xmp
+        path = tmp_path / name
+        path.write_bytes(data[:2] + seg + data[2:])  # splice APP1 right after SOI
+        return path
+
+    @pytest.mark.parametrize("marker", [b"trainedAlgorithmicMedia", b"AISystemUsed"])
+    def test_jpeg_strip_removes_iptc_marker_in_xmp(self, tmp_path: Path, marker: bytes):
+        """Regression: the lossless JPEG strip must drop an AI-bearing APP1 XMP packet
+        when the AI signal is an IPTC ``digitalSourceType`` / 2025.1 field, not only a
+        C2PA or China-AIGC token. Before the fix these survived because the APP1 branch
+        of ``_jpeg_app_carries_ai`` checked only c2pa + AIGC markers, leaving the
+        Instagram/MidJourney/Meta 'Made with AI' XMP intact. Pixels stay bit-identical."""
+        import numpy as np
+
+        from remove_ai_watermarks import image_io
+        from remove_ai_watermarks.metadata import remove_ai_metadata
+
+        src = self._xmp_iptc_jpeg(tmp_path, "iptc-xmp.jpg", marker)
+        assert has_ai_metadata(src)  # detected before
+        before = image_io.imread(str(src))
+        out = tmp_path / "clean.jpg"
+        remove_ai_metadata(src, out)
+        after = image_io.imread(str(out))
+        assert before is not None
+        assert after is not None
+        assert np.array_equal(before, after), "pixels changed: the DCT scan was re-encoded"
+        assert not has_ai_metadata(out), "IPTC AI marker in XMP survived the strip"
+
+    def test_remove_ai_metadata_failsafe_on_truncated_png(self, tmp_path: Path):
+        """Regression: a truncated / corrupt image must NOT crash remove_ai_metadata (a
+        direct library caller like a web worker would 500 on a partial upload). PIL raises
+        OSError decoding a truncated PNG; the strip must fail SAFE -- copy the input through
+        unchanged and return, mirroring strip_c2pa_boxes. Real prod corpus: ~0.2% of
+        uploads are truncated."""
+        import cv2
+        import numpy as np
+
+        from remove_ai_watermarks.metadata import remove_ai_metadata
+
+        real = tmp_path / "real.png"
+        cv2.imwrite(str(real), np.random.default_rng(0).integers(0, 256, (128, 128, 3), dtype=np.uint8))
+        truncated = tmp_path / "truncated.png"
+        truncated.write_bytes(real.read_bytes()[: real.stat().st_size // 2])  # chop the IDAT stream
+        out = tmp_path / "out.png"
+        # Must not raise; output is the input copied through (undecodable -> nothing to strip).
+        result = remove_ai_metadata(truncated, out)
+        assert result == out
+        assert out.read_bytes() == truncated.read_bytes()
+
 
 class TestC2paMarkerIn:
     """The C2PA presence check requires a JUMBF wrapper or the C2PA uuid box, so
@@ -212,6 +334,59 @@ class TestSamsungGenai:
         p = self._samsung_jpeg(tmp_path, "stray.jpg", b'some other blob "genAIType":1 elsewhere')
         assert samsung_genai(p) is None
 
+    def test_remove_strips_post_eoi_trailer(self, tmp_path: Path):
+        """Regression: Galaxy AI appends ``PhotoEditor_Re_Edit_Data`` as a trailer AFTER
+        the JPEG EOI, so the verbatim scan copy in the lossless strip carried it through
+        (survived 0/8 on the corpus). The strip now truncates a Samsung AI trailer at EOI;
+        pixels stay bit-identical and a non-Samsung trailer is preserved."""
+        import cv2
+        import numpy as np
+
+        from remove_ai_watermarks import image_io
+        from remove_ai_watermarks.metadata import remove_ai_metadata
+
+        real = tmp_path / "real.jpg"
+        cv2.imwrite(str(real), np.full((32, 32, 3), 180, np.uint8), [cv2.IMWRITE_JPEG_QUALITY, 100])
+        src = tmp_path / "galaxy.jpg"
+        src.write_bytes(real.read_bytes() + b'PhotoEditor_Re_Edit_Data{"genAIType":1}')
+        assert samsung_genai(src) == 1  # detected before
+        before = image_io.imread(str(src))
+        out = tmp_path / "clean.jpg"
+        remove_ai_metadata(src, out)
+        after = image_io.imread(str(out))
+        assert before is not None
+        assert after is not None
+        assert np.array_equal(before, after), "pixels changed: the DCT scan was re-encoded"
+        assert samsung_genai(out) is None, "Samsung genAIType trailer survived the strip"
+
+    def test_non_samsung_trailer_preserved(self, tmp_path: Path):
+        """A benign post-EOI trailer (e.g. an MPF block) must NOT be truncated."""
+        import cv2
+        import numpy as np
+
+        from remove_ai_watermarks.metadata import _strip_samsung_trailer
+
+        real = tmp_path / "real.jpg"
+        cv2.imwrite(str(real), np.full((16, 16, 3), 90, np.uint8))
+        tail = real.read_bytes() + b"MPF-benign-trailer-bytes"
+        assert _strip_samsung_trailer(tail) == tail
+
+    def test_detects_trailer_past_scan_window(self, tmp_path: Path):
+        """Regression: the marker is a trailer AFTER the JPEG EOI, so on a multi-MB
+        photo it sits past the 512 KB quick-scan window. Detection must read the file
+        tail too, else it disagrees with removal (which reads the whole file). A random
+        1400x1400 q100 JPEG exceeds 512 KB; the marker is only in its post-EOI tail."""
+        import cv2
+        import numpy as np
+
+        real = tmp_path / "big.jpg"
+        big = np.random.default_rng(0).integers(0, 256, (1400, 1400, 3), dtype=np.uint8)
+        cv2.imwrite(str(real), big, [cv2.IMWRITE_JPEG_QUALITY, 100])
+        assert real.stat().st_size > 512 * 1024  # trailer will be past the quick-scan window
+        p = tmp_path / "galaxy_big.jpg"
+        p.write_bytes(real.read_bytes() + b'PhotoEditor_Re_Edit_Data{"genAIType":1}')
+        assert samsung_genai(p) == 1
+
     def test_clean_image_is_none(self, tmp_clean_png):
         assert samsung_genai(tmp_clean_png) is None
 
@@ -277,7 +452,6 @@ class TestGetAiMetadataRealSample:
     [
         b"trainedAlgorithmicMedia",
         b"compositeSynthetic",
-        b"algorithmicMedia",
         b"compositeWithTrainedAlgorithmicMedia",
     ],
 )
@@ -288,6 +462,21 @@ def test_has_ai_metadata_detects_each_iptc_marker(tmp_path: Path, marker: bytes)
     assert has_ai_metadata(path)
 
 
+def test_bare_algorithmic_media_not_flagged_ai(tmp_path: Path):
+    """Regression: the IPTC ``algorithmicMedia`` digitalSourceType is PROCEDURAL (an
+    algorithm not trained on sampled data), NOT AI/ML generation. It must NOT be flagged
+    -- flagging it made identify assert is_ai=high + has_invisible_target=True, which
+    would trigger a diffusion scrub of clean procedural content. It is a distinct token
+    from ``trainedAlgorithmicMedia``, so real 'Made with AI' labels are unaffected."""
+    path = tmp_path / "proc.jpg"
+    path.write_bytes(
+        b"\xff\xd8\xff\xe1<x:xmpmeta><Iptc4xmpExt:DigitalSourceType>"
+        b"http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia"
+        b"</Iptc4xmpExt:DigitalSourceType></x:xmpmeta>\xff\xd9"
+    )
+    assert not has_ai_metadata(path)
+
+
 # ── SynthID-source detection (metadata proxy) ────────────────────────
 
 
@@ -789,6 +978,19 @@ class TestAIGCLabel:
         assert "aigc_label" in meta
         assert "TC260" in meta["aigc_label"]
 
+    def test_empty_namespaced_label_is_still_surfaced(self, tmp_path: Path):
+        """The namespaced element is unambiguous even when its JSON object is empty."""
+        from remove_ai_watermarks.metadata import aigc_label
+
+        p = tmp_path / "empty_aigc.png"
+        Image.new("RGB", (32, 32)).save(p)
+        with open(p, "ab") as f:
+            f.write(b"<TC260:AIGC>{}</TC260:AIGC>")
+
+        assert aigc_label(p) == {}
+        assert has_ai_metadata(p)
+        assert "aigc_label" in get_ai_metadata(p)
+
     def _aigc_chunk_png(self, tmp_path: Path, producer: str = "doubao") -> Path:
         """Doubao writes the TC260 object as a PNG ``tEXt`` chunk keyed ``AIGC``
         with raw JSON (no XMP, no namespaced marker)."""
@@ -826,6 +1028,44 @@ class TestAIGCLabel:
     def test_has_ai_metadata_detects_png_chunk_form(self, tmp_path: Path):
         assert has_ai_metadata(self._aigc_chunk_png(tmp_path))
 
+    def _aigc_serviceprovider_png(self, tmp_path: Path, provider: str = "腾讯云") -> Path:
+        """Tencent Cloud's AIGC variant uses a service-provider schema
+        (``ServiceProvider`` / ``ServiceUser`` / ``Time`` / ``ContentId``) rather
+        than the producer schema, embedded in EXIF ``ImageDescription`` -- none of
+        its fields overlap the producer-side ``_TC260_FIELDS``, so the generic
+        ``"AIGC":{...}`` gate must recognize them too."""
+        import json
+
+        import piexif
+
+        p = tmp_path / "tencent_aigc.png"
+        payload = json.dumps(
+            {
+                "AIGC": {
+                    "ServiceProvider": provider,
+                    "ServiceUser": "1379431822",
+                    "Time": "2026-06-30 23:54:50.067",
+                    "ContentId": "a284dd3d-15ae-4cce-b2dd-010be84921df",
+                }
+            },
+            ensure_ascii=False,
+        )
+        exif = piexif.dump(
+            {"0th": {piexif.ImageIFD.ImageDescription: payload.encode("utf-8")}, "Exif": {}, "GPS": {}, "1st": {}}
+        )
+        Image.new("RGB", (32, 32)).save(p, exif=exif)
+        return p
+
+    def test_parses_serviceprovider_schema(self, tmp_path: Path):
+        from remove_ai_watermarks.metadata import aigc_label
+
+        info = aigc_label(self._aigc_serviceprovider_png(tmp_path))
+        assert info is not None
+        assert "ServiceProvider" in info
+
+    def test_has_ai_metadata_detects_serviceprovider_schema(self, tmp_path: Path):
+        assert has_ai_metadata(self._aigc_serviceprovider_png(tmp_path))
+
     def test_remove_strips_png_chunk_form(self, tmp_path: Path):
         from remove_ai_watermarks.metadata import aigc_label, remove_ai_metadata
 
@@ -859,16 +1099,31 @@ class TestAIGCLabel:
     def test_has_ai_metadata_detects_raw_json_exif_form(self, tmp_path: Path):
         assert has_ai_metadata(self._aigc_exif_jpeg(tmp_path))
 
-    def _aigc_bare_jpeg(self, tmp_path: Path, producer: str = "00119144030008867405X210002") -> Path:
+    def test_remove_strips_raw_json_exif_form(self, tmp_path: Path):
+        """Regression: the TC260 AIGC ``{"AIGC":{...}}`` block Doubao embeds in EXIF
+        UserComment must be scrubbed on removal. Before the fix it survived because
+        ``_scrub_ai_exif`` only touched Software/Make/Artist/ImageDescription in the
+        0th IFD, never UserComment in the Exif sub-IFD."""
+        from remove_ai_watermarks.metadata import aigc_label, remove_ai_metadata
+
+        out = tmp_path / "clean.jpg"
+        remove_ai_metadata(self._aigc_exif_jpeg(tmp_path), out)
+        assert aigc_label(out) is None
+        assert not has_ai_metadata(out)
+
+    def _aigc_bare_jpeg(
+        self, tmp_path: Path, producer: str = "00119144030008867405X210002", marker: bytes = b"\xff\xe9"
+    ) -> Path:
         """Some China-served generators glue the TC260 label straight to its JSON
         as a bare ``AIGC{...}`` blob inside a JPEG APP segment (no ``"AIGC":``
         key wrapper, no PNG chunk, no namespaced XMP) -- seen near the JFIF
-        header on real 2026-06 downloads."""
+        header on real 2026-06 downloads. ``marker`` selects the APP segment
+        (default APP9; the real corpus also uses APP11)."""
         p = tmp_path / "aigc_bare.jpg"
         Image.new("RGB", (32, 32)).save(p)
         raw = p.read_bytes()
         blob = b'AIGC{"Label":"1","ContentProducer":"' + producer.encode() + b'","ProduceID":"8F995586"}'
-        segment = b"\xff\xe9" + (len(blob) + 2).to_bytes(2, "big") + blob  # APP9
+        segment = marker + (len(blob) + 2).to_bytes(2, "big") + blob
         p.write_bytes(raw[:2] + segment + raw[2:])  # splice after SOI
         return p
 
@@ -883,6 +1138,50 @@ class TestAIGCLabel:
     def test_has_ai_metadata_detects_bare_aigc_jpeg_form(self, tmp_path: Path):
         assert has_ai_metadata(self._aigc_bare_jpeg(tmp_path))
 
+    def test_remove_strips_bare_aigc_jpeg_form(self, tmp_path: Path):
+        """Regression: a bare ``AIGC{...}`` blob in a non-standard JPEG APP segment
+        (APP9 here) is detected by aigc_label, so removal must drop that segment too.
+        Before the fix ``_jpeg_app_carries_ai`` only inspected APP11/APP1-XMP/APP13, so
+        the blob survived the lossless strip (detection<->removal parity break)."""
+        from remove_ai_watermarks.metadata import aigc_label, remove_ai_metadata
+
+        out = tmp_path / "clean.jpg"
+        remove_ai_metadata(self._aigc_bare_jpeg(tmp_path), out)
+        assert aigc_label(out) is None
+        assert not has_ai_metadata(out)
+
+    def test_remove_strips_bare_aigc_in_app11(self, tmp_path: Path):
+        """Regression (real corpus, 19/27 survivors): the bare ``AIGC{...}`` blob lives
+        in APP11 (0xEB) on many China gens. That marker's branch in _jpeg_app_carries_ai
+        only checked for a C2PA/JUMBF manifest and RETURNED, so the AIGC blob slipped past
+        the generic check -> survived the strip. The specific checks must fall through to
+        the generic AIGC check."""
+        from remove_ai_watermarks.metadata import aigc_label, remove_ai_metadata
+
+        src = self._aigc_bare_jpeg(tmp_path, marker=b"\xff\xeb")  # APP11
+        assert aigc_label(src) is not None
+        out = tmp_path / "clean.jpg"
+        remove_ai_metadata(src, out)
+        assert aigc_label(out) is None
+        assert not has_ai_metadata(out)
+
+    def test_remove_strips_aigc_in_png_text_chunk(self, tmp_path: Path):
+        """Regression (real corpus, 2 survivors): the TC260 ``{"AIGC":{...}}`` block in a
+        STANDARD PNG text chunk (Description) -- _is_ai_key keeps that key, so removal
+        must also drop it on the VALUE carrying an AIGC block."""
+        from PIL.PngImagePlugin import PngInfo
+
+        from remove_ai_watermarks.metadata import aigc_label, remove_ai_metadata
+
+        p = tmp_path / "aigc_desc.png"
+        info = PngInfo()
+        info.add_text("Description", '{"AIGC":{"Label":"1","ContentProducer":"00119144030008867405X210002"}}')
+        Image.new("RGB", (32, 32)).save(p, pnginfo=info)
+        assert aigc_label(p) is not None
+        out = tmp_path / "clean.png"
+        remove_ai_metadata(p, out)
+        assert aigc_label(out) is None
+
     def test_bare_aigc_without_tc260_field_ignored(self, tmp_path: Path):
         """A bare ``AIGC{...}`` blob with no TC260 field must not false-positive."""
         from remove_ai_watermarks.metadata import aigc_label
@@ -1131,6 +1430,27 @@ class TestLateProvenanceBox:
         p.write_bytes(b"\x89PNG\r\n\x1a\n not an isobmff file")
         assert scan_c2pa_region(p) == b""
 
+    def test_scan_c2pa_region_reads_largesize_uuid(self, tmp_path: Path):
+        """A 64-bit largesize (size32 == 1) uuid box must be walked and collected."""
+        import struct
+
+        from remove_ai_watermarks.noai.isobmff import scan_c2pa_region
+
+        payload = b"LARGESIZE-C2PA-MANIFEST"
+        total = 16 + len(payload)  # 4 (size32=1) + 4 (type) + 8 (largesize) + payload
+        uuid_box = struct.pack(">I", 1) + b"uuid" + struct.pack(">Q", total) + payload
+        p = tmp_path / "large.mp4"
+        p.write_bytes(_MP4_FTYP + uuid_box)
+        assert payload in scan_c2pa_region(p)
+
+    def test_scan_c2pa_region_caps_at_max_total(self, tmp_path: Path):
+        """The collected payload is bounded by ``max_total`` (never unbounded)."""
+        from remove_ai_watermarks.noai.isobmff import scan_c2pa_region
+
+        p = tmp_path / "big.mp4"
+        p.write_bytes(_MP4_FTYP + _box(b"uuid", b"A" * 5000))
+        assert len(scan_c2pa_region(p, max_total=1000)) <= 1000
+
     def test_front_placed_manifest_still_detected(self, tmp_path: Path):
         # Regression: a faststart MP4 (manifest before mdat) is unaffected.
         from remove_ai_watermarks.metadata import C2PA_UUID
@@ -1336,3 +1656,28 @@ class TestC2paCloudManifest:
         assert r.is_ai_generated is None
         assert any("Durable Content Credentials" in w for w in r.watermarks)
         assert any(s.name == "c2pa_cloud" for s in r.signals)
+
+
+def test_remove_all_bypasses_lossless_jpeg(tmp_path, monkeypatch):
+    # keep_standard=False (--remove-all) must NOT take the AI-only lossless JPEG path,
+    # which leaves standard (non-AI) metadata in place; it must fall through to the full
+    # re-encode strip (#7).
+    import remove_ai_watermarks.metadata as md
+
+    calls: list[int] = []
+    real = md._strip_jpeg_metadata_lossless
+
+    def spy(s, o):
+        calls.append(1)
+        return real(s, o)
+
+    monkeypatch.setattr(md, "_strip_jpeg_metadata_lossless", spy)
+    src = tmp_path / "x.jpg"
+    Image.new("RGB", (32, 32), (128, 128, 128)).save(src, "JPEG")
+    out = tmp_path / "o.jpg"
+
+    md.remove_ai_metadata(src, out, keep_standard=True)
+    assert calls, "lossless JPEG strip should run when keeping standard metadata"
+    calls.clear()
+    md.remove_ai_metadata(src, out, keep_standard=False)
+    assert not calls, "keep_standard=False must bypass the AI-only lossless JPEG path"

tests/test_noai.py

@@ -1,4 +1,5 @@
-"""Tests for vendored noai submodules: constants, extractor, cleaner, c2pa."""
+"""Tests for vendored noai submodules: constants, extractor, c2pa, plus the
+consolidated metadata strip (formerly noai.cleaner)."""
 
 from __future__ import annotations
 
@@ -7,6 +8,9 @@ from pathlib import Path
 
 import pytest
 
+from remove_ai_watermarks.metadata import (
+    remove_ai_metadata as noai_remove_ai_metadata,
+)
 from remove_ai_watermarks.noai.c2pa import (
     _parse_c2pa_chunk,
     cbor_text_after,
@@ -16,12 +20,6 @@ from remove_ai_watermarks.noai.c2pa import (
     inject_c2pa_chunk,
     synthid_verdict,
 )
-from remove_ai_watermarks.noai.cleaner import (
-    has_ai_content,
-)
-from remove_ai_watermarks.noai.cleaner import (
-    remove_ai_metadata as noai_remove_ai_metadata,
-)
 from remove_ai_watermarks.noai.constants import (
     AI_KEYWORDS,
     AI_METADATA_KEYS,
@@ -53,6 +51,15 @@ class TestConstants:
     def test_supported_formats_include_jpg(self):
         assert ".jpg" in SUPPORTED_FORMATS
 
+    def test_supported_formats_include_heic_avif(self):
+        # HEIC/AVIF are first-class on the pixel path now (read+write via pillow-heif),
+        # so batch discovers them and the CLI does not warn.
+        assert {".heic", ".heif", ".avif"} <= SUPPORTED_FORMATS
+
+    def test_supported_formats_exclude_jpeg_xl(self):
+        # JPEG-XL stays metadata/strip-only -- no pixel decoder without pillow-jxl.
+        assert ".jxl" not in SUPPORTED_FORMATS
+
     def test_ai_metadata_keys_not_empty(self):
         assert len(AI_METADATA_KEYS) > 0
 
@@ -107,7 +114,8 @@ class TestExtractor:
 
 
 class TestCleaner:
-    """Tests for noai.cleaner functions."""
+    """Metadata stripping via the single, consolidated ``metadata.remove_ai_metadata``
+    (the legacy ``noai.cleaner`` duplicate was retired)."""
 
     def test_remove_ai_metadata(self, tmp_png_with_ai_metadata, tmp_path):
         output = tmp_path / "cleaned.png"
@@ -118,7 +126,7 @@ class TestCleaner:
         assert "parameters" not in meta
 
     def test_has_ai_content(self, tmp_png_with_ai_metadata):
-        assert has_ai_content(tmp_png_with_ai_metadata)
+        assert has_ai_metadata(tmp_png_with_ai_metadata)
 
 
 # ── C2PA ────────────────────────────────────────────────────────────
@@ -313,6 +321,18 @@ class TestC2PADigitalSourceType:
         assert "compositeWithTrainedAlgorithmicMedia" in info["source_type"]
         assert "synthid_watermark" in info  # AI-enhanced + OpenAI issuer
 
+    def test_composite_and_bare_algorithmic_cooccur_is_ai(self):
+        """Regression: a manifest carrying BOTH ``compositeWithTrainedAlgorithmicMedia``
+        (AI-enhanced) and a bare procedural ``algorithmicMedia`` token must classify as
+        AI-enhanced. Before the reorder the bare-token elif fired first and returned
+        non-AI, dropping the composite AI signal (a false negative)."""
+        from remove_ai_watermarks.noai.c2pa import _populate_registry_fields
+
+        info: dict = {}
+        _populate_registry_fields(b"x compositeWithTrainedAlgorithmicMedia x algorithmicMedia x", info)
+        assert info.get("ai_source_kind") == "enhanced"
+        assert "compositeWithTrainedAlgorithmicMedia" in info["source_type"]
+
 
 # ── ISOBMFF (AVIF / HEIF / JPEG-XL container stripping) ──────────────
 
@@ -392,6 +412,33 @@ class TestISOBMFF:
         assert ifd[piexif.ImageIFD.Software].strip() == b""
         assert ifd[piexif.ImageIFD.Make] == b"Canon"
 
+    def test_blank_aigc_block_in_exif(self):
+        """Parity with the JPEG path: the China TC260 ``{"AIGC":{...}}`` block in EXIF
+        ImageDescription must be blanked on the ISOBMFF path too -- ``blank_ai_exif_tokens``
+        is the ONLY EXIF scrubber for HEIC/AVIF (``_scrub_ai_exif`` never runs there)."""
+        import piexif
+
+        aigc = b'{"AIGC":{"Label":"1","ContentProducer":"00119144030008867405X210002","ProduceID":"abc"}}'
+        data = self._avif_with_exif({piexif.ImageIFD.ImageDescription: aigc, piexif.ImageIFD.Make: b"Canon"})
+        out, blanked = blank_ai_exif_tokens(data)
+        assert blanked >= 1
+        assert len(out) == len(data)  # same length -> box sizes / iloc stay valid
+        assert b'"AIGC"' not in out  # TC260 block destroyed
+        assert b"Canon" in out  # camera tag preserved
+
+    def test_blank_xai_signature_pair_in_exif(self):
+        """Parity: the xAI/Grok ``Signature:`` blob + UUID ``Artist`` pair in EXIF is
+        dropped together on the ISOBMFF path too."""
+        import piexif
+
+        sig = b"Signature: " + b"A" * 80
+        art = b"12345678-1234-1234-1234-123456789012"
+        data = self._avif_with_exif({piexif.ImageIFD.ImageDescription: sig, piexif.ImageIFD.Artist: art})
+        out, blanked = blank_ai_exif_tokens(data)
+        assert blanked == 2  # both the signature and the UUID artist
+        assert len(out) == len(data)
+        assert b"Signature: AAAA" not in out
+
     def test_blank_leaves_clean_exif_untouched(self):
         import piexif
 
@@ -406,6 +453,105 @@ class TestISOBMFF:
         assert out == FTYP + b"\x00\x00\x00\x0cmdat" + b"pixels!!"
 
 
+class TestIterTopLevelBoxes:
+    """The box walker's three size encodings and its underflow/overflow guards."""
+
+    def test_64bit_largesize(self):
+        from remove_ai_watermarks.noai.isobmff import _iter_top_level_boxes
+
+        # size32 == 1 -> a 64-bit largesize follows the type; total box length = 24.
+        box = struct.pack(">I", 1) + b"uuid" + struct.pack(">Q", 24) + b"payload!"
+        boxes = list(_iter_top_level_boxes(box))
+        assert len(boxes) == 1
+        start, end, btype, payload_off = boxes[0]
+        assert (start, end, btype, payload_off) == (0, 24, b"uuid", 16)
+
+    def test_size0_runs_to_eof(self):
+        from remove_ai_watermarks.noai.isobmff import _iter_top_level_boxes
+
+        box = struct.pack(">I", 0) + b"mdat" + b"tail-to-eof"
+        boxes = list(_iter_top_level_boxes(box))
+        assert len(boxes) == 1
+        start, end, btype, payload_off = boxes[0]
+        assert (start, end, btype, payload_off) == (0, len(box), b"mdat", 8)
+
+    def test_underflow_size_stops_safely(self):
+        from remove_ai_watermarks.noai.isobmff import _iter_top_level_boxes
+
+        # size (4) < the 8-byte header -> the guard returns without yielding a box.
+        assert list(_iter_top_level_boxes(struct.pack(">I", 4) + b"ftyp" + b"more")) == []
+
+    def test_overflow_size_stops_safely(self):
+        from remove_ai_watermarks.noai.isobmff import _iter_top_level_boxes
+
+        # size claims 999 but the buffer is far shorter -> guard returns, no partial box.
+        assert list(_iter_top_level_boxes(struct.pack(">I", 999) + b"uuid" + b"x")) == []
+
+
+class TestBlankAiXmpPackets:
+    """XMP-packet blanking: same-length overwrite only for AI-marked packets, and only
+    when the packet is fully delimited."""
+
+    AIMARK = b"trainedAlgorithmicMedia"
+
+    def test_ai_packet_blanked_same_length(self):
+        from remove_ai_watermarks.noai.isobmff import blank_ai_xmp_packets
+
+        packet = b'<?xpacket begin="x"?><x:xmpmeta>' + self.AIMARK + b'</x:xmpmeta><?xpacket end="w"?>'
+        data = b"boxhdr" + packet + b"tail"
+        out, n = blank_ai_xmp_packets(data)
+        assert n == 1
+        assert len(out) == len(data)  # same length -> iloc offsets stay valid
+        assert self.AIMARK not in out
+        assert b"boxhdr" in out
+        assert b"tail" in out
+
+    def test_clean_packet_left_intact(self):
+        from remove_ai_watermarks.noai.isobmff import blank_ai_xmp_packets
+
+        packet = b'<?xpacket begin="x"?><x:xmpmeta>plain copyright</x:xmpmeta><?xpacket end="w"?>'
+        out, n = blank_ai_xmp_packets(packet)
+        assert n == 0
+        assert out == packet
+
+    def test_missing_end_delimiter_not_blanked(self):
+        from remove_ai_watermarks.noai.isobmff import blank_ai_xmp_packets
+
+        # No <?xpacket end?> -> the packet regex cannot match, so it is left unchanged.
+        data = b'<?xpacket begin="x"?><x:xmpmeta>' + self.AIMARK + b"</x:xmpmeta>"
+        out, n = blank_ai_xmp_packets(data)
+        assert n == 0
+        assert out == data
+
+
+class TestC2paBufferScans:
+    """The shared buffer-scan helpers (used by both the PNG caBX parser and the
+    format-agnostic binary scan). Data-driven off the registries so they stay valid
+    as vendors are added."""
+
+    def test_soft_binding_vendors_in(self):
+        from remove_ai_watermarks.noai.c2pa import C2PA_SOFT_BINDINGS, soft_binding_vendors_in
+
+        sig, name = next(iter(C2PA_SOFT_BINDINGS.items()))
+        assert name in soft_binding_vendors_in(b"...manifest..." + sig + b"...tail...")
+        assert soft_binding_vendors_in(b"") == []
+        assert soft_binding_vendors_in(b"no soft-binding assertion here") == []
+
+    def test_synthid_vendors_in_requires_synthid_issuer(self):
+        from remove_ai_watermarks.noai.c2pa import C2PA_ISSUERS, SYNTHID_C2PA_ISSUERS, synthid_vendors_in
+
+        syn_sig = next(s for s in C2PA_ISSUERS if s in SYNTHID_C2PA_ISSUERS)
+        non_sig = next(s for s in C2PA_ISSUERS if s not in SYNTHID_C2PA_ISSUERS)
+        assert C2PA_ISSUERS[syn_sig] in synthid_vendors_in(b"x" + syn_sig + b"x")
+        # an issuer that does NOT pair SynthID with C2PA must not be reported as one
+        assert C2PA_ISSUERS[non_sig] not in synthid_vendors_in(b"x" + non_sig + b"x")
+
+    def test_synthid_verdict_format(self):
+        from remove_ai_watermarks.noai.c2pa import synthid_verdict
+
+        assert synthid_verdict("Google LLC") == "likely present (Google LLC embeds SynthID with C2PA)"
+
+
 class TestC2PAInvalidSignature:
     """A .png file that is not actually PNG-signed must read as clean, not crash."""
 

tests/test_pill_engine.py

@@ -93,27 +93,28 @@ class TestFootprintFlatness:
 
 
 class TestPillRegistry:
-    def test_pill_is_capture_less(self) -> None:
+    def test_pill_registered_top_left(self) -> None:
         m = registry.get_mark("jimeng_pill")
-        assert m.has_capture is False
+        assert m.location == "top-left"
+        assert m.in_auto is True
 
-    def test_capture_less_routes_every_method_to_inpaint(self) -> None:
-        # a capture-less mark cannot reverse-alpha; even explicit reverse-alpha -> inpaint
-        assert registry.resolve_removal_method("reverse-alpha", False) == "inpaint"
-        assert registry.resolve_removal_method("auto", False) == "inpaint"
-        assert registry.resolve_removal_method("inpaint", False) == "inpaint"
+    def test_pill_mask_is_top_left_via_registry(self) -> None:
+        # The registry mask callable delegates to the pill engine's top-left footprint.
+        mask = registry.get_mark("jimeng_pill")._mask(np.full((1600, 1200, 3), 150, np.uint8))
+        assert mask is not None
+        assert mask.any()
 
 
 class TestPillGate:
     """Pill removal is gated (``_keep_pill``): the reliable bottom-right wordmark
-    removes it unrestricted, the metadata-only arm removes it ONLY on a flat footprint
-    (safe inpaint), Doubao/no-confirmation never remove it. Fakes detect_marks so no
-    image content is needed; cv2 backend so nothing downloads. Frame flatness matters
-    now, so tests pass a flat or a textured frame explicitly."""
+    removes it unrestricted, the metadata arm (``"jimeng"`` provenance) removes it ONLY
+    on a flat footprint (safe fill), Doubao/no-confirmation never remove it. Fakes each
+    mark's detect so no image content is needed; cv2 backend so nothing downloads. Frame
+    flatness matters, so tests pass a flat or textured frame."""
 
     @staticmethod
     def _fakes(monkeypatch: pytest.MonkeyPatch, keys: set[str]) -> None:
-        from remove_ai_watermarks.watermark_registry import MarkDetection
+        from remove_ai_watermarks.watermark_registry import KnownMark, MarkDetection
 
         labels = {
             "doubao": "Doubao 豆包AI生成 text",
@@ -121,40 +122,59 @@ class TestPillGate:
             "jimeng_pill": "Jimeng AI生成 pill",
         }
         monkeypatch.setattr(registry, "preferred_inpaint_backend", lambda: "cv2")
-        monkeypatch.setattr(
-            registry,
-            "detect_marks",
-            lambda image, *, include_explicit=True: [
-                MarkDetection(k, labels[k], "loc", True, 0.6, (10, 10, 40, 40)) for k in keys
-            ],
-        )
+
+        def fake_detect(self: KnownMark, image: object, *, provenance: bool = False) -> MarkDetection:
+            return MarkDetection(
+                self.key, labels.get(self.key, self.key), "loc", self.key in keys, 0.6, (10, 10, 40, 40)
+            )
+
+        monkeypatch.setattr(registry.KnownMark, "detect", fake_detect)
 
     def test_pill_kept_with_metadata_on_flat_footprint(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        # metadata-only + flat background -> safe inpaint, remove
+        # jimeng provenance (TC260) + flat background -> safe fill, remove
         self._fakes(monkeypatch, {"jimeng_pill"})
-        _, removed = registry.remove_auto_marks(np.full((400, 300, 3), 150, np.uint8), pill_metadata=True)
+        _, removed = registry.remove_auto_marks(np.full((400, 300, 3), 150, np.uint8), provenance=frozenset({"jimeng"}))
         assert "Jimeng AI生成 pill" in removed
 
     def test_pill_dropped_with_metadata_on_textured_footprint(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        # metadata-only + textured background (ceiling-like) -> inpaint would smear, skip
+        # jimeng provenance + textured background (ceiling-like) -> fill would smear, skip
         self._fakes(monkeypatch, {"jimeng_pill"})
-        _, removed = registry.remove_auto_marks(_textured_frame(), pill_metadata=True)
+        _, removed = registry.remove_auto_marks(_textured_frame(), provenance=frozenset({"jimeng"}))
         assert "Jimeng AI生成 pill" not in removed
 
     def test_pill_kept_via_wordmark_ignores_texture(self, monkeypatch: pytest.MonkeyPatch) -> None:
         # wordmark confirmation (~94% precise, survives metadata stripping) is NOT
         # texture-gated: a wordmark-confirmed pill is removed even on a textured frame
         self._fakes(monkeypatch, {"jimeng", "jimeng_pill"})
-        _, removed = registry.remove_auto_marks(_textured_frame(), pill_metadata=False)
+        _, removed = registry.remove_auto_marks(_textured_frame())
         assert "Jimeng AI生成 pill" in removed
 
+    def test_pill_dropped_on_textured_footprint(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        # The metadata arm keeps the flatness guard: textured false fires visibly smear.
+        self._fakes(monkeypatch, {"jimeng_pill"})
+        _, removed = registry.remove_auto_marks(_textured_frame(), provenance=frozenset({"jimeng"}))
+        assert "Jimeng AI生成 pill" not in removed
+
     def test_pill_dropped_without_metadata_or_wordmark(self, monkeypatch: pytest.MonkeyPatch) -> None:
         self._fakes(monkeypatch, {"jimeng_pill"})
-        _, removed = registry.remove_auto_marks(np.full((400, 300, 3), 150, np.uint8), pill_metadata=False)
+        _, removed = registry.remove_auto_marks(np.full((400, 300, 3), 150, np.uint8))
         assert "Jimeng AI生成 pill" not in removed
 
     def test_pill_dropped_on_doubao_even_with_metadata(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        # doubao is faked as detected, which drives the pill gate (pill never rides on a
+        # Doubao detection). The same flat + jimeng-metadata setup WITHOUT doubao keeps the
+        # pill (test_pill_kept_with_metadata_on_flat_footprint), so doubao is the
+        # differentiator. Doubao itself is not asserted in `removed` here: this synthetic
+        # frame is flat with no real glyph, so the text mask has nothing to fill (its real
+        # removal is covered by TestRealSample on the committed doubao sample).
         self._fakes(monkeypatch, {"doubao", "jimeng_pill"})
-        _, removed = registry.remove_auto_marks(np.full((400, 300, 3), 150, np.uint8), pill_metadata=True)
-        assert "Doubao 豆包AI生成 text" in removed
+        _, removed = registry.remove_auto_marks(np.full((400, 300, 3), 150, np.uint8), provenance=frozenset({"jimeng"}))
         assert "Jimeng AI生成 pill" not in removed
+
+
+def test_detect_bgra_no_crash() -> None:
+    # A 4-channel BGRA array must be normalized, not crash cv2.cvtColor(BGR2GRAY) (#10).
+    bgra = np.zeros((256, 256, 4), np.uint8)
+    det = PillEngine().detect(bgra)
+    assert det.detected in (True, False)
+    assert PillEngine().footprint_texture(bgra) >= 0.0

tests/test_platform.py

@@ -178,6 +178,54 @@ class TestFp16WeightVariant:
         assert "variant" not in cls.from_pretrained.call_args.kwargs
 
 
+class TestNoReembeddedWatermark:
+    """F2 regression: the SDXL removal pipelines must disable the diffusers default
+    invisible watermarker (``add_watermarker=False``).
+
+    diffusers stamps an open "Stable Diffusion XL" DWT-DCT watermark onto every SDXL
+    output whenever ``invisible-watermark`` is installed. A watermark REMOVER that left
+    it on would replace one detectable AI watermark (SynthID) with another -- the cleaned
+    output re-reads as AI. The ControlNet sub-model load must NOT receive the kwarg (it
+    is not a pipeline and does not accept it).
+    """
+
+    def _remover(self, profile: str):
+        if not is_watermark_removal_available():
+            pytest.skip("torch/diffusers not installed")
+        from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
+
+        return WatermarkRemover(device="cpu", pipeline=profile)
+
+    def _capture(self, monkeypatch, remover):
+        from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
+
+        calls: list[tuple[str, dict]] = []
+
+        def fake_load(self, cls, model_id, **kwargs):
+            calls.append((getattr(cls, "__name__", str(cls)), kwargs))
+            return MagicMock()
+
+        monkeypatch.setattr(WatermarkRemover, "_load_from_pretrained", fake_load)
+        monkeypatch.setattr(WatermarkRemover, "_move_to_device_and_optimize", lambda self, p: p)
+        return calls
+
+    def test_sdxl_pipeline_disables_watermarker(self, monkeypatch: pytest.MonkeyPatch):
+        remover = self._remover("sdxl")
+        calls = self._capture(monkeypatch, remover)
+        remover._load_pipeline()
+        assert any(kw.get("add_watermarker") is False for _, kw in calls), calls
+
+    def test_controlnet_pipeline_disables_watermarker(self, monkeypatch: pytest.MonkeyPatch):
+        remover = self._remover("controlnet")
+        calls = self._capture(monkeypatch, remover)
+        remover._load_controlnet_pipeline()
+        by_cls = dict(calls)
+        # the SDXL pipeline load disables the watermarker...
+        assert by_cls["StableDiffusionXLControlNetImg2ImgPipeline"].get("add_watermarker") is False
+        # ...but the ControlNet sub-model load must not carry the kwarg (it would error).
+        assert "add_watermarker" not in by_cls["ControlNetModel"]
+
+
 class _StubImage:
     """Minimal PIL.Image stand-in: just the ``width``/``height`` the pure helper reads."""
 

tests/test_qwen_engine.py

@@ -0,0 +1,155 @@
+"""Tests for the Qwen (千问AI生成) visible-watermark engine (localize -> fill).
+
+Every tuned constant in ``qwen_engine`` was measured on the 117-frame vendor
+cohort (2026-07-21, ``scripts/vendor_mark_calibrate.py``); these tests pin the
+load-bearing ones so a later "cleanup" cannot silently re-inherit Doubao's
+geometry (the exact failure the calibration had to fix).
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+import pytest
+
+from remove_ai_watermarks import watermark_registry as registry
+from remove_ai_watermarks.qwen_engine import (
+    _ALPHA_HEIGHT_FRAC,
+    _ALPHA_WIDTH_FRAC,
+    _LADDER,
+    QwenEngine,
+    _alpha_template,
+    _glyph_silhouette,
+)
+
+# The two measured size modes (fraction of the short side): a single fraction on
+# the shared 3-rung ladder covers only ~75% of marks; the per-mark 2-rung ladder
+# centres one rung on each mode.
+_BIG_MODE, _SMALL_MODE = 0.203, 0.124
+_MARGIN = 0.025  # measured right/bottom margin of the real mark
+
+
+def _compose(w: int, h: int, mode: float = _BIG_MODE, bg: float = 100.0):
+    """Composite the Qwen silhouette at a measured size mode onto a flat bg."""
+    img = np.full((h, w, 3), bg, np.float32)
+    at = _alpha_template()
+    short = min(w, h)
+    gw = int(mode * short)
+    gh = max(4, int(mode * (_ALPHA_HEIGHT_FRAC / _ALPHA_WIDTH_FRAC) * short))
+    margin = int(_MARGIN * short)
+    ax = w - margin - gw
+    ay = h - margin - gh
+    amap = np.zeros((h, w), np.float32)
+    amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+    a3 = amap[:, :, None]
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return wm, amap > 0.2
+
+
+class TestLocate:
+    def test_box_anchored_bottom_right_off_the_corner(self):
+        # The measured right margin (~0.025 of short) is wider than Doubao's 0.004;
+        # inheriting Doubao's anchor clipped the first glyph (0.73 -> 0.26 NCC).
+        eng = QwenEngine()
+        img = np.zeros((2048, 2048, 3), np.uint8)
+        loc = eng.locate(img)
+        assert 2048 - (loc.x + loc.w) == pytest.approx(2048 * 0.0203, rel=0.15)
+        assert 2048 - (loc.y + loc.h) == pytest.approx(2048 * 0.0218, rel=0.15)
+
+    def test_box_scales_with_short_side_not_width(self):
+        # scale_basis="short" (measured: frac_short CV 0.189 vs width 0.273).
+        eng = QwenEngine()
+        landscape = eng.locate(np.zeros((640, 1280, 3), np.uint8))
+        wider = eng.locate(np.zeros((640, 2560, 3), np.uint8))
+        assert wider.w == landscape.w  # same short side -> same box
+        bigger = eng.locate(np.zeros((1280, 1920, 3), np.uint8))  # 2x the short side
+        assert bigger.w == pytest.approx(landscape.w * 2, rel=0.05)
+
+
+class TestConfig:
+    def test_per_mark_ladder_and_shared_default_untouched(self):
+        # Qwen's two size modes need their own 2-rung ladder; every other mark must
+        # keep the shipped 3-rung default (the field's whole point is per-mark).
+        assert _LADDER == (0.78, 1.27)
+        assert QwenEngine().config.ladder == (0.78, 1.27)
+        from remove_ai_watermarks.doubao_engine import _CONFIG as db
+        from remove_ai_watermarks.jimeng_engine import _CONFIG as jm
+        from remove_ai_watermarks.samsung_engine import _CONFIG as ss
+
+        assert db.ladder == jm.ladder == ss.ladder == (0.8, 1.0, 1.25)
+
+    def test_strict_only_no_provenance_relaxation(self):
+        # The sub-gate band is dominated by non-Qwen banners on same-cohort frames,
+        # so the relaxed arm was measured to be mostly false fills: factor pinned 1.0.
+        assert QwenEngine().config.provenance_ncc_factor == 1.0
+
+    def test_registry_row(self):
+        mark = registry.get_mark("qwen")
+        assert mark.location == "bottom-right"
+        assert "千问AI生成" in mark.label
+        assert mark.in_auto
+
+
+class TestDetect:
+    def test_clean_gradient_not_detected(self):
+        eng = QwenEngine()
+        ramp = np.tile(np.linspace(0, 255, 1024, dtype=np.uint8), (1024, 1))
+        img = cv2.cvtColor(ramp, cv2.COLOR_GRAY2BGR)
+        assert not eng.detect(img).detected
+
+    def test_solid_blob_corner_not_detected(self):
+        eng = QwenEngine()
+        img = np.zeros((1024, 1024, 3), np.uint8)
+        x, y, bw, bh = eng.locate(img).bbox
+        img[y + bh // 4 : y + bh * 3 // 4, x : x + bw // 2] = 200
+        assert not eng.detect(img).detected
+
+    def test_silhouette_loads(self):
+        sil = _glyph_silhouette()
+        assert sil is not None
+        assert set(np.unique(sil)).issubset({0, 255})
+
+    @pytest.mark.parametrize("mode", [_BIG_MODE, _SMALL_MODE])
+    def test_both_size_modes_detected(self, mode):
+        # The registration's core claim: a mark at EITHER measured mode scores over
+        # the gate (a single fraction on the shared ladder lost the small mode).
+        # The floor is deliberately far above the gate: the synthetic mark is clean,
+        # so it scores ~0.88/~0.94 when the geometry is right, but ~0.49 with Doubao's
+        # box margins (the first glyph is clipped) and ~0.67 on the shared 3-rung
+        # ladder -- the floor is what makes this test discriminate both regressions
+        # (every variant passes a bare gate check on the synthetic).
+        wm, _ = _compose(853, 640, mode=mode)
+        det = QwenEngine().detect(wm)
+        assert det.detected
+        assert det.confidence >= 0.80
+
+    def test_small_image_guarded(self):
+        wm, _ = _compose(853, 640)
+        eng = QwenEngine()
+        assert eng.detect(wm).detected
+        assert not eng.detect(cv2.resize(wm, (150, 112))).detected
+
+
+class TestFootprintMaskAndRemoval:
+    @pytest.mark.parametrize("mode", [_BIG_MODE, _SMALL_MODE])
+    def test_removes_composed_mark_at_both_modes(self, mode):
+        wm, mark = _compose(853, 640, mode=mode)
+        assert float(np.abs(wm.astype(np.float32)[mark] - 100.0).mean()) > 15  # mark visible
+        assert QwenEngine().detect(wm).detected
+        out, region = registry.get_mark("qwen").remove(wm, backend="cv2")
+        assert region is not None
+        assert not QwenEngine().detect(out).detected
+        h, w = wm.shape[:2]
+        assert np.array_equal(out[: h // 2, : w // 2], wm[: h // 2, : w // 2])  # far region exact
+
+    def test_footprint_mask_in_bottom_right(self):
+        wm, _ = _compose(853, 640)
+        mask = QwenEngine().footprint_mask(wm)
+        assert mask is not None
+        ys, xs = np.where(mask > 0)
+        assert ys.mean() > wm.shape[0] / 2
+        assert xs.mean() > wm.shape[1] / 2
+
+    def test_clean_frame_produces_no_mask(self):
+        clean = cv2.GaussianBlur(np.full((640, 853, 3), 120, np.uint8), (5, 5), 0)
+        assert QwenEngine().footprint_mask(clean, force=False) is None

tests/test_region_eraser.py

@@ -8,6 +8,40 @@ import pytest
 from remove_ai_watermarks.region_eraser import boxes_to_mask, erase, lama_available, migan_available
 
 
+class TestPaddedCropBox:
+    """The padded bounding box that bounds the learned backends' ONNX working set."""
+
+    def test_empty_mask_returns_none(self):
+        from remove_ai_watermarks.region_eraser import _padded_crop_box
+
+        assert _padded_crop_box(np.zeros((100, 100), np.uint8), 100, 100, pad_frac=0.1, pad_min=8) is None
+
+    def test_pad_min_dominates_and_clamps_at_border(self):
+        from remove_ai_watermarks.region_eraser import _padded_crop_box
+
+        mask = np.zeros((100, 100), np.uint8)
+        mask[0:5, 0:5] = 255  # 5-px mark in the top-left corner
+        # pad = max(8, int(0.1*5)) = 8; x0 clamps to 0 (not -8), x1 = min(100, 4+1+8) = 13.
+        assert _padded_crop_box(mask, 100, 100, pad_frac=0.1, pad_min=8) == (0, 0, 13, 13)
+
+    def test_pad_frac_dominates_for_large_mark(self):
+        from remove_ai_watermarks.region_eraser import _padded_crop_box
+
+        mask = np.zeros((400, 400), np.uint8)
+        mask[100:300, 100:300] = 255  # 200-px span
+        # pad = max(8, int(0.2*200)) = 40; box = (100-40, .., 299+1+40, ..).
+        assert _padded_crop_box(mask, 400, 400, pad_frac=0.2, pad_min=8) == (60, 60, 340, 340)
+
+    def test_clamps_at_far_border(self):
+        from remove_ai_watermarks.region_eraser import _padded_crop_box
+
+        mask = np.zeros((50, 60), np.uint8)
+        mask[45:50, 55:60] = 255  # bottom-right corner
+        _x0, _y0, x1, y1 = _padded_crop_box(mask, 50, 60, pad_frac=0.1, pad_min=8)
+        assert x1 == 60  # clamped to w, no overflow
+        assert y1 == 50  # clamped to h, no overflow
+
+
 class TestBoxesToMask:
     def test_mask_set_inside_box(self):
         mask = boxes_to_mask((100, 100), [(10, 20, 30, 40)], dilate=0)
@@ -171,6 +205,7 @@ class TestMiganWrapper:
 
             def run(self, _outputs, feeds):
                 self.outer.captured["mask"] = feeds["mask"]
+                self.outer.captured["image_shape"] = feeds["image"].shape
                 img = feeds["image"]  # (1,3,H,W) RGB
                 red = np.zeros_like(img)
                 red[:, 0] = 255  # pure red in RGB
@@ -191,6 +226,21 @@ class TestMiganWrapper:
         assert m[50, 50] == 0
         assert m[10, 10] == 255
 
+    @pytest.mark.usefixtures("_fake_migan")
+    def test_crops_around_mask_so_onnx_input_is_bounded(self):
+        # Large frame, small corner mark: the tensor fed to MI-GAN is the padded
+        # CROP (pad = max(256, 2*bbox)), not the full image -- this is what holds the
+        # ONNX working set roughly constant on big uploads instead of scaling with
+        # the image (the memory fix). Untouched pixels stay exact; the mark is filled.
+        img = np.full((2000, 3000, 3), 120, np.uint8)
+        out = erase(img, boxes=[(2900, 1900, 60, 60)], backend="migan", dilate=0)
+        assert out.shape == img.shape
+        _, _, fh, fw = self.captured["image_shape"]
+        assert fh < 700  # crop height, not the 2000px frame
+        assert fw < 700  # crop width, not the 3000px frame
+        assert tuple(int(v) for v in out[1930, 2930]) == (0, 0, 255)  # mark -> red fill
+        assert np.array_equal(out[:100, :100], img[:100, :100])  # far corner untouched
+
     @pytest.mark.usefixtures("_fake_migan")
     def test_grayscale_2d_does_not_raise(self):
         gray = np.full((100, 100), 120, np.uint8)

tests/test_runninghub_engine.py

@@ -0,0 +1,135 @@
+"""Tests for the RunningHub ("RunningHub AI生成") visible-watermark engine.
+
+Every tuned constant in ``runninghub_engine`` was measured on the 73-frame
+vendor cohort (2026-07-22, ``scripts/vendor_cohort_harvest.py`` +
+``scripts/vendor_mark_calibrate.py``); these tests pin the load-bearing ones:
+the top-left corner, the gray front-end, the exact-size tight ladder, the
+strict-only gate, and the mask/coverage parity regression (the partial-blob
+"Runni" miss).
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+import pytest
+
+from remove_ai_watermarks import watermark_registry as registry
+from remove_ai_watermarks.runninghub_engine import (
+    _ALPHA_HEIGHT_FRAC,
+    _ALPHA_WIDTH_FRAC,
+    RunningHubEngine,
+    _alpha_template,
+)
+
+_MARK_FRAC = 0.32  # measured mark width, fraction of the frame WIDTH
+
+
+def _compose(w: int, h: int, mode: float = _MARK_FRAC, bg: float = 100.0):
+    """Composite the RunningHub silhouette at the measured size, top-left."""
+    img = np.full((h, w, 3), bg, np.float32)
+    at = _alpha_template()
+    gw = int(mode * w)
+    gh = max(4, int(mode * (_ALPHA_HEIGHT_FRAC / _ALPHA_WIDTH_FRAC) * w))
+    ax, ay = int(0.008 * w), int(0.006 * h)
+    amap = np.zeros((h, w), np.float32)
+    amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+    a3 = amap[:, :, None]
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return wm, (ax, ay, gw, gh)
+
+
+class TestLocate:
+    def test_box_anchored_top_left(self):
+        eng = RunningHubEngine()
+        img = np.zeros((2048, 1536, 3), np.uint8)
+        loc = eng.locate(img)
+        assert loc.x < 40  # hugs the left edge
+        assert loc.y < 40  # hugs the top edge (corner="tl")
+
+    def test_box_scales_with_width(self):
+        # scale_basis="width" (measured: mark width is 0.32 of the frame width).
+        eng = RunningHubEngine()
+        narrow = eng.locate(np.zeros((2048, 1024, 3), np.uint8))
+        wide = eng.locate(np.zeros((2048, 2048, 3), np.uint8))
+        assert wide.w == pytest.approx(narrow.w * 2, rel=0.05)
+
+
+class TestConfig:
+    def test_gray_frontend(self):
+        # The mark is a faint mid-gray the top-hat suppresses to clean-arm levels;
+        # the raw-grayscale front-end is what separates (measured 2026-07-22).
+        assert RunningHubEngine().config.detect_frontend == "gray"
+
+    def test_tight_ladder(self):
+        # The NCC comb is razor-sharp in size (0.537 on-size, 0.223 at +5.6%), so
+        # the nominal sits exactly on the measured 0.32 with +-5% rungs.
+        assert RunningHubEngine().config.ladder == (0.95, 1.0, 1.05)
+        assert RunningHubEngine().config.alpha_width_frac == pytest.approx(0.32)
+
+    def test_strict_only_no_provenance_relaxation(self):
+        assert RunningHubEngine().config.provenance_ncc_factor == 1.0
+
+    def test_gate_above_clean_arm_max(self):
+        # Clean arm scored p99 0.273 / max 0.295 on 286 hand-labelled frames.
+        assert RunningHubEngine().config.detect_ncc_threshold > 0.295
+
+    def test_registry_row(self):
+        mark = registry.get_mark("runninghub")
+        assert mark.location == "top-left"
+        assert mark.in_auto
+
+
+class TestDetectAndMask:
+    def test_detects_composed_mark(self):
+        eng = RunningHubEngine()
+        wm, _ = _compose(1080, 1620)
+        det = eng.detect(wm)
+        assert det.detected, f"composed mark missed (conf={det.confidence:.3f})"
+
+    def test_clean_frame_stays_quiet(self):
+        eng = RunningHubEngine()
+        img = np.full((1620, 1080, 3), 100, np.uint8)
+        assert not eng.detect(img).detected
+
+    def test_mask_covers_the_whole_mark(self):
+        """Regression (2026-07-22): the binary blob under-segments the faint head
+        glyphs, so a blob-bbox mask left "Runni" unremoved. The gray front-end's
+        mask must come from the detector's own match box and cover the mark."""
+        eng = RunningHubEngine()
+        wm, (ax, ay, gw, gh) = _compose(1080, 1620)
+        mask = eng.footprint_mask(wm)
+        assert mask is not None
+        ys, xs = np.where(mask > 0)
+        assert xs.min() <= ax + int(0.05 * gw)  # covers the LEFT edge of the mark
+        assert xs.max() >= ax + gw - int(0.05 * gw)
+        assert ys.min() <= ay + gh // 2 <= ys.max()
+
+    def test_no_mask_on_clean_frame(self):
+        eng = RunningHubEngine()
+        img = np.full((1620, 1080, 3), 100, np.uint8)
+        assert eng.footprint_mask(img) is None
+
+    def test_anchor_window_rejects_off_corner_match(self):
+        """The raw-gray front-end false-fires on text-like structure ANYWHERE in
+        the box (37/42009 outside-cohort frames in the 2026-07-22 sweep); the
+        anchor window is what keeps it about THIS mark. A composed mark placed
+        off the measured corner anchor must NOT be detected."""
+        eng = RunningHubEngine()
+        wm, _ = _compose(1080, 1620)
+        det = eng.detect(wm)
+        assert det.detected  # on-anchor control
+        # the same mark shifted right/down, off the anchor window
+        shifted = np.full((1620, 1080, 3), 100, np.uint8)
+        region = wm[10:60, 12:360]
+        shifted[100 : 100 + region.shape[0], 200 : 200 + region.shape[1]] = region
+        assert not eng.detect(shifted).detected
+
+
+class TestPillInteraction:
+    def test_confident_runninghub_detection_suppresses_the_jimeng_pill(self):
+        # A RunningHub frame names its own product; its detection must veto the
+        # Jimeng pill the same way Doubao/Qwen/Kling do (``_keep_pill``).
+        from remove_ai_watermarks.watermark_registry import _keep_pill
+
+        assert not _keep_pill({"runninghub"}, provenance=frozenset({"jimeng"}), footprint_flat=1.0)

tests/test_samsung_engine.py

@@ -12,11 +12,9 @@ import cv2
 import numpy as np
 import pytest
 
+from remove_ai_watermarks import watermark_registry as registry
 from remove_ai_watermarks.samsung_engine import (
     _ALPHA_HEIGHT_FRAC,
-    _ALPHA_LOGO_BGR,
-    _ALPHA_MARGIN_BOTTOM_FRAC,
-    _ALPHA_MARGIN_LEFT_FRAC,
     _ALPHA_NATIVE_WIDTH,
     _ALPHA_WIDTH_FRAC,
     DETECT_NCC_THRESHOLD,
@@ -33,12 +31,13 @@ def _compose(w: int, h: int, bg: float = 100.0):
     img = np.full((h, w, 3), bg, np.float32)
     at = _alpha_template()
     gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-    ax = int(_ALPHA_MARGIN_LEFT_FRAC * w)
-    ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh
+    margin = int(0.015 * w)
+    ax = margin
+    ay = h - margin - gh
     amap = np.zeros((h, w), np.float32)
     amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
     a3 = amap[:, :, None]
-    wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    wm = (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
     return wm, amap > 0.15
 
 
@@ -106,7 +105,7 @@ class TestDetect:
         assert det.confidence >= DETECT_NCC_THRESHOLD
 
 
-class TestReverseAlpha:
+class TestAlphaAssetAndRemoval:
     def test_alpha_asset_loads(self):
         at = _alpha_template()
         assert at is not None
@@ -114,89 +113,58 @@ class TestReverseAlpha:
         assert float(at.min()) >= 0.0
         assert float(at.max()) <= 1.0
 
-    def test_logo_is_white(self):
-        assert _ALPHA_LOGO_BGR == (255.0, 255.0, 255.0)
-
-    def test_available_whenever_asset_present(self):
-        eng = SamsungEngine()
-        assert eng.reverse_alpha_available(np.zeros((1086, 1086, 3), np.uint8))
-        assert eng.reverse_alpha_available(np.zeros((4054, 2958, 3), np.uint8))
-        assert not eng.reverse_alpha_available(np.zeros((0, 0, 3), np.uint8))
+    def test_footprint_mask_in_bottom_left(self):
+        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, int(_ALPHA_NATIVE_WIDTH * 1.33))
+        mask = SamsungEngine().footprint_mask(wm)
+        assert mask is not None
+        assert mask.shape == wm.shape[:2]
+        ys, xs = np.where(mask > 0)
+        assert ys.mean() > wm.shape[0] / 2  # bottom
+        assert xs.mean() < wm.shape[1] / 2  # left
 
     def test_removes_synthetic_mark(self):
-        """Reverse-alpha + residual inpaint clears the composed mark (re-detect no
-        longer fires)."""
-        eng = SamsungEngine()
+        """localize -> cv2 fill clears the composed mark (re-detect no longer fires)."""
         wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, int(_ALPHA_NATIVE_WIDTH * 1.33))
-        assert eng.detect(wm).detected
-        out = eng.remove_watermark_reverse_alpha(wm)
-        assert not eng.detect(out).detected
+        assert SamsungEngine().detect(wm).detected
+        out, region = registry.get_mark("samsung").remove(wm, backend="cv2")
+        assert region is not None
+        assert not SamsungEngine().detect(out).detected
 
     @pytest.mark.parametrize(
-        ("w", "h", "max_err"),
+        ("w", "h"),
         [
-            (_ALPHA_NATIVE_WIDTH, int(_ALPHA_NATIVE_WIDTH * 1.33), 5.0),  # captured width
-            (2958, 4054, 10.0),  # real-photo width (~2.7x native) -> NCC alignment generalizes
+            (_ALPHA_NATIVE_WIDTH, int(_ALPHA_NATIVE_WIDTH * 1.33)),  # captured width
+            (2958, 4054),  # real-photo width (~2.7x native) -> template-free footprint generalizes
         ],
     )
-    def test_recovers_flat_background(self, w, h, max_err):
-        eng = SamsungEngine()
+    def test_fill_removes_and_leaves_far_region(self, w, h):
         wm, mark = _compose(w, h)
         assert float(np.abs(wm.astype(np.float32)[mark] - 100.0).mean()) > 15  # mark visible
-        out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-        assert float(np.abs(out[mark] - 100.0).mean()) < max_err
-
-    def test_far_region_untouched(self):
-        """The residual inpaint only touches the bottom-left footprint; the
-        opposite (top-right) corner stays pixel-identical."""
-        eng = SamsungEngine()
-        wm, _mark = _compose(_ALPHA_NATIVE_WIDTH, int(_ALPHA_NATIVE_WIDTH * 1.33))
-        out = eng.remove_watermark_reverse_alpha(wm)
-        h, w = wm.shape[:2]
-        assert np.array_equal(wm[: h // 2, w // 2 :], out[: h // 2, w // 2 :])
-
-    def test_recovers_shifted_mark_on_texture(self):
-        """A real mark is re-rasterized a few px off its fixed slot, so removal must
-        NCC-align to it (a too-tight locate box would let a corner-ward shift escape
-        the search and leave a readable outline). Composes the real alpha SHIFTED on
-        a known texture and asserts the texture is recovered."""
-        eng = SamsungEngine()
-        w, h = _ALPHA_NATIVE_WIDTH, int(_ALPHA_NATIVE_WIDTH * 1.33)
-        at = _alpha_template()
-        gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
-        ax = max(0, int(_ALPHA_MARGIN_LEFT_FRAC * w) + 9)  # shift right of the fixed slot
-        ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh - 7  # shift up
-        amap = np.zeros((h, w), np.float32)
-        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
-        a3 = amap[:, :, None]
-        yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
-        base = 120 + 40 * np.sin(xx / 90.0) + 30 * np.cos(yy / 70.0)
-        bg = np.clip(np.stack([base, base * 0.95, base * 1.05], axis=-1), 0, 255)
-        wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * bg).clip(0, 255).astype(np.uint8)
-        mark = amap > 0.15
-        assert float(np.abs(wm.astype(np.float32)[mark] - bg[mark]).mean()) > 20  # mark clearly visible
-        out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-        assert float(np.abs(out[mark] - bg[mark]).mean()) < 10.0  # texture recovered, no outline
+        before = SamsungEngine().detect(wm)
+        out, _ = registry.get_mark("samsung").remove(wm, backend="cv2")
+        assert SamsungEngine().detect(out).confidence < before.confidence
+        # The mark is bottom-left; the opposite (top-right) corner stays exact.
+        assert np.array_equal(out[: h // 2, w // 2 :], wm[: h // 2, w // 2 :])
 
 
 class TestDegenerateAndChannelInputs:
-    """Removal must not crash on degenerate sizes or non-3-channel inputs."""
+    """footprint_mask must not crash on degenerate sizes or non-3-channel inputs."""
 
     @pytest.mark.parametrize(("w", "h"), [(2048, 1), (1, 2048), (2048, 8)])
     def test_wide_short_does_not_raise(self, w, h):
         eng = SamsungEngine()
         img = np.zeros((h, w, 3), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(img)
-        assert out.shape == img.shape
+        mask = eng.footprint_mask(img, force=True)
+        assert mask is None or mask.shape == (h, w)
 
     def test_grayscale_2d_does_not_raise(self):
         eng = SamsungEngine()
         gray = np.zeros((1448, 1086), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(gray)
-        assert out.shape == (1448, 1086, 3)
+        mask = eng.footprint_mask(gray, force=True)
+        assert mask is None or mask.shape == (1448, 1086)
 
     def test_bgra_4channel_does_not_raise(self):
         eng = SamsungEngine()
         bgra = np.zeros((1448, 1086, 4), np.uint8)
-        out = eng.remove_watermark_reverse_alpha(bgra)
-        assert out.shape == (1448, 1086, 3)
+        mask = eng.footprint_mask(bgra, force=True)
+        assert mask is None or mask.shape == (1448, 1086)

tests/test_text_mark_engine.py

@@ -0,0 +1,191 @@
+"""Policy-level tests for the shared text-mark engine config.
+
+These assert TUNING that was set by corpus measurement, not algorithm behaviour --
+they exist so a future edit cannot silently revert a calibrated constant back to a
+value that was measured to be wrong. The measurements themselves live in
+`docs/module-internals.md` and in the comment at
+`_text_mark_engine._DEFAULT_PROVENANCE_NCC_FACTOR`.
+"""
+
+
+class TestRivalMargin:
+    """Detection among same-corner marks is COMPETITIVE, not just absolute.
+
+    Doubao "豆包AI生成" and Jimeng "★ 即梦AI" both sit bottom-right in near-white CJK
+    and survive binarization as similar blobs, so an absolute NCC gate cannot tell
+    them apart -- 33 of jimeng's 68 false additions were Doubao marks. Measured
+    separability scoring both templates on the SAME blob (n=40 jimeng / 75 doubao):
+    absolute ncc_jimeng 0.96, ncc_jimeng MINUS ncc_doubao 0.99. Corpus effect of the
+    margin gate: jimeng precision 38% -> 63% with genuine detections unchanged at 40
+    (false fires 65 -> 23).
+    """
+
+    def test_jimeng_competes_against_doubao(self):
+        from remove_ai_watermarks import jimeng_engine
+
+        assert "doubao_alpha.png" in jimeng_engine._CONFIG.rivals
+
+    def test_doubao_has_no_rival_margin(self):
+        """Asymmetric by measurement, not oversight: the symmetric gate cost Doubao 7
+        genuine detections to prevent 5 false ones (1.4:1 against), while Jimeng gained
+        25pp for free. Doubao's absolute detector is already 86% precise."""
+        from remove_ai_watermarks import doubao_engine
+
+        assert doubao_engine._CONFIG.rivals == ()
+
+    def test_a_doubao_shaped_blob_loses_the_jimeng_margin(self):
+        """The decisive case: a blob matching Doubao BETTER than Jimeng must not be
+        booked as a Jimeng wordmark, however high its absolute Jimeng score."""
+        import numpy as np
+
+        from remove_ai_watermarks import jimeng_engine
+        from remove_ai_watermarks._text_mark_engine import glyph_silhouette
+
+        eng = jimeng_engine.JimengEngine()
+        doubao_blob = glyph_silhouette("doubao_alpha.png")
+        assert doubao_blob is not None
+        canvas = np.zeros((doubao_blob.shape[0] + 20, doubao_blob.shape[1] + 20), np.uint8)
+        canvas[10 : 10 + doubao_blob.shape[0], 10 : 10 + doubao_blob.shape[1]] = doubao_blob
+        width = int(doubao_blob.shape[1] / jimeng_engine._CONFIG.alpha_width_frac)
+        jimeng_score = eng._template_match_score(canvas, width)
+        assert not eng._rival_margin_ok(jimeng_score, canvas, width)
+
+
+class TestPerMarkProvenanceRelaxation:
+    """The provenance NCC relaxation is PER MARK, not one shared multiplier.
+
+    Corpus-measured 2026-07-18 on the default `auto` path (4417 unique TC260
+    carriers, blind hand-label, two-sided control): the single shared 0.7 ran at
+    76% precision on doubao but 17% on jimeng, because jimeng's relaxed silhouette
+    keys on "text in the bottom-right corner" rather than the wordmark -- 33 of its
+    68 false additions were DOUBAO marks. Full table at
+    `_text_mark_engine._DEFAULT_PROVENANCE_NCC_FACTOR`.
+    """
+
+
+class TestScaleBasis:
+    """Mark geometry scales with a PER-MARK image dimension, measured not assumed.
+
+    Every tuned fraction was calibrated on PORTRAIT captures, where width and short
+    side coincide, so the basis was never exercised until landscape inputs were
+    measured. Corpus-measured 2026-07-18 (2572 unique TC260 carriers): doubao
+    detection was portrait 60% / square 41% / **landscape 0% of 435** -- a width-scaled
+    box is inflated by the aspect ratio on a wide image and the glyph never lands in
+    it. A short-side basis recovered 56% of the previously-undetected landscape set.
+    The same switch broke JIMENG (labelled landscape positives 13/13 -> 0/13), whose
+    wordmark tracks the width -- hence per-mark, not a house rule.
+    """
+
+    def test_doubao_scales_with_the_short_side(self):
+        from remove_ai_watermarks import doubao_engine
+
+        assert doubao_engine._CONFIG.scale_basis == "short"
+
+    def test_jimeng_scales_with_width(self):
+        """Measured, not an oversight: the short-side basis took jimeng's labelled
+        landscape positives from 13/13 to 0/13."""
+        from remove_ai_watermarks import jimeng_engine
+
+        assert jimeng_engine._CONFIG.scale_basis == "width"
+
+    def test_samsung_keeps_width_because_it_is_unmeasured(self):
+        """1 addition corpus-wide, so there is no evidence either way; an unmeasured
+        change is not an improvement."""
+        from remove_ai_watermarks import samsung_engine
+
+        assert samsung_engine._CONFIG.scale_basis == "width"
+
+    def test_basis_only_differs_on_non_square_images(self):
+        """The basis is a no-op wherever width IS the short side, which is why the bug
+        survived: every calibration capture was portrait."""
+        import numpy as np
+
+        from remove_ai_watermarks import doubao_engine, jimeng_engine
+
+        portrait = np.zeros((1600, 900, 3), np.uint8)
+        landscape = np.zeros((900, 1600, 3), np.uint8)
+        d, j = doubao_engine.DoubaoEngine(), jimeng_engine.JimengEngine()
+        assert d.scale_base(portrait) == j.scale_base(portrait) == 900
+        assert d.scale_base(landscape) == 900
+        assert j.scale_base(landscape) == 1600
+
+    def test_landscape_box_stays_inside_the_frame(self):
+        """The concrete failure: a width-scaled box on a wide image overshoots the
+        mark's real footprint. The short-side box must be proportionally smaller."""
+        import numpy as np
+
+        from remove_ai_watermarks import doubao_engine
+
+        landscape = np.zeros((900, 2400, 3), np.uint8)
+        loc = doubao_engine.DoubaoEngine().locate(landscape)
+        assert loc.w < int(2400 * doubao_engine._CONFIG.width_frac)
+        assert loc.x + loc.w <= 2400
+        assert loc.y + loc.h <= 900
+
+
+class TestTophatFrontend:
+    """Detection can correlate the CONTINUOUS top-hat instead of a binarized blob.
+
+    `extract_mask` thresholds the top-hat into a 0/255 glyph blob, which is fine for a
+    mark stamped bold and opaque and destructive for a faint one -- a thin translucent
+    overlay shatters into specks and no template can match a blob that is not there
+    (measured: 千问 scored 0.170 mean vs doubao's 0.723 through the binary path, 0% over
+    the gate). The `tophat` front-end never binarizes: the saturation/luma gates become
+    weights, and the response is max-normalized so the score is contrast-invariant.
+
+    Corpus effect on the 240-image unbiased recall sample: doubao recall 89% -> 92% at
+    an unchanged 99% precision.
+    """
+
+    def test_doubao_uses_the_continuous_frontend(self):
+        from remove_ai_watermarks import doubao_engine
+
+        assert doubao_engine._CONFIG.detect_frontend == "tophat"
+
+    def test_other_marks_stay_binary_until_measured(self):
+        """A front-end switch must be measured per mark before it ships; jimeng and
+        samsung have no such measurement yet."""
+        from remove_ai_watermarks import jimeng_engine, samsung_engine
+
+        assert jimeng_engine._CONFIG.detect_frontend == "binary"
+        assert samsung_engine._CONFIG.detect_frontend == "binary"
+
+    def test_response_is_contrast_invariant(self):
+        """The whole point: a faint mark and a bold one produce the same response, so a
+        single threshold works for both. Binarizing is what loses the faint one."""
+        import numpy as np
+
+        from remove_ai_watermarks import doubao_engine
+
+        eng = doubao_engine.DoubaoEngine()
+        h, w = 400, 900
+        out = []
+        for amplitude in (12, 90):  # a barely-there overlay and a bold one
+            img = np.full((h, w, 3), 100, np.uint8)
+            loc = eng.locate(img)
+            x, y, bw, bh = loc.bbox
+            img[y + bh // 3 : y + 2 * bh // 3, x + bw // 4 : x + 3 * bw // 4] = 100 + amplitude
+            resp = eng.tophat_response(img, loc)
+            assert resp is not None
+            out.append(resp)
+        # max-normalized, so the two responses agree despite a 7.5x contrast difference
+        assert abs(int(out[0].max()) - int(out[1].max())) <= 1
+
+    def test_flat_input_yields_no_response(self):
+        """A blank corner has no top-hat at all; the engine must return None rather
+        than divide by a zero peak."""
+        import numpy as np
+
+        from remove_ai_watermarks import doubao_engine
+
+        eng = doubao_engine.DoubaoEngine()
+        img = np.full((400, 900, 3), 128, np.uint8)
+        assert eng.tophat_response(img, eng.locate(img)) is None
+
+    def test_threshold_is_frontend_specific(self):
+        """The continuous front-end scores higher overall (0.809 vs 0.723 mean on the
+        same positives), so it needs its own gate; the binary-era 0.40 left the
+        provenance-relaxed gate low enough to admit 8 false fires where 0.50 admits 1."""
+        from remove_ai_watermarks import doubao_engine
+
+        assert doubao_engine._CONFIG.detect_ncc_threshold == 0.50

tests/test_text_mark_faint_mask.py

@@ -0,0 +1,141 @@
+"""A mark the `tophat` front-end DETECTS must also be MASKABLE.
+
+Corpus-found 2026-07-20: Doubao's detection moved to the continuous `tophat` front-end
+(which does not binarize, and that is where its recall 89% -> 92% came from), but the
+removal mask still came from the BINARIZED glyph blob. A mark faint enough to be found
+only by the continuous response therefore produced an empty binary blob, `localize`
+returned mask=None, and `remove()` was a silent no-op: `identify` reported
+`visible_doubao` while `visible` said "no visible mark" on the same file. Measured on the
+full corpus parity sweep: 57 of 60 sampled still-detected Doubao marks were untouched
+no-ops, ~8% of all Doubao detections.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+import pytest
+
+from remove_ai_watermarks.doubao_engine import DoubaoEngine
+
+
+def _faint_mark_image(w: int = 900, h: int = 1200, alpha: float = 0.06, textured: bool = False) -> np.ndarray:
+    """A frame carrying the REAL Doubao glyph shape at very low opacity.
+
+    The shape has to be genuine or the NCC detector will not fire and the test would be
+    exercising nothing; the low ``alpha`` is what keeps the binarizing path from finding
+    a blob. Composited with the same forward model the marks use:
+    ``stamped = (1-a)*bg + a*white``.
+
+    ``textured`` adds fine luminance noise to the background. It is not decoration: on a
+    FLAT frame the top-hat response is non-zero only on the glyph, so every threshold
+    yields the same bounding box and a test built on a flat fixture cannot see a wrong
+    threshold at all -- mutating the constant to an absurd value left the flat tests green.
+    Texture puts response outside the glyph, which is the condition under which the mask's
+    sizing actually matters, and is what real corner backgrounds look like.
+    """
+    from remove_ai_watermarks._text_mark_engine import load_alpha_template
+
+    tmpl = load_alpha_template("doubao_alpha.png")
+    if tmpl is None:
+        pytest.skip("doubao alpha asset unavailable")
+    img = np.full((h, w, 3), 120, np.uint8)
+    if textured:
+        rng = np.random.default_rng(7)
+        noise = rng.normal(0, 14, (h, w, 1)).repeat(3, axis=2)
+        img = np.clip(img.astype(np.float32) + noise, 0, 255).astype(np.uint8)
+        img = cv2.GaussianBlur(img, (0, 0), sigmaX=1.2)
+    eng = DoubaoEngine()
+    loc = eng.locate(img)
+    base = eng.scale_base(img)
+    gw = max(eng.config.min_gw, int(eng.config.alpha_width_frac * base))
+    gh = max(4, int(eng.config.alpha_height_frac * base))
+    a = cv2.resize(tmpl, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32) * alpha
+    x = loc.x + (loc.w - gw) // 2
+    y = loc.y + (loc.h - gh) // 2
+    roi = img[y : y + gh, x : x + gw].astype(np.float32)
+    a3 = a[..., None]
+    img[y : y + gh, x : x + gw] = np.clip(roi * (1 - a3) + 255.0 * a3, 0, 255).astype(np.uint8)
+    return img
+
+
+class TestFaintMarkIsMaskable:
+    def test_binary_glyph_blob_is_empty_on_a_faint_mark(self):
+        """The premise: this is the input class the binarizing path cannot segment."""
+        eng = DoubaoEngine()
+        img = _faint_mark_image()
+        loc = eng.locate(img)
+        glyph = eng.extract_mask(img, loc)
+        assert int((glyph > 0).sum()) < eng._MIN_GLYPH_PIXELS
+
+    def test_footprint_mask_is_not_empty_when_the_continuous_response_has_signal(self):
+        """The fix: a faint mark must still yield a removal mask, without --no-detect.
+
+        Without it `localize` returns None and removal silently does nothing while
+        `identify` keeps reporting the mark.
+        """
+        eng = DoubaoEngine()
+        img = _faint_mark_image()
+        mask = eng.footprint_mask(img, force=False)
+        assert mask is not None, "a detectable faint mark produced no removal mask"
+        assert int((mask > 0).sum()) > 0
+
+    def test_a_clean_frame_still_produces_no_mask(self):
+        """The guard: the fallback must not turn every flat corner into a fill."""
+        eng = DoubaoEngine()
+        clean = cv2.GaussianBlur(np.full((1200, 900, 3), 120, np.uint8), (5, 5), 0)
+        assert eng.footprint_mask(clean, force=False) is None
+
+    @pytest.mark.parametrize("alpha", [0.5, 0.9])
+    def test_a_bold_mark_is_unaffected(self, alpha: float):
+        """A mark the binary path already segments must keep its tight glyph box."""
+        eng = DoubaoEngine()
+        img = _faint_mark_image(alpha=alpha)
+        mask = eng.footprint_mask(img, force=False)
+        assert mask is not None
+        assert int((mask > 0).sum()) > 0
+
+
+class TestFaintMaskStaysTight:
+    """The faint fallback must cover the mark WITHOUT filling the whole corner.
+
+    Corpus-found 2026-07-20: the first version of the fallback thresholded the continuous
+    response at 0.5, but `tophat_response` returns uint8 0..255 -- so it selected every
+    non-zero pixel, not "half the peak" as its comment claimed. On 12 of 12 real frames
+    taking this path the resulting box covered 100% of the corner ROI, so removal inpainted
+    the entire corner instead of the glyph. Parity could not see it: parity asks whether
+    the detector is clean afterwards, and a mask that fills everything passes trivially.
+    The cost, not the outcome, was the defect.
+    """
+
+    def test_mask_does_not_swallow_the_whole_corner_on_a_textured_frame(self):
+        eng = DoubaoEngine()
+        img = _faint_mark_image(alpha=0.10, textured=True)
+        # Asserted, not skipped: a skip here would silently stop guarding the moment the
+        # detector changed, which is exactly when this needs to be guarding.
+        assert eng.detect(img).detected, "fixture must reach the faint path to test it"
+        mask = eng.footprint_mask(img, force=False)
+        assert mask is not None, "a detected faint mark must still produce a mask"
+        area = int((mask > 0).sum())
+        loc = eng.locate(img)
+        roi = loc.w * loc.h
+        # The mark's own glyph box is ~40% of the corner ROI and the mask pads it, so a
+        # correct mask lands near 60%. The pre-fix behaviour measured 120.9% (the whole
+        # ROI plus padding), which this bound excludes.
+        assert area < 0.85 * roi, f"mask covers {100 * area / roi:.0f}% of the corner box"
+
+    def test_mask_still_covers_the_stamped_glyph(self):
+        """Tightness is only a virtue if the mark is still inside. Guards the other way."""
+        eng = DoubaoEngine()
+        img = _faint_mark_image(alpha=0.10, textured=True)
+        assert eng.detect(img).detected, "fixture must reach the faint path to test it"
+        mask = eng.footprint_mask(img, force=False)
+        assert mask is not None
+        loc = eng.locate(img)
+        base = eng.scale_base(img)
+        gw = max(eng.config.min_gw, int(eng.config.alpha_width_frac * base))
+        gh = max(4, int(eng.config.alpha_height_frac * base))
+        x = loc.x + (loc.w - gw) // 2
+        y = loc.y + (loc.h - gh) // 2
+        covered = int(np.count_nonzero(mask[y : y + gh, x : x + gw])) / max(1, gw * gh)
+        assert covered > 0.6, f"mask covers only {100 * covered:.0f}% of the stamped glyph"

tests/test_text_mark_memory.py

@@ -1,19 +1,9 @@
-"""Byte-identity guards for the text-mark engine memory optimization.
+"""Memory guard for the text-mark engine ``extract_mask``.
 
-The reverse-alpha text-mark engine used to allocate full-frame arrays where only
-the glyph footprint is ever read:
-
-  * ``extract_mask`` built a full ``(h, w)`` uint8 mask and every caller cropped
-    it to the located box;
-  * ``_fixed_alpha_map`` / ``_aligned_alpha_map`` each built a full ``(h, w)``
-    float32 alpha map that is non-zero only inside the glyph box, and two were
-    held at once during removal.
-
-Both now return footprint-sized arrays. These tests prove the new footprint-sized
-path is BYTE-IDENTICAL to the old full-frame path by reconstructing the old
-behavior inline from the new building blocks (so the proof survives a cv2/asset
-version bump, unlike a pinned output hash), and lock in the O(footprint) memory
-characteristic so a regression back to a full-frame allocation fails loudly.
+``extract_mask`` used to build a full ``(h, w)`` uint8 mask that every caller
+cropped to the located box; it now returns the box-sized mask directly. This test
+locks in the O(footprint) memory characteristic so a regression back to a
+full-frame allocation fails loudly.
 """
 
 from __future__ import annotations
@@ -38,19 +28,20 @@ ENGINES = [
 
 
 def _watermarked(engine, module) -> np.ndarray:
-    """Composite the engine's real alpha glyph onto a flat mid-gray field at the
-    captured native width (so both placement candidates fire)."""
+    """Composite the engine's real alpha glyph (white) onto a flat mid-gray field at
+    the captured native width, anchored in the mark's configured corner."""
     cfg = engine.config
     nw = module._ALPHA_NATIVE_WIDTH
     at = module._alpha_template()
     gw, gh = int(cfg.alpha_width_frac * nw), int(cfg.alpha_height_frac * nw)
-    ax = (nw - int(cfg.alpha_margin_x_frac * nw) - gw) if cfg.corner == "br" else int(cfg.alpha_margin_x_frac * nw)
-    ay = nw - int(cfg.alpha_margin_bottom_frac * nw) - gh
+    margin = int(0.015 * nw)
+    ax = (nw - margin - gw) if cfg.corner == "br" else margin
+    ay = nw - margin - gh
     amap = np.zeros((nw, nw), np.float32)
     amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
     a3 = amap[:, :, None]
     img = np.full((nw, nw, 3), 100.0, np.float32)
-    return (a3 * np.array(cfg.alpha_logo_bgr, np.float32) + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+    return (a3 * 255.0 + (1 - a3) * img).clip(0, 255).astype(np.uint8)
 
 
 @pytest.mark.parametrize(("factory", "module"), ENGINES)
@@ -65,70 +56,3 @@ class TestExtractMaskFootprint:
         assert box.shape == (loc.h, loc.w)
         # Footprint, not full frame: the box is a tiny fraction of the image.
         assert box.size * 4 < img.shape[0] * img.shape[1]
-
-
-@pytest.mark.parametrize(("factory", "module"), ENGINES)
-class TestAlphaMapFootprint:
-    def test_maps_are_footprint_sized_blocks(self, factory, module):
-        eng = factory()
-        img = _watermarked(eng, module)
-        for placed in (eng._fixed_alpha_map(img), eng._aligned_alpha_map(img)):
-            assert placed is not None
-            block, (ax, ay, gw, gh) = placed
-            assert block.dtype == np.float32
-            assert block.shape == (gh, gw)
-            # The placement stays fully inside the image (no clipping needed).
-            assert ax >= 0
-            assert ax + gw <= img.shape[1]
-            assert ay >= 0
-            assert ay + gh <= img.shape[0]
-            # O(footprint): far smaller than the frame.
-            assert block.size * 4 < img.shape[0] * img.shape[1]
-
-    def test_apply_reverse_alpha_equals_old_fullframe(self, factory, module):
-        """``_apply_reverse_alpha`` with the glyph block is byte-identical to the
-        old full-frame path: rebuild the full ``(h, w)`` map, run the old-style
-        full-frame reverse-alpha, and compare to the new block-based output."""
-        eng = factory()
-        img = _watermarked(eng, module)
-        h, w = img.shape[:2]
-        for placed in (eng._fixed_alpha_map(img), eng._aligned_alpha_map(img)):
-            assert placed is not None
-            block, region = placed
-            ax, ay, gw, gh = region
-
-            new_out = eng._apply_reverse_alpha(img, block, region)
-
-            # Old behavior: a full-frame map, indexed by region inside _apply_reverse_alpha.
-            full = np.zeros((h, w), np.float32)
-            full[ay : ay + gh, ax : ax + gw] = block
-            old_out = img.copy()
-            a3 = np.clip(full[ay : ay + gh, ax : ax + gw], 0.0, 1.0)[:, :, None]
-            logo = np.array(eng.config.alpha_logo_bgr, np.float32)
-            roi = old_out[ay : ay + gh, ax : ax + gw].astype(np.float32)
-            old_out[ay : ay + gh, ax : ax + gw] = np.clip(
-                (roi - a3 * logo) / np.clip(1.0 - a3, 0.25, 1.0), 0, 255
-            ).astype(np.uint8)
-
-            assert np.array_equal(new_out, old_out)
-
-    def test_residual_mask_equals_old_fullframe(self, factory, module):
-        """The residual inpaint mask built from the block embedded in a full-frame
-        canvas equals thresholding the old full-frame float32 map (zero outside the
-        block), so the dilate + inpaint see the same mask."""
-        eng = factory()
-        img = _watermarked(eng, module)
-        h, w = img.shape[:2]
-        cfg = eng.config
-        block, (ax, ay, gw, gh) = eng._fixed_alpha_map(img)
-
-        # New: embed the block into a uint8 canvas, then threshold.
-        new_mask = np.zeros((h, w), np.uint8)
-        new_mask[ay : ay + gh, ax : ax + gw] = (block > cfg.residual_alpha_floor).astype(np.uint8) * 255
-
-        # Old: a full-frame float32 map, thresholded everywhere.
-        old_full = np.zeros((h, w), np.float32)
-        old_full[ay : ay + gh, ax : ax + gw] = block
-        old_mask = (old_full > cfg.residual_alpha_floor).astype(np.uint8) * 255
-
-        assert np.array_equal(new_mask, old_mask)

tests/test_text_mark_oversubtraction.py

@@ -1,120 +0,0 @@
-"""Reverse-alpha over-subtraction guard for the visible text-mark engines.
-
-Ported from the Gemini sparkle fix (commit 41f6797) to Doubao/Jimeng/Samsung
-(retained-corpus mining 2026-06-20, roadmap P0#8): on a dark or mid-tone
-background the captured alpha can over-estimate THIS image's mark opacity, and
-reverse-alpha leaves a darker-than-background glyph ghost (a "dark pit") instead
-of recovering the true pixels. The guard predicts the reverse-alpha output per
-pixel and, when the glyph body lands far below the local ring, reconstructs the
-footprint from the original surroundings instead of shipping the pit.
-
-These assert visual residual (pixel levels vs the local background), not just a
-detector re-fire -- a dark pit can clear the NCC detector while still looking wrong.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-import pytest
-
-from remove_ai_watermarks import image_io
-from remove_ai_watermarks._text_mark_engine import _OVERSUB_DARK_MARGIN
-from remove_ai_watermarks.doubao_engine import DoubaoEngine
-from remove_ai_watermarks.jimeng_engine import JimengEngine
-from remove_ai_watermarks.samsung_engine import SamsungEngine
-
-_ENGINES = [DoubaoEngine, JimengEngine, SamsungEngine]
-
-
-def _compose(engine, bg: float, opacity_gain: float, w: int = 1024, h: int = 1024):
-    """Composite the engine's captured mark onto a flat ``bg`` at ``opacity_gain``.
-
-    ``opacity_gain < 1`` makes the mark FAINTER than the capture, so reverse-alpha
-    at the full captured alpha over-subtracts into a dark pit -- the case the guard
-    must catch. Returns ``(watermarked_uint8, alpha_block, region)`` where the block
-    and region are exactly what the engine's reverse-alpha receives.
-    """
-    img = np.full((h, w, 3), float(bg), np.float32)
-    block, (ax, ay, gw, gh) = engine._fixed_alpha_map(img)
-    a = np.clip(block * opacity_gain, 0.0, 0.99)[:, :, None]
-    logo = np.array(engine.config.alpha_logo_bgr, np.float32)
-    img[ay : ay + gh, ax : ax + gw] = img[ay : ay + gh, ax : ax + gw] * (1 - a) + logo * a
-    return np.clip(img, 0, 255).astype(np.uint8), block, (ax, ay, gw, gh)
-
-
-def _body_vs_ring(out, region, block) -> tuple[float, float]:
-    """Median luma of the glyph body vs the local background ring in ``out``."""
-    ax, ay, gw, gh = region
-    g = out.astype(np.float32).mean(axis=2)
-    body = block >= 0.15
-    pad = max(4, int(gh * 0.6))
-    ry1, ry2 = max(0, ay - pad), min(g.shape[0], ay + gh + pad)
-    rx1, rx2 = max(0, ax - pad), min(g.shape[1], ax + gw + pad)
-    ring = g[ry1:ry2, rx1:rx2]
-    fy1, fy2, fx1, fx2 = ay - ry1, ay - ry1 + gh, ax - rx1, ax - rx1 + gw
-    ring_mask = np.ones(ring.shape, dtype=bool)
-    ring_mask[fy1:fy2, fx1:fx2] = False
-    core = float(np.median(g[ay : ay + gh, ax : ax + gw][body]))
-    return core, float(np.median(ring[ring_mask]))
-
-
-@pytest.mark.parametrize("Engine", _ENGINES, ids=lambda e: e.__name__)
-class TestOversubtractionGuard:
-    @pytest.mark.parametrize(("bg", "gain"), [(120, 0.45), (150, 0.4), (90, 0.5)])
-    def test_guard_trips_on_faint_mark(self, Engine, bg, gain):
-        eng = Engine()
-        wm, block, region = _compose(eng, bg, gain)
-        assert eng._reverse_alpha_oversubtracts(image_io.to_bgr(wm), block, region)
-
-    @pytest.mark.parametrize("bg", [255, 200, 128, 60])
-    def test_guard_skips_clean_full_strength_mark(self, Engine, bg):
-        # A cleanly captured (gain 1.0) mark predicts back to the background, so the
-        # guard must NOT trip -- no regression of the common clean-removal path.
-        eng = Engine()
-        wm, block, region = _compose(eng, bg, 1.0)
-        assert not eng._reverse_alpha_oversubtracts(image_io.to_bgr(wm), block, region)
-
-    @pytest.mark.parametrize(("bg", "gain"), [(120, 0.45), (150, 0.4)])
-    def test_faint_removal_leaves_no_dark_pit(self, Engine, bg, gain):
-        # End-to-end acceptance (roadmap P0#8): after removal the glyph footprint is
-        # not a region more than _OVERSUB_DARK_MARGIN below the local background.
-        eng = Engine()
-        wm, block, region = _compose(eng, bg, gain)
-        out = eng.remove_watermark_reverse_alpha(wm)
-        core, ring_bg = _body_vs_ring(out, region, block)
-        assert core >= ring_bg - _OVERSUB_DARK_MARGIN, f"dark pit: body {core:.0f} vs ring {ring_bg:.0f}"
-
-    def test_clean_mark_removal_unchanged_by_guard(self, Engine, monkeypatch):
-        # On a clean mark the guard must be a no-op: forcing it off yields the same
-        # output (the guard only ever diverts the over-subtraction case).
-        eng = Engine()
-        wm, _block, _region = _compose(eng, 200, 1.0)
-        guarded = eng.remove_watermark_reverse_alpha(wm)
-        monkeypatch.setattr(type(eng), "_reverse_alpha_oversubtracts", lambda self, *a, **k: False)
-        unguarded = eng.remove_watermark_reverse_alpha(wm)
-        assert np.array_equal(guarded, unguarded)
-
-
-@pytest.mark.parametrize("Engine", _ENGINES, ids=lambda e: e.__name__)
-def test_guard_recovers_pit_on_textured_background(Engine):
-    """The guard's footprint inpaint reconstructs from the ORIGINAL surroundings,
-    so a faint mark over-subtracted on a textured background recovers to roughly the
-    local content level rather than a glyph-shaped dark ghost."""
-    eng = Engine()
-    w = h = 1024
-    yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
-    base = 120 + 35 * np.sin(xx / 80.0) + 25 * np.cos(yy / 60.0)
-    bg_img = np.clip(np.stack([base, base * 0.95, base * 1.05], axis=-1), 0, 255)
-    block, (ax, ay, gw, gh) = eng._fixed_alpha_map(bg_img)
-    a = np.clip(block * 0.45, 0.0, 0.99)[:, :, None]
-    logo = np.array(eng.config.alpha_logo_bgr, np.float32)
-    bg_img[ay : ay + gh, ax : ax + gw] = bg_img[ay : ay + gh, ax : ax + gw] * (1 - a) + logo * a
-    wm = np.clip(bg_img, 0, 255).astype(np.uint8)
-    out = eng.remove_watermark_reverse_alpha(wm).astype(np.float32)
-    # Compare the recovered glyph body to the clean texture under the mark.
-    clean = np.clip(np.stack([base, base * 0.95, base * 1.05], axis=-1), 0, 255)
-    body = block >= 0.15
-    region_out = out[ay : ay + gh, ax : ax + gw].mean(axis=2)
-    region_clean = clean[ay : ay + gh, ax : ax + gw].mean(axis=2)
-    err = float(np.abs(region_out[body] - region_clean[body]).mean())
-    assert err < 25.0, f"glyph body not recovered (mean abs err {err:.1f})"

tests/test_watermark_profiles.py

@@ -0,0 +1,48 @@
+"""Pure tests for the strength/steps profile helpers (no model, no torch needed)."""
+
+from __future__ import annotations
+
+import pytest
+
+from remove_ai_watermarks.noai.watermark_profiles import resolve_strength, viable_steps
+
+
+class TestViableSteps:
+    """Guards the crash found by the release smoke matrix on 2026-07-19.
+
+    diffusers derives its img2img timesteps as ``int(steps * strength)``. When that
+    rounds to zero the pipeline builds an empty tensor and dies deep inside attention
+    with "cannot reshape tensor of 0 elements into shape [0, -1, 1, 512]". At the
+    default strength 0.15 that was every ``--steps`` below 7, reachable with entirely
+    valid CLI arguments and no special flags.
+    """
+
+    @pytest.mark.parametrize(
+        ("steps", "strength"),
+        [(1, 0.15), (2, 0.15), (5, 0.15), (6, 0.15), (5, 0.10), (9, 0.10), (1, 0.5)],
+    )
+    def test_never_returns_a_count_that_denoises_zero_steps(self, steps: int, strength: float):
+        assert int(viable_steps(steps, strength) * strength) >= 1
+
+    @pytest.mark.parametrize(
+        ("steps", "strength"),
+        [(50, 0.15), (20, 0.15), (7, 0.15), (10, 0.10), (2, 0.5), (50, 1.0)],
+    )
+    def test_leaves_a_workable_count_untouched(self, steps: int, strength: float):
+        assert viable_steps(steps, strength) == steps
+
+    def test_raises_only_to_the_minimum_needed(self):
+        # strength 0.15 needs 7 (int(7*0.15)==1); it must not jump to some larger default.
+        assert viable_steps(5, 0.15) == 7
+        assert viable_steps(1, 0.10) == 10
+
+    def test_the_vendor_defaults_all_have_a_reachable_floor(self):
+        for vendor in (None, "openai", "google"):
+            strength = resolve_strength(None, vendor)
+            assert int(viable_steps(1, strength) * strength) >= 1
+
+    @pytest.mark.parametrize("strength", [0.0, -0.1])
+    def test_a_non_positive_strength_cannot_loop_or_divide_by_zero(self, strength: float):
+        # No denoising is possible at all here; return the caller's value rather than
+        # dividing by zero or spinning.
+        assert viable_steps(20, strength) == 20

tests/test_watermark_registry.py

@@ -1,4 +1,4 @@
-"""Tests for the known-visible-watermark registry (reverse-alpha only)."""
+"""Tests for the known-visible-watermark registry (localize -> fill)."""
 
 from __future__ import annotations
 
@@ -14,17 +14,28 @@ DOUBAO_SAMPLE = Path(__file__).resolve().parents[1] / "data" / "samples" / "doub
 
 class TestCatalog:
     def test_keys(self):
-        assert reg.mark_keys() == ["gemini", "doubao", "jimeng", "samsung", "jimeng_pill"]
+        assert reg.mark_keys() == [
+            "gemini",
+            "doubao",
+            "jimeng",
+            "qwen",
+            "kling",
+            "samsung",
+            "runninghub",
+            "baidu",
+            "liblib",
+            "jimeng_pill",
+        ]
 
     def test_all_in_auto(self):
         assert all(m.in_auto for m in reg.known_marks())
 
-    def test_recovery(self):
-        # Capture marks recover by reverse-alpha; the capture-less pill is inpaint-only.
-        by_key = {m.key: m for m in reg.known_marks()}
-        assert all(by_key[k].recovery == "reverse-alpha" for k in ("gemini", "doubao", "jimeng", "samsung"))
-        assert by_key["jimeng_pill"].recovery == "inpaint"
-        assert by_key["jimeng_pill"].has_capture is False
+    def test_marks_expose_detect_and_mask(self):
+        # Every mark drives the uniform localize -> fill contract: a detect callable
+        # (verdict + bbox, no mask) and a mask callable (full-frame footprint).
+        for m in reg.known_marks():
+            assert callable(m._detect)
+            assert callable(m._mask)
 
     def test_locations(self):
         by_key = {m.key: m for m in reg.known_marks()}
@@ -43,34 +54,380 @@ class TestScan:
     def test_detect_marks_scans_all(self):
         img = np.zeros((256, 256, 3), np.uint8)
         keys = {d.key for d in reg.detect_marks(img)}
-        assert keys == {"gemini", "doubao", "jimeng", "samsung", "jimeng_pill"}
+        assert keys == {
+            "gemini",
+            "doubao",
+            "jimeng",
+            "qwen",
+            "kling",
+            "samsung",
+            "runninghub",
+            "baidu",
+            "liblib",
+            "jimeng_pill",
+        }
 
     def test_blank_image_no_auto_mark(self):
-        assert reg.best_auto_mark(np.zeros((256, 256, 3), np.uint8)) is None
+        dets = reg.detect_marks(np.zeros((256, 256, 3), np.uint8), include_explicit=False)
+        assert not any(d.detected for d in dets)
+
+    @pytest.mark.parametrize("shape", [(1, 1, 3), (8, 8, 3), (15, 15, 3), (12, 300, 3), (300, 10, 3)])
+    def test_tiny_image_no_crash(self, shape):
+        """Regression: an image whose short side is < 16 px (below the Gemini template
+        floor) must yield no detection, not crash. detect_marks/remove_auto_marks are
+        the public visible/all/batch path; a tiny thumbnail in a batch used to take the
+        whole auto pass down with an IndexError (empty candidate list dereference)."""
+        img = np.full(shape, 100, np.uint8)
+        assert not any(d.detected for d in reg.detect_marks(img, include_explicit=False))
+        result, removed = reg.remove_auto_marks(img, backend="cv2")
+        assert removed == []
+        assert result.shape == img.shape
+
+    @pytest.mark.parametrize("shape", [(0, 5), (5, 0), (0, 5, 4), (0, 0)])
+    def test_forced_remove_on_empty_array_no_crash(self, shape):
+        """Regression: footprint_mask ran to_bgr (cvtColor) before any size check, so a
+        forced remove on a zero-size ndarray crashed (cv2.error on an empty Mat). detect
+        already guarded this; footprint_mask must too. Covers the text + gemini engines."""
+        empty = np.zeros(shape, np.uint8)
+        for key in ("doubao", "jimeng", "qwen", "samsung", "gemini"):
+            _result, mask = reg.get_mark(key).remove(empty, force=True)
+            assert mask is None
+
+
+class TestBackendResolution:
+    def test_auto_resolves_to_available_backend(self):
+        assert reg.resolve_backend("auto") in ("cv2", "migan", "lama")
+
+    def test_explicit_backend_passes_through(self):
+        assert reg.resolve_backend("cv2") == "cv2"
+        assert reg.resolve_backend("lama") == "lama"
+
+    def test_cv2_fallback_warns_once(self, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture):
+        import logging
+
+        from remove_ai_watermarks import region_eraser
+
+        monkeypatch.setattr(region_eraser, "lama_available", lambda: False)
+        monkeypatch.setattr(region_eraser, "migan_available", lambda: False)
+        monkeypatch.setattr(reg, "_warned_cv2_fallback", False)
+        with caplog.at_level(logging.WARNING):
+            assert reg.preferred_inpaint_backend() == "cv2"
+            assert reg.preferred_inpaint_backend() == "cv2"
+        assert sum("cv2 classical inpaint" in r.message for r in caplog.records) == 1
+
+
+class TestFill:
+    def test_fill_erases_masked_region(self):
+        # A bright square on a flat field, masked, is inpainted away (cv2 backend).
+        img = np.full((128, 128, 3), 60, np.uint8)
+        img[40:70, 40:70] = 240
+        mask = np.zeros((128, 128), np.uint8)
+        mask[36:74, 36:74] = 255
+        out = reg.fill(img, mask, backend="cv2")
+        assert out.shape == img.shape
+        # the masked bright square is pulled toward the surrounding field
+        assert int(out[55, 55].mean()) < 160
+
+    def test_fill_empty_mask_is_noop(self):
+        img = np.full((64, 64, 3), 100, np.uint8)
+        out = reg.fill(img, np.zeros((64, 64), np.uint8), backend="cv2")
+        assert np.array_equal(out, img)
+
+
+class TestProvenanceGate:
+    """The Gemini trust gate relaxes from GEMINI_SPARKLE_TRUST_CONF to
+    _GEMINI_PROVENANCE_MIN_CONF when provenance confirms Google; tested
+    deterministically by stubbing the engine's raw detection confidence."""
+
+    def _stub(self, monkeypatch: pytest.MonkeyPatch, conf: float) -> None:
+        from remove_ai_watermarks.gemini_engine import DetectionResult
+
+        # `detected` mirrors the engine's own internal floor (0.35), which is
+        # independent of the registry gate under test here.
+        def fake_detect(image, force_size=None, *, trust_provenance=False):
+            return DetectionResult(detected=conf >= 0.35, confidence=conf, region=(10, 10, 48, 48))
+
+        monkeypatch.setattr(reg._engine("gemini"), "detect_watermark", fake_detect)
+
+    def test_midband_conf_needs_provenance(self, monkeypatch: pytest.MonkeyPatch):
+        # Comfortably inside the relaxed band: demoted without provenance, trusted with it.
+        conf = (reg._GEMINI_PROVENANCE_MIN_CONF + reg.GEMINI_SPARKLE_TRUST_CONF) / 2
+        self._stub(monkeypatch, conf)
+        img = np.zeros((256, 256, 3), np.uint8)
+        assert reg.get_mark("gemini").detect(img).detected is False
+        assert reg.get_mark("gemini").detect(img, provenance=True).detected is True
+
+    def test_below_provenance_gate_rejected_even_with_provenance(self, monkeypatch: pytest.MonkeyPatch):
+        """Provenance relaxes the gate, it does not remove it.
+
+        Guards the 2026-07-18 raise of _GEMINI_PROVENANCE_MIN_CONF (0.35 -> 0.42).
+        The engine still reports `detected` down at its own 0.35 floor, so without
+        the registry gate this confidence would be accepted and inpainted. Measured
+        precision just below the gate was 13% (n=30, 95% CI 5-30%) on real
+        Google-metadata uploads -- i.e. ~7 of 8 accepts there destroy pixels on an
+        image that never carried a sparkle, and report a removal that did not happen.
+        """
+        # 0.38 is inside the measured 13%-precision band and above the engine's own
+        # 0.35 floor, so the engine reports `detected` and only the registry gate can
+        # reject it. Hardcoded on purpose: if the gate is ever lowered back under this
+        # value, this test must fail on the BEHAVIOUR below, not on its own arithmetic.
+        self._stub(monkeypatch, 0.38)
+        img = np.zeros((256, 256, 3), np.uint8)
+        assert reg.get_mark("gemini").detect(img).detected is False
+        assert reg.get_mark("gemini").detect(img, provenance=True).detected is False
+
+    def test_provenance_gate_stays_below_the_strict_gate(self):
+        """The relaxed gate must actually relax, and must not collapse onto the floor."""
+        assert 0.35 < reg._GEMINI_PROVENANCE_MIN_CONF < reg.GEMINI_SPARKLE_TRUST_CONF
+
+    def test_high_conf_detected_either_way(self, monkeypatch: pytest.MonkeyPatch):
+        self._stub(monkeypatch, 0.72)
+        img = np.zeros((256, 256, 3), np.uint8)
+        assert reg.get_mark("gemini").detect(img).detected is True
+        assert reg.get_mark("gemini").detect(img, provenance=True).detected is True
 
 
 @pytest.mark.skipif(not DOUBAO_SAMPLE.exists(), reason="doubao sample not present")
 class TestRealSample:
-    def test_doubao_sample_wins_auto(self):
+    def test_doubao_sample_detected(self):
         from remove_ai_watermarks.image_io import imread
 
-        best = reg.best_auto_mark(imread(DOUBAO_SAMPLE))
-        assert best is not None
-        assert best.key == "doubao"
+        fired = [d.key for d in reg.detect_marks(imread(DOUBAO_SAMPLE), include_explicit=False) if d.detected]
+        assert "doubao" in fired
 
     def test_doubao_remove_returns_region(self):
         from remove_ai_watermarks.image_io import imread
 
-        img = imread(DOUBAO_SAMPLE)  # 2048 wide -> reverse-alpha applies
-        result, region = reg.get_mark("doubao").remove(img)
+        img = imread(DOUBAO_SAMPLE)
+        result, region = reg.get_mark("doubao").remove(img, backend="cv2")
         assert region is not None
         assert result.shape == img.shape
 
 
-class TestReverseAlphaOnly:
-    def test_doubao_off_resolution_is_skipped(self):
-        # No alpha capture for this width -> no inpaint fallback, image untouched.
+class TestLocalizeFill:
+    def test_clean_corner_is_untouched(self):
+        # No glyph in the corner -> no mask -> remove is a no-op copy.
         img = np.zeros((512, 512, 3), np.uint8)
-        result, region = reg.get_mark("doubao").remove(img)
+        result, region = reg.get_mark("doubao").remove(img, backend="cv2")
         assert region is None
         assert np.array_equal(result, img)
+
+
+class TestSensitivity:
+    """``resolve_trust`` turns the sensitivity policy + evidence into the per-mark
+    trust level the engines consume."""
+
+    def test_strict_never_relaxes(self):
+        # even with metadata provenance, strict keeps the conservative gate
+        assert (
+            reg.resolve_trust("gemini", sensitivity="strict", provenance=frozenset({"gemini"}), strict_keys=set())
+            == "strict"
+        )
+
+    def test_auto_relaxes_on_own_metadata(self):
+        assert (
+            reg.resolve_trust("gemini", sensitivity="auto", provenance=frozenset({"gemini"}), strict_keys=set())
+            == "confirmed"
+        )
+
+    def test_auto_strict_without_evidence(self):
+        assert reg.resolve_trust("gemini", sensitivity="auto", provenance=frozenset(), strict_keys=set()) == "strict"
+
+    def test_auto_cross_mark_same_product(self):
+        # a detected Jimeng wordmark relaxes the Jimeng pill (same product, other corner)
+        assert (
+            reg.resolve_trust("jimeng_pill", sensitivity="auto", provenance=frozenset(), strict_keys={"jimeng"})
+            == "confirmed"
+        )
+
+    def test_auto_no_cross_mark_across_products(self):
+        # a detected Jimeng wordmark must NOT relax Doubao (distinct products, same corner)
+        assert (
+            reg.resolve_trust("doubao", sensitivity="auto", provenance=frozenset(), strict_keys={"jimeng"}) == "strict"
+        )
+
+    def test_remove_auto_marks_accepts_all_sensitivities(self):
+        blank = np.zeros((256, 256, 3), np.uint8)
+        for s in ("auto", "strict"):
+            _, removed = reg.remove_auto_marks(blank, sensitivity=s, backend="cv2")
+            assert removed == []
+
+
+class TestNoBlanketRelaxation:
+    """There is NO path that relaxes a mark's gate without same-product evidence.
+
+    ``assume_ai`` was that path and was removed 2026-07-19: it bypassed every mark's
+    false-positive gate on the caller's bare assertion that the image is AI, which says
+    nothing about WHICH vendor or WHERE -- exactly what the bypass is contracted to
+    require. Before it carried a confidence floor it filled a phantom sparkle on 59.8%
+    of genuine camera photos. A user who can SEE a mark is served by `erase --region`
+    (they supply the coordinates) or `--mark <name> --no-detect` for a text mark.
+    """
+
+    def test_sensitivity_has_exactly_two_levels(self):
+        import typing
+
+        assert set(typing.get_args(reg.Sensitivity)) == {"auto", "strict"}
+
+    def test_trust_ladder_has_no_assumed_level(self):
+        import typing
+
+        assert set(typing.get_args(reg.Trust)) == {"strict", "confirmed"}
+
+    def test_no_sensitivity_relaxes_without_same_product_evidence(self):
+        for sens in ("auto", "strict"):
+            assert reg.resolve_trust("gemini", sensitivity=sens, provenance=frozenset(), strict_keys=set()) == "strict"
+
+    def test_the_assumed_floor_helper_is_gone(self):
+        """It existed only to make the blanket relaxation tolerable."""
+        assert not hasattr(reg, "assumed_floor_ok")
+        assert not hasattr(reg, "_ASSUMED_CONF_FLOOR")
+
+    def test_the_removed_value_raises_instead_of_silently_meaning_auto(self):
+        """`Sensitivity` is a Literal and unenforced at runtime, so a 0.15 caller passing
+        the removed value would quietly get `auto` -- a silent semantic change on exactly
+        the release where they need to be told. The error names the replacement."""
+        import pytest
+
+        with pytest.raises(ValueError, match="erase"):
+            reg.validate_sensitivity("assume_ai")
+        with pytest.raises(ValueError, match="unknown sensitivity"):
+            reg.validate_sensitivity("aggressive")
+        assert reg.validate_sensitivity("auto") == "auto"
+        assert reg.validate_sensitivity("strict") == "strict"
+
+    def test_context_rejects_it_too(self):
+        """The arbiter's own entry point validates, so a direct `decide()` caller cannot
+        smuggle the removed mode past the public API."""
+        import pytest
+
+        with pytest.raises(ValueError, match=r"removed in 0\.16"):
+            reg.Context(sensitivity="assume_ai")
+
+
+class TestArbiter:
+    """``decide`` is the PURE removal arbiter: (candidates, context) -> ordered
+    winners, no image / no I/O. Tested in isolation by handing it fabricated
+    Candidates -- this is the payoff of separating decision from perception."""
+
+    @staticmethod
+    def _c(key, *, strict=False, relaxed=False, flat=False):
+        feats = {"footprint_flat": 1.0} if flat else {}
+        return reg.Candidate(key, f"L:{key}", strict, relaxed, feats)
+
+    def _keys(self, cands, ctx):
+        return {d.candidate.key for d in reg.decide(cands, ctx)}
+
+    def test_empty(self):
+        assert reg.decide([], reg.Context()) == []
+
+    def test_strict_uses_strict_verdict(self):
+        # relaxed-only detection must NOT fire under strict
+        assert self._keys([self._c("gemini", relaxed=True)], reg.Context(sensitivity="strict")) == set()
+
+    def test_auto_relaxes_on_provenance(self):
+        c = [self._c("gemini", relaxed=True)]
+        assert self._keys(c, reg.Context(provenance=frozenset({"gemini"}))) == {"gemini"}
+        assert self._keys(c, reg.Context()) == set()  # no evidence -> strict verdict (not fired)
+
+    def test_cross_mark_relaxes_pill_via_jimeng(self):
+        cands = [self._c("jimeng", strict=True, relaxed=True), self._c("jimeng_pill", relaxed=True, flat=True)]
+        assert self._keys(cands, reg.Context()) == {"jimeng", "jimeng_pill"}
+
+    def test_pill_dropped_on_doubao(self):
+        cands = [
+            self._c("doubao", strict=True, relaxed=True),
+            self._c("jimeng_pill", strict=True, relaxed=True, flat=True),
+        ]
+        keys = self._keys(cands, reg.Context(provenance=frozenset({"jimeng"})))
+        assert "doubao" in keys
+        assert "jimeng_pill" not in keys
+
+    def test_pill_dropped_on_qwen(self):
+        # A Qwen frame is TC260 too but is not Jimeng-basic either: a confident
+        # bottom-right 千问AI生成 detection suppresses the pill exactly like Doubao's.
+        cands = [
+            self._c("qwen", strict=True, relaxed=True),
+            self._c("jimeng_pill", strict=True, relaxed=True, flat=True),
+        ]
+        keys = self._keys(cands, reg.Context(provenance=frozenset({"jimeng"})))
+        assert "qwen" in keys
+        assert "jimeng_pill" not in keys
+
+    def test_pill_metadata_arm_gated_on_flatness(self):
+        ctx = reg.Context(provenance=frozenset({"jimeng"}))
+        assert self._keys([self._c("jimeng_pill", strict=True, relaxed=True, flat=True)], ctx) == {"jimeng_pill"}
+        assert self._keys([self._c("jimeng_pill", strict=True, relaxed=True, flat=False)], ctx) == set()
+
+    def test_pill_wordmark_arm_ignores_flatness(self):
+        # wordmark present -> pill removed even on a textured (non-flat) footprint
+        cands = [
+            self._c("jimeng", strict=True, relaxed=True),
+            self._c("jimeng_pill", strict=True, relaxed=True, flat=False),
+        ]
+        assert "jimeng_pill" in self._keys(cands, reg.Context())
+
+    def test_weak_pill_detection_does_not_confirm_the_jimeng_wordmark(self):
+        """The pill is too false-fire-prone (~7%) to grant a sibling `confirmed` trust.
+
+        Corpus-measured defect (2026-07-18): a pill false fire on clean non-ByteDance
+        content confirmed jimeng, relaxing its NCC gate 0.45 -> 0.3825; jimeng then
+        false-fired, and _keep_pill's wordmark arm removed the pill UNRESTRICTED,
+        skipping the flatness guard. Closed loop on the default `auto` path.
+        """
+        # Only the pill is strictly detected. jimeng scores in the band that is
+        # reachable ONLY via the relaxed gate.
+        cands = [
+            self._c("jimeng_pill", strict=True, relaxed=True, flat=False),
+            self._c("jimeng", strict=False, relaxed=True),
+        ]
+        fired = {d.candidate.key for d in reg.decide(cands, reg.Context("auto", frozenset()))}
+        assert "jimeng" not in fired, "a weak pill hit must not relax the jimeng wordmark"
+        # and with jimeng gone, the pill loses the wordmark arm too -- no unrestricted
+        # removal of a textured footprint on content nothing confirmed.
+        assert "jimeng_pill" not in fired
+
+    def test_real_jimeng_wordmark_still_corroborates_the_pill(self):
+        """The fix removes only the pill's TESTIMONY, not the wordmark's."""
+        cands = [
+            self._c("jimeng", strict=True, relaxed=True),
+            self._c("jimeng_pill", strict=True, relaxed=True, flat=False),
+        ]
+        fired = {d.candidate.key for d in reg.decide(cands, reg.Context("auto", frozenset()))}
+        assert fired == {"jimeng", "jimeng_pill"}
+
+
+class TestProvenanceMaskThreading:
+    """Regression for the provenance-relaxed Gemini no-op (#1) and the false 'removed'
+    label (#2). Before the fix, footprint_mask re-detected WITHOUT trust_provenance, the
+    FP gate demoted the sparkle to detected=False, the mask came back None, yet
+    remove_auto_marks still reported the mark as removed."""
+
+    def test_relaxed_sparkle_yields_mask(self, monkeypatch: pytest.MonkeyPatch):
+        # A sparkle a strict re-detect would demote (detected False) but a
+        # provenance-relaxed detect accepts must still produce a removal mask.
+        from remove_ai_watermarks.gemini_engine import DetectionResult
+
+        def fake(image, force_size=None, *, trust_provenance=False):
+            return DetectionResult(
+                detected=trust_provenance, confidence=0.42 if trust_provenance else 0.30, region=(400, 400, 60)
+            )
+
+        monkeypatch.setattr(reg._engine("gemini"), "detect_watermark", fake)
+        img = np.full((512, 512, 3), 90, np.uint8)
+        assert reg.get_mark("gemini").localize(img, provenance=True).mask is not None
+        assert reg.get_mark("gemini").localize(img, provenance=False).mask is None
+
+    def test_no_label_when_mask_none(self, monkeypatch: pytest.MonkeyPatch):
+        # A decided mark whose mask comes back None must NOT be reported as removed.
+        from remove_ai_watermarks.gemini_engine import DetectionResult
+
+        eng = reg._engine("gemini")
+        monkeypatch.setattr(
+            eng,
+            "detect_watermark",
+            lambda image, force_size=None, *, trust_provenance=False: DetectionResult(True, 0.9, (10, 10, 40)),
+        )
+        monkeypatch.setattr(eng, "footprint_mask", lambda image, *, force=False, region=None, dilate=None: None)
+        _, removed = reg.remove_auto_marks(np.zeros((256, 256, 3), np.uint8), sensitivity="strict", backend="cv2")
+        assert "Google Gemini sparkle" not in removed

typings/piexif/__init__.pyi

@@ -14,7 +14,9 @@ class ImageIFD:
     Artist: int
     ImageDescription: int
 
-class ExifIFD: ...
+class ExifIFD:
+    UserComment: int
+
 class GPSIFD: ...
 
 def load(input_data: bytes | str, key_is_name: bool = ...) -> dict[str, Any]: ...