chore(release): v0.10.0

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -1,3 +1,3 @@
-# HuggingFace token (required for invisible watermark removal)
+# HuggingFace token (optional; only needed for gated/private models)
 # Get yours at: https://huggingface.co/settings/tokens
 HF_TOKEN=

.github/workflows/publish.yml

@@ -17,8 +17,25 @@ jobs:
 
       - uses: astral-sh/setup-uv@v7
 
+      - name: Verify release tag matches package version
+        run: |
+          tag="${{ github.event.release.tag_name }}"
+          version="$(grep -m1 '^version = ' pyproject.toml | sed -E 's/^version = "([^"]+)"/\1/')"
+          if [ "${tag#v}" != "$version" ]; then
+            echo "Release tag '$tag' does not match pyproject.toml version '$version'" >&2
+            exit 1
+          fi
+          echo "Release tag '$tag' matches package version '$version'"
+
       - name: Build package
         run: uv build
 
+      # Publish with `uv publish` (its own uploader, not the twine bundled in the
+      # old pypa action). Trusted publishing is automatic in GitHub Actions: the
+      # `id-token: write` permission + the `pypi` environment supply the OIDC token,
+      # and PyPI's trusted-publisher entry matches on repo + workflow filename +
+      # environment name (all unchanged from the pypa-action setup), so no API token
+      # is needed. uv's uploader also accepts Metadata-Version 2.5 -- the permanent
+      # fix that lets the hatchling pin be relaxed (see pyproject [build-system]).
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        run: uv publish

.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Sync dev environment
+        run: uv sync --frozen --extra dev
+      - name: Ruff lint
+        run: uv run ruff check
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+  test:
+    name: test ${{ matrix.os }} py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Cross-OS x Python-floor/recent. The default-install surface only
+        # needs the core deps plus dev tooling (no GPU extra): the model-running
+        # paths are availability-gated and skip when torch/diffusers are absent,
+        # so this matrix exercises metadata, identify, visible, and the cv2
+        # eraser on every OS without pulling the heavy ML stack.
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync dev environment
+        run: uv sync --frozen --extra dev
+      - name: Run tests
+        run: uv run pytest -q

.gitignore

@@ -34,10 +34,21 @@ yolov8n.pt
 
 # Claude Code local settings
 .claude/settings.local.json
+.claude/scheduled_tasks.lock
 
-# Doubao watermark calibration (local only; ship only the derived alpha-map asset).
-# Synthetic seeds + raw Doubao captures are regenerable and not committed.
-# Non-ours reference artifacts go in any _refs/ dir (already ignored above): usable
-# locally for bootstrap/validation, never redistributed in the repo.
+# Visible-watermark alpha calibration. The solid black/gray/white CAPTURES are
+# committed (content-free: a solid colour + the watermark; the source for
+# scripts/visible_alpha_solve.py so the alpha assets are reproducible). The
+# synthetic seeds (regenerable) and any real-content validation download (a real
+# generated scene, kept local for privacy) are NOT committed.
 data/doubao_capture/seeds/
-data/doubao_capture/captures/
+data/jimeng_capture/seeds/
+data/jimeng_capture/captures/jimeng_content_*.png
+data/gemini_capture/seeds/
+data/gemini_capture/captures/gemini_content_*.png
+data/samsung_capture/seeds/
+data/samsung_capture/captures/samsung_content_*
+
+# GFPGAN downloads its RetinaFace/parsing weights to a CWD ./gfpgan/weights/
+# working dir on first use (the restore extra). Runtime artifact, never committed.
+gfpgan/

.python-version

@@ -0,0 +1 @@
+3.12

CLAUDE.md

@@ -4,64 +4,92 @@ You are a **principal Python engineer** maintaining a CLI tool and library for r
 
 ## How to run
 
-- `uv run remove-ai-watermarks all <image.png> -o <output.png>`
-- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — visible-mark removal, CPU, no GPU. `--mark auto` (default) routes between the Gemini sparkle and the Doubao "豆包AI生成" text strip by detector confidence; `--mark gemini` / `--mark doubao` force one.
+- `uv run remove-ai-watermarks all <image.png> -o <output.png>` — full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible` below, plus the visible-pass `--inpaint/--no-inpaint`/`--inpaint-method`.
+- `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` (default `controlnet`), `--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), and `--adaptive-polish/--no-adaptive-polish` (**ON by default**; detail-targeted polish that self-gates to a no-op where there is no deficit). `--auto` is deprecated and now a no-op that only warns (the polish it used to enable is ON by default).
+- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — known-visible-mark removal, CPU, no GPU. Reverse-alpha based: each mark is removed by inverting its captured alpha map. `--mark auto` (default) picks the strongest detected of the Gemini sparkle, the Doubao "豆包AI生成" text strip, the Jimeng "★ 即梦AI" wordmark, and the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-LEFT, locale-specific — Italian variant calibrated); `--mark gemini` / `--mark doubao` / `--mark jimeng` / `--mark samsung` force one (choices come from the registry). 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`.
 - `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) or `--backend lama` (big-LaMa via onnxruntime, extra `lama`); `--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** (`--strength`/`--steps`/`--guidance-scale`/`--pipeline`/`--controlnet-scale`/`--model`/`--device`/`--max-resolution`/`--min-resolution`/`--upscaler`/`--seed`/`--hf-token`/`--humanize`/`--unsharp`/`--adaptive-polish`), plus `--inpaint/--no-inpaint` for the visible pass. `--adaptive-polish` is ON by default; `--auto` is deprecated and a no-op that only warns. One engine cached per pipeline; the polish is resolved once before the loop.
 
 ## Test and lint
 
+- **CI** (`.github/workflows/test.yml`): runs on push to `main` + every PR. A `lint` job (ubuntu: `ruff check` + `ruff format --check`) plus a `test` matrix (ubuntu/macos/windows x py3.10/3.12) that does `uv sync --frozen --extra dev` then `pytest`. The matrix installs only core + dev (no `gpu` extra), so the GPU/model-running tests skip there and it exercises the metadata/identify/visible/cv2-eraser surface on all three OSes. Keep `uv.lock` valid (don't break `--frozen`) when editing `pyproject.toml`. `publish.yml` stays release-only and now verifies the release tag matches the `pyproject.toml` version (fails the build on a mismatch) before building, then uploads via `uv publish` (PyPI trusted publishing over OIDC, no token — replaced the `pypa/gh-action-pypi-publish` action so the upload no longer depends on that action's bundled twine accepting the Metadata-Version; the `id-token: write` permission + `pypi` environment + workflow filename are unchanged, so PyPI's trusted-publisher entry still matches). **Release flow:** bump the version in `pyproject.toml` + `src/remove_ai_watermarks/__init__.py` + `uv.lock` (the project's own `[[package]]` entry — find it with `grep -n 'name = "remove-ai-watermarks"' uv.lock`, the `version =` line right below it, ~line 2246), commit `chore(release): vX.Y.Z`, `git tag -a vX.Y.Z -m vX.Y.Z` (annotated — `git tag` without `-m` errors here), push `main` + the tag, then `gh release create vX.Y.Z` — **PyPI publish triggers on the GitHub Release `published` event, NOT on the tag push**, so the tag alone does not publish. **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. **A failed PyPI upload of one artifact still leaves the other live and you cannot re-upload the same version** — fix the build and cut the next patch. **Build backend is pinned `hatchling<1.31`** (`[build-system] requires`): hatchling **1.30.0** made **Metadata-Version 2.5** (PEP 794) the default, which the twine bundled in `pypa/gh-action-pypi-publish@release/v1` rejects (`"'2.5' is not a valid Metadata-Version"`) — this **failed the v0.8.3 PyPI upload on 2026-06-01** (tag-match + build passed, the upload step failed; nothing was uploaded, so the version stayed empty on PyPI), when unpinned `requires = ["hatchling"]` pulled 1.30.0. **hatchling 1.30.1 reverted the default back to 2.4** ("kept at 2.4 until more tools support 2.5"), and 1.27-1.29 always emitted 2.4 — so `<1.31` keeps `uv build` on a 2.4-emitting hatchling (it resolves to the latest allowed, **1.30.1**, which uploads fine). (The earlier "1.28+ emits 2.5" note was imprecise: the 2.5 default landed only in 1.30.0, verified against hatch's changelog.) The publish workflow **now uses `uv publish`** (its uploader handles 2.5), so this pin is no longer load-bearing — it stays as belt-and-suspenders so the first uv-publish release ships 2.4 metadata (isolating the uploader swap from the metadata-version bump); drop it to `requires = ["hatchling"]` once that release confirms the path.
 - `bash maintain.sh` — uv-outdated, uv-secure, ruff check/fix, ruff format, pyright, pytest -n auto
-- `maintain.sh` may not finish fully green (pre-existing, not per-change): strict pyright carries debt in `remove_ai_metadata` / `cli.py` (untyped piexif/PIL/click/rich). (`uv-secure` is clean since idna was bumped 3.11 -> 3.16, fixing GHSA-65pc-fj4g-8rjx.) To gate a change, run `uv run ruff check`, `uv run pyright <changed files>`, `uv run pytest` directly.
+- **Strict pyright is clean across `src/` (0 errors).** The cv2/torch/diffusers boundary files (`gemini_engine`, `region_eraser`, `doubao_engine`, `humanizer`, `invisible_engine`, `noai/watermark_remover`) carry a documented per-file `# pyright:` relax pragma that turns off only the unknown-type / untyped-third-party rules — those libs ship no usable types, so strict typing there fights the ecosystem. Pure-logic files stay fully strict; `typings/piexif/__init__.pyi` is a local stub so `metadata.py`/`extractor.py` resolve piexif. Public ndarray-returning signatures on the relaxed engines are still annotated `NDArray[Any]` so strict consumers (`cli.py`) stay clean. When touching a relaxed file, prefer fixing real issues over widening the pragma; keep the pragma scoped to genuinely-untyped boundaries. (`uv-secure` is clean since idna was bumped 3.11 -> 3.16, fixing GHSA-65pc-fj4g-8rjx, and aiohttp 3.13.5 -> 3.14.0 via `uv lock --upgrade-package aiohttp`, fixing GHSA-hg6j-4rv6-33pg + GHSA-jg22-mg44-37j8. (The basicsr Dependabot alert (GHSA-86w8-vhw6-q9qq, command injection, no patch, <= 1.4.2): accepted, not fixable -- basicsr is the optional `restore` extra pinned to 1.4.2 as the only buildable version, experimental and off by default.)
+- **Full-project `uv run pyright` (no path) OOMs/crashes node on this ML-heavy repo** (emits a `libnode` stack frame, no summary) — a known environment limit, not a code error. Gate with `uv run --extra dev --extra gpu pyright src/` (completes, authoritative) or scope to changed files; also run `uv run ruff check` and `uv run pytest` directly.
 - Run `uv run` from the repo root — from another cwd it falls back to a bare env without numpy/cv2/torch.
+- To add a dev tool (pytest/ruff/pyright) into the env, use `uv sync --frozen --extra dev --extra gpu`, **never `uv pip install`** — `uv pip install` re-resolves and rewrites `uv.lock`, which silently bumped `transformers` to a build incompatible with the pinned `diffusers` (`cannot import name 'Qwen3VLForConditionalGeneration'`) and broke every `identify`/metadata import. Recovery: `git checkout uv.lock && uv sync --frozen --extra gpu --extra dev`. The `gpu` extra holds `diffusers`/`transformers`/`torch`, so a bare `uv sync` (no extras) removes them; `noai/__init__` is now **lazy** (PEP 562 `__getattr__`, so importing `identify`/`metadata` no longer pulls `watermark_remover`/torch), so a bare env breaks only when the removal pipeline is actually invoked, not on import. `maintain.sh`'s `uv sync --all-extras` also pulls the heavy `trustmark`/`lama` wheels (pytorch-lightning, onnxruntime) — fine on a good connection, but on flaky DNS sync only `--extra gpu --extra dev` and run the lint/test steps by hand.
 - Metadata/C2PA tests assert against real committed fixtures in `data/samples/` (`chatgpt-*.png` = OpenAI C2PA, `firefly-1.png` = Adobe, `mj-*` = Midjourney IPTC, `doubao-1.png` = ByteDance Doubao with the China TC260 `<TC260:AIGC>` XMP label **and** a visible "豆包AI生成" text mark bottom-right; `grok-1.jpg` = xAI Grok with its EXIF-only `Signature:` blob + UUID `Artist` and no C2PA/SynthID/IPTC); synthetic byte blobs cover the JPEG/ISOBMFF format paths. The "non-AI / clean photo" control is no longer in `data/samples/` -- the `clean_photo` conftest fixture serves a verified-negative image from the corpus `neg/` set (skips if the corpus is absent).
-- SynthID reference corpus: `scripts/synthid_corpus.py` ingests labeled images into `data/synthid_corpus/`. The labeled `images/` (`pos/` `neg/` `cleaned/`) are **committed** (public repo -- review every image for private content before adding; `manifest.csv` is kept in sync with the files on disk, one row per tracked image); only the synthetic `refs/` calibration fills are gitignored. See its README for the collection protocol and verification oracles.
+- SynthID reference corpus: `scripts/synthid_corpus.py` ingests labeled images into `data/synthid_corpus/`. The labeled `images/` (`pos/` `neg/` `cleaned/`) are **committed** (public repo -- review every image for private content before adding; `manifest.csv` is kept in sync with the files on disk, one row per tracked image); only the synthetic `refs/` calibration fills are gitignored. See its README for the collection protocol and verification oracles. **`cleaned/` examples must be produced by a CURRENT shipped removal method** -- the default SDXL img2img pass (optionally `--max-resolution`). Do NOT archive cleaned outputs from methods that are no longer in the pipeline (ctrlregen, the old text/face-protection, IP-Adapter FaceID, CodeFormer) or from the experimental opt-in paths (controlnet, face restore) as corpus examples; a cleaned reference should represent the canonical removal, and a removed method's output is not a reproducible example. Keep those experiment outputs in a local working dir, never in the committed corpus.
 
 ## Configuration
 
-- GPU/ML modules (invisible_engine, ctrlregen, watermark_remover) are optional — guard imports with `is_available()` checks
+- GPU/ML modules (invisible_engine, watermark_remover) are optional — guard imports with `is_available()` checks
 - Optional detection extras: `detect` (imwatermark — open SD/SDXL/FLUX watermark) and `trustmark` (Adobe TrustMark decoder; pulls torch + downloads weights). Both are guarded by `is_available()` and skipped by `identify` when absent.
-- Tests for the *model-running* paths are limited to availability checks (multi-GB downloads). But the **pure helpers inside ML-adjacent modules are unit-tested without any download** and must stay that way: `_target_size` (native-vs-downscale, `test_invisible_engine.py`), the MPS->CPU fallback control flow via mocked pipelines (`test_img2img_runner.py`, 100% cover), and the tiling math `tile_positions`/`make_blend_weight`/`resize_center_crop` (`test_tiling.py`; `pytest.importorskip("torch")` since `tiling.py` imports torch at module top). Don't skip these as "ML, needs a model" — only `run_tiled`/`remove_watermark`/the diffusion bodies do.
+- Optional `esrgan` extra (spandrel only): Real-ESRGAN pre-diffusion super-resolution for small inputs (`upscaler.py`, CLI `--upscaler esrgan` on `invisible`/`all`/`batch`). Guarded by `upscaler.is_available()`; the default upscaler stays Lanczos (cv2, no deps) and the engine falls back to Lanczos when the extra is absent or the model errors. spandrel is MIT and pulls NO basicsr (only torch/torchvision/safetensors/numpy/einops); Real-ESRGAN weights are BSD-3-Clause and download on first use via `torch.hub` (never bundled). Kept OUT of `all` (heavy + model download).
+- Tests for the *model-running* paths are limited to availability checks (multi-GB downloads). But the **pure helpers inside ML-adjacent modules are unit-tested without any download** and must stay that way: `_target_size` (native-vs-downscale-cap-vs-upscale-floor, `test_invisible_engine.py`), `humanizer.unsharp_mask`/`adaptive_polish` (`test_humanizer.py`), and the MPS->CPU fallback control flow via mocked pipelines (`test_img2img_runner.py`, 100% cover). Don't skip these as "ML, needs a model" — only `remove_watermark`/the diffusion bodies do.
 
 ## Key modules
 
-- `noai/c2pa.py` — PNG chunk parser; use `extract_c2pa_chunk(path)` to get raw caBX payload, `has_c2pa_metadata(path)` to detect. Do not reimplement chunk parsing. `extract_c2pa_info(path)` sets `synthid_watermark`/`synthid_vendors` when the manifest is signed by a SynthID-using vendor, and `soft_binding`/`soft_binding_vendors` when a `c2pa.soft-binding` `alg` names a forensic-watermark vendor (`soft_binding_vendors_in(buffer)` is the shared byte-scan, used by both the PNG parser and the non-PNG binary path).
-- `noai/constants.py` — PNG_SIGNATURE, C2PA_CHUNK_TYPE, C2PA_SIGNATURES, C2PA_ISSUERS, `SYNTHID_C2PA_ISSUERS` (issuers that pair SynthID with C2PA: Google, OpenAI), and `C2PA_SOFT_BINDINGS` (soft-binding `alg` prefix → forensic-watermark vendor: Adobe TrustMark, Digimarc, Imatag, Steg.AI, Microsoft, ...). Add a new issuer/binding here, not inline.
-- `metadata.py` — `synthid_source(path)` returns the vendor name(s) if the C2PA manifest implies a SynthID pixel watermark, else None. Format-agnostic: PNG via the caBX parser, JPEG/WebP/AVIF/HEIF/JXL via a binary scan (C2PA marker + SynthID issuer + AI-source marker). `get_ai_metadata` surfaces the verdict, and `metadata --check` prints it as a callout. Both `get_ai_metadata` and `has_ai_metadata` guard the PIL open with `except Exception` (HEIC/unknown formats raise non-OSError) and fall through to the binary scan. `xai_signature(path)` detects xAI/Grok's EXIF-only scheme (`ImageDescription` = `Signature: <base64>` + UUID `Artist`); it feeds `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify`. `iptc_ai_system(path)` detects the IPTC Photo Metadata 2025.1 AI-disclosure XMP properties (`IPTC_AI_FIELD_MARKERS` = `AISystemUsed`/`AISystemVersionUsed`/`AIPromptInformation`/`AIPromptWriterName`) and returns the `AISystemUsed` generator name (or `"fields present"`). `remove_ai_metadata` routes **ISOBMFF video** (`.mp4`/`.mov`/`.m4v`) through the same `isobmff.strip_c2pa_boxes` as AVIF/HEIF (MP4 is ISOBMFF), and `_scrub_ai_exif` removes the xAI signature + AI-generator EXIF tags on JPEG output.
-- `identify.py` — `identify(path)` aggregates every locally-readable signal (C2PA issuer→platform, C2PA soft-binding forensic-watermark vendor, IPTC "Made with AI" + IPTC 2025.1 `AISystemUsed`, embedded SD/ComfyUI params, SynthID proxy, xAI/Grok EXIF signature via `metadata.xai_signature`, visible Gemini sparkle, open invisible watermark, Adobe TrustMark via `trustmark_detector`) into one `ProvenanceReport`. `is_ai_generated` is True or None (never asserted False — stripped metadata is not proof of clean origin). Visible-sparkle is promoted only at confidence ≥ `_SPARKLE_THRESHOLD` (0.5; corpus-tuned to separate Gemini sparkles ≥0.56 from non-sparkle ≤0.49). The cv2 dependency lives in `gemini_engine.detect_sparkle_confidence`, not here. **C2PA platform attribution is device-token-first, issuer-scan fallback** (`_device_platform` scans manifest bytes for `_DEVICE_C2PA_PLATFORM` tokens, then `_attribute_platform`/`_ISSUER_PLATFORM`). **Why, verified on real signed files 2026-05-26:** the old issuer-only byte-scan matched ANY issuer substring anywhere, so multi-entity manifests mis-attributed -- Leica→"Truepic" (a signing authority in the trust chain), Nikon→"Adobe Firefly" (XMP-toolkit "Adobe" + the sample's "Adobe_MAX" name), Pixel→"Google (Gemini)" ("Google LLC" cert org), Truepic→"Google". A distinctive device token wins instead. **Token distinctiveness is load-bearing:** bare `b"Truepic"` mis-fires (it appears in unrelated trust chains -- it mis-attributed the OpenAI `chatgpt-1.png` fixture), so the token is the specific `b"Truepic_Lens"` from the Lens SDK claim generator; likewise `b"Pixel Camera"` (cert CN) not bare `b"Pixel"`. `_DEVICE_C2PA_PLATFORM` lists ONLY tokens **verified against a real C2PA file**: Leica (`lc_c2pa`/`Leica Camera`), Nikon (`NIKON`), Pixel (`Pixel Camera` -- from a real Pixel 10 Pro file attached to c2pa-rs issue #1609/#1554), Sony (`sony.sig`/`sony.cert` -- Sony's own C2PA assertion namespace, verified on a real Sony PXW-Z300 file; NOT bare "Sony" which is a common EXIF Make), Truepic (`Truepic_Lens`). Canon/Samsung/Bria have **no public direct-download C2PA sample** (checked exhaustively: GitHub issue/PR attachments, contentcredentials gallery, HF datasets -- all upload-to-verify or token-gated; Canon's only public file was a self-signed hobbyist CR3, not factory), so they stay unmapped until a real file is captured (same fixture discipline as Grok/Doubao). The Sony sample is video (MP4) -- our ISOBMFF C2PA path detects it; Sony Alpha stills likely share the `sony.*` namespace but are not separately verified. 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). Add device tokens to `_DEVICE_C2PA_PLATFORM`, generator/issuer platforms to `_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` and XMP `CreatorTool` generator tags 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. **Ideogram tags its output with EXIF `Make="Ideogram AI"`** (verified on a real download 2026-05-24) — that's why `Make` is read.
-- `gemini_engine.py` — visible Gemini-sparkle remover/detector (cv2/numpy, no GPU). `detect_sparkle_confidence(path)` is the file-level entry point used by `identify.py`.
-- `doubao_engine.py` — visible Doubao "豆包AI生成" remover/detector (cv2/numpy, no GPU). `DoubaoEngine.locate` anchors a bottom-right box by **geometry** (mark scales with image WIDTH, fractions in module constants; no bundled template), `extract_mask` pulls the light low-saturation glyphs with a **polarity-aware white top-hat** (brighter-than-blurred-local-bg, so white-paper documents are left untouched instead of smeared), `detect` thresholds glyph coverage (`DETECT_MIN_COVERAGE` 0.16 separates real marks ≥0.20 from corner noise, which stays ≤0.06 on large images but can spike to ~0.15 on tiny ones), `remove_watermark` inpaints (cv2 Telea/NS) and **bails when coverage > `MAX_INPAINT_COVERAGE` 0.50** (dense-text background → would smear). Wired into `visible --mark` via `cli._run_doubao_if_selected`. **Logo is near-white (~253), not the gray some third-party tools assume.** Best on photo/illustration backgrounds; high-contrast edges leave faint residue (cv2-inpaint limit). Clean per-pixel reverse-alpha (Gemini-style) is the future upgrade but needs a captured/distilled alpha map — see below.
-- `region_eraser.py` — universal region eraser (`erase` CLI). `erase(image, boxes=|mask=, backend=)`: `boxes_to_mask` → `cv2.inpaint` (`cv2` backend, default, no deps) or big-LaMa via onnxruntime (`lama` backend, extra `lama`, `Carve/LaMa-ONNX` Apache-2.0 model downloaded on first use, never bundled). `erase_lama` crops a padded region around the mask, runs LaMa at its fixed 512² input, pastes only masked pixels back (untouched areas stay pixel-exact). Lazy `_get_lama_session` singleton; `lama_available()` guards the optional import. **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.
+- `noai/c2pa.py` — PNG chunk parser; use `extract_c2pa_chunk(path)` to get raw caBX payload, `has_c2pa_metadata(path)` to detect. Do not reimplement chunk parsing. `extract_c2pa_info(path)` sets `synthid_watermark`/`synthid_vendors` when the manifest is signed by a SynthID-using vendor, and `soft_binding`/`soft_binding_vendors` when a `c2pa.soft-binding` `alg` names a forensic-watermark vendor (`soft_binding_vendors_in(buffer)` is the shared byte-scan, used by both the PNG parser and the non-PNG binary path). PNG/caBX chunk reads are clamped to the remaining file size (`safe_length = min(length, remaining)`; skipped chunks use seek) so a malformed huge `length` cannot drive a multi-GB allocation (shared safety discipline matching `isobmff.scan_c2pa_region`).
+- `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.
+- `metadata.py` — `scan_head(path, size=1MB)` is the shared input for every C2PA/AIGC/IPTC byte scan: first `size` bytes plus the payloads of any provenance metadata found beyond that window — for ISOBMFF, the late provenance boxes from `isobmff.scan_c2pa_region` (catches a manifest after a large `mdat`); for **PNG**, the late `tEXt`/`iTXt`/`zTXt`/`eXIf`/`iCCP` chunks from `_png_late_metadata` (catches an XMP/EXIF packet appended after a large `IDAT`, e.g. a TC260 AIGC label at ~2.7 MB). Behavior-neutral (`f.read(size)`) for non-ISOBMFF inputs and for any file that fits within `size`. Use it instead of `open().read(1MB)` for any new marker scan. **Memoized per (path, size, mtime)** (added 2026-06-09, `_scan_head_cached` lru_cache, `maxsize=8`): one `identify`/`get_ai_metadata` call fans out to ~8 byte-scan detectors that each re-read the same file head, so the cache turns those into a single read; the mtime key invalidates on change, a stat failure falls back to an uncached read. `synthid_source(path)` returns the vendor name(s) if the C2PA manifest implies a SynthID pixel watermark, else None. Format-agnostic: PNG via the caBX parser, JPEG/WebP/AVIF/HEIF/JXL via a binary scan (C2PA marker + SynthID issuer + AI-source marker). `get_ai_metadata` surfaces the verdict, and `metadata --check` prints it as a callout. Both `get_ai_metadata` and `has_ai_metadata` guard the PIL open with `except Exception` (HEIC/unknown formats raise non-OSError) and fall through to the binary scan. `xai_signature(path)` detects xAI/Grok's EXIF-only scheme (`ImageDescription` = `Signature: <base64>` + UUID `Artist`); it feeds `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify`. `iptc_ai_system(path)` detects the IPTC Photo Metadata 2025.1 AI-disclosure XMP properties (`IPTC_AI_FIELD_MARKERS` = `AISystemUsed`/`AISystemVersionUsed`/`AIPromptInformation`/`AIPromptWriterName`) and returns the `AISystemUsed` generator name (or `"fields present"`). `remove_ai_metadata` routes **ISOBMFF video** (`.mp4`/`.mov`/`.m4v`) through the same `isobmff.strip_c2pa_boxes` as AVIF/HEIF (MP4 is ISOBMFF), and `_scrub_ai_exif` removes the xAI signature + AI-generator EXIF tags on JPEG output. `strip_c2pa_boxes` is **fail-safe** on a malformed box: it returns the original bytes unchanged with a logged warning instead of truncating the tail to EOF (detection-only `scan_c2pa_region` still stops at a malformed box). `_png_late_metadata` clamps each late-chunk read to the remaining file size (`safe_length = min(length, remaining)`) so a malformed `length` cannot drive a multi-GB allocation, AND advances the cursor by `safe_length` (not the raw `length`) so an inflated length cannot jump past EOF and abort the scan, silently skipping a genuine AI-label chunk after it.
+- `identify.py` — the OpenAI rollout caveat is keyed on `_vendor_of(synthid) == "OpenAI"` (not a raw substring over the issuer + verdict blob). `identify(path)` aggregates every locally-readable signal (C2PA issuer→platform, C2PA soft-binding forensic-watermark vendor, IPTC "Made with AI" + IPTC 2025.1 `AISystemUsed`, embedded SD/ComfyUI params, SynthID proxy, xAI/Grok EXIF signature via `metadata.xai_signature`, the China TC260 AIGC label via `metadata.aigc_label`, the HuggingFace `hf-job-id` job marker via `metadata.huggingface_job`, the Samsung Galaxy AI editing marker via `metadata.samsung_genai`, the visible marks — Gemini sparkle plus the ByteDance Doubao 豆包AI生成 / Jimeng 即梦AI / Samsung Galaxy AI "Contenuti generati dall'AI" text marks via the `watermark_registry` — open invisible watermark, Adobe TrustMark via `trustmark_detector`) into one `ProvenanceReport`. `is_ai_generated` is True or None (never asserted False — stripped metadata is not proof of clean origin). The `hf_job`, visible-mark, and Samsung `samsung_genai` signals are **medium** confidence: each lifts an otherwise-Unknown verdict to a tentative AI (`hf_only` / `visible_only` / `samsung_only`, parallel branches; `visible_only` fires on any `visible_*` signal) but is excluded from the high-confidence `ai_from_metadata` set, so none overrides a hard metadata signal. **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` 0.5; 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. **`import identify` is deliberately light** (~21 MB; ~36 MB with cv2 loaded by a visible-mark run, ~106 MB for a full `check_visible` run): it imports only the pure `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. 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. **C2PA platform attribution is device-token-first, issuer-scan fallback** (`_device_platform` scans manifest bytes for `_DEVICE_C2PA_PLATFORM` tokens, then `_attribute_platform`/`_ISSUER_PLATFORM`). **Why, verified on real signed files 2026-05-26:** the old issuer-only byte-scan matched ANY issuer substring anywhere, so multi-entity manifests mis-attributed -- Leica→"Truepic" (a signing authority in the trust chain), Nikon→"Adobe Firefly" (XMP-toolkit "Adobe" + the sample's "Adobe_MAX" name), Pixel→"Google (Gemini)" ("Google LLC" cert org), Truepic→"Google". A distinctive device token wins instead. **Token distinctiveness is load-bearing:** bare `b"Truepic"` mis-fires (it appears in unrelated trust chains -- it mis-attributed the OpenAI `chatgpt-1.png` fixture), so the token is the specific `b"Truepic_Lens"` from the Lens SDK claim generator; likewise `b"Pixel Camera"` (cert CN) not bare `b"Pixel"`. `_DEVICE_C2PA_PLATFORM` lists ONLY tokens **verified against a real C2PA file**: Leica (`lc_c2pa`/`Leica Camera`), Nikon (`NIKON`), Pixel (`Pixel Camera` -- from a real Pixel 10 Pro file attached to c2pa-rs issue #1609/#1554), Sony (`sony.sig`/`sony.cert` -- Sony's own C2PA assertion namespace, verified on a real Sony PXW-Z300 file; NOT bare "Sony" which is a common EXIF Make), Truepic (`Truepic_Lens`). Canon/Bria have **no public direct-download C2PA sample** (checked exhaustively: GitHub issue/PR attachments, contentcredentials gallery, HF datasets -- all upload-to-verify or token-gated; Canon's only public file was a self-signed hobbyist CR3, not factory), so they stay unmapped until a real file is captured (same fixture discipline as Grok/Doubao). The Sony sample is video (MP4) -- our ISOBMFF C2PA path detects it; Sony Alpha stills likely share the `sony.*` namespace but are not separately verified. **Samsung Galaxy + ASUS Gallery live in a separate `_SIGNER_C2PA_PLATFORM` (scaLine truncated
+- `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. **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()`. **`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. **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.
+- `gemini_engine.py` — visible Gemini-sparkle remover/detector (cv2/numpy, no GPU). `detect_sparkle_confidence(path)` is the file-level entry point used by `identify.py`. The public entry points normalize a grayscale (2D) or RGBA (4-channel) input to BGR up front so a non-BGR image does not crash the cv2 pipeline. **Detection localization (issue #36):** `detect_watermark`'s global multi-scale NCC search applies a size weight (`(scale/96)**0.5`) that suppresses tiny-patch false positives but can let a larger, mediocre match (e.g. a bright collar in a portrait) outrank a small, near-perfect sparkle in the corner — so a faint sparkle on a busy background scored below threshold and read as clean (the regression osachub reported from widening the search window 256px->512px between v0.7.2 and v0.8.8). `_corner_promote` adds a bottom-right-corner raw-NCC pass on top of the global search: a match with raw NCC >= `_CORNER_PROMOTE_NCC` 0.85 that beats the global pick overrides it (it only ever replaces a lower-fidelity pick, so it cannot weaken an existing detection), rescuing the buried sparkle without reverting the wider window. The corner side is **relative-clamped** (`_CORNER_PROMOTE_FRAC` 0.20 of the short side, clamped to `[_CORNER_PROMOTE_MIN` 96, `_CORNER_PROMOTE_MAX` 384`]`): a fixed 256px is a true corner on a large image but covers ~70% of a small portrait, where a real photo raw-matches the star at ~0.81 (relative tightening drops that worst case to ~0.69, while the upper clamp stops the corner ballooning on huge images where a real photo reached ~0.83 at 512px). The 0.85 gate sits midway between the worst real-photo corner match (~0.78 across native + downscaled negatives) and a genuine faint sparkle (~0.93), so promotion adds true detections with zero corpus false positives (Gemini's sparkle sits ~60-160px from the corner at fixed margins, covered by the [96, 384] band at every measured size). Regression-guarded by `test_gemini_engine.py::TestCornerPromotion`. **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. **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. **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). **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-captLine truncated
+- `_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.
+- `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). **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. **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/`. **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`.
+- `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`. **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). **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. **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.
+- `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). **Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; white capture confirms). **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 = 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). **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`). **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`. **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).
+- `region_eraser.py` — universal region eraser (`erase` CLI). `erase(image, boxes=|mask=, backend=)` accepts grayscale (2D) and RGBA (4-channel) inputs on **both** backends (`erase_cv2` and `erase_lama` each split off any alpha plane and re-attach it unchanged, and promote grayscale to BGR for processing — LaMa would otherwise crash on grayscale and drop alpha on BGRA): `boxes_to_mask` → `cv2.inpaint` (`cv2` backend, default, no deps) or big-LaMa via onnxruntime (`lama` backend, extra `lama`, `Carve/LaMa-ONNX` Apache-2.0 model downloaded on first use, never bundled). `erase_lama` crops a padded region around the mask, runs LaMa at its fixed 512² input, pastes only masked pixels back (untouched areas stay pixel-exact). Lazy `_get_lama_session` singleton; `lama_available()` guards the optional import. **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.
 - `invisible_watermark.py` — `detect_invisible_watermark(path)` decodes the OPEN DWT-DCT watermarks (public decoder, no key) embedded by Stable Diffusion / SDXL / FLUX via the `imwatermark` library. Known fixed patterns (verified against upstream source) live in `_BITS_48` (SDXL 48-bit, FLUX.2 48-bit) and `_SD1_STRING` ("StableDiffusionV1", SD 1.x/2.x). Optional dep (extra `detect`); returns None when absent. The `detect` extra pulls **torch** transitively (invisible-watermark declares torch a hard dep, and `WatermarkDecoder` eagerly imports `rivaGan` -> `torch` at import time), so detection needs torch present even though dwtDct runs CPU-only on cv2/numpy/pywavelets — no GPU and no separate `gpu` extra required. **Unlike SynthID this is locally detectable**, but the watermark is fragile (does not survive JPEG re-encode/resize — verified gone after JPEG q90), so it confirms origin only on pristine files. Add new known patterns here. The file carries a top-of-module pyright pragma because imwatermark/cv2 ship no type stubs.
-- `trustmark_detector.py` — `detect_trustmark(path)` decodes the OPEN, keyless **Adobe TrustMark** watermark (the soft binding behind Adobe Durable Content Credentials, `alg` `com.adobe.trustmark.P`) via the optional `trustmark` package (extra `trustmark`; pulls torch, downloads model weights on first use). Mirrors `invisible_watermark.py` (lazy singleton, top-of-module pyright pragma, returns None when absent). It detects *provenance*, not AI origin as such (TrustMark also marks human-authored content), so `identify` lists it as a watermark without setting `is_ai_generated`. Other soft-binding vendors (Digimarc/Imatag/Steg.AI/...) have no public decoder — they are only *named* via the `C2PA_SOFT_BINDINGS` scan, not decoded.
-- `face_protector.py` — YOLO detect + soft-blend pattern; mirror this for any "protect region during diffusion" features
+- `trustmark_detector.py` — `detect_trustmark(path)` decodes the OPEN, keyless **Adobe TrustMark** watermark (the soft binding behind Adobe Durable Content Credentials, `alg` `com.adobe.trustmark.P`) via the optional `trustmark` package (extra `trustmark`; pulls torch, downloads model weights on first use). Mirrors `invisible_watermark.py` (lazy singleton guarded by a double-checked `threading.Lock` so concurrent callers do not double-download the weights, top-of-module pyright pragma, returns None when absent). It detects *provenance*, not AI origin as such (TrustMark also marks human-authored content), so `identify` lists it as a watermark without setting `is_ai_generated`. Other soft-binding vendors (Digimarc/Imatag/Steg.AI/...) have no public decoder — they are only *named* via the `C2PA_SOFT_BINDINGS` scan, not decoded. **False-positive gate (added 2026-05-29):** TrustMark's `wm_present` is a BCH error-correction validity flag that spuriously validates on a content-correlated fraction of un-watermarked images — AI-generated textures trip it far more than camera photos (verified 2026-05-29 on real files: it fires on Gemini/OpenAI/Doubao output that *cannot* carry Adobe's watermark, with a random-bytes decoded secret, while signal-free camera photos did not trip it). A genuine TrustMark is a *durable* soft binding engineered to survive re-encoding, so `detect_trustmark` re-decodes after a mild JPEG round-trip (`_survives_reencode`, `_REENCODE_QUALITY` 95) and requires the same schema both times; every observed false positive collapsed (none survived even q95), so the gate is the durability property the watermark guarantees. The second decode runs only on the rare initial hit, so the cost is negligible. Do NOT remove the gate to "catch more" — a lone TrustMark hit without it is almost always content noise.
+- `noai/watermark_remover.py` — the `WatermarkRemover` class has two diffusion pipelines, selected by the explicit `pipeline` ctor arg (NOT inferred from `model_id` -- both use the same SDXL base, `DEFAULT_MODEL_ID`). **`sdxl`** (renamed from `default` 2026-06-09; `default` kept as a back-compat alias via `normalize_profile`) runs plain SDXL img2img (`_run_img2img`); it is the lighter opt-down alternative (no ControlNet weights). **`controlnet`** (**the DEFAULT pipeline since 2026-06-09** for `invisible`/`all`/`batch` and both engine ctors; `_run_controlnet`, `_load_controlnet_pipeline`) runs `StableDiffusionXLControlNetImg2ImgPipeline` with the SDXL-native canny ControlNet `xinsir/controlnet-canny-sdxl-1.0` (`watermark_profiles.CONTROLNET_CANNY_MODEL`): the control image is `cv2.Canny(gray, 100, 200)` stacked to 3 channels (`_CANNY_LOW`/`_CANNY_HIGH`, prompt `_CONTROLNET_PROMPT` / `_CONTROLNET_NEGATIVE`). **Removal comes from the img2img regeneration (`strength`); the ControlNet only PRESERVES text and face STRUCTURE via the edge map.** No original pixels are copied or frozen, BUT **validation 2026-06-04 disproved the old "so SynthID does not survive" claim: SynthID CAN survive controlnet on photoreal/high-detail content.** At the shared low removal strength the canny edge-conditioning keeps the regeneration so close to the original that the pixel perturbation that destroys SynthID does not happen (oracle-confirmed: an OpenAI bracelet photo + a 9-face grid read **SynthID-detected** after controlnet at strength 0.10/0.15, but **SynthID-not-detected** after the `default` pipeline at the SAME strength + resolution -- only the pipeline differed). **But the reverse also holds: a flat-graphic logo/poster SURVIVED `default` while clearing controlnet** -- removal at the low strength is content×pipeline dependent and neither pipeline is universally safe; the real lever is a higher strength. See the controlnet Known-limitations bullet for the full table + root cause. Canny holds face STRUCTURE but NOT identity (the regenerated face drifts in likeness -- canny carries edges, not identity). The drifted cleaned face is the LEAST-AI state we can reach without re-introducing SynthID; the library does NOT ship a face-restore extra. Every restore approach we evaluated (GFPGAN-on-cleaned, PhotoMaker-V2 txt2img, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps, 2026-06-04 - 2026-06-08 Modal cert sweeps) regenerated the face from an ArcFace embedding via SDXL diffusion -- which makes the output face look MORE AI-generated, not less. Empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up". For production face preservation, ship the cleaned image as-is. `controlnet_conditioning_scale` (ctor arg, default 1.0) is the structure-preservation knob. Same dtype rule as `default` (fp32 on cpu/mps, fp16 only on cuda/xpu; the fp16-fixed SDXL VAE `_SDXL_FP16_VAE_ID` is swapped in on fp16 GPUs -- issue #29) and the same MPS->CPU fallback (reload on cpu/fp32, drop a non-cpu generator, retry once).
+- **`auto_config.py` + the content-detection layer were REMOVED 2026-06-09.** History: `auto_config.plan()` was a content-adaptive planner that detected faces/text/edges (bundled OpenCV YuNet + PP-OCRv3 DBNet models) to route the pipeline and toggle the adaptive polish. Once `controlnet` became the default-and-only auto pipeline (it no longer downgrades a structure-less image to `sdxl`) and the adaptive polish was confirmed to **self-gate by detail level** (`humanizer.adaptive_polish` no-ops when the cleaned image already meets the input's Laplacian variance, so it does real work only on over-smoothed photo/face texture and ~nothing on text/flat), the detection no longer changed any behavior — it only annotated a `reason` string. So the whole layer was deleted: `auto_config.py`, `tests/test_auto_config.py`, and the two detection assets (`assets/face_detection_yunet_2023mar.onnx`, `assets/text_detection_ppocrv3_2023may.onnx`, ~2.6 MB). **`--auto` is now a DEPRECATED no-op** (`cli._resolve_auto_polish`): controlnet is already the default pipeline AND the adaptive polish is ON by default, so `--auto` has nothing left to do — it only prints a deprecation warning and passes `adaptive_polish` through unchanged (an explicit `--no-adaptive-polish` still wins). (Originally it re-enabled the polish; once the polish default flipped to ON the same day, the parameter-source branch became dead and was dropped.) The **adaptive polish itself lives on** in `humanizer.adaptive_polish` (CLI `--adaptive-polish/--no-adaptive-polish`, **ON by default since 2026-06-09** — it self-gates to a no-op where there is no detail deficit, so default-on is safe; uses the full-res original as the detail reference) — see the `humanizer` test note. `batch` resolves the polish once before the loop (one warning) and caches the invisible engine per pipeline (`ctx.obj["_inv_engines"]`).
+- `upscaler.py` — optional Real-ESRGAN pre-diffusion super-resolution for small inputs (spandrel boundary, top-of-file pyright pragma). `is_available()` gates on spandrel+torch (via `importlib.util.find_spec`); `upscale(bgr, device=None)` loads a lazily-built spandrel `ImageModelDescriptor` singleton (double-checked lock) and upscales by the model's native factor (x2), with a non-CPU→CPU device fallback mirroring the diffusion engine's MPS→CPU retry. Weights (`RealESRGAN_x2plus.pth`, BSD-3-Clause) download on first use to the `torch.hub` checkpoints cache; never bundled. Used only when UPscaling to the `min_resolution` floor (a `max_resolution` downscale always uses Lanczos). The wiring is `InvisibleEngine._esrgan_upscale(pil, target)` — Real-ESRGAN at native factor, then a Lanczos resize to the exact target, falling back to a plain Lanczos resize if the extra is absent or the model errors (so an optional upscaler can never break removal). The default `--upscaler` is `lanczos` (cv2, no deps). **ESRGAN is a generic photo/texture GAN with no face/glyph prior**, so it best fits photo/texture content and can degrade faces (glassy/asymmetric eyes -- the diffusion pass regenerates faces so the full-pipeline final recovers) and thin/small text (the GAN invents wrong strokes, and low-strength diffusion will not fix it). Verified 2026-06-04: isolated upscale lap-var ~5x Lanczos on faces+textures but glassy eyes; end-to-end `invisible` final lap-var 1634 vs Lanczos 663 with natural faces (diffusion cleaned the artifact). Kept a **manual opt-in knob** (the auto plan never selects it) with `lanczos` the default; not content-gated by design (use Lanczos for text-heavy inputs). spandrel is MIT and pulls no basicsr. Unit-tested without the model: `tests/test_upscaler.py` (availability guard + the not-installed RuntimeError) and `tests/test_invisible_engine.py::TestEsrganUpscale` (the three `_esrgan_upscale` branches via a monkeypatched `upscaler`).
+- `image_io.py` — Unicode-safe cv2 IO (issue #17). `imread(path, flags=None)` / `imwrite(path, img)` wrap `np.fromfile`+`cv2.imdecode` / `cv2.imencode`+`tofile` so non-ASCII paths work on Windows -- bare `cv2.imread`/`cv2.imwrite` use the platform ANSI code-page API there and fail (empty decode + `can't open/read file`) on Chinese/Cyrillic/accented filenames. `imread` keeps `cv2.imread` semantics (defaults to `IMREAD_COLOR`, returns `None` on missing/empty/undecodable). **Every cv2 file read/write in the package routes through here; do not call `cv2.imread`/`cv2.imwrite` directly.** `imwrite` returns `False` on an unwritable path (`OSError` caught) instead of raising, matching `cv2.imwrite` semantics. macOS/Linux already accept UTF-8 paths, so it is behavior-neutral there (the bug only reproduces on Windows). **`to_bgr(image)` (added 2026-06-09)** is the shared channel normalizer: promotes 2D grayscale / (h,w,1) / 4-channel BGRA to 3-channel BGR (a 3-channel input is returned unchanged, no copy). Use it instead of inlining the `cvtColor(GRAY2BGR/BGRA2BGR)` branch — the gemini engine and the `TextMarkEngine` base both route through it so a grayscale/BGRA input (a real Gemini-app export is opaque RGBA) does not crash the `axis=2` channel reductions. cv2/numpy are imported lazily inside the functions, so the module is cheap to import in a bare env.
 
-### Doubao clean-reverse-alpha distillation (researched 2026-05-26, NOT yet shipped)
+### Doubao clean-reverse-alpha distillation (re-investigated 2026-05-29)
 
-Plan to get Gemini-style pixel-accurate reverse-alpha for Doubao at cv2 cost (so it runs on a minimal CPU droplet): use LaMa **offline** to reconstruct the clean background `O`, then per-pixel solve `I=(1-α)O+αL` for the alpha map + logo colour (this is Google's CVPR-2017 multi-image idea, with LaMa standing in for the multi-image optimisation). Validated in principle (glyph error drops as alignment improves) but **blocked on data**, confirmed empirically over 6 attempts: a clean canonical alpha map needs **several PRISTINE images at ONE resolution** with varied backgrounds. The findable public Doubao images (ayaya, Tools_CleanMark, ours) are all different resolutions AND lossy (jpg/webp), and Doubao's mark position drifts ~±50 px even at the same resolution, so cross-image registration (ECC / phase-correlation) fails (1/11 templates aligned) — error floor ~64/255 on glyph pixels, not shippable. To finish: ~5-8 pristine same-resolution Doubao originals → per-image α via LaMa → align the clean α templates → median → ship the tiny map + an NCC localiser (Doubao's mark drifts, so runtime needs the same locate-then-reverse-alpha the Gemini engine already does). Don't retry on lossy/mixed-resolution scraped images — proven insufficient.
+**RESOLVED 2026-05-29: black+gray Doubao captures were obtained and a reverse-alpha is built** (`doubao_engine.remove_watermark_reverse_alpha`, `assets/doubao_alpha.png`; see the `doubao_engine.py` bullet above). The captures (`data/doubao_capture/captures/`, now committed) confirmed the alpha-composite model: on black `captured = a*logo`, logo pure white. **UPDATE 2026-05-31 (issue #13 follow-up): the first build was NOT "exact"** — it left a readable "豆包AI生成" outline on the real sample (the detector was fooled, conf 0.0). The alpha is now rebuilt by `scripts/visible_alpha_solve.py` (the careful gray-self solve shared with Jimeng), removal always-aligns + thin-inpaints, and the locate box was widened; see the `doubao_engine.py` bullet. The notes below (the failed content-image distillation) are retained as the record of why controlled captures were necessary.
+
+**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 -- `data/spaces/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.**
+
+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.
+
+**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.
+
+**Until black captures arrive, the shipped direction is precise canonical glyph mask + inpaint (cv2 default, lama optional), NOT reverse-alpha.** The consensus glyph silhouette across the aligned marks distills cleanly (proto: a tight "豆包AI生成" strip, width ≈ 0.156 × image-width) and is good both as an exact inpaint mask and as an NCC localiser -- the latter also fixes the #23 detector false-positives (match the real glyph shape, not any bright low-saturation corner). Do **not** retry content-image reverse-alpha: it is data-limited by physics (no dark-background observations), not by effort.
 
 ## Watermarking landscape (research 2026-05-24)
 
 Who embeds what, and whether it is locally detectable (so we know which gaps are fillable). See `identify.py` for what we read.
 - **Locally detectable (open decoder, no key/API):** Stable Diffusion / SDXL / FLUX via `imwatermark` DWT-DCT (now covered by `invisible_watermark.py`). FLUX uses the same library (`black-forest-labs/flux2` `src/flux2/watermark.py`, 48-bit `0b001010101111111010000111100111001111010100101110`); SDXL is the diffusers `WATERMARK_MESSAGE` (`0b101100111110110010010000011110111011000110011110`). Caveat: fragile to re-encoding.
-- **C2PA / IPTC (covered by the issuer/marker scan):** OpenAI, Google, Adobe Firefly, Microsoft (Designer + **Bing Image Creator** — collected 2026-05-24; Bing now runs Microsoft's own **MAI-Image** model, signs C2PA as "Microsoft", NOT OpenAI/DALL-E), and **Stability AI** (collected from Brand Studio / DreamStudio successor; signs C2PA as "Stability AI Ltd", no SynthID, no imwatermark on its current Stable Image model — issuer added to `C2PA_ISSUERS`). Still unsampled: Canva (its downloads are re-encoded design *exports* that strip C2PA, so a Canva "positive" is inconclusive — skipped), Getty, Shutterstock. Midjourney embeds NO C2PA and no invisible watermark (our `mj-*` sample carried only the IPTC tag).
+- **C2PA / IPTC (covered by the issuer/marker scan):** OpenAI, Google, Adobe Firefly, Microsoft (Designer + **Bing Image Creator** — collected 2026-05-24; Bing now runs Microsoft's own **MAI-Image** model, signs C2PA as "Microsoft", NOT OpenAI/DALL-E), and **Stability AI** (collected from Brand Studio / DreamStudio successor; signs C2PA as "Stability AI Ltd", no SynthID, no imwatermark on its current Stable Image model — issuer added to `C2PA_ISSUERS`). Still unsampled: Canva (its downloads are re-encoded design *exports* that strip C2PA, so a Canva "positive" is inconclusive — skipped), Getty, Shutterstock. Midjourney embeds NO C2PA and no invisible watermark (our `mj-*` sample carried only the IPTC tag). **Samsung Galaxy AI** (Generative Edit / Sketch to Image / Portrait Studio on Galaxy S23 FE / S24 / S25, One UI 7+) signs C2PA as "Samsung Galaxy" with the standard `trainedAlgorithmicMedia` source type AND a proprietary `genAIType` marker; verified on real signed files 2026-05-29 (the standard scan catches the source type; `genAIType` additionally catches a Galaxy S24 file that omits it). It ALSO burns a **visible** localized wordmark into the pixels — a sparkle + "generated with AI" string in the bottom-LEFT corner (issue #37; the Italian "✦ Contenuti generati dall'AI" variant is calibrated) — removed by `samsung_engine.py` / `visible --mark samsung` (reverse-alpha, see the engine bullet); detection feeds `identify` as the medium `visible_samsung` signal. The string is locale-specific, so each locale needs its own captured alpha template. **ASUS Gallery** also signs edited photos as C2PA (`com.asus.gallery`) but with no AI source type — a signer, not an AI marker. **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.
 - **EXIF/XMP 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).
 - **xAI / Grok — its own EXIF signature scheme, NOT C2PA (DETECTED by `metadata.xai_signature`, built 2026-05-26).** Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC** — only EXIF `Artist` = a UUID and EXIF `ImageDescription` = `Signature: <base64>` (a crypto signature, unverifiable locally without xAI's public key). This empirically kills the earlier unverified "xAI signs C2PA as xAI" lead — xAI is not even a C2PA member. `exif_generator` misses it (neither field holds an `AI_GENERATOR_TOKENS` token), so a dedicated detector `xai_signature(path)` matches the pair (`ImageDescription ~ ^Signature: [A-Za-z0-9+/=]{64,}` AND UUID `Artist`); wired into `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify` (signal `xai_signature`, platform "xAI (Grok / Aurora)"). **Format confirmed stable across n=3 genuine generations:** exactly three EXIF tags (`Artist`, `ExifOffset`, `ImageDescription`), `Signature:` prefix constant, base64 payload 300-1004 chars. Two capture facts: (a) the `Artist` UUID **equals the public image id** in the asset URL (`https://imagine-public.x.ai/imagine-public/images/<uuid>.jpg`), so it is NOT a private per-user secret — only the `Signature` blob is; (b) the Grok web-UI image is a re-encoded **WebP with no signature** — the EXIF survives only in the *original* JPEG (download button or that public tokenless URL), which is why screenshots / re-encodes are metadata-stripped. A real fixture `data/samples/grok-1.jpg` plus **synthetic** JPEG fixtures (fake UUID + fake `Signature:` blob) cover the detector; never add a real Grok image carrying private content (the repo is public). **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` json-decodes the (HTML-entity-encoded) block; container-agnostic raw-byte scan.
+- **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 **three 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"`), **and** 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"`). Both generic forms (the PNG chunk and the bare `{"AIGC":...}` object) 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).
+- **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.
 - **C2PA 2.4 "Durable Content Credentials" (April 2026; verified against the spec) raise the bar for metadata stripping.** 2.4 defines soft bindings (an invisible watermark or a content fingerprint) plus a server-side manifest repository and a new `c2pa.repository-receipt` assertion. Per the spec: "if a C2PA manifest is removed from an asset, but a copy of that manifest remains in a provenance store elsewhere, the manifest and asset may be matched using available soft bindings." So our local `metadata --remove` deletes the *embedded* manifest, but a fingerprint/watermark soft binding can still re-link the image to its manifest in a repository server-side. Stripping the file is becoming necessary-but-not-sufficient against durable provenance. (Our parsers target the stable embedded-manifest format documented in C2PA 2.1 §11; that format is unchanged in 2.4 -- the new pieces are repository/soft-binding infra, not the on-file box layout, so no parser change is implied.) Spec: https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html We now READ the soft-binding `alg` (`C2PA_SOFT_BINDINGS` / `soft_binding_vendors_in`) to name the forensic-watermark vendor, and locally DECODE the one open scheme, Adobe TrustMark (`trustmark_detector`); the rest (Digimarc/Imatag/Steg.AI/...) stay name-only (proprietary decoders).
-- **Built 2026-05-26 (this batch):** soft-binding `alg` vendor detection; IPTC Photo Metadata 2025.1 AI-disclosure fields (`AISystemUsed` etc.); **video C2PA metadata** detect + strip for MP4/MOV/M4V (free — `isobmff.py` is format-agnostic, MP4 is ISOBMFF); Adobe TrustMark open decoder. NOT done (out of cheap reach, per the feasibility review): visible video-logo removal (needs a video frame pipeline) and audio (SynthID/ElevenLabs/Resemble/Suno all oracle-only or unmarked). The soft-binding **box detection window**: non-PNG/video detection scans the first 1 MB, so a C2PA box placed after a large `mdat` in a streaming MP4 can be missed — front-placed manifests (the common case) are caught.
-- **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 Jan 2026 (verified via Kim & Chang; 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.
+- **Built 2026-05-26 (this batch):** soft-binding `alg` vendor detection; IPTC Photo Metadata 2025.1 AI-disclosure fields (`AISystemUsed` etc.); **video C2PA metadata** detect + strip for MP4/MOV/M4V (free — `isobmff.py` is format-agnostic, MP4 is ISOBMFF); Adobe TrustMark open decoder. NOT done (out of cheap reach, per the feasibility review): visible video-logo removal (needs a video frame pipeline) and audio (SynthID/ElevenLabs/Resemble/Suno all oracle-only or unmarked). **Box detection window — now handled (v0.6.8):** detection no longer relies on a fixed first-MB read. `metadata.scan_head(path, size)` reads the first `size` bytes and, for ISOBMFF, appends the payloads of late provenance boxes found by `isobmff.scan_c2pa_region` (a file-seeking top-level box walker that skips past `mdat` by size without reading it), so a C2PA/AIGC/IPTC manifest placed AFTER a large `mdat` in a streaming/non-faststart MP4 is now caught. Every C2PA/marker byte scan (`has_ai_metadata`, `aigc_label`, `iptc_ai_system`, `synthid_source`, `exif_generator` XMP, `get_ai_metadata` soft-binding, and `identify`) goes through `scan_head`; it is behavior-neutral for non-ISOBMFF inputs (exactly `f.read(size)`). **Meta-box XMP removal — now handled (v0.6.9):** an AI-label XMP packet stored as a meta-box `mime` item (HEIF/AVIF; out of reach of the top-level box stripper) is blanked in place by `isobmff.blank_ai_xmp_packets` — it locates the packet by its `<?xpacket begin … end?>` delimiters and, if it carries an AI marker (`_AI_LABEL_MARKERS`), overwrites it with spaces of the SAME length, so box sizes / `iloc` offsets stay valid and the coded image is untouched (selective: plain non-AI XMP is left alone, mirroring the top-level uuid logic). Wired into `remove_ai_metadata`'s ISOBMFF branch after `strip_c2pa_boxes`. The remaining gap is an `Exif` meta-box *item* (rare; the AI labels are XMP) — still needs `iinf`/`iloc` surgery or exiftool.
+- **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.
 
 ## Known limitations
 
-- `invisible` pipeline processes at **native resolution by default** (`max_resolution=0`), matching the hosted raiw.cc backend (fal fast-sdxl, no pre-downscale). The old forced downscale-to-1024 -> upscale-back round-trip was the main quality loss (issue #10) and is gone; at strength ~0.05 SDXL img2img does not need the ~1024 downscale. `--max-resolution N` re-introduces an opt-in long-side cap purely to bound GPU/MPS memory on very large inputs (it reintroduces the lossy round-trip). For huge images that OOM at native, tile-based diffusion is still the proper long-term fix. **Concrete MPS data point (verified 2026-05-25 on a 1254x1254 gpt-image SDXL run, fp32, 20 GB MPS ceiling):** native res OOMs at the *UNet* step (peak ~17 GiB), not only the VAE decode, and the auto-fallback in `img2img_runner` reloads on CPU and finishes (slow, ~13 min) -- the output is still weight-identical and defeats SynthID, so "looks hung/crashed" on Mac is usually this CPU fallback, not a pipeline error. Adding `enable_vae_tiling()` alone does NOT prevent it (the peak is the UNet, not the VAE). The fast Mac workarounds are fp16 on MPS (roughly halves memory) or `--max-resolution` to cap the long side; neither is wired as the default. The native-vs-downscale decision lives in the pure helper `invisible_engine._target_size(w, h, max_resolution)` (returns `None` for native, a clamped target tuple otherwise) so it is unit-tested (`tests/test_invisible_engine.py::TestTargetSize`, the #10/#15 regression guard) without loading the model -- keep that logic in the helper, don't re-inline it.
+- `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. **Final `--unsharp` post-filter (`humanizer.unsharp_mask`, opt-in, default 0):** applied LAST (after the face-restore pass, else it would be smoothed over) to counter the soft/over-smoothed look diffusion + restoration leave (an AI tell); ~0.5-0.8 safe, higher risks halos. Pairs with `--humanize` (grain adds sensor-noise texture, unsharp adds crispness). `--max-resolution N` re-introduces an opt-in long-side cap purely to bound GPU/MPS memory on very large inputs (it reintroduces the lossy round-trip). For huge images that OOM at native, tile-based diffusion is still the proper long-term fix. **Concrete MPS data points (the OOM is memory-tier-dependent, NOT a hard MPS limit):** on a ~24 GB unified-memory machine (verified 2026-05-25, 1254x1254 gpt-image SDXL, fp32) native res OOMs at the *UNet* step (peak ~17 GiB), not only the VAE decode, and the auto-fallback in `img2img_runner` reloads on CPU and finishes (slow, ~13 min) -- the output is still weight-identical and defeats SynthID, so "looks hung/crashed" on Mac is usually this CPU fallback, not a pipeline error. On a **32 GB** unified-memory machine the same default SDXL pass runs entirely on MPS with **no CPU fallback** (verified 2026-05-31, 1122x1402 gpt-image, `all`/default, ~155 s end-to-end), so 32 GB clears the native-res UNet peak that 24 GB could not. Adding `enable_vae_tiling()` alone does NOT prevent the 24 GB OOM (the peak is the UNet, not the VAE). The fast Mac workarounds for memory-constrained machines are fp16 on MPS (roughly halves memory) or `--max-resolution` to cap the long side; neither is wired as the default. The `controlnet` pipeline adds the canny ControlNet weights on top of SDXL, so its peak is a bit higher than the plain `default` pass; the same MPS->CPU fallback covers an OOM. The native-vs-cap-vs-floor decision lives in the pure helper `invisible_engine._target_size(w, h, max_resolution, min_resolution)` (returns `None` for native, a target tuple for a downscale cap OR an upscale floor; cap takes precedence, the floor is skipped on a min>max misconfig) so it is unit-tested (`tests/test_invisible_engine.py::TestTargetSize`, the #10/#15/#36 regression guard) without loading the model -- keep that logic in the helper, don't re-inline it.
+- **fp16 VAE black-output fix (issue #29, 2026-05-30):** on a **CUDA/XPU fp16** backend the stock SDXL VAE overflows to NaN and the *plain* img2img path decodes to an **all-black** image (reproduced on the raiw.cc result: a 1086x1448 input -> a uniformly black 4.6 KB PNG, mean 0). `watermark_remover._load_pipeline` / `_load_controlnet_pipeline` swap in the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix` = `_SDXL_FP16_VAE_ID`) when `_needs_fp16_vae_fix(model_id, DEFAULT_MODEL_ID, is_fp16)` is true -- only the default SDXL checkpoint on fp16. **cpu/mps run fp32** (the stock VAE is fine there, which is why the bug never reproduces on Mac). A custom non-SDXL `model_id` keeps its own VAE (the fp16-fix VAE is SDXL-architecture-specific). The decision is a pure helper, unit-tested without a download (`tests/test_platform.py::TestFp16VaeFix`); the actual black->clean recovery needs a CUDA GPU. **Confirmed on real CUDA hardware 2026-06-03:** running `all` on a 1086x1448 OpenAI gpt-image (the #29 repro size) at fp16 produced a normal (non-black) output, so the fp16-fix VAE swap resolves the all-black decode. (It was not reproducible on this MPS machine, which runs fp32, so the verification had to happen on an NVIDIA box.) **Follow-up safety net (issue #41, 2026-06-04):** the swap is gated to `model_id == DEFAULT_MODEL_ID`, so a custom model, a stale pre-fix install, or a fal/custom loader can still hit the black decode -- a new reporter did (gpt-image 1448x1086, the #29 size, with the exact `image_processor.py:142 invalid value encountered in cast` warning the NaN->0 cast emits). `remove_watermark` now adds a model-agnostic backstop: after generation, if the run was fp16 AND the output is degenerate (`_is_degenerate_image`: mean and std both below `_DEGENERATE_THRESHOLD` 1.0 -- a uniform all-black/NaN frame; the variance guard spares a legitimately dark-but-textured photo), it rebuilds the pipeline in fp32 on the SAME device and re-runs once. fp32 is the verified-clean path, so the user never gets a black image regardless of model_id/version. Mirrors the existing MPS->CPU fallback's self-mutation pattern (reset `torch_dtype` + clear `_pipeline`/`_controlnet_pipeline`); `batch` inherits it through `remove_watermark`, and once one image trips it the rest of the batch stays on the safe fp32. The detector is a pure helper, unit-tested without a model (`tests/test_platform.py::TestDegenerateOutputGuard`); the full fp16->detect->fp32-retry chain was verified e2e on this MPS machine by forcing fp16 with the swap disabled (first pass black, guard fired, retry produced a normal image). CAVEAT: the fp32 retry uses ~2x memory, so on a VRAM-constrained GPU it can OOM (a visible error, still better than a silent black frame; the MPS->CPU fallback covers that path). The reporter's "CPU also black" symptom is NOT reproducible here -- fp32 (cpu/mps) decodes clean -- so it points at an old version or a non-fp32 run, pending their version + command.
 - 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.
-- `ultralytics` monkey-patches `PIL.Image.open` and tries to autoload `pi_heif`. When `pi_heif` is missing, opening files raises `ModuleNotFoundError`, not `UnidentifiedImageError`. Code that opens user-supplied or unknown-format files should `except Exception`, not just `OSError`/`UnidentifiedImageError`.
-- Metadata detection for AVIF/HEIF/JPEG-XL relies on a binary scan for `C2PA_UUID` + `IPTC_AI_MARKERS`, plus EXIF `Software` / XMP `CreatorTool` generator tags via `metadata.exif_generator` (validated with synthesized AVIF/JPEG fixtures + an XMP raw-scan fixture). C2PA removal in those containers is implemented via `noai/isobmff.py` (top-level ``uuid`` / ``jumb`` box stripper, no re-encoding), which now also drops a top-level XMP ``uuid`` box that carries an AI label (matched by AI-marker content, not by the XMP UUID, so byte-order-robust) and covers MP4/MOV/M4V/M4A by content sniff. **Non-ISOBMFF audio/video removal is via ffmpeg** (`_FFMPEG_STRIP_EXTS` -> `_strip_with_ffmpeg`): WebM/Matroska (EBML), MP3 (ID3), WAV/FLAC/OGG (RIFF/Vorbis) are stripped losslessly with `ffmpeg -map_metadata -1 -map_chapters -1 -c copy` (codec data untouched). Requires ffmpeg on PATH; raises `RuntimeError` if absent or if ffmpeg can't parse the file. Verified end-to-end (a real ffmpeg-made WAV/MP3 with a `title=Suno AI` tag -> tag gone, audio bytes preserved). **Still NOT built (deliberate):** EXIF/XMP stored as *items inside the ``meta`` box* (typical for AVIF/HEIF images) needs meta-box surgery (iinf/iloc edit + mdat splice) with corruption risk -- exiftool would do it but is a non-installed binary dep, so it stays a documented gap. **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.)
-- **SynthID detection is metadata-only.** There is no reliable *local* detector of the SynthID *pixel* watermark — Google's decoder is proprietary, no public spec or API (only a waitlisted portal). Authoritative confirmation: Google DeepMind's own paper "SynthID-Image: Image watermarking at internet scale" (Gowal et al., arXiv:2510.09263) states the verification service is restricted to "trusted testers" and does not release detector weights or a reproducible algorithm — so a local pixel detector is infeasible by design, not just unbuilt. https://arxiv.org/abs/2510.09263 We detect SynthID by its C2PA companion (`synthid_source` / `SYNTHID_C2PA_ISSUERS`), which is reliable while the manifest is intact but says nothing once C2PA is stripped. **Surface-dependent blind spot (verified 2026-05-24):** the same Google model emits different metadata per surface -- the Gemini *app* wraps outputs in Google C2PA, but the *API/playground* (AI Studio, Nano Banana / gemini-2.5-flash-image) emits the SynthID *pixel* watermark (confirmed via the Gemini-app oracle) + the visible sparkle but **no C2PA/IPTC at all**, so `synthid_source` returns None despite SynthID being present. Only the pixel oracle or the visible-sparkle detector catches those. (Meta AI is another surface mismatch: it writes the IPTC `digitalSourceType=trainedAlgorithmicMedia` marker, not C2PA and not SynthID.) Google→SynthID is long-standing; OpenAI→SynthID is confirmed by OpenAI's Help Center (ChatGPT/Codex/API "include both C2PA metadata and SynthID watermarks", updated 2026-05-21) but time-gated (pre-rollout OpenAI images carry C2PA without SynthID), so the OpenAI verdict is hedged "likely". Oracles: Gemini app "Verify with SynthID" (Google), openai.com/verify (OpenAI). The spectral phase-coherence approach from `github.com/aloshdenny/reverse-SynthID` was evaluated (May 2026) and **does not work for real-content detection**: on its own shipped codebook + validation set, watermarked and cleaned images were indistinguishable (conf within noise, cleaned often higher); it only fires on pure-black 1024x1024 reference images at exact resolution (the controlled case it was calibrated on). The README's "90% / conf=0.91" reproduces only in that lab condition. Do not build a production detector on it; if revisited, it is experimental/diagnostic only and needs a per-resolution, per-model reference corpus. A from-scratch gpt-image pilot (2026-05-24) confirmed this independently: 5 independent solid-black gpt-image outputs share a near-identical fixed signature (pairwise residual correlation **0.92**, avg-template retains 97% energy), so the watermark/carrier IS strongly present and consistent on flat content — but the carrier frequencies extracted from it do NOT discriminate real content (carrier-to-random ratio: cleaned 1.86 > watermarked 1.53; a non-gpt-image image scored highest at 3.67). The signature drowns in content texture. Net: a perfectly consistent solid-color signature still yields no real-content pixel detector with magnitude/carrier methods. A corpus discrimination test (2026-05-24, `scripts/synthid_pixel_probe.py`, raw zero-mean residual NCC) independently re-confirms this: at matched resolution, SynthID positives do NOT cluster apart from negatives (within-Gemini 0.07; at 1024 px pos-vs-neg >= pos-vs-pos). The only high correlations were near-duplicate *content* (5 ChatGPT renders of one prompt at ~0.92, while a distinct ChatGPT image scored ~0 against them) — content, not a carrier. The probe is solid-fills-only and EXPERIMENTAL/DIAGNOSTIC; do not use it on real content. **Correction (deeper re-examination 2026-05-25):** the carrier IS real on solid fills — the earlier "no carrier" was a *method* artifact of using spatial / FFT-magnitude NCC, which can't see it. The carrier is a fixed *phase* at specific low frequencies, so the right metric is **per-bin phase coherence**. On 8 white `gemini-2.5-flash-image` fills (generated via the reverse-SynthID trick: identity-edit prompt "Recreate this image exactly as it is" on a synthetic pure-white PNG — this bypasses the recitation block that rejects text prompts for pure colors), phase coherence at the white carriers `(0,±7..±12,±20..±23)` = **0.86** vs **0.31** random; single-image leave-one-out phase-match **+0.83** vs real photos **-0.24**. (Black `2.5-flash` fills clip to std≈0 — SynthID can't push values below 0, so no carrier in black; the repo's dark carriers come from nano-banana-pro.) **But it does not generalize:** (a) carriers are model-version + resolution + color specific — the repo's v4 codebook (built for `gemini-3.1-flash-image-preview` + `nano-banana-pro-preview`) scores ~0.527 on my 2.5-flash white fills, indistinguishable from negatives (~0.50), i.e. carriers shift across model versions and need a per-model codebook; (b) on real content (30 `2.5-flash` images) the carrier collapses — set phase coherence at carriers 0.37 ≈ random 0.42, and the repo's v4 deteLine truncated
+- 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 (CLI + scripts print plain text via `click.echo`).** `cli.py` renders through small `_Console`/`_Table`/`_Progress` shims; the analysis scripts (`scripts/synthid_corpus.py`, `synthid_pixel_probe.py`, `text_detection_benchmark.py`, `corpus_gap_scan.py`) import `Console`/`Table` from the shared `scripts/_plain_console.py` shim (markup like `[bold]`/`[/]` is stripped, tables render aligned). Consequences: (1) `rich` is NOT a dependency, so anything that imports it breaks a clean `uv sync --frozen` (CI installs core+dev only) — this exact gap red-failed CI after the refactor when those 4 scripts still imported rich; if you add a script, use the `_plain_console` shim, not rich. (2) The old `[gpu]`-bracket-eaten bug (#19) is gone — plain `click.echo` prints `pip install 'remove-ai-watermarks[gpu]'` verbatim, no escaping needed (regression-guarded by `tests/test_cli.py::TestGpuHintMarkup`). (3) No Unicode glyphs / colors / progress bars in CLI output by design.
+- Metadata detection for AVIF/HEIF/JPEG-XL relies on a binary scan for `C2PA_UUID` + `IPTC_AI_MARKERS`, plus EXIF `Software` / XMP `CreatorTool` generator tags via `metadata.exif_generator` (validated with synthesized AVIF/JPEG fixtures + an XMP raw-scan fixture). C2PA removal in those containers is implemented via `noai/isobmff.py` (top-level ``uuid`` / ``jumb`` box stripper, no re-encoding), which now also drops a top-level XMP ``uuid`` box that carries an AI label (matched by AI-marker content, not by the XMP UUID, so byte-order-robust) and covers MP4/MOV/M4V/M4A by content sniff. **Non-ISOBMFF audio/video removal is via ffmpeg** (`_FFMPEG_STRIP_EXTS` -> `_strip_with_ffmpeg`): WebM/Matroska (EBML), MP3 (ID3), WAV/FLAC/OGG (RIFF/Vorbis) are stripped losslessly with `ffmpeg -map_metadata -1 -map_chapters -1 -c copy` (codec data untouched). Requires ffmpeg on PATH; raises `RuntimeError` if absent or if ffmpeg can't parse the file. Verified end-to-end (a real ffmpeg-made WAV/MP3 with a `title=Suno AI` tag -> tag gone, audio bytes preserved). **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). **Still NOT built:** an `Exif` *item* inside the `meta` box (rare -- AI labels are XMP) needs full `iinf`/`iloc` surgery (offset rewrite) with corruption risk -- exiftool (R/W/C for HEIC/AVIF EXIF+XMP, verified on exiftool.org 2026-05-27) would do it but is a non-installed binary dep, so it stays a documented gap. **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.)
+- **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.** There is no reliable *local* detector of the SynthID *pixel* watermark — Google's decoder is proprietary, no public spec or API (only a waitlisted portal). Authoritative confirmation: Google DeepMind's own paper "SynthID-Image: Image watermarking at internet scale" (Gowal et al., arXiv:2510.09263) states the verification service is restricted to "trusted testers" and does not release detector weights or a reproducible algorithm — so a local pixel detector is infeasible by design, not just unbuilt. https://arxiv.org/abs/2510.09263 We detect SynthID by its C2PA companion (`synthid_source` / `SYNTHID_C2PA_ISSUERS`), which is reliable while the manifest is intact but says nothing once C2PA is stripped. **Surface-dependent blind spot (verified 2026-05-24):** the same Google model emits different metadata per surface -- the Gemini *app* wraps outputs in Google C2PA, but the *API/playground* (AI Studio, Nano Banana / gemini-2.5-flash-image) emits the SynthID *pixel* watermark (confirmed via the Gemini-app oracle) + the visible sparkle but **no C2PA/IPTC at all**, so `synthid_source` returns None despite SynthID being present. Only the pixel oracle or the visible-sparkle detector catches those. (Meta AI is another surface mismatch: it writes the IPTC `digitalSourceType=trainedAlgorithmicMedia` marker, not C2PA and not SynthID.) Google→SynthID is long-standing; OpenAI→SynthID is confirmed by OpenAI's Help Center (ChatGPT/Codex/API "include both C2PA metadata and SynthID watermarks", updated 2026-05-21) but time-gated (pre-rollout OpenAI images carry C2PA without SynthID), so the OpenAI verdict is hedged "likely". Oracles: Gemini app "Verify with SynthID" (Google), openai.com/verify (OpenAI). **Each vendor's oracle detects only its OWN content (verified on the page 2026-05-31):** `openai.com/research/verify` states verbatim "OpenAI generation signals will only be detected if the image was generated with our tools" and "Content could also still be AI-generated by another company's model, which the tool currently does not detect" -- SynthID is shared tech but the verifier is keyed to its own vendor's payload, so a Google-SynthID image reads clean on OpenAI's verifier and vice-versa. **This explains the recurring "oracle says clean but `identify` still flags SynthID" report (#14):** the oracle reads the *pixel* watermark (gone after our SDXL pass), while `identify` reads the *C2PA-metadata proxy* (still present if the manifest survived). Different signals, not a contradiction -- strip the metadata too (`metadata --remove` / `all`) and the proxy goes quiet, but a quiet proxy is not proof the pixel watermark is gone. **SynthID is durable to JPEG re-encode by design, so a GitHub-recompressed issue attachment is still a valid SynthID test subject** (verified 2026-06-01 on issue #14's pic3: the GitHub-served JPEG survived re-encoding and openai.com/verify still detected SynthID). Do NOT dismiss issue-attachment JPEGs as "not faithful originals" when reproducing a SynthID-survival report: the recompression strips the **C2PA metadata** (so `identify` reads Unknown on the attachment) but NOT the **pixel watermark** that openai.com/verify reads. A true byte-original only matters for the metadata/C2PA path, not for the pixel-SynthID-removal test. (Contrast the open imwatermark above, which IS fragile to JPEG.) The spectral phase-coherence approach from `github.com/aloshdenny/reverse-SynthID` was evaluated (May 2026) and **does not work for real-content detection**: on its own shipped codebook + validation set, watermarked and cleaned images were indistinguishable (conf within noise, cleaned often higher); it only fires on pure-black 1024x1024 reference images at exact resolution (the controlled case it was calibrated on). The README's "90% / conf=0.91" reproduces only in that lab condition. Do not build a production detector on it; if revisited, it is experimental/diagnostic only and needs a per-resolution, per-model reference corpus. A from-scratch gpt-image pilot (2026-05-24) confirmed this independently: 5 independent solid-black gpt-image outputs share a near-identical fixed signature (pairwise residual correlation **0.92**, avg-template retains 97% energy), so the watermark/carrier IS strongly present and consistent on flat content — but the carrier frequencies extracted from it do NOT discriminate real content (carrier-to-random ratio: cleaned 1.86 > watermarked 1.53; a non-gpt-image image scored highest at 3.67). The signature drowns in content texture. Net: a perfectly consistent solid-color signature still yields no real-content pixel detector with magnitude/carrier methods. A corpus discrimination test (2026-05-24, `scripts/synthid_pixel_probe.py`, raw zero-mean residual NCC) independently re-confirms this: at matched resolution, SynthID positives do NOT cluster apart from negatives (within-Gemini 0.07; at 1024 px pos-vs-neg >= pos-vs-pos). The only high correlations Line truncated
 - **External AI-vs-real classifier models are out of scope (decided 2026-05-24).** Generic HuggingFace detectors (`Organika/sdxl-detector` Swin Transformer, `umm-maybe/AI-image-detector`, and fine-tunes) exist and report ~0.98 on their *own* SDXL-vs-real validation sets, but they are per-generator and the model cards themselves note degraded accuracy off-distribution; they are untested on gpt-image / Gemini Nano Banana (the metadata-stripped surfaces we care about), and our own light SDXL pass would likely defeat them the same way it defeats SynthID. Detection here stays local + signal-based (metadata + visible sparkle); do not add a bundled classifier dependency.
-- **SynthID v2 vs default pipeline:** the SDXL-based default profile (since May 2026) defeats SynthID v2. **Verified end-to-end (May 2026):** local SDXL run on a Gemini 3 Pro output, checked via the Gemini app's "Verify with SynthID" feature, returned "no SynthID watermark detected". Also confirmed against **OpenAI's** SynthID (2026-05-23): a fresh ChatGPT/gpt-image output read "SynthID detected" on openai.com/verify before the local SDXL run and "SynthID not detected" after (corpus regression chain: pos `4ef377bd` -> cleaned `47188e88`). The same configuration is used in raiw-app production (`fal-ai/fast-sdxl/image-to-image`, strength 0.05, steps 50, guidance 7.5, no pre-downscale). fal's own `llms.txt` for `fast-sdxl` names the base checkpoint as `stabilityai/stable-diffusion-xl-base-1.0` (verified 2026-05-25) -- the exact checkpoint the local CLI defaults to (`DEFAULT_MODEL_ID`). So the local `invisible` default is weight-for-weight identical to prod; "fast-sdxl" is fal's optimized serving, not different weights. After the native-resolution fix the local pipeline matches prod on weights + strength + steps + guidance + resolution. SD-1.5 dreamshaper at 768 px was previously the default and does NOT defeat v2 — verified empirically against the same feature (strength 0.04, 0.10, and elastic warp α∈{5,8} all flagged positive). That SD-1.5 path was removed; only `default` (SDXL) and `ctrlregen` profiles remain. **Scope of the claim: defeating the SynthID verifier is NOT the same as forensic invisibility.** "Removing the Watermark Is Not Enough: Forensic Stealth in Generative-AI Watermark Removal" (arXiv:2605.09203, 2026-05) shows that six removal attacks across four families (UnMarker, CtrlRegen+, WatermarkAttacker, etc.) all leave forensic traces: independent detectors flag *removal-processed* images vs genuinely-clean ones at **>98% TPR at 1% FPR**. So our SDXL pass makes the oracle read "SynthID not detected," but the output can still be classifiable as "an image that went through a removal pipeline." Do not over-claim "indistinguishable from a real photo." https://arxiv.org/abs/2605.09203
+- **DEFAULT STRENGTH IS VENDOR-ADAPTIVE, ONE LADDER FOR BOTH PIPELINES (raised + unified 2026-06-09; vendor-adaptive since 2026-06-01, SUPERSEDES every fixed-default claim in this bullet and the next).** `resolve_strength(strength, vendor)` + `vendor_for_strength(path)` (`watermark_profiles.py`) read the C2PA issuer (`metadata.synthid_source`) on the ORIGINAL input and pick `OPENAI_STRENGTH` **0.20** / `GEMINI_STRENGTH` **0.30** / `UNKNOWN_STRENGTH` **0.30** when `--strength` is unset; explicit `--strength` always wins. **The SAME ladder applies to BOTH pipelines** (`sdxl` and `controlnet`) -- these are the 2026-06-04 Modal-cert controlnet floors. **Why one ladder (NOT a per-pipeline split):** the cert was run on controlnet and does NOT transfer to `sdxl` by symmetry (opposite hard cases -- controlnet leaves SynthID on photoreal, `sdxl` on flat graphics), BUT on its OWN hard case (flat fills) `sdxl` is the WEAKER remover (plain img2img barely perturbs a flat region at low strength), so it needs AT LEAST controlnet's strength -- hence the certified floor is the right floor for `sdxl` too. It is a MARGIN argument for `sdxl`, not a fresh certification (no local SynthID detector to self-verify); raise `--strength` if an oracle still reads a flat `sdxl` output. The higher strength costs little quality because `controlnet` is now the default pipeline AND the only `--auto` pick, so `sdxl` is reached only via an explicit `--pipeline sdxl` (a deliberate opt-down for inputs without faces/text), where over-regeneration has nothing to damage. (A short-lived per-pipeline split ladder -- `sdxl` 0.15/0.20 vs controlnet 0.20/0.30 -- existed on 2026-06-09 before being unified the same day; the `resolve_strength` `pipeline` param and the `CONTROLNET_*_STRENGTH` constants were removed.) The CLI detects the vendor from the pristine source (before the visible pass / metadata-strip removes C2PA from the temp file) and passes it to display calls so display and execution agree; `cmd_invisible`/`cmd_all`/`batch` thread `vendor`. **This replaces the single 0.30 default AND the prior "do NOT build a vendor-adaptive default" policy** -- both came from the now-debunked region-rescrub-contaminated study (the per-region re-scrub that contaminated those numbers was removed in the controlnet refactor). Basis: the oracle-verified June 2026 controlled study (clean v0.8.6, protect OFF): OpenAI clears at 0.05 across 1024-1600 (n=4, resolution-independent); Google needs 0.15 on the capped-1536 path (n=4). `docs/synthid.md` §2.2 (data) + §5.2 (the adaptive default) are authoritative. **CAVEAT (oracle pass 2026-06-04): the OpenAI 0.10 default is content-dependent, NOT universal -- a flat-graphic OpenAI logo/poster still read SynthID-detected after `default` at 0.10, and photoreal images after controlnet at 0.10/0.15 (low-change regions under-perturbed). Removal at 0.10/0.15 is content×pipeline dependent (see the controlnet Known-limitations bullet); the lever is a higher strength, oracle-revalidated per content type. Do NOT assume the vendor-adaptive default clears every image.** CAVEAT: Google's 0.15 was validated only on `--max-resolution 1536`; native large Gemini (2816) was not locally measurable (OOM on M-series) and is pending GPU validation on raiw.cc -- if it survives 0.15 native, raise `--strength`. **Everything below in this bullet about a fixed 0.10/0.30 default is HISTORICAL; trust the vendor-adaptive constants + docs/synthid.md.**
+- **SynthID removal: strength + oracle scope.** Default strength is vendor-adaptive (see the bullet above); `docs/synthid.md` §2.2 is authoritative for the numbers. **Oracle scope (load-bearing):** the Gemini app "Verify with SynthID" is the ONLY valid SynthID oracle (detects Google's mark on any image); `openai.com/verify` is scoped to OpenAI provenance (its own C2PA), NOT a SynthID oracle -- a negative there is meaningless for SynthID. There is no local SynthID detector, so the tool cannot self-check; if the oracle still reads SynthID, raise `--strength` to the lowest value that verifies clean. Only the `sdxl` (plain SDXL img2img; `default` is a back-compat alias) and `controlnet` (SDXL + canny ControlNet) profiles exist; the local `invisible` default is weight-for-weight identical to raiw.cc prod (`fal-ai/fast-sdxl` = `stabilityai/stable-diffusion-xl-base-1.0`, runtime-downloaded, not bundled). **Forensic-stealth caveat** (arXiv:2605.09203): defeating the SynthID verifier is NOT forensic invisibility -- independent detectors flag *removal-processed* images vs genuinely-clean ones at >98% TPR@1%FPR, so do not over-claim "indistinguishable from a real photo".
+- **`controlnet` pipeline (text/face STRUCTURE preservation, THE DEFAULT since 2026-06-09; `--pipeline default` opts down to plain SDXL).** SDXL + the canny ControlNet `xinsir/controlnet-canny-sdxl-1.0` via `StableDiffusionXLControlNetImg2ImgPipeline` (`watermark_remover._run_controlnet` / `_load_controlnet_pipeline`). **Removal still comes from the img2img regeneration (`strength`); the ControlNet only PRESERVES text and face STRUCTURE by conditioning on the canny edge map** (`cv2.Canny(gray, 100, 200)`, 3-channel). Canny preserves edges, NOT face identity (a regenerated face drifts in likeness). The drifted cleaned face is the LEAST-AI state we can reach without re-introducing SynthID; **the library does NOT ship a face-restore extra** (every approach evaluated 2026-06-04 - 2026-06-08 -- GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps -- regenerated the face via SDXL and made it look MORE AI-generated). Full empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up". For production face preservation, ship the cleaned image as-is. No original pixels are copied or frozen, **BUT removal at the low vendor-adaptive strength is CONTENT × PIPELINE dependent and NEITHER pipeline clears all content -- oracle-validated against the OpenAI verifier 2026-06-04 (8 images, strength 0.10/0.15, `--max-resolution 1536`).** The survivors FLIP by content type: **photoreal** (a 9-face grid, a bracelet product photo) SURVIVES controlnet but CLEARS `default` (controlnet's dense edge map keeps the regen too close to the original, so the SynthID-destroying perturbation never happens; plain img2img perturbs photoreal texture enough); **flat graphic** (a logo/poster with large flat color fills) SURVIVES `default` but CLEARS controlnet (at low strength img2img barely changes flat fills so SynthID persists there, while controlnet repaints them more freely); a flat **text** card cleared under both. **Root cause is insufficient STRENGTH, not the pipeline: at 0.10 the low-change regions -- dense-edge photoreal under controlnet, large flat fills under `default` -- are not perturbed enough to destroy SynthID. The vendor-adaptive 0.10 from the June study is NOT universally sufficient (that study's content happened to clear at 0.10).** The robust fix is a HIGHER strength, oracle-revalidated per content type (controlnet can be cranked harder without losing structure; a lower `controlnet_conditioning_scale` also frees the regen on photoreal). So at today's default strength **both pipelines AND `--auto` can LEAVE SynthID on some content** -- a removal-priority caller (raiw.cc) MUST oracle-validate strength across content types before adopting, not pick a pipeline and assume removal. **Follow-up same day: re-running the two photoreal survivors through controlnet at an explicit `--strength 0.15` cleared BOTH on the oracle -- BUT one of them (the bracelet) had SURVIVED the SAME 0.15 controlnet config in the first pass (only the random, unset seed differed). So removal near the threshold is SEED-NON-DETERMINISTIC: the same image+pipeline+strength+resolution can pass or fail run-to-run (img2img uses `seed=None`/random unless `--seed` is passed, and there is no local SynthID detector to self-verify). 0.15 is the borderline, NOT a robust floor -- pick a strength with MARGIN (controlnet ~>= 0.20) rather than exactly on it; the content×pipeline table's 0.15 data point is near-threshold noise. A confirming run at `--strength 0.20` controlnet cleared BOTH photoreal survivors on the oracle (ladder: 0.10 grid detected → 0.15 borderline/non-deterministic → 0.20 both clean), so **0.20 is the recommended robust controlnet floor for OpenAI photoreal** (one margin run, not an N-run repeatability proof -- a service should add margin or verify repeatability since there is no local SynthID detector to self-check). **Engineering follow-up DONE 2026-06-09 (three coupled changes):** (1) **strength raised + unified** -- `resolve_strength(strength, vendor)` now applies ONE vendor-adaptive ladder (the certified controlnet floors 0.20/0.30/0.30) to BOTH pipelines; see the DEFAULT STRENGTH bullet above for why one ladder covers `sdxl`. (2) **`controlnet` is now the DEFAULT pipeline** (CLI `--pipeline` default = `controlnet` + both engine ctors). Rationale: with the certified higher ladder it clears BOTH content classes that flipped in the content-x-pipeline table (photoreal AND flat graphic), whereas plain SDXL left SynthID on flat graphics -- so controlnet is the more removal-robust default. Cost: every non-`--auto` run now downloads the canny ControlNet weights + a higher memory peak (MPS->CPU fallback covers OOM). (3) **the plain-SDXL profile was renamed `default` -> `sdxl`** (`watermark_profiles.SDXL_PROFILE`/`normalize_profile`); `default` stays as a back-compat CLI/ctor alias (the `--pipeline` Choice accepts `sdxl`/`controlnet`/`default`, a click callback `_noLine truncated

LICENSE

@@ -1,21 +1,217 @@
-MIT License
 
-Copyright (c) 2025 wiltodelta
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+   1. Definitions.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+   Copyright 2025-2026 wiltodelta
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -8,22 +8,25 @@ Strips SynthID, C2PA Content Credentials, EXIF/XMP "Made with AI" labels, and vi
 >
 > No Python, no GPU, no setup. Visible-watermark and metadata removal are **free**. Invisible-watermark removal (SynthID / SDXL regeneration) normally needs a local GPU and ~2 GB of models. On **[raiw.cc](https://raiw.cc)** it runs on cloud GPUs in one click for a small per-image fee.
 
+[![Tests](https://github.com/wiltodelta/remove-ai-watermarks/actions/workflows/test.yml/badge.svg)](https://github.com/wiltodelta/remove-ai-watermarks/actions/workflows/test.yml)
 [![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/wiltodelta)
 
 If this tool saves you time, consider [sponsoring its development](https://github.com/sponsors/wiltodelta).
 
+> **Intended for lawful use only.** Publishing and running this software is lawful; responsibility for any downstream use, and for compliance with local law, rests entirely with the user. Some jurisdictions restrict removing an AI label as such (see [Legal](#legal)). The authors do not condone use for deception, fraud, or any unlawful activity.
+
 ## Features
 
-- **Visible watermark removal** — Gemini / Nano Banana sparkle logo (reverse alpha blending) and the Doubao "豆包AI生成" text strip (locate + mask + inpaint); fast, offline, deterministic, no GPU. `visible --mark auto` picks the right one
+- **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
 - **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, and **MP4 / MOV / M4V video** at the container level), XMP DigitalSourceType
-- **"Made with AI" label removal** — removes the metadata that triggers AI labels on Instagram, Facebook, X (Twitter)
-- **Analog Humanizer** — film grain and chromatic aberration to bypass AI image classifiers
-- **Smart Face Protection** — automatic extraction and blending of human faces to prevent AI distortion
+- **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)
+- **Analog Humanizer** — optional film grain and chromatic aberration post-processing
+- **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. 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 SynthID metadata proxy, the visible sparkle, 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, or EXIF), the HuggingFace `hf-job-id` job marker, the SynthID metadata proxy, 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)
 
 ## Examples
 
@@ -46,13 +49,16 @@ If this tool saves you time, consider [sponsoring its development](https://githu
 | **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 `<TC260:AIGC>` XMP label (China's mandatory AI labeling) | Locate + mask + inpaint (cv2, CPU) + 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`) | 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 |
+| **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) and by Doubao / China AIGC generators (the mandated "...AI生成" corner text). Both are removed deterministically on CPU. 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), 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.
 
-> **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, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, the visible sparkle, 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, or EXIF), the HuggingFace `hf-job-id` job marker, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, 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.
 
 ## How it works
 
@@ -76,9 +82,27 @@ A three-stage NCC (Normalized Cross-Correlation) detector finds the watermark po
 
 ### 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. Unlike the fixed-size Gemini sparkle, it is a text strip that scales with image width, so we anchor a generous bottom-right box by geometry, extract the light low-saturation glyph pixels with a polarity-aware white top-hat mask, and inpaint them (cv2 Telea/NS). The mask is background-relative, so it leaves white-paper documents untouched instead of smearing their text. On dense-text backgrounds where the mask would explode, removal is skipped rather than guessed.
+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.
 
-**Speed**: ~0.03s per image. No GPU needed. Best on photo / illustration backgrounds; on high-contrast edges a faint residue can remain (use `erase --backend lama` for neural-quality fill).
+**Speed**: ~0.05s, 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).
+
+```bash
+remove-ai-watermarks visible jimeng.png -o clean.png            # --mark auto picks Jimeng
+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).
+
+```bash
+remove-ai-watermarks visible samsung.jpg -o clean.jpg            # --mark auto picks Samsung
+remove-ai-watermarks visible samsung.jpg --mark samsung -o clean.jpg
+```
 
 ### Universal region eraser
 
@@ -93,15 +117,27 @@ The removal pipeline (default profile, SDXL):
 ```text
 image → encode to latent space (VAE) at native resolution
       → add controlled noise (forward diffusion)
-      → denoise (reverse diffusion, ~50 steps at strength 0.05)
+      → denoise (reverse diffusion, ~50 steps; strength is vendor-adaptive:
+        0.20 OpenAI / 0.30 Google / 0.30 unknown, same for both pipelines;
+        override with --strength)
       → decode back to pixels (VAE)
 ```
 
-By default the image is processed at its **native resolution** with no pre-downscale, matching the hosted raiw.cc backend (fal `fast-sdxl`, which is `stabilityai/stable-diffusion-xl-base-1.0` — the same checkpoint the CLI defaults to). At strength ~0.05 SDXL img2img does not need the input shrunk, and the old forced downscale-to-1024 then upscale-back round-trip was the main quality loss. Pass `--max-resolution N` to cap the long side only when a very large image runs out of GPU/MPS memory (it reintroduces that lossy round-trip).
+- Large inputs run at native resolution (no down-then-up round-trip, which was the main quality loss in issue #10); use `--max-resolution N` only to cap GPU/MPS memory on very large inputs. Small inputs (long side under 1024 px) are auto-upscaled to a 1024 px floor before diffusion, because SDXL distorts on a tiny latent, and the result is restored to the original size (a transparent quality boost). Disable the floor with `--min-resolution 0`. The floor upscale uses Lanczos by default; `--upscaler esrgan` (the `esrgan` extra) runs Real-ESRGAN first for sharper detail and falls back to Lanczos if the extra is absent. ESRGAN is a generic photo/texture GAN with no face/glyph prior, so it is best for photo/texture content -- it can degrade faces (the diffusion pass regenerates them, so the final recovers) and thin text; keep Lanczos for text-heavy inputs.
+
+> **Default strength is vendor-adaptive (no flag needed).** The tool reads the C2PA issuer to detect which vendor's SynthID is present and picks the strength accordingly: **OpenAI gpt-image → `0.20`**, **Google Gemini → `0.30`**, **unknown source → `0.30`**. The **same ladder applies to both pipelines** — these are the oracle-certified `controlnet` floors (June 2026 Modal cert, multi-seed). They also cover plain `sdxl`: the two pipelines have opposite hard cases (controlnet leaves SynthID on photoreal, sdxl on flat graphics), but on its own hard case sdxl is the weaker remover, so it needs at least controlnet's strength — using one certified ladder is the safe choice (margin-based for sdxl, not separately certified). The dominant factor is the vendor (Google's SynthID is ~3x more robust). There is no local SynthID detector, so if the oracle still reads SynthID, raise `--strength`; if you care more about preserving fine detail, lower it. (Caveat: Google's `0.30` was validated only at `--max-resolution 1536`; a very large native Gemini image may need ~`0.35`+.)
+>
+> **The default pipeline is `controlnet` — it preserves text and face structure.** It runs the same SDXL img2img scrub but adds a canny ControlNet that conditions the regeneration on the image's edge map, so text and structure stay sharp at the strengths that remove SynthID. The watermark removal still comes from the img2img regeneration (`--strength`); the ControlNet only preserves structure — no original pixels are copied or frozen. The default strength ladder (OpenAI `0.20` / Google `0.30`) is the oracle-certified controlnet floor. `--controlnet-scale` tunes the preservation strength (higher = closer to the original structure). Runs fp32 on mps/cpu (fp16 only on cuda/xpu, where the fp16-fixed SDXL VAE is loaded automatically). Pass `--pipeline sdxl` for plain SDXL img2img (lighter, no extra model download) on inputs without text or faces.
+>
+> **No face-restore extra in the library.** Every ArcFace-based regeneration approach we evaluated (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps, 2026-06-04 - 2026-06-08 Modal cert sweeps) regenerated the face via SDXL diffusion — the output face pixels were diffusion-fresh (SynthID not re-introduced), but the face inherently looked more AI-generated than the cleaned image (SDXL "clean skin" gloss, lost original identity precision). The cleaned image from the main controlnet 0.20 pass is the least-AI face state we can reach without re-introducing SynthID. Empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md`.
 
 SDXL is the default since May 2026: empirically defeats SynthID v2 on Gemini 3 Pro outputs, where the older SD-1.5 pipeline at 768 px did not. The SD-1.5 path was removed once it was verified not to handle v2. Note the scope: this defeats the SynthID *verifier*, which is not the same as being forensically indistinguishable from a real photo. Recent work ([arXiv:2605.09203](https://arxiv.org/abs/2605.09203)) shows watermark-removal pipelines leave detectable traces, so a separate "this image was processed" classifier can still flag the output.
 
-**Face Protection**: before diffusion, YOLO detects people in the image and extracts them. After diffusion, the original faces are blended back with a soft elliptical mask to prevent AI distortion of facial features.
+> **Oracle vs `identify` can disagree, and that is expected.** An online verifier reads the actual SynthID *pixel* watermark and detects only its own vendor's content — [openai.com/research/verify](https://openai.com/research/verify/) states "OpenAI generation signals will only be detected if the image was generated with our tools". Our `identify` cannot decode the pixel watermark (no vendor ships a local decoder), so it infers SynthID from the **C2PA metadata** instead. So after the SDXL pass the oracle can read "no SynthID" (pixel watermark gone) while `identify` still reports SynthID from a surviving C2PA manifest. They measure different signals. Run `metadata --remove` (or `all`) to also strip the manifest; note that a quiet metadata proxy is not proof the pixel watermark itself is gone.
+
+> **Technical deep-dive:** see [`docs/synthid.md`](docs/synthid.md) for a primary-source-cited breakdown of how SynthID works mechanically (post-hoc encoder/decoder, 136-bit payload, pixel-space embedding), what it empirically survives (JPEG, crop, resize: ~99.98% TPR at 0.1% FPR from arXiv:2510.09263), what removes it, and the forensic-stealth tradeoff (all known removal attacks are detectable at >98% TPR@1%FPR per arXiv:2605.09203).
+
+**Text and face preservation** (the default pipeline; `--pipeline sdxl` opts down to plain SDXL): a canny ControlNet keeps text and face *structure* sharp through the removal pass, without copying or freezing any original pixels (so SynthID is still removed). Tune the preservation strength with `--controlnet-scale`. Canny preserves structure but not face *identity*: the regenerated face drifts in likeness. The library does not ship a face-restore extra (see the callout above).
 
 **Analog Humanizer**: optional film grain and chromatic aberration injection that mimics a photo of a screen, raising the bar for AI-generated image classifiers. (It frustrates generic classifiers but does not guarantee forensic invisibility — see the [arXiv:2605.09203](https://arxiv.org/abs/2605.09203) note above.)
 
@@ -178,6 +214,14 @@ After installation the `remove-ai-watermarks` command is available system-wide.
 > ```bash
 > pip install -e ".[trustmark]"   # or: uv pip install -e ".[trustmark]"
 > ```
+>
+> For sharper upscaling of small inputs before diffusion (`--upscaler esrgan`,
+> Real-ESRGAN), install the `esrgan` extra. It loads via spandrel (MIT, no basicsr);
+> the Real-ESRGAN weights (BSD-3-Clause) download on first use:
+>
+> ```bash
+> pip install -e ".[esrgan]"   # or: uv pip install -e ".[esrgan]"
+> ```
 
 #### Invisible watermark removal
 
@@ -232,9 +276,10 @@ 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) picks
-# between the Gemini sparkle and the Doubao "豆包AI生成" text strip; force one
-# with --mark gemini / --mark doubao.
+# 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).
 remove-ai-watermarks visible image.png -o clean.png
 
 # Erase arbitrary region(s) — universal, any logo/watermark/object, any position.
@@ -242,9 +287,21 @@ remove-ai-watermarks visible image.png -o clean.png
 remove-ai-watermarks erase image.png --region 1640,1930,400,100 -o clean.png
 
 # Invisible watermark only (SynthID etc.) — requires GPU
-remove-ai-watermarks invisible image.png -o clean.png --humanize 4.0
-# Runs at native resolution by default. On a very large image that OOMs the
+remove-ai-watermarks invisible image.png -o clean.png --humanize 4.0 --unsharp 0.5
+# --humanize adds film grain, --unsharp counters the soft "AI" look (both opt-in).
+# Large images run at native resolution; small ones are upscaled to a 1024 floor
+# first (disable with --min-resolution 0); --upscaler esrgan uses Real-ESRGAN for
+# that floor upscale (needs the 'esrgan' extra). On a very large image that OOMs the
 # GPU/MPS, cap the long side: --max-resolution 2048
+# Strength is vendor-adaptive by default (OpenAI 0.20 / Google 0.30, same
+# for both pipelines); override with --strength. controlnet (text/face
+# structure preservation) is the default pipeline; --pipeline sdxl opts down
+# to plain SDXL for non-structure inputs. Tune structure preservation with
+# --controlnet-scale, the CFG with --guidance-scale (default 7.5), and the
+# diffusion model with --model (default: SDXL base).
+# --adaptive-polish (ON by default) restores the input's detail level (sparing
+# text) to counter the over-smoothed look; it self-limits to a no-op where
+# there is no detail deficit. Disable with --no-adaptive-polish.
 
 # Check / strip AI metadata (C2PA, EXIF, "Made with AI" labels)
 # --check also flags SynthID-bearing sources: a C2PA manifest signed by
@@ -256,6 +313,10 @@ remove-ai-watermarks metadata image.png --remove
 
 # Batch with a specific mode
 remove-ai-watermarks batch ./images/ --mode visible
+
+# Batch accepts the full invisible knob set (--strength/--guidance-scale/--model/
+# --pipeline/...); --adaptive-polish is on by default (--no-adaptive-polish to disable)
+remove-ai-watermarks batch ./images/ --mode all
 ```
 
 ### Python API
@@ -276,6 +337,30 @@ clean = engine.remove_watermark(image)
 cv2.imwrite("clean.png", clean)
 ```
 
+#### Invisible removal (diffusion)
+
+```python
+from pathlib import Path
+from remove_ai_watermarks.invisible_engine import InvisibleEngine
+
+# pipeline: "controlnet" (default, preserves text/face structure) or "sdxl" (plain).
+# model_id=None uses the SDXL base; controlnet_conditioning_scale tunes preservation.
+engine = InvisibleEngine(pipeline="controlnet")
+
+engine.remove_watermark(
+    Path("watermarked.png"),
+    Path("clean.png"),
+    strength=None,          # None = vendor-adaptive default (OpenAI 0.20 / Google 0.30)
+    num_inference_steps=50,
+    guidance_scale=None,    # None = the library default (7.5)
+    seed=None,              # set for reproducible output
+    adaptive_polish=True,   # detail-targeted polish, self-gating (default on in the CLI)
+    min_resolution=1024,    # upscale tiny inputs to this floor before diffusion
+    max_resolution=0,       # 0 = native; set only to cap GPU/MPS memory
+    upscaler="lanczos",     # or "esrgan" for the floor upscale (needs the 'esrgan' extra)
+)
+```
+
 ### Metadata stripping
 
 ```python
@@ -310,7 +395,7 @@ pip install certifi
 
 - [noai-watermark](https://github.com/mertizci/noai-watermark) by mertizci — invisible watermark removal engine
 - [GeminiWatermarkTool](https://github.com/allenk/GeminiWatermarkTool) by Allen Kuo (MIT) — visible watermark removal algorithm
-- [CtrlRegen](https://github.com/yepengliu/CtrlRegen) by Liu et al. (ICLR 2025) — controllable regeneration pipeline
+- [controlnet-canny-sdxl-1.0](https://huggingface.co/xinsir/controlnet-canny-sdxl-1.0) by xinsir — SDXL canny ControlNet used by the `controlnet` pipeline to preserve text/face structure
 - NeuralBleach (MIT) — analog humanizer technique
 
 ## Roadmap
@@ -321,8 +406,10 @@ Tracked but not yet implemented:
 - **Local SynthID *pixel* detector**. Not feasible today: Google's decoder is proprietary, and magnitude/carrier spectral methods do not separate real content (confirmed by three independent evaluations, including a from-scratch gpt-image pilot; see CLAUDE.md). Blocked on either (a) a programmatic generation path (OpenAI / Gemini API) to build a per-(model, resolution) labeled corpus at scale, or (b) a raw watermarked-output dataset. If data arrives, the next approach to try is a learned classifier on diverse content rather than a fixed carrier codebook.
 - **Grow the SynthID reference corpus** (`data/synthid_corpus/`) with oracle-labeled samples per model and resolution (Gemini app for Google, openai.com/verify for OpenAI). Prerequisite for any pixel-detector attempt and for an automated removal-regression set.
 - **Real non-PNG C2PA fixtures**. SynthID-source detection for JPEG / WebP / AVIF is currently covered only by synthetic byte blobs; replace with real vendor-emitted files to ground the binary-scan path.
-- **Maintenance debt**. Clear strict-pyright debt in `remove_ai_metadata` / `cli.py` (untyped piexif / PIL / click / rich) so `maintain.sh` can finish green. (`uv-secure` is already clean since `idna` was bumped to 3.16.)
-- **AVIF / HEIF / JPEG-XL detection limits**. Removal strips top-level C2PA `uuid` and JUMBF `jumb` boxes. EXIF/XMP boxes inside these containers are not yet scrubbed (PNG and JPEG are fully covered).
+- **Maintenance debt**. Strict pyright is now clean across `src/` (0 errors): pure-logic files are fully typed, the cv2 / torch / diffusers boundary files carry a documented per-file relax pragma, and a local `typings/piexif` stub covers piexif. Remaining: full-project `pyright` (no path) still OOMs node on this ML-heavy repo, so it must be scoped to `src/`; narrowing the boundary pragmas back toward full strict (as upstream stubs improve) is the long tail. (`uv-secure` is already clean since `idna` was bumped to 3.16.)
+- **AVIF / HEIF `Exif` item inside the `meta` box**. An AI-label *XMP* packet in a `meta`-box item is now blanked in place (v0.6.9), but EXIF stored as a `meta`-box `Exif` *item* is still not removed — it needs full `iinf`/`iloc` surgery (offset rewrite, corruption risk) or `exiftool` (a non-bundled binary dependency). Low priority: the AI labels we target are XMP, not EXIF, so an EXIF-only meta-box case is rare.
+- **More C2PA device signers**. Leica, Nikon, Google Pixel, Sony, and Truepic capture cameras are mapped (each verified against a real signed file); **Samsung Galaxy AI**, **Black Forest Labs (FLUX)**, and **ByteDance Volcano Engine** (Doubao / Jimeng) are now attributed too (verified on real signed files). Canon is still deferred until a real signed sample surfaces — no public direct-download C2PA file exists for it today (upload-to-verify / news-agency-licensed only).
+- **Resemble PerTh audio detection** — evaluated, not feasible with the public API: `get_watermark()` returns a raw bit array with no presence/confidence flag, so watermarked vs. clean audio can't be reliably separated without Resemble's fixed payload or a confidence service. Same wall as the SynthID pixel detector.
 - **Video pipeline (`noai-video`)**: per-frame inpainting and tracking for Sora 2 dynamic logo, Veo 3.1 badge, Kling, Runway. Separate package, not folded into this repo.
 
 Won't fix:
@@ -336,10 +423,10 @@ Watermarking and provenance for AI-generated content is now regulated in several
 | Jurisdiction | Instrument | Status (May 2026) | Relevance |
 | --- | --- | --- | --- |
 | EU | AI Act, Article 50 | Transparency duties apply from **2 August 2026**. Legacy generative systems (placed on the market before that date) get a grandfathering period to **2 December 2026** for the Article 50(2) marking duty, under the Digital Omnibus (Commission proposal Nov 2025; co-legislator political agreement 7 May 2026). Article 50 guidelines and a marking Code of Practice are being finalised through 2026. | Removing mandated provenance markers with intent to deceive may be sanctioned under national implementations. |
-| US (federal) | COPIED Act | **Reintroduced April 2025; not enacted** (pending in the Senate). | If passed, would set NIST provenance standards and prohibit tampering with / removing provenance information. The tool itself is lawful; usage may not be. |
-| US (state) | CA AB 2655, TX SB 751, similar | TX SB 751 in force; **CA AB 2655 struck down** by a federal court (Aug 2025, Section 230 / First Amendment). | Content-specific (election deepfakes, sexual deepfakes). Not tool-specific. |
+| US (federal) | COPIED Act (S. 1396, 119th Cong.) | **Reintroduced April 2025; not enacted** (referred to Senate Commerce Committee). | If passed, would set NIST provenance standards and prohibit tampering with / removing provenance information. The tool itself is lawful; usage may not be. |
+| US (state) | CA AB 2655, TX SB 751 (2019), similar | TX SB 751 (2019) in force; **CA AB 2655 struck down** by a federal court (E.D. Cal., Aug 2025, *Kohls v. Bonta*) as preempted by **Section 230**; the court did not reach the First Amendment (the companion law AB 2839 was separately enjoined on First Amendment grounds). | Content-specific (election deepfakes, sexual deepfakes). Not tool-specific. |
 | US (state) | CA AB 853 (amends the California AI Transparency Act) | Core provider duties operative **2 August 2026** (delayed from 1 January 2026); large platforms 1 January 2027; capture devices 1 January 2028. | Covered providers (1M+ monthly users) must embed a latent disclosure that is "permanent or extraordinarily difficult to remove" and offer a free detection tool. Removing that disclosure is what this tool does. |
-| South Korea | AI Framework Act (Basic Act on AI), Article 31 | In force since **January 2026** (one-year transition after promulgation). | Art. 31(3): AI output "difficult to distinguish from reality" must be labeled so users "clearly recognize" it; the draft Enforcement Decree accepts a machine-readable (invisible-watermark) label. Artistic/creative works get a presentation exception. |
+| South Korea | AI Framework Act (Basic Act on AI), Article 31 | In force since **22 January 2026** (one-year transition after promulgation). | Art. 31(3): AI output "difficult to distinguish from reality" must be labeled so users "clearly recognize" it; the draft Enforcement Decree accepts a machine-readable (invisible-watermark) label. Artistic/creative works get a presentation exception. |
 | China | Measures for Labeling AI-Generated Content (+ GB 45438-2025) | In force since **1 September 2025**. | Mandatory explicit (visible) + implicit (metadata) labels across image / audio / video; tampering with, forging, or removing labels is prohibited. |
 | India | IT (Intermediary Guidelines and Digital Media Ethics Code) Amendment Rules, 2026 | In force since **20 February 2026** (notified 10 February 2026). | All "synthetically generated information" must be **prominently labelled** and carry **permanent metadata / a provenance identifier**; the rules expressly **prohibit modifying, suppressing, or removing** that label or metadata. Covers image, audio, and audio-visual content. |
 | UK | Online Safety Act 2023 / Ofcom guidance | In force, but **no statutory AI-provenance or watermarking obligation**. | Ofcom encourages watermarking / provenance metadata as voluntary "attribution measures"; platform duties, not user obligations. |
@@ -375,4 +462,4 @@ Legitimate uses — publishing your own work, privacy (stripping metadata that l
 
 ## License
 
-MIT
+[Apache 2.0](LICENSE). Copyright 2025-2026 wiltodelta.

data/doubao_capture/README.md

@@ -1,5 +1,12 @@
 # Doubao visible watermark capture
 
+> **Status (captured 2026-05-29; alpha rebuilt 2026-05-31):** the black/gray/white captures were
+> taken and are now **committed** in `captures/` (solid colour + watermark, content-free). The alpha
+> map is rebuilt by `scripts/visible_alpha_solve.py doubao` (the careful gray-self solve shared with
+> Jimeng). The first build claimed "pixel-exact" but left a readable outline on the real sample (issue
+> #13 follow-up); removal now reverse-alphas, NCC-aligns, and applies a thin residual inpaint. See the
+> `doubao_engine.py` notes in the root `CLAUDE.md`. The text below is kept as the historical capture plan.
+
 Goal: capture the Doubao "豆包AI生成" visible watermark over known flat backgrounds so we can
 build a per-pixel alpha map and a reverse-alpha-blend remover, the same way the Gemini sparkle
 engine works (`src/remove_ai_watermarks/gemini_engine.py`).
@@ -16,8 +23,10 @@ engine works (`src/remove_ai_watermarks/gemini_engine.py`).
 - Size **scales with resolution**. Third-party numbers (~90x18 at <=1024, ~180x40 at >1024) are
   approximate and calibrated for ~1024-1280 outputs; at 2048 the strip is much larger. A shipped
   third-party alpha map is only 120x20, too small for our 2K/4K target -> capture fresh.
-- In practice clean inversion leaves residue on textured backgrounds, so the remover pairs the alpha
-  map with inpainting (our Gemini engine already does gradient-masked inpainting for residual edges).
+- The planning assumption was that clean inversion leaves residue on textured backgrounds, so the
+  remover would pair the alpha map with inpainting. After the capture this turned out unnecessary at
+  the native width (recovery is pixel-exact there and inpaint is off); the shipped remover is
+  reverse-alpha only, with a residual inpaint applied off-native only.
 
 ## Use doubao.com specifically
 

data/gemini_capture/README.md

@@ -0,0 +1,45 @@
+# Gemini (Nano Banana) visible sparkle capture
+
+> **Status (captured 2026-05-31):** black/gray/white captures taken and **committed**
+> in `captures/` (solid colour + the sparkle, content-free). The sparkle-on-black assets
+> `gemini_bg_{96,48}.png` are rebuilt by `scripts/visible_alpha_solve.py gemini`.
+
+Google Gemini (Nano Banana) stamps a four-point sparkle icon in the bottom-right corner
+via alpha compositing: `watermarked = a*logo + (1-a)*original`. Unlike the Doubao/Jimeng
+text marks, the sparkle is captured over a **pure-black** background, where
+`watermarked = a*255` (logo is near-white), so the alpha reads directly off the capture
+(`alpha = max(R,G,B)/255`) -- no background fit needed. This is the "golden" capture case.
+
+## What the captures confirmed (2026-05-31)
+
+- The sparkle at a 2048-wide image is **96x96 px** (width_frac ~0.047), bottom-right,
+  margins ~0.031, alpha max ~0.51 -- matching the engine's existing 96px asset.
+- Our own controlled capture matches the previously third-party-sourced
+  `gemini_bg_96.png` to **NCC 0.9998**, so the bundled asset is validated and now
+  reproducible from our own capture.
+
+## How to capture (image-edit path)
+
+For each solid-colour seed (`seeds/seed_{black,gray,white}_2048.png`, gitignored):
+
+1. Open Gemini image generation, image-edit / reference mode, upload the seed.
+2. Prompt: `Recreate this image exactly as it is, keep it identical, do not add or change anything`
+3. Download the ORIGINAL output (not a screenshot). Do not crop / edit / re-save.
+
+Black is the key one (sparkle on black -> exact alpha). Gray/white cross-check.
+
+## Naming, drop into `captures/`
+
+```
+gemini_black_2048.png   # the key capture (sparkle on black)
+gemini_gray_2048.png
+gemini_white_2048.png
+```
+
+The solid captures are **committed** (content-free). The synthetic `seeds/` and any
+real-content `gemini_content_*.png` validation download are gitignored (local-only).
+Rebuild the assets with:
+
+```
+uv run python scripts/visible_alpha_solve.py gemini   # or: all
+```

data/jimeng_capture/README.md

@@ -0,0 +1,75 @@
+# Jimeng (即梦AI) visible watermark capture
+
+> **Status (completed 2026-05-30):** solid black/gray/white Jimeng captures were
+> obtained (issue #13, from @powersee) and the alpha map was solved. Removal is
+> reverse-alpha plus a residual inpaint over the glyph footprint; see the
+> `jimeng_engine.py` notes in the root `CLAUDE.md`. The text below is kept as the
+> capture plan.
+
+Goal: capture the Jimeng / Dreamina "★ 即梦AI" visible wordmark over known flat
+backgrounds so we can build a per-pixel alpha map and a reverse-alpha remover, the
+same way the Gemini sparkle and Doubao strip engines work
+(`src/remove_ai_watermarks/gemini_engine.py`, `doubao_engine.py`).
+
+## What we learned (verified from the captures, 2026-05-30)
+
+- Mark: a four-point sparkle icon followed by the "即梦AI" characters, near-white
+  semi-transparent overlay, bottom-right corner.
+- Blend model: **alpha compositing with a pure-white logo** `watermarked =
+  a*255 + (1-a)*original`, confirmed in sRGB (a linear-light solve made the
+  black/gray cross-residual much worse, so the compositing is plain sRGB). An
+  L-pair-solve (independent of the L assumption) lands at ~254.6, confirming white.
+- **Alpha is solved from the GRAY capture**, not black: `a = (I - B)/(255 - B)`
+  with B a per-capture CUBIC background fit over the non-glyph pixels, averaged
+  over channels, at FULL halo extent (down to a~0.02) and UNBLURRED. Gray (bg ~132)
+  is the best proxy for real content (the mark sits on bright photo areas, not on
+  black). This careful build drops the gray self-residual to ~1.3; an earlier
+  max-channel / quadratic-bg / blurred / halo-truncated build (and a black-dominated
+  least-squares solve) left a visible outline -- the mask quality, not the method,
+  was the limit.
+- Geometry (fraction of image WIDTH, at the captured 2048): asset width ~0.211,
+  height ~0.068, right margin ~0.023, bottom margin ~0.023. The mark scales with
+  width; a real 1440-wide download matched width_frac ~0.21.
+- **Per-image render variation:** the alpha maps solved independently from the
+  black and the gray capture correlate 0.998 but not 1.0 (mean |Δa| ~0.02). Jimeng
+  re-rasterizes the mark per generation AND jitters its position a few px, so a
+  single alpha map does NOT pixel-cancel the mark the way Doubao's deterministic
+  overlay does. Removal therefore: NCC-aligns the alpha to the actual mark (always,
+  not only off-native), reverse-alphas, then clears the residual with a THIN inpaint
+  over the glyph footprint (a wide full-footprint pass smeared the texture/edges).
+
+## How to capture (image-edit path, most reliable)
+
+For each solid-color seed:
+
+1. Open Jimeng image generation, use the image-edit / reference mode, upload the seed.
+2. Prompt (Chinese preferred):
+   `请完全按照原图重新生成这张图片，保持完全一致，不要添加或修改任何内容`
+3. Download the ORIGINAL output file (not a screenshot). Do not crop / edit / re-save.
+
+The black capture is the key one (white logo on black -> `captured ~= a*255`); the
+gray capture refines the alpha at mid-tones; the white capture confirms the logo is
+pure white (the mark is nearly invisible on white, as expected).
+
+## Hygiene
+
+- Original download, never a screenshot. PNG preferred; if Jimeng only gives JPEG, note it.
+- No crop / edit / re-save. Default settings, watermark left ON.
+
+## Naming, drop into `captures/`
+
+```
+jimeng_cap_A.png   # black seed run through Jimeng
+jimeng_cap_B.png   # white seed
+jimeng_cap_C.png   # gray seed
+jimeng_content_1.png  # a normal-content download, for end-to-end validation
+```
+
+The solid `jimeng_cap_{A,B,C}.png` captures are **committed** (content-free: a solid
+colour + the watermark; the source for `scripts/visible_alpha_solve.py jimeng`). The
+synthetic `seeds/` and the real-content `jimeng_content_*.png` validation download are
+gitignored (local-only). Rebuild the alpha asset with:
+
+```
+uv run python scripts/visible_alpha_solve.py jimeng   # or: all
+```

data/samsung_capture/README.md

@@ -0,0 +1,66 @@
+# Samsung Galaxy AI visible watermark capture
+
+> **Status (built 2026-06-05):** flat black/gray/white Samsung Galaxy AI captures
+> were obtained (issue #37, from @f-liva) and the alpha map was solved. Removal is
+> reverse-alpha plus a thin residual inpaint over the glyph footprint; see the
+> `samsung_engine.py` notes in the root `CLAUDE.md`. The text below is the capture
+> plan and the open quality follow-up.
+
+Goal: capture the Samsung Galaxy AI "✦ Contenuti generati dall'AI" visible wordmark
+over known flat backgrounds so we can build a per-pixel alpha map and a reverse-alpha
+remover, the same way the Gemini sparkle and the Doubao / Jimeng strips work
+(`src/remove_ai_watermarks/gemini_engine.py`, `doubao_engine.py`, `jimeng_engine.py`).
+
+## What we learned (verified from the captures, 2026-06-05)
+
+- Mark: a sparkle icon followed by the locale string "Contenuti generati dall'AI"
+  (Italian), a light low-opacity (peak alpha ~0.38) semi-transparent **white**
+  overlay, anchored **bottom-LEFT** (Doubao/Jimeng are bottom-right). The string is
+  locale-specific, so the alpha template is per-locale; this build is the Italian
+  variant. Other locales need their own captured template.
+- Blend model: alpha compositing with a pure-white logo, `watermarked =
+  a*255 + (1-a)*original`, solved from the GRAY capture (same careful recipe as
+  Doubao/Jimeng: cubic-background fit, mean over channels, full halo extent,
+  unblurred). The white capture confirms the logo is white; on white the mark is
+  white-on-white and not detectable (no contrast), which is fine -- there is nothing
+  to recover there.
+- Geometry (fraction of image WIDTH): asset width ~0.32, height ~0.038, left margin
+  ~0.011, bottom margin ~0.006. The mark scales with width: a 1086-wide flat capture
+  and a 2958-wide real photo both measure width_frac ~0.31.
+- **Resolution caveat (open quality follow-up):** the flat black/gray/white captures
+  arrived at the phone's flat-edit size (1086 wide and a landscape 1920 set), while
+  the real photos are ~3000 wide, so the captured glyph (~334 px) is ~2.7x smaller
+  than on a real photo (~900 px). The alpha is solved at the capture size and
+  width-scaled + NCC-aligned per image, which removes the mark cleanly (verified on a
+  real 2958-wide photo: re-detect 0.79 -> 0.00, no readable text or outline), but a
+  flat capture taken at the real photo resolution (~3000 wide) would let the alpha be
+  pixel-sharp instead of upscaled. Not a blocker; a quality upgrade if a full-res
+  flat capture is provided.
+
+## Capture protocol (to re-capture or add a locale)
+
+On a Samsung Galaxy AI device (set the UI language to the target locale):
+
+1. Run the AI edit (Generative Edit / Sketch to Image) on a solid black image, so
+   the overlay lands on a flat black background. Download the ORIGINAL output file
+   (not a screenshot, no crop or re-save).
+2. Repeat over solid white and solid gray (those pin the exact glyph color).
+3. Ideally run all three flat edits at the same resolution as real photos (~3000
+   wide) so the alpha map is pixel-sharp rather than upscaled.
+4. Plus 3-5 real outputs with the visible mark over normal content for validation.
+
+## Files
+
+- `captures/samsung_black_1.png`, `samsung_gray_1.png`, `samsung_white_1.png` --
+  portrait flat edits (1086 wide), the primary calibration set.
+- `captures/samsung_black_2.png`, `samsung_gray_2.png`, `samsung_white_2.png` --
+  a second (landscape 1920) set.
+- `captures/samsung_content_*` -- real-photo validation downloads, **gitignored**
+  (user content, repo is public).
+- `seeds/` -- synthetic solid-color inputs, gitignored (regenerable).
+
+Rebuild the alpha asset with:
+
+```
+uv run python scripts/visible_alpha_solve.py samsung
+```

data/synthid_corpus/manifest.csv

@@ -24,3 +24,17 @@ d20d4cc936dbdfe909c52502039a9e84ba93d97b42b24a0acee5b7d6c71930ae,d20d4cc9-Gemini
 c86973424817f62510e2a312b85c52e05adf47ace87a8e717fd442607596f501,c8697342-aistudio_lake.png,pos,Google AI Studio (Nano Banana),gemini-2.5-flash-image,1024,1024,png,,,gemini-app,2026-05-24T21:39:09Z,"API/playground: SynthID pixel CONFIRMED (Gemini-app oracle) + visible sparkle, but NO C2PA/IPTC -> synthid_source blind spot"
 1f81827c06d67cf6f6c7f5d53ec8f9738183942a6d1d2717b161fea0fdcc540a,1f81827c-Designer.png,pos,Microsoft Designer,dall-e (Designer),1024,1024,png,"OpenAI, Microsoft",yes,c2pa-metadata,2026-05-24T22:18:40Z,C2PA issuer OpenAI+Microsoft; synthid_source=OpenAI (DALL-E surface inherits OpenAI SynthID+C2PA)
 f6dd47a5ffd319aea21bf10dcf9877097666420b02c2620080bac12b03976e7e,f6dd47a5-4ef377bd-gpt-image-2-cleaned.png,cleaned,"our pipeline (invisible/SDXL, native-res default)",stabilityai/stable-diffusion-xl-base-1.0,1254,1254,png,,,openai-verify,2026-05-25T20:50:38Z,"cleaned from 4ef377bd via v0.5.3 'all' at native 1254x1254 (prod-equivalent); openai.com/verify: SynthID NOT detected. Re-confirms #10 native-res default defeats OpenAI SynthID (closes #15 root cause). Note: native res OOMs on 20GB MPS, auto-fell back to CPU."
+05b836ecfe40fd689177fda74384ae4fdcc446505bbc4281cd3cbb6523eb669e,05b836ec-openai_1_original.png,pos,ChatGPT,gpt-image,1122,1402,png,OpenAI,yes,openai-verify,2026-06-04T00:07:53Z,June 2026 strength-study subject; openai.com/verify: SynthID detected (docs/synthid.md 2.2)
+794e023ea7ae321267fe5af76f4080c98a84a9865669c0733ebfb9757b8638df,794e023e-openai_2_original.png,pos,ChatGPT,gpt-image,1024,1536,png,OpenAI,yes,openai-verify,2026-06-04T00:07:53Z,June 2026 strength-study subject; openai.com/verify: SynthID detected (docs/synthid.md 2.2)
+28ff8732b037f98a4ef5bc277bbcdaa32e5eb9ccbd00b6c8c616e46ef68ae8a0,28ff8732-openai_3_original.png,pos,ChatGPT,gpt-image,1448,1086,png,OpenAI,yes,openai-verify,2026-06-04T00:07:53Z,June 2026 strength-study subject; openai.com/verify: SynthID detected (docs/synthid.md 2.2)
+4affd7f27767a445db6abf741355743ba8d95108ad922c9fff045feed8492236,4affd7f2-gemini_1_original.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+8c1a6fb03ef3d45a1f958fb3401e4264e409ff88c2a793061db7f29023454d0e,8c1a6fb0-gemini_2_original.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+45d79a683134fcba1b147b2aedb669783d474e1fb8a4df329729a0904fd1b46b,45d79a68-gemini_3_original.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+2c33e75a2db614ce74c83cc0a6ac6c3ac735aca83ab88c9c9345843b124f7856,2c33e75a-gemini_4_original.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+2e4ce41cfab456c1d9ea0898e47a5a1d434266ba24e88d4cc807a4180a56925f,2e4ce41c-openai_1_clean_s005.png,cleaned,"our pipeline (SDXL img2img, native)",stabilityai/stable-diffusion-xl-base-1.0,1122,1402,png,,,openai-verify,2026-06-04T00:08:05Z,cleaned at strength 0.05 native; openai.com/verify: SynthID NOT detected (docs/synthid.md 2.2)
+f7c52cdfeb14a6be2fff449e89b0181e66e365f36635ee4fcb21567e4cb770ef,f7c52cdf-openai_3_clean_s005.png,cleaned,"our pipeline (SDXL img2img, native)",stabilityai/stable-diffusion-xl-base-1.0,1448,1086,png,,,openai-verify,2026-06-04T00:08:05Z,cleaned at strength 0.05 native; openai.com/verify: SynthID NOT detected (docs/synthid.md 2.2)
+37b34274210888702e56eb74f4aa36578f15bf57157a3ebf394f0b8eaa820e19,37b34274-openai_2_clean_s010.png,cleaned,"our pipeline (SDXL img2img, native)",stabilityai/stable-diffusion-xl-base-1.0,1024,1536,png,,,openai-verify,2026-06-04T00:08:05Z,cleaned at strength 0.10 native (min captured for this subject); openai.com/verify: SynthID NOT detected
+f99bd9a51814265a23de467d14792db903fef99678b7e7c960d0c6813ed9b0fc,f99bd9a5-gemini_1_clean_s015_max1536.png,cleaned,"our pipeline (SDXL img2img, --max-resolution 1536)",stabilityai/stable-diffusion-xl-base-1.0,2816,1536,png,,,gemini-app,2026-06-04T00:08:05Z,cleaned at strength 0.15 --max-resolution 1536; Gemini-app: SynthID NOT detected (docs/synthid.md 2.2)
+4aa5f61c55c1f3fa9bbc49dffff8a404527722637ae694a932245629635b3f2b,4aa5f61c-gemini_2_clean_s015_max1536.png,cleaned,"our pipeline (SDXL img2img, --max-resolution 1536)",stabilityai/stable-diffusion-xl-base-1.0,2816,1536,png,,,gemini-app,2026-06-04T00:08:05Z,cleaned at strength 0.15 --max-resolution 1536; Gemini-app: SynthID NOT detected (docs/synthid.md 2.2)
+356196dd63abf011b30b582a0408ccecb726d746065af20ad3611dde72a88725,356196dd-gemini_3_clean_s015_max1536.png,cleaned,"our pipeline (SDXL img2img, --max-resolution 1536)",stabilityai/stable-diffusion-xl-base-1.0,2816,1536,png,,,gemini-app,2026-06-04T00:08:05Z,cleaned at strength 0.15 --max-resolution 1536; Gemini-app: SynthID NOT detected (docs/synthid.md 2.2)
+9e4160bb8e3e915d2d4593e37c71495ee7cfcec183602541166f622ebfd84403,9e4160bb-gemini_4_clean_s015_max1536.png,cleaned,"our pipeline (SDXL img2img, --max-resolution 1536)",stabilityai/stable-diffusion-xl-base-1.0,2816,1536,png,,,gemini-app,2026-06-04T00:08:05Z,cleaned at strength 0.15 --max-resolution 1536; Gemini-app: SynthID NOT detected (docs/synthid.md 2.2)

docs/controlnet-removal-pipeline-research.md

@@ -0,0 +1,644 @@
+# ControlNet-as-removal-pipeline research: can structure-conditioned regeneration scrub SynthID and keep text?
+
+Date: 2026-06-02. Source: a manual primary-source pass (WebSearch + WebFetch over the
+watermark-removal-attack and SDXL-ControlNet literature). Prompted by issue #35
+(@newideas99 / Jacob): "as we use SDXL even at low strength that kills small text ... Do you
+think ControlNet could be added to preserve and still remove the watermark?" Clarified scope:
+Jacob means **replacing the removal pipeline itself** with a ControlNet-conditioned
+regeneration (structure held by the control signal), NOT a separate text-protection add-on.
+
+A deep-research workflow run was attempted first (`wf_3244411d-ffd`) and failed at the harness
+level (97 agents completed without emitting StructuredOutput; ~4.3 M tokens, no report). This
+note is the hand-run replacement.
+
+## The question, precisely
+
+Can a single full-image ControlNet-conditioned diffusion pass **replace** plain SDXL base 1.0
+img2img as the watermark remover, so that one structure-guided regeneration removes the
+invisible robust pixel watermark (Google SynthID) **everywhere** while keeping fine detail and
+small/CJK **text** legible across the whole image? The hard constraint is unchanged from
+`text-protection-research.md`: the watermark must be scrubbed everywhere including inside text,
+so any path that freezes or composites original text pixels is disqualified.
+
+## Executive summary
+
+The idea is **already academically validated as a watermark remover and is literally what we
+already ship** — CtrlRegen (ICLR 2025) is a canny-ControlNet + DINOv2-semantic pipeline that
+regenerates from clean noise. But the make-or-break gap is exact: **none of the
+watermark-removal papers validate TEXT or fine-detail preservation at all** — CtrlRegen reports
+only FID/PSNR/quality-model scores and explicitly contains no text, fine-detail, or
+hallucination analysis. Our shipped ctrlregen's empirical failure ("destroys real content,
+hallucinates micro-text in smooth regions") is precisely this unstudied failure mode of the
+published method, most likely driven by our **512 px tiling** (text occupies too few pixels per
+tile to regenerate legibly; edge-free smooth regions get DINOv2-semantic hallucination). The
+constructive path is NOT to keep fixing the SD1.5 CtrlRegen, but to port the structure-control
+idea onto an **SDXL-native** ControlNet (xinsir tile-sdxl / ControlNet-Union-SDXL) as a control
+add to our existing SDXL base 1.0 img2img, run it at **1024+, not 512 tiles**, and empirically
+sweep the (denoise strength x conditioning scale x resolution) cube against the SynthID oracle
+AND a text-legibility check. The central tension may be fundamental and must be measured: the
+conditioning strong enough to keep text legible may suppress regeneration enough to let SynthID
+survive; the regeneration strong enough to scrub may deform text regardless of edges.
+
+## Oracle validation 2026-06-04 — measured answer (AUTHORITATIVE; supersedes pre-oracle "scrubs SynthID" claims below)
+
+The central tension the summary predicted is now MEASURED against the live oracles
+(OpenAI `openai.com/verify` for OpenAI content; the Gemini app "Verify with SynthID"
+for Google content — each detects only its own vendor's payload). **Verdict: at the
+shipped low vendor-adaptive strength, controlnet is NOT a drop-in SynthID remover.**
+It preserves structure so well that the watermark survives on exactly the photoreal
+content it protects. Controlnet is the text/structure PRESERVATION pipeline; removal
+is set by STRENGTH, separately calibrated, not by the pipeline choice.
+
+This section is the single consolidated reference for the controlnet pipeline's
+removal behavior. (Mirrored briefly in `docs/synthid.md` §5.5 and the CLAUDE.md
+controlnet / face_restore bullets, which point here.)
+
+### What we measured (real gpt-image + Gemini originals)
+
+**1. Content × pipeline — neither pipeline clears all content at low strength.**
+OpenAI set, strength = vendor-adaptive (0.10 OpenAI / 0.15 no-C2PA), `--max-resolution 1536`:
+
+| content | controlnet (`--auto`) | plain `default` |
+|---|---|---|
+| flat text card | clean | clean |
+| flat graphic (logo/poster, large flat fills) | clean | **SynthID detected** |
+| photoreal (9-face grid) | **SynthID detected** | clean |
+| photoreal (bracelet product photo) | **SynthID detected** | clean |
+
+Mechanism: controlnet's dense edge map keeps the regeneration very close to the original
+on photoreal, so the SynthID-destroying perturbation never happens; but it freely
+repaints large flat fills. Plain img2img at low strength perturbs photoreal texture
+enough yet barely touches flat fills. So the survivors FLIP by content type — pipeline
+choice alone does not guarantee removal.
+
+**2. Seed non-determinism near threshold.** img2img uses a random seed unless `--seed`
+is passed, and there is no local SynthID detector to self-verify. The bracelet survived
+controlnet @0.15 in one run and CLEARED @0.15 in another (same pipeline+strength+res).
+So a single clean run does NOT establish a strength as safe — characterizing a reliable
+floor needs a seed-repeatability sweep (N runs, varied seed), not one pass.
+
+**3. Per-vendor controlnet strength ladder (photoreal, oracle):**
+- **OpenAI:** 0.10 detected → 0.15 borderline/non-deterministic → 0.20 cleared (with margin).
+- **Gemini** (harder vendor; default 0.15 vs OpenAI 0.10): most cleared at 0.15–0.25.
+- **Resolution is NOT the lever:** SynthID is robust to downscaling, and the study's
+  trend says LOWER processing res needs LESS strength, so 1024 was never the wall. A
+  Gemini face that resisted 0.15/0.20/0.25 was blocked by face-restore (#4), not strength.
+
+**4. `--restore-faces` RE-INTRODUCES SynthID (was the "stubborn face" mystery).** A
+Gemini face image stayed SynthID-detected through controlnet 0.15/0.20/0.25 WITH restore,
+but CLEARED at 0.20 with `--no-restore-faces` (clean single-variable A/B). GFPGAN runs on
+the **ORIGINAL watermarked** face at fidelity weight 0.5, blends ~half its pixels with the
+StyleGAN2 prior, and composites that back OVER the diffusion-cleaned face → the watermark
+returns in the face region. Content-dependent (smaller faces can clear with restore). So
+raising strength cannot fix it — the face is re-pasted from the original after diffusion.
+This also corrects the prior "GFPGAN scrubs SynthID / oracle-confirmed clean" claim (it was
+checked on one lucky image).
+
+### Certified controlnet strength floors (Modal GPU sweep + oracle, 2026-06-04)
+
+Run via the isolated `raiw-controlnet-cert` Modal app (`raiw-app/modal_cert.py`):
+controlnet, `restore_faces` OFF (it re-introduces SynthID), `--max-resolution 1536`,
+each image checked on ITS OWN vendor oracle (OpenAI -> openai.com/verify, Gemini -> the
+Gemini app; the two payloads are vendor-specific and never cross-checked):
+
+| vendor | **floor** | evidence (oracle, restore OFF, <= 1536) |
+|---|---|---|
+| **OpenAI** | **0.20** | 2 photoreal images (9-face grid + bracelet) x seed {1,2,3} = **6/6 clean**; the bracelet that FLIPPED at 0.15 is seed-robust at 0.20 |
+| **Gemini** | **0.30** | hardest face (gemini_3): 0.20 detected -> 0.30 clean on **2/2 seeds**; Gemini is the harder vendor (default 0.15 vs OpenAI 0.10) AND resolution-sensitive |
+
+- **OpenAI 0.20 transfers to prod as-is** (OpenAI removal is resolution-independent:
+  the study clears it at 0.05 across 1024-1600).
+- **Gemini 0.30 is the floor at <= 1536 only.** Gemini is resolution-sensitive (study:
+  native 2816 likely needs >= 0.30 even on `default`), and **raiw.cc runs NATIVE**
+  (`max_resolution=0` in `modal_app.py`). So either CAP Gemini to <= 1536 in raiw.cc and
+  use 0.30, or run a native-resolution Gemini cert and expect a higher floor (~0.35+).
+
+### Recommendations for a removal pipeline (raiw.cc)
+
+- **Treat controlnet as PRESERVATION, not removal.** Choose it for text/structure content,
+  `default` for photoreal; removal efficacy comes from STRENGTH in both.
+- **Give controlnet a higher, per-vendor strength than `default`** (today both share
+  `resolve_strength` 0.10/0.15, tuned for plain img2img). **Certified controlnet floors:
+  OpenAI 0.20, Gemini 0.30** (see table above) — add a controlnet-specific per-vendor
+  schedule to `resolve_strength` rather than reusing the `default` ladder.
+- **Fix the seed in prod.** The non-determinism is purely `seed=None` (random); a fixed
+  `--seed` makes every run reproduce the certified-clean result, so you ship a
+  deterministic, re-certifiable config (and the seed sweep collapses to one config).
+- **`--restore-faces` is OFF in prod and stays opt-in.** Two methods ship
+  (`instantid` default, `photomaker`), both NON-COMMERCIAL. They REGENERATE the face
+  from an ArcFace embedding via SDXL diffusion, making the output face look more
+  AI-generated than the cleaned image (gloss, symmetric pores, SDXL "clean skin"
+  aesthetic). For production face preservation the cleaned image from controlnet 0.20
+  is the LEAST-AI state we can reach — any restore on top trades original-look for
+  embedding-driven regeneration. Empirical sweep summary: GFPGAN-on-cleaned polished
+  without identity recovery; PhotoMaker-V2 produced a different person; InstantID
+  txt2img produced studio-portrait patchwork on group photos; InstantID
+  img2img-on-cleaned with three parameter settings integrated scene context cleanly
+  but never recovered original identity precisely — every setting traded one problem
+  for another. See `docs/synthid-robust-identity-research-2026-06-08.md`
+  "Empirical follow-up" for the full sweep.
+- **No local SynthID detector exists** → the service can't self-verify; bake in strength
+  margin and periodic oracle spot-checks.
+- **Lesson:** visual-quality / face-identity recovery does NOT prove removal — only the
+  oracle does, across MULTIPLE content types; never conclude from a partial result (the
+  photoreal-only data first read as "controlnet shields, default removes"; the flat-graphic
+  result reversed it; the face mystery was restore, not strength).
+
+## Findings (with confidence and sources)
+
+### Finding 1 — confidence: high
+
+**Claim.** "ControlNet as the removal pipeline" is exactly CtrlRegen (ICLR 2025), and our
+shipped `ctrlregen` profile is a faithful implementation of it. Its **spatial control is canny
+edges** extracted from the watermarked image; its **semantic control is DINOv2-giant** via a
+trainable projection + decoupled cross-attention. Clean-noise (full-strength) regeneration
+scrubs the watermark from both pixel and latent space while the two control nets hold structure.
+
+**Evidence.** CtrlRegen: spatial control "conditioned on Canny edge images extracted from the
+watermarked image," integrated into the U-Net decoder blocks via a ControlNet structure;
+semantic control on "DINOv2-giant" embeddings. Removal is strong: TPR@1%FPR driven from 1.00 ->
+0.01 (StegaStamp) and 0.99 -> 0.12 (TreeRing). This matches our `ctrlregen/engine.py` exactly
+(canny detector + `facebook/dinov2-giant` + spatial ControlNet from `yepengliu/ctrlregen`).
+
+**Sources.** https://arxiv.org/html/2410.05470v1 · https://github.com/yepengliu/CtrlRegen ·
+https://openreview.net/forum?id=mDKxlfraAn
+
+### Finding 2 — confidence: high
+
+**Claim.** Regeneration provably removes any bounded-perturbation pixel watermark **given enough
+noise** — the operative constraint is the amount of regeneration, which is the same knob that
+trades against fidelity.
+
+**Evidence.** Zhao et al., "Invisible Image Watermarks Are Provably Removable Using Generative
+AI" (NeurIPS 2024): a noise-then-reconstruct regeneration attack "guarantees the removal of any
+invisible watermark" that perturbs the image within a bounded L2 distance. The guarantee is a
+function of injected noise magnitude — low noise preserves detail but leaves the watermark; high
+noise scrubs but discards original signal. This is the knob ControlNet conditioning is meant to
+make survivable (push regeneration high while the control signal holds composition).
+
+**Sources.** https://arxiv.org/abs/2306.01953 · https://github.com/XuandongZhao/WatermarkAttacker
+
+### Finding 3 — confidence: high
+
+**Claim.** The make-or-break gap: **no watermark-removal paper validates text or fine-detail
+preservation.** CtrlRegen's "high perceptual quality" is FID/PSNR/quality-model only and
+explicitly omits text, fine-detail, and hallucination analysis. So the literature does NOT
+support the specific claim Jacob needs (text survives), it is simply unmeasured.
+
+**Evidence.** CtrlRegen reports CLIP-FID, PSNR, Q-Align, LIQE; the fetched analysis confirms
+"the paper contains no discussion of text preservation, fine-detail retention, or hallucination
+artifacts," and "explicitly avoids discussing failure modes." Pixel metrics like PSNR are
+acknowledged not to reflect perception, and text legibility is a different axis than FID.
+
+**Sources.** https://arxiv.org/html/2410.05470v1
+
+### Finding 4 — confidence: medium-high
+
+**Claim.** Resolution is the prime suspect for our shipped ctrlregen's content destruction. We
+tile to **512 px** and run full clean-noise per tile; at 512 px text occupies too few pixels per
+tile to regenerate legibly, and smooth edge-free regions (no canny signal) are filled by the
+DINOv2 semantic prior, which hallucinates texture/micro-text. The paper omits resolution
+entirely, so this is an implementation regime it never characterized.
+
+**Evidence.** Our `ctrlregen/engine.py`: `PROCESS_SIZE = 512`, `TILE_SIZE = 512`, full strength
+on each tile. This mirrors the `_run_region_hires` insight (text needs MORE pixels under
+regeneration so strokes exceed the VAE's ~8 px latent floor), but ctrlregen runs the regeneration
+at LOW res, the opposite. CtrlRegen's paper gives no resolution/tiling spec to contradict this.
+
+**Sources.** internal (`src/remove_ai_watermarks/noai/ctrlregen/engine.py`); resolution-omission
+confirmed against https://arxiv.org/html/2410.05470v1
+
+### Finding 5 — confidence: high
+
+**Claim.** SDXL-native ControlNets exist, so the removal-pipeline upgrade need NOT be the SD1.5
+re-architecture our current ctrlregen is. xinsir `controlnet-tile-sdxl-1.0` and
+`controlnet-union-sdxl-1.0` (ControlNet++) run on SDXL base 1.0. The tile model has a `tile_var`
+image-variation mode purpose-built to regenerate detail while preserving structure, at
+`controlnet_conditioning_scale = 1.0`, optimal 1024 px. This is a drop-in control add to our
+existing SDXL img2img.
+
+**Evidence.** xinsir tile-sdxl model card: use cases = deblur/detail-repaint, **image variation
+(preserving structure)**, super-resolution; `controlnet_conditioning_scale = 1.0`, ~30 steps,
+optimal 1024x1024, works with `madebyollin/sdxl-vae-fp16-fix` (the same VAE our fp16 path
+already swaps in). ControlNet-Union-SDXL / ControlNet++ merges 10+ control types (canny, HED,
+tile, depth, lineart) into one SDXL model.
+
+**Sources.** https://huggingface.co/xinsir/controlnet-tile-sdxl-1.0 ·
+https://huggingface.co/xinsir/controlnet-union-sdxl-1.0 · https://github.com/xinsir6/ControlNetPlus
+
+### Finding 6 — confidence: high
+
+**Claim.** The community tile-ControlNet upscale workflow runs at **LOW denoise (0.3-0.4)** —
+the wrong regime for watermark removal. It preserves detail precisely by regenerating little, so
+a naive tile-upscale preserves text AND preserves the watermark. The open empirical question is
+whether at `conditioning_scale ~1.0` you can push denoise high enough to scrub SynthID while the
+tile conditioning still holds text — the exact cell to test.
+
+**Evidence.** Stable-Diffusion-Art ControlNet-tile upscale: denoise "typically 0.3, max ~0.4 to
+avoid artifacts"; some users push 0.6 with ControlNet strength 0.5. Our own data: SynthID
+survives below the removal-strength threshold (current Gemini needs notably higher denoise than
+the tile-upscale regime). So the detail-preserving regime and the watermark-scrubbing regime are
+on opposite ends of the denoise axis; ControlNet conditioning is the bet that they can meet.
+
+**Sources.** https://stable-diffusion-art.com/controlnet-upscale/ ·
+internal (`docs/synthid.md` strength data)
+
+### Finding 7 — confidence: high
+
+**Claim.** Forensic-stealth caveat: diffusion-based regeneration is among the MOST detectable
+removal families. Even a ControlNet-regeneration that fools the SynthID oracle leaves forensic
+traces flagging the output as "removal-processed" at >98% TPR@1%FPR. This bounds the claim (do
+not over-promise "indistinguishable from an original") but does not block the use case — the
+SynthID oracle still reads negative.
+
+**Evidence.** "Removing the Watermark Is Not Enough: Forensic Stealth in Generative-AI Watermark
+Removal" (arXiv:2605.09203, Goonatilake & Ateniese, GMU): across six removal attacks including
+diffusion-based regeneration, independent forensic detectors separate removal-processed from
+clean content at >98% TPR under a 1% FPR budget.
+
+**Sources.** https://arxiv.org/html/2605.09203v1
+
+### Finding 8 — confidence: low (watch, do not build on yet)
+
+**Claim.** Partial/semantic-guided regeneration is an active sub-direction that explicitly targets
+the removal-vs-fidelity tradeoff, but the specific fidelity-on-text claims were not verifiable
+from the source in this pass.
+
+**Evidence.** "Removing Watermarks with Partial Regeneration using Semantic Information"
+(arXiv:2505.08234) proposes focusing regeneration on watermarked regions with semantic (VLM)
+conditioning to preserve untouched areas; the PDF body did not render cleanly enough to confirm
+its quantitative text/detail results. Treat as a pointer, not evidence.
+
+**Sources.** https://arxiv.org/pdf/2505.08234
+
+## Recommendation / decision
+
+**ControlNet-as-removal-pipeline is worth prototyping — but not by fixing the SD1.5 ctrlregen.**
+Port the structure-control idea onto an SDXL-native ControlNet as a control add to the existing
+SDXL base 1.0 img2img, run it at full resolution (1024+, NOT 512 tiles), and treat the
+text-vs-scrub tension as an empirical question to measure, not assume.
+
+**Prototype (runs locally on 32 GB MPS — no dedicated GPU required):**
+
+Compute is NOT the bottleneck. On a 32 GB Apple-silicon machine (M5 here) native SDXL already
+runs entirely on MPS with no CPU fallback (~155 s at 1122x1402, verified — see `synthid.md` /
+CLAUDE.md). The prototype runs at **1024** (fewer pixels than that) with SDXL base + an SDXL
+ControlNet + activations in **fp32** (MPS fp16 decodes to all-black NaN — issue #29 — confirmed
+on run 1 below; fp32 is the required default on mps/cpu) — fits the 32 GB budget with vae-tiling +
+attention-slicing; ~1-2 min/image, so a coarse sweep is a sub-hour background run. A dedicated GPU
+is needed ONLY for the separate
+native-large-Gemini (2816 px) case, which OOMs even without a ControlNet (that stays a raiw.cc
+GPU task). The genuine external dependency is NOT compute but the **manual SynthID oracle**:
+there is no local SynthID detector, so removal is verified by hand in the Gemini app
+("Verify with SynthID") per image, regardless of where the diffusion runs.
+
+Runner: **`scripts/controlnet_sweep.py`** (built 2026-06-02) implements exactly this sweep —
+SDXL base 1.0 + an SDXL-native ControlNet img2img, one output per (control x strength x scale)
+cell, plus a `sweep_index.csv` with empty `synthid_oracle` / `text_legible` columns to fill by
+hand. It uses the dedicated single-type xinsir models (`controlnet-canny-sdxl-1.0`,
+`controlnet-tile-sdxl-1.0`) rather than the Union model to keep the diffusers API path robust.
+
+    uv run python scripts/controlnet_sweep.py watermarked.png -o sweep_out
+
+1. SDXL base 1.0 img2img + `xinsir/controlnet-canny-sdxl-1.0` / `controlnet-tile-sdxl-1.0`
+   (sweep both `tile` and `canny` control), full image at 1024, `sdxl-vae-fp16-fix`.
+2. Sweep the cube on fresh Gemini + gpt-image inputs that contain small/CJK text:
+   - denoise strength {0.15, 0.3, 0.5, 0.7, 1.0}
+   - `controlnet_conditioning_scale` {0.5, 0.8, 1.0}
+   - control type {tile, canny}
+3. Per cell, measure BOTH axes:
+   - **removal**: Gemini app "Verify with SynthID" oracle (the only valid SynthID oracle; for
+     gpt-image also openai.com/verify for provenance) — must read clean.
+   - **text**: OCR round-trip / visual legibility of the small text.
+   - secondary: SSIM/FID vs original for global fidelity.
+4. Find the Pareto cell where the oracle is clean AND text stays legible.
+
+**The honest fork the prototype resolves:**
+- If such a cell exists -> the answer to Jacob is YES, ship an SDXL-native ControlNet removal
+  profile (replacing the SD1.5 ctrlregen) tuned to that cell.
+- If no cell clears both (the tension is fundamental: scrub-strength always deforms text, or
+  text-preserving conditioning always spares the watermark) -> the canny/tile-ControlNet middle
+  path is dead for text, and the standing answer reverts to `text-protection-research.md`: a full
+  **glyph-conditioned re-render** (EasyText / TextSR on a FLUX-DiT base) is required, which is a
+  base-model migration, not a control add.
+
+**Do not:** keep tuning the 512 px SD1.5 ctrlregen for text (wrong resolution, wrong base model);
+run tile-ControlNet at the community 0.3-0.4 upscale denoise and expect watermark removal (that
+regime preserves the watermark); over-claim forensic invisibility (Finding 7).
+
+## Prototype run 1 — 2026-06-02 (text axis measured; watermark axis pending the oracle)
+
+First sweep on a real, SynthID-positive, text-dense input: the corpus tokyo-street-night
+gpt-image (`88e61a38-chatgpt_tokyo.png`, 1023x1537 -> 680x1024, dense small CJK + Latin neon
+signage; SynthID + C2PA confirmed, so its valid oracle is openai.com/verify). Grid: control
+{canny, tile} x strength {0.3, 0.5, 0.7, 1.0} x `conditioning_scale` 1.0, fp32 on MPS. Outputs +
+`sweep_index.csv` (text verdicts filled by visual inspection; `synthid_oracle` left for the
+manual run) are under `/tmp/cnsweep/` (not committed — derived regenerations of corpus content).
+
+**Measured — PSNR vs input (proxy for how much was regenerated):**
+- canny: 0.3 -> 16.91, 0.5 -> 15.91, 0.7 -> 14.82, 1.0 -> 13.22 (monotonic drop = progressively
+  more regeneration as strength rises; canny only pins edges, so flat regions change).
+- tile: 0.3 -> 17.89, 0.5 -> 17.84, 0.7 -> 17.83, 1.0 -> 17.74 (**flat and high — near-identity
+  even at strength 1.0**; tile@scale1.0 pins the whole image to the input and barely regenerates).
+
+**Measured — text legibility (visual, focused on SMALL text; large high-contrast glyphs survive
+everything because canny/tile hold their edges):**
+- canny: legible at 0.3, softening at 0.5 (partial), garbling at 0.7, hallucinated pseudo-glyphs
+  at 1.0 ("NEC" -> "NWENES"). Same plain-img2img small-text deformation, only big text protected.
+- tile: near-identity through 0.7, only tiny alterations at 1.0 — small text preserved throughout.
+
+**Reading (the make-or-break tension, now visible in the data):**
+- **tile@scale1.0 does not actually regenerate** (flat PSNR), so it preserves all text but almost
+  certainly leaves the watermark intact — it is a near-identity pass, exactly the community
+  "tile-upscale preserves detail by not regenerating" regime (Finding 6), confirmed.
+- **canny@scale1.0 regenerates progressively** (PSNR drops) and so could scrub — but small text
+  breaks at exactly the strength where scrubbing would start to bite. canny saves big edges, not
+  sub-stroke small text.
+- Net on the text axis: neither cell at scale 1.0 cleanly gives "high regeneration + legible small
+  text." This is the literature prior (Findings 3, 6) reproduced empirically. Lowering
+  `conditioning_scale` to force small-text regeneration is the same tradeoff knob, not an escape.
+
+**Still pending (the decisive half, cannot be done locally):** run the 8 cells through the SynthID
+oracle and fill `synthid_oracle`. The most informative cells: canny 1.0 (text dead — does it at
+least scrub? if not, the canny path is dead outright), canny 0.5 (text partial — does it scrub?),
+tile 1.0 (text perfect — predicted to still read present). If no cell is `oracle=clean` AND
+`text=yes`, the fork resolves to the glyph-re-render path (`text-protection-research.md`).
+
+**Incidental bug caught:** the first run used fp16 on MPS (the script's original default) and
+produced **all-black** outputs across every cell (2 KB PNGs, PSNR 9.22 flat) — the issue #29
+fp16-VAE-NaN failure, and the fp16-fix VAE did not save it on MPS. Fixed `scripts/controlnet_sweep.py`
+to default fp32 on mps/cpu (fp16 only on cuda/xpu), matching the production pipeline.
+
+## Tuning ControlNet for text preservation across image types (research 2026-06-03)
+
+Goal: how to configure the canny-ControlNet path to best preserve text (and faces) on diverse
+images. Primary sources: diffusers ControlNet doc, the ControlNet paper (arXiv:2302.05543),
+xinsir model cards, practitioner guides. The **critical reframe**: almost all community ControlNet
+advice optimizes a txt2img *generation* tradeoff (control vs creative freedom). OUR context is
+img2img *watermark removal*, where the objective is the opposite -- maximum faithful preservation
+while regenerating just enough to scrub. So several common recommendations INVERT here.
+
+**Removal is `strength`; everything below is preservation and does not change removal efficacy**
+(only the watermark-shielding risk -- see the caveat). Set `strength` by the oracle/vendor need;
+tune these to keep text/faces intact at that strength.
+
+Knobs, ranked by impact for text:
+
+1. **Canny edge density (the per-image lever, currently hardcoded `_CANNY_LOW=100`/`_CANNY_HIGH=200`).**
+   Lower thresholds capture more/finer edges; higher thresholds keep only major outlines (diffusers
+   doc + practitioner guides; ControlNet paper uses 100/200 as the default). Small-text strokes and
+   fine facial features fall below the default 100/200 and are missed. **For dense small text
+   (infographics, signage) lower the thresholds (~50/120, even 30/100 for facial likeness per
+   practitioner tests); for high-contrast large text 100/200 already suffices.** Denser canny is
+   still a BINARY thresholded edge map, so it does not carry the low-amplitude SynthID pixel pattern
+   -- it passes more shape, not the watermark (still oracle-verify). This is the single highest-value
+   unexplored lever and should become a CLI knob.
+
+2. **`controlnet_conditioning_scale` -> keep at 1.0 (max structure hold).** Community defaults to 0.5
+   for creative balance; we want maximum preservation, so 1.0 (xinsir canny/tile cards also recommend
+   1.0). We measured text on a clean high-contrast image surviving across strength 0.1-0.5 at scale
+   1.0 (PSNR ~26 flat), so scale 1.0 is the right default; only lower it if a specific image needs
+   more regeneration to scrub (raises shielding risk the other way).
+
+3. **`control_guidance_start=0.0`, `control_guidance_end=1.0` (full window) -- KEEP, do not shorten.**
+   The common "end=0.5: establish structure early then let the model render detail freely" is a
+   creative-generation recipe; for text it is HARMFUL -- the late free steps re-render and deform the
+   glyphs. We want the edge control active through ALL denoise steps so text stays pinned. (Our
+   pipeline already uses the 0->1 default; the point is to NOT adopt the shorten-the-window advice.)
+
+4. **Control type, per image type:**
+   - **Text / graphics / high-contrast -> canny** (the literature's reliable choice for defined edges
+     and text; what we ship).
+   - **Faces / smooth tonal content -> soft-edge / HED is a candidate worth testing.** Canny's hard
+     binary threshold fractures smooth skin gradients; HED/soft-edge gives gradual edges that may hold
+     faces better. UNVERIFIED for removal (softer edges may carry slightly more original signal ->
+     oracle-check). A face-heavy image is the test (gemini group photos).
+   - **tile -> NOT for removal.** It is near-identity (detail-enhancement at low denoise); it shields
+     the watermark (measured flat PSNR ~17.8 across strength on the tokyo sweep). Do not use it as the
+     removal control.
+
+5. **Resolution** -- higher long-side = strokes span more VAE latent cells = less softening, while
+   still fully regenerating. Already a knob (`--max-resolution`); for tiny text prefer native/large.
+
+**Multi-ControlNet (canny + soft-edge), list scales e.g. `[1.0, 0.8]`** (diffusers MultiControlNet):
+could hold text edges AND face geometry at once, but doubles ControlNet memory/latency and raises the
+shielding risk; defer to a v2 after the single-canny path is dialed in.
+
+**Image-type playbook (proposed, to validate with the oracle):**
+- Clean high-contrast text (openai_1-style): canny 100/200, scale 1.0, full window -- already optimal.
+- Dense small text / infographics (big_pic3, neon signage): canny **lower thresholds (~50/120)**,
+  scale 1.0, full window, larger resolution.
+- Faces / portraits: try **soft-edge/HED** control, scale 1.0; or multi-ControlNet canny+softedge.
+
+**Hard caveat:** every change that increases preservation (higher scale, denser canny, fuller window,
+softer edges) marginally REDUCES effective regeneration and so raises the chance the watermark
+survives -- exactly the shielding failure mode. There is no local SynthID detector, so each tuning
+change must be re-confirmed on the oracle. These are img2img-context recommendations derived from
+generation-context sources plus our own measurements; treat the playbook as hypotheses to verify, not
+settled defaults.
+
+**Sources.** https://huggingface.co/docs/diffusers/en/using-diffusers/controlnet ·
+https://arxiv.org/pdf/2302.05543 · https://huggingface.co/xinsir/controlnet-canny-sdxl-1.0 ·
+https://huggingface.co/xinsir/controlnet-tile-sdxl-1.0 · https://blog.cephalon.ai/canny-and-softedge/
+
+## FaceID research: identity-preserving face conditioning (research 2026-06-03)
+
+Motivation: canny alone preserves face STRUCTURE/position better than plain SDXL but does NOT hold
+IDENTITY -- verified on a real Gemini group photo (gemini_3, s015): faces drift in expression and
+likeness (the smile/mouth and eyes change), they are "a similar person," not the same one. Canny
+carries edges, not identity, so the regenerated face is identity-drifted. To hold identity WITHOUT
+copying original pixels (the hard constraint -- copied pixels carry SynthID), the conditioning must
+be an identity EMBEDDING, not pixels. Primary sources: diffusers IP-Adapter doc, InstantID
+(arXiv:2401.07519), IP-Adapter (arXiv:2308.06721), practitioner comparisons.
+
+### Findings
+
+**1. IP-Adapter FaceID conditions on an ArcFace identity VECTOR, not pixels (confidence: high).**
+FaceID extracts `insightface` ArcFace `normed_embedding` (a ~512-d identity vector) via
+`FaceAnalysis`, and passes it as `ip_adapter_image_embeds` -- NOT a CLIP image embedding, NOT the
+original pixels. So it is constraint-compatible: the watermark (a pixel-amplitude pattern) is not in
+the identity vector, and the img2img still regenerates the pixels (removal via `strength` unchanged).
+It loads on any SDXL via `load_ip_adapter` (~100 MB), is fast/low-VRAM, but identity fidelity on SDXL
+is ~5-10% lower than the SD1.5 line / dedicated methods.
+
+**2. Multiple distinct faces ARE handled, via regional attention masks (confidence: high -- THE key
+unlock).** This is the make-or-break for group photos (our hardest case). diffusers supports a LIST
+of IP-Adapter face images each with its own binary region mask: `IPAdapterMaskProcessor` builds the
+masks, `set_ip_adapter_scale([[s1, s2, ...]])`, and `cross_attention_kwargs={"ip_adapter_masks":
+masks}`. So you detect each face, extract its own ArcFace embedding, assign it a region mask, and one
+pass preserves N different identities simultaneously. (InstantID, by contrast, is single-subject --
+it averages embeddings for multiple refs, which is wrong for distinct people -- so for group photos
+**IP-Adapter FaceID + masks beats InstantID**.)
+
+**3. IP-Adapter + ControlNet + img2img compose (confidence: high).** The doc shows IP-Adapter +
+ControlNet (depth) in one pipeline and IP-Adapter + img2img (`strength`). Our target stack is the
+union: `StableDiffusionXLControlNetImg2ImgPipeline` (canny = structure) + `load_ip_adapter` (FaceID =
+identity) + `strength` (removal). `set_ip_adapter_scale` (1.0 = image-only, 0.5 = balanced) is the
+identity-hold knob. API friction to verify in implementation: that `ip_adapter_masks` via
+`cross_attention_kwargs` works on the *ControlNet img2img* pipeline (the masking is an attention-
+processor feature, so it should be pipeline-agnostic, but confirm).
+
+**4. InstantID / PuLID positioning (confidence: medium).** InstantID does not train the UNet so it
+composes with canny/depth ControlNets, and gives better single-face fidelity than FaceID -- but it is
+single-subject (needs its own landmark ControlNet + dedicated weights). PuLID has the best identity
+fidelity but is heaviest and Flux-leaning. For our multi-face, constraint-bound, SDXL-canny case,
+IP-Adapter FaceID + masks is the right first build; InstantID/PuLID are single-portrait upgrades.
+
+### Architecture (proposed)
+
+```
+detect faces (insightface) -> per face: ArcFace embed + region mask
+one img2img pass:
+  image=init, control_image=canny(init),                      # structure (existing)
+  ip_adapter_image_embeds=[face_embeds],                       # identity per face
+  cross_attention_kwargs={"ip_adapter_masks": face_masks},     # each face -> its region
+  controlnet_conditioning_scale=1.0, set_ip_adapter_scale(~0.6),
+  strength=vendor-adaptive                                     # removal (unchanged)
+```
+Pixels are regenerated (SynthID removed by `strength`), structure held by canny, each face's identity
+held by its masked ArcFace vector -- no original pixel copied.
+
+### Risks / honest costs
+
+- **Shielding risk (same wall):** FaceID conditioning, like canny, reduces effective regeneration ->
+  higher `set_ip_adapter_scale` raises the chance SynthID survives in the face region (echo of why the
+  old region-hires failed). MUST oracle-verify removal at the chosen FaceID scale; keep `strength` at
+  the vendor threshold.
+- **New heavy dependency:** `insightface` + `onnxruntime` + the `buffalo_l` model (~300 MB, downloaded
+  on first use). Detection + embedding is CPU/ONNX, separate from the diffusion.
+- **Detection floor:** insightface needs faces large enough (det_size ~640); tiny faces in a dense
+  group may not be detected -> not preserved (falls back to canny-only for those).
+- **Identity ceiling:** SDXL FaceID is ~5-10% off true identity -- a meaningful boost over canny-only
+  drift, NOT a perfect face swap. Set expectations; PuLID/InstantID are the higher-fidelity (heavier)
+  paths if needed.
+- **Value scales with strength:** at low strength (OpenAI 0.10) faces barely drift, so FaceID is
+  marginal; at the higher strength a hard vendor (Google 0.30) needs, FaceID earns its keep.
+
+### Build plan (staged)
+
+- v1: optional `--face-id` flag on `--pipeline controlnet`. Detect faces; if any, run the masked
+  FaceID pass (works for 1 or N faces -- masks generalize). If none detected, fall through to plain
+  canny. Oracle-verify SynthID removal is preserved at the default FaceID scale on a face image.
+- v2 (if identity still short): InstantID for single-portrait, or PuLID, as a higher-fidelity opt-in.
+
+**Sources.** https://huggingface.co/docs/diffusers/main/en/using-diffusers/ip_adapter ·
+https://huggingface.co/h94/IP-Adapter-FaceID · https://arxiv.org/pdf/2401.07519 (InstantID) ·
+https://instantid.github.io/ · https://arxiv.org/abs/2308.06721 (IP-Adapter)
+
+### FaceID prototype run 1 -- 2026-06-03 (NEGATIVE on dense small-face groups)
+
+Built and shipped the masked multi-face FaceID layer (`--face-id`, `face_id.py`, `faceid` extra).
+First real run on the gemini_3 group photo (Google, s015, scale 0.6, native 2816 via cap 1536):
+insightface detected **17 faces**, the masked multi-face pass composed and ran end-to-end (non-black
+output), so the API is correct. **At s015 the result is a clear FAILURE: every face corrupted --
+melted/discolored/psychedelic, materially WORSE than canny-only.**
+
+**ROOT CAUSE FOUND (confirmed by ablation, not speculation) -- it is STRENGTH, not scale/masks/faces.**
+Investigated the real data: masks are fine (max overlap depth 2, 33% coverage, only 0.2% of pixels
+double-covered -- NOT an overlap problem), embeddings are fine (`normed_embedding` norm 1.000), the
+FaceID LoRA is not required for SDXL (h94 model card), and faces span 34-181 px (7 medium + 10 tiny).
+None of those is the cause. The decisive test: the SAME image + FaceID at **strength 0.5** produces
+**clean, coherent faces across the whole group** (no psychedelic artifacts). So FaceID needs
+substantial regeneration: the h94 usage is full generation (txt2img, 30 steps); at our removal
+strength (0.10-0.15 = ~7 effective steps) the strong identity cross-attention cannot reconcile with
+a latent that is ~85% the untouched original, so it smears identity-colored noise onto the faces.
+
+**This is a FUNDAMENTAL tension, not a tuning bug:** watermark removal wants LOW strength (minimal
+degradation, just enough to scrub), FaceID wants HIGH strength (regenerate the face to impose
+identity). They are opposed. At strength 0.5 FaceID works AND removes the watermark, but the whole
+image regenerates much more (canny still holds text/edge structure, but texture/detail drifts well
+beyond the 0.15 "minimal degradation" target). So `--face-id` is a HIGH-STRENGTH option: it trades
+whole-image fidelity for face identity, and is a footgun at the low default strength (guaranteed
+garbage). Required follow-up code guard: when `--face-id` is set, floor `strength` at ~0.5 (or refuse
++ warn) -- never run FaceID at the vendor-adaptive removal strength. Open question: whether
+high-strength FaceID's whole-image drift is acceptable for face-centric images, or whether identity
+preservation at LOW strength needs a different mechanism entirely (FaceID structurally cannot do it). (Infra lesson: the `faceid` extra must
+stay numpy<2.0 -- pin `onnx<1.18` + `scipy<1.18`; pinning numpy UP, as the first build did, leaves a
+numpy-1.26 env with a numpy-2-only scipy that crashes the diffusers import via `np.long`.)
+
+## Face preservation, done properly (research 2026-06-03, after the FaceID failure)
+
+The FaceID run failed and I wrongly concluded "faces can't be preserved." Re-research corrected the
+understanding. The hard constraint is unchanged: to remove the watermark FROM a face the face MUST
+be regenerated (freezing it leaves SynthID), so the goal is identity-preserving REGENERATION of the
+face, at minimal overall image degradation. Three things I got wrong and the corrected picture:
+
+**What I got wrong:** (1) I applied FaceID at GLOBAL high strength -- the literature is clear the
+architecture must be REGION-ADAPTIVE (face region handled separately, background stays low-strength);
+(2) I used IP-Adapter FaceID, the WEAKEST identity tool -- InstantID uses an ArcFace encoder and hits
+82-86% face-recognition similarity vs FaceID's weak CLIP-ish signal; (3) I missed the entire
+face-restoration class (CodeFormer / GFPGAN), which is purpose-built for "regenerate a face, keep
+identity."
+
+**The most promising mechanism -- CodeFormer face-restoration post-pass (confidence: high on the
+mechanism, unverified on our watermark).** CodeFormer is a VQ-VAE: a frozen discrete CODEBOOK of HQ
+facial priors + a Transformer that predicts code *tokens* from the input, and a frozen decoder that
+regenerates the face FROM THE CODEBOOK ENTRIES -- "does not depend on feature fusion with low-quality
+cues." So the output face pixels come from a finite learned codebook, NOT from the input pixels:
+**the SynthID pixel-amplitude pattern physically cannot survive a codebook re-synthesis** -- a
+stronger scrub than low-strength img2img (which keeps ~85% of the latent). Fidelity knob `w` in
+[0,1]: higher w preserves identity but fuses MORE low-quality (input) cues (more watermark risk),
+lower w leans on the codebook (cleaner scrub, identity drift) -- the same scrub-vs-fidelity tension,
+settled per-image by the oracle; there is likely a `w` that holds identity AND clears the oracle.
+
+**Constraint-compatible architecture:** run the normal canny low-strength controlnet removal globally
+(minimal degradation everywhere), then detect+align each face, run CodeFormer on the **ORIGINAL** face
+crop (to capture true identity AND re-synthesize from the codebook = scrub), and composite the
+CodeFormer output (codebook-generated, not original pixels -> no copy, no watermark) into the cleaned
+image. Decouples whole-image minimal-degradation from face identity -- no high GLOBAL strength needed.
+
+**Honest costs/caveats:** (a) **License -- CodeFormer is NTU S-Lab 1.0 (non-commercial/research)**, so
+it cannot be bundled in this MIT tool for general use; the license-clean alternative is **GFPGAN
+(Apache-2.0)**, slightly lower quality. (b) Deps (basicsr/facexlib) are heavy and numpy-version-finicky
+(same class of conflict as insightface). (c) CodeFormer is a *restoration* model -- it can subtly
+alter expression/asymmetry; identity is held but not pixel-identical. (d) **The watermark-scrub is
+mechanistically strong but UNVERIFIED -- must oracle-check.** InstantID + region-adaptive strength is
+the alternative if the restoration route disappoints, but it is more complex (differential strength).
+Prototype plan: validate CodeFormer on a real face in a THROWAWAY env (identity held? oracle clean?)
+before any project-env integration or the license/GFPGAN decision.
+
+### CodeFormer prototype -- VALIDATED end-to-end 2026-06-03 (oracle-confirmed)
+
+Prototyped the CodeFormer face-restoration post-pass (codeformer-pip in a throwaway venv, forced CPU
+-- the pip wrapper has an MPS device-mismatch bug) on the gemini_3 group photo (18 faces). Pipeline:
+`all --pipeline controlnet --strength 0.15` (sparkle + SynthID removed from the whole image, minimal
+degradation) -> CodeFormer on the ORIGINAL faces -> feather-composite the CodeFormer faces into the
+all-cleaned image. Oracle results (Gemini app "Verify with SynthID"), isolating each part:
+- pure controlnet-0.15 background (no faces): **clean** -> the background scrub works at 0.15 (no
+  ControlNet-shielding problem for Google on this image).
+- composite with CodeFormer faces at **w0.7**: **SynthID DETECTED** -> high fidelity fuses too much of
+  the original face signal (the watermark) through.
+- composite at **w0.5**: **clean**. composite at **w0.3**: **clean**.
+So the scrub-vs-fidelity threshold is between 0.5 and 0.7; **w=0.5 is the sweet spot** (highest
+fidelity / best identity that still clears the oracle). Identity at w0.3-0.7 all looks like the same
+person (the face is large enough), so the lower w costs little.
+
+**This VALIDATES the corrected face-preservation approach** (and refutes my earlier "faces can't be
+preserved" / FaceID conclusion): controlnet low-strength background scrub + CodeFormer-codebook face
+re-synthesis at w~0.5 + feather composite = oracle-clean SynthID removal everywhere (background AND
+faces), identity preserved, minimal overall degradation, zero original-pixel copying (CodeFormer faces
+are codebook-generated). CodeFormer's discrete-codebook re-synthesis DOES scrub the pixel watermark,
+but only when w is low enough that the decoder leans on the codebook rather than fusing the input
+(watermark-carrying) features -- exactly the predicted fidelity-vs-scrub tension, with an empirical
+clean threshold at w<=0.5.
+
+**Production TODO (not built -- still a throwaway prototype):** (1) license -- CodeFormer is NTU S-Lab
+(non-commercial); decide CodeFormer-as-user-installed-extra vs GFPGAN (Apache-2.0, re-verify it scrubs
+at its fidelity setting); (2) wire a `--restore-faces` post-pass (detect -> restore w~0.5 -> feather
+composite) onto the controlnet pipeline; (3) handle the MPS device bug (force CPU for the face model
+or fix); (4) re-verify the w threshold on more images / vendors (w=0.5 confirmed on one Gemini group
+photo only).
+
+**Sources.** https://arxiv.org/abs/2206.11253 (CodeFormer) · https://github.com/sczhou/CodeFormer ·
+https://arxiv.org/pdf/2401.07519 (InstantID) ·
+https://openaccess.thecvf.com/content/WACV2024/papers/Suin_Diffuse_and_Restore... (region-adaptive) ·
+https://arxiv.org/pdf/2504.12809 (saliency-aware watermark removal)
+
+## Provenance
+
+Hand-run primary-source pass, 2026-06-02. Sources fetched and quoted above; the central
+make-or-break claim (structure-conditioned high-strength regeneration scrubs the watermark while
+keeping text) is **unverified and explicitly flagged as the thing the local prototype must
+measure** (against the manual Gemini SynthID oracle) — the literature supports removal (Findings 1, 2) and supports structure-preserving
+regeneration (Finding 5) but never jointly validated text (Finding 3). No code change implied
+until the prototype validates a Pareto cell on the SynthID oracle.

docs/synthid-robust-identity-research-2026-06-08.md

@@ -0,0 +1,185 @@
+# Deep research: SynthID-safe face-identity recovery for SDXL (2026-06-08)
+
+**Stats:** {"angles": 6, "sourcesFetched": 28, "claimsExtracted": 104, "claimsVerified": 25, "confirmed": 19, "killed": 6, "afterSynthesis": 6, "urlDupes": 1, "budgetDropped": 7, "agentCalls": 111}
+
+## Summary
+
+For SDXL-based SynthID-removal pipelines, the entire ArcFace-class identity-adapter ecosystem (PhotoMaker-V2, InstantID, PuLID, IP-Adapter FaceID, Arc2Face) is blocked from commercial use by a single chokepoint: InsightFace's pretrained model packs (buffalo_l, antelopev2, buffalo_s, buffalo_m) are explicitly non-commercial research-only, regardless of the adapter weights' Apache-2.0/MIT license. The InstantX maintainers themselves acknowledged this on HuggingFace ("cannot be Apache 2.0 if it is using Insight Face") and stated intent to retrain on commercially-licensed embedders — work that as of the verified sources has not shipped. The only verified commercial-safe SDXL adapter surfaced is MS-Diffusion (ICLR 2025), which uses CLIP-ViT-bigG-14 instead of ArcFace and runs on SDXL-base-1.0, but it is an IP-Adapter-class subject-similarity method, not a face-identity method — CLIP image embeddings are empirically weaker for face identity than ArcFace (~81% vs ~88% face-ID accuracy), so it solves the license problem but likely not the identity-fidelity problem. Arc2Face is SD1.5-only and so not a drop-in regardless of license; StyleGAN2-based methods (e4e) terminate in a GAN generator with no SDXL wiring. Net: no fully commercial-safe SynthID-robust SDXL identity-preservation stack with ArcFace-grade fidelity exists today — the space is genuinely blocked by InsightFace's grip on commercial ArcFace embeddings, and AdaFace as a permissive ArcFace alternative was REFUTED in verification.
+
+## Findings
+
+### 1. The InsightFace pretrained model packs (buffalo_l, antelopev2, buffalo_s, buffalo_m) are non-commercial research-only and this restriction propagates at runtime to any adapter that calls FaceAnalysis(), regardless of the adapter's own license tag.
+
+**Confidence:** high  
+**Vote:** 3-0 unanimous across 4 supporting claims
+
+
+InsightFace upstream: code is MIT but 'The training data containing the annotation (and the models trained with these data) are available for non-commercial research purposes only.' Licensing page enumerates buffalo_l, antelopev2, buffalo_s, buffalo_m as needing separate commercial licensing. InstantX maintainer on HF: 'cannot be Apache 2.0 if it is using Insight Face... we plan to train on other face encoders that support commercial license.' Mechanical propagation: the runtime FaceAnalysis() call pulls these packs.
+
+- https://github.com/deepinsight/insightface
+- https://www.insightface.ai/solutions/face-recognition-licensing
+- https://huggingface.co/InstantX/InstantID/discussions/2
+
+### 2. InstantID is Apache-2.0 on the adapter weights and architecturally a clean plugin to SDXL-base-1.0 (no UNet training, semantic IdentityNet conditioning + landmark weak-spatial, no pixel copying) — but at runtime it instantiates FaceAnalysis(name='antelopev2'), inheriting the InsightFace non-commercial restriction.
+
+**Confidence:** high  
+**Vote:** 3-0 across 5 claims
+
+
+HF model card: 'License: apache-2.0' AND 'For face encoder, you need to manutally download via this URL to models/antelopev2' with 'from insightface.app import FaceAnalysis' in usage. Diffusers community pipeline shows literal `app = FaceAnalysis(name='antelopev2', ...)` then `face_emb = face_info['embedding']`. Paper: 'IdentityNet by imposing strong semantic and weak spatial conditions, integrating facial and landmark images with textual prompts' + 'seamlessly integrates with SD1.5 and SDXL'. So mechanism is semantic (good for SynthID-no-pixel-leak) but license is blocked.
+
+- https://huggingface.co/InstantX/InstantID
+- https://github.com/huggingface/diffusers/blob/main/examples/community/pipeline_stable_diffusion_xl_instantid.py
+- https://arxiv.org/pdf/2401.07519
+- https://instantid.github.io/
+
+### 3. Arc2Face is SD1.5-only (not SDXL) AND requires InsightFace antelopev2 with arcface.onnx replacing glintr100.onnx — so it is doubly blocked: not a drop-in for the SDXL pipeline AND non-commercial via the model pack.
+
+**Confidence:** high  
+**Vote:** 3-0 across 3 claims
+
+
+Arc2Face README verbatim: 'Arc2Face is built upon SD1.5' with stable-diffusion-v1-5 checkpoint as base. Same README: 'manually download the antelopev2 package and place the checkpoints under models/antelopev2', 'Download arcface.onnx from HuggingFace', 'delete glintr100.onnx (the default backbone from insightface)'. Code is MIT but the runtime antelopev2 dependency carries the non-commercial restriction. No SDXL adaptation exists in the official repo.
+
+- https://github.com/foivospar/Arc2Face
+
+### 4. MS-Diffusion (ICLR 2025) is the one verified candidate that combines SDXL-base-1.0 as its foundation with a non-ArcFace image encoder (CLIP-ViT-bigG-14), so it avoids the InsightFace non-commercial blocker — but it is an IP-Adapter-class multi-subject personalization method, NOT a face-identity-recognition method, so license safety does not equal face-identity fidelity.
+
+**Confidence:** medium  
+**Vote:** 3-0 on the narrow factual claims (SDXL base + CLIP-G encoder)
+
+
+GitHub README explicitly instructs 'Download the pretrained base models from SDXL-base-1.0 and CLIP-G' (CLIP-ViT-bigG-14-laion2B-39B-b160k). Neither README nor arXiv 2406.07209 mention ArcFace/InsightFace/antelopev2/buffalo_l. Architecturally descended from IP-Adapter (CLIP-image-embedding family), not from FaceID/InstantID/PhotoMaker-V2. Verifier caveat (high confidence on the license-narrow claim, medium on suitability): CLIP-image face-ID accuracy ~80.95% vs specialized face recognition ~87.61% — license-safe but probably not identity-grade for portraits. Confidence is medium because the suitability claim for raiw.cc face-identity use case has not been validated empirically.
+
+- https://proceedings.iclr.cc/paper_files/paper/2025/file/ed4df1609bf7d8602435341c9ce2ab5f-Paper-Conference.pdf
+- https://github.com/MS-Diffusion/MS-Diffusion
+
+### 5. ID-Aligner and the StyleGAN2/e4e-based identity method (arXiv 2510.25084) do not solve the problem: the former does not disclose embedder/license in the primary source; the latter terminates identity in a StyleGAN2 generator with no SDXL adapter, so it cannot be wired into the SDXL+canny ControlNet pipeline.
+
+**Confidence:** high  
+**Vote:** 3-0 across 3 claims
+
+
+ID-Aligner paper: no license terms, no weight-release status, no specific face embedder named in the primary source — commercial-safety unresolved. arXiv 2510.25084: 'facial identity features... mapped into the W+ latent space of StyleGAN2 using the e4e encoder' — identity pixels come from StyleGAN2's generator, not from any SDXL-compatible adapter, so architecturally incompatible with our SDXL+canny ControlNet pipeline. Abstract also does not name the face embedder or disclose weights license.
+
+- https://arxiv.org/pdf/2404.15449
+- https://arxiv.org/pdf/2510.25084
+
+### 6. The honest verdict: no fully commercial-safe SynthID-robust ArcFace-grade face-identity stack for SDXL exists today; the space is blocked by InsightFace's grip on ArcFace-class pretrained packs, and the verified permissive alternative (AdaFace as a drop-in replacement) was REFUTED in this verification round.
+
+**Confidence:** high  
+**Vote:** 3-0 on the chokepoint claim, 0-3 against the AdaFace escape hatch
+
+
+Every ArcFace-grade SDXL adapter audited (PhotoMaker-V2, InstantID, PuLID, IP-Adapter FaceID, Arc2Face) instantiates an InsightFace FaceAnalysis pack at runtime. The maintainer-acknowledged commercial-retrain path (InstantX) has not shipped. AdaFace as a permissive ArcFace alternative was refuted 0-3 by the adversarial verifier (MIT-licensed claim and drop-in-replacement claim both failed). Outcome: commercial-safe option for SDXL today is CLIP-image-embedding-based (MS-Diffusion class), which is weaker for face identity than ArcFace. For non-commercial / research-only deployments, InstantID on SDXL is the strongest semantic-only (no-pixel-leak) candidate.
+
+- https://github.com/deepinsight/insightface
+- https://huggingface.co/InstantX/InstantID/discussions/2
+- https://github.com/mk-minchul/AdaFace
+
+## Caveats
+
+Six claims were refuted in adversarial verification, two of them load-bearing: AdaFace as a permissive ArcFace drop-in (both the MIT license and the drop-in characterization failed 0-3) — so the most attractive escape hatch from the InsightFace chokepoint did not survive verification. PuLID's superiority claim and ID-Aligner's embedder claim also failed, leaving those methods uncharacterized at the mechanism level. None of the verified claims directly answered the diffusers-0.38 compat question — InstantID's compat with our shipped diffusers version is unverified by primary source. MS-Diffusion's identity-fidelity for portraits is not empirically validated for the SynthID-removal use case; it is verified as a CLIP-G/SDXL adapter, not as a face-identity method. No 2025-2026 candidate other than MS-Diffusion was both surfaced AND verified as license-safe and SDXL-compatible — the verification round did not produce a confirmed CCSR-V2/ConsistencyID/OmniGen-V2/ConsistentID/MagicID candidate. The multi-face scenario (group photos) was not addressed by any verified claim — MS-Diffusion is the only multi-subject candidate but its face-identity strength is unmeasured. Time-sensitivity: InstantX's stated intent to retrain on commercial embedders ("We agree, we plan to train on other face encoders that support commercial license") is dated and unfulfilled per the verified sources; this could change.
+
+## Open questions
+
+- Does MS-Diffusion (or any CLIP-image-embedding SDXL adapter) achieve usable face-identity fidelity on the raiw.cc input distribution (portraits + group photos), or is the ArcFace gap (~7 pp face-ID accuracy) visually disqualifying — and can a face-specific CLIP fine-tune close it?
+- Has InstantX (or any community fork) actually shipped an InstantID variant retrained on a commercially-licensed face embedder since the maintainer's 2024 commitment, and if so what is its identity-fidelity vs the antelopev2 original?
+- What is the exact diffusers-0.38 compat status of InstantID, MS-Diffusion, and PuLID-FLUX inference scripts — does any need a fork the way PhotoMaker-V1 did, and if so what specifically breaks?
+- Is there a single-pipeline multi-subject identity-preservation method (mask-guided regional ID-adapters, multi-subject InstantID, MS-Diffusion multi-subject mode) that handles group photos without the per-face crop+composite patchwork that PhotoMaker-V2 produced?
+
+## Refuted claims
+
+- **AdaFace code is released under the MIT license, making it permissively licensed for commercial use (in contrast to InsightFace's research-only model packs).** — vote 0-3 — source: https://github.com/mk-minchul/AdaFace
+- **AdaFace produces 512-dim face recognition embeddings comparable to ArcFace, positioning it as a drop-in alternative for ID-conditioning adapters that currently depend on InsightFace ArcFace.** — vote 0-3 — source: https://github.com/mk-minchul/AdaFace
+- **The paper claims PuLID achieves superior performance in both ID fidelity and editability compared to prior ID-customization methods.** — vote 0-3 — source: https://arxiv.org/pdf/2404.16022
+- **Identity consistency in ID-Aligner is enforced by reward feedback from face detection and recognition models, implying dependency on an external face-recognition embedder (typically ArcFace/InsightFace-class) rather than a CLIP-only path.** — vote 1-2 — source: https://arxiv.org/pdf/2404.15449
+- **The pipeline decouples face detection from inference by accepting a pre-computed embedding via image_embeds, so any ArcFace-class embedder could be swapped in if a commercially-licensed equivalent existed.** — vote 1-2 — source: https://github.com/huggingface/diffusers/blob/main/examples/community/pipeline_stable_diffusion_xl_instantid.py
+- **The model card does not explicitly prohibit commercial use, but the license of the required InsightFace antelopev2 embedder is not specified on this page.** — vote 1-2 — source: https://huggingface.co/InstantX/InstantID
+
+## Sources
+
+- [source](https://huggingface.co/InstantX/InstantID/discussions/2)
+- [source](https://www.insightface.ai/solutions/face-recognition-licensing)
+- [source](https://github.com/mk-minchul/AdaFace)
+- [source](https://github.com/foivospar/Arc2Face)
+- [source](https://apatero.com/blog/instantid-vs-pulid-vs-faceid-ultimate-face-swap-comparison-2025)
+- [source](https://arxiv.org/pdf/2404.16022)
+- [source](https://instantid.github.io/)
+- [source](https://arxiv.org/pdf/2404.15449)
+- [source](https://arxiv.org/pdf/2511.11989)
+- [source](https://arxiv.org/pdf/2510.25084)
+- [source](https://github.com/huggingface/diffusers/blob/main/examples/community/pipeline_stable_diffusion_xl_instantid.py)
+- [source](https://huggingface.co/InstantX/InstantID)
+- [source](https://github.com/huggingface/diffusers/issues/9158)
+- [source](https://github.com/huggingface/diffusers/issues/5904)
+- [source](https://github.com/Mikubill/sd-webui-controlnet/discussions/2589)
+- [source](https://arxiv.org/pdf/2401.07519)
+- [source](https://proceedings.iclr.cc/paper_files/paper/2025/file/ed4df1609bf7d8602435341c9ce2ab5f-Paper-Conference.pdf)
+- [source](https://github.com/huggingface/diffusers/issues/8626)
+- [source](https://arxiv.org/pdf/2404.04243)
+- [source](https://huggingface.co/OmniGen2/OmniGen2)
+- [source](https://github.com/VectorSpaceLab/OmniGen)
+- [source](https://github.com/ToTheBeginning/PuLID)
+- [source](https://arc2face.github.io/)
+- [source](https://github.com/mk-minchul/AdaFace/blob/master/LICENSE)
+- [source](https://github.com/IrvingMeng/MagFace/blob/main/LICENSE)
+- [source](https://github.com/askerlee/AdaFace-dev)
+- [source](https://openreview.net/forum?id=Hc2ZwCYgmB)
+- [source](https://github.com/tencent-ailab/IP-Adapter/wiki/IP%E2%80%90Adapter%E2%80%90Face)
+
+## Empirical follow-up (2026-06-08, end of session)
+
+After the research synthesis above, InstantID was integrated end-to-end and cert-swept
+on Modal A100 in two phases:
+
+1. **Phase 1: InstantID txt2img per-face crop + composite.** Per-face InstantID
+   txt2img with the upstream `pipeline_stable_diffusion_xl_instantid`, ArcFace
+   embedding from the original face, landmark stick figure. Three composite
+   iterations:
+   - v1 (rectangular Gaussian alpha on the 2x square_box around each face):
+     visible patchwork on group photos, generated 1024 backgrounds clashing.
+   - v2 (tight crop on YuNet-detected face in the generated 1024 + elliptical
+     alpha 0.45*bw x 0.55*bh + soft feather): ellipse axis exceeded bbox
+     vertically, clipped forehead/chin on single portrait, group still had
+     visible elliptical seams + cool-vs-warm tone clash with scene.
+   - v3 (tighter ellipse 0.32*bw x 0.42*bh + per-channel mean color match to
+     local cleaned canvas + softer feather): patchwork visually softened; faces
+     still read as studio portraits inserted into the scene, not as people
+     shot in the scene. Single portrait identity drifted (tatsunari -> "round
+     Asian male" vs original's thin face).
+2. **Phase 2: InstantID img2img on cleaned crop.** Switched to the upstream
+   `pipeline_stable_diffusion_xl_instantid_img2img` (downloaded at first use
+   from raw.githubusercontent.com; requires `trust_remote_code=True`). Same
+   ArcFace + landmark conditioning but the SDXL diffusion source is the
+   CLEANED face crop, so the diffusion sees scene lighting / shoulders /
+   shadow direction directly. Multi-face composition jumped substantially:
+   faces sit in the bar scene with matching warm tone, no more elliptical
+   seams. Single-portrait identity at the default (`strength=0.55`,
+   `ip_adapter_scale=0.8`, `controlnet_conditioning_scale=0.8`) was "similar
+   person, not exactly the original"; raising to `strength=0.7`,
+   `ip_adapter_scale=1.0`, `controlnet_scale=1.0` brought identity closer to
+   original but introduced more "SDXL gloss / clean skin" aesthetic.
+
+**Net finding for raiw.cc (load-bearing).** The fundamental issue is structural:
+ArcFace encodes "this person's general look" (ethnicity, gender, basic facial
+geometry) at 512 dimensions; SDXL decodes that embedding into pixels with the
+inherent SDXL aesthetic (smooth skin, symmetric pores, AI-photoreal look).
+Stronger identity push (higher strength / IP-Adapter scale) makes the face
+CLOSER to the embedded identity but MORE AI-looking; weaker push leaves
+identity to drift but face looks less AI-generated. There is no parameter
+setting that simultaneously recovers original identity AND looks less AI than
+the cleaned image, because the cleaned image is itself a controlnet-light
+denoise of the original (closer to original pixels) while a restore pass is a
+full SDXL regeneration (further from original pixels).
+
+**Operational conclusion.** Do not ship `--restore-faces` in any monetized
+deployment. The cleaned image from the main controlnet 0.20 pass is the
+LEAST-AI state we can reach without re-introducing SynthID; every restore
+method tested (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img,
+InstantID img2img-on-cleaned at three parameter sweeps) trades original-look
+for embedding-driven regeneration and makes the face read as "AI-generated"
+rather than "the original person". The `instantid` and `photomaker` extras
+stay in the library as opt-in for research / personal use where users
+explicitly want identity regeneration; the CLI flag and module docstrings
+state the trade-off at every entry point.

docs/synthid-robust-identity-research.md

@@ -0,0 +1,282 @@
+# SynthID-robust face identity for an SDXL removal pipeline (research)
+
+> **Status (2026-06-08): retired.** Every approach described below was empirically
+> tested and rejected -- see `docs/synthid-robust-identity-research-2026-06-08.md`
+> "Empirical follow-up" for the final conclusion. The library no longer ships any
+> face-restore extra: the cleaned image from the main controlnet 0.20 pass is the
+> least-AI face state we can reach without re-introducing SynthID. This document
+> is kept as historical record of the exploration.
+
+**Question.** Which face identity-preservation mechanism for an SDXL img2img +
+canny-ControlNet watermark-removal pipeline (denoise 0.20-0.30) is BOTH (a)
+commercial-safe end-to-end and (b) does not re-introduce the SynthID pixel
+watermark the removal pass just destroyed?
+
+**Constraint.** raiw.cc is a paid service, so every component (adapter weights AND
+the face embedder it conditions on AND any base model) must be Apache-2.0 / MIT /
+BSD or otherwise clearly commercial-permitted. Non-commercial is disqualifying.
+
+**One-line verdict.** Today there is **ONE** SDXL identity-conditioning stack that
+is commercial-safe end-to-end: **PhotoMaker-V1** (Apache-2.0, identity encoded as a
+fine-tuned OpenCLIP-ViT-H/14 image embedding -- NO InsightFace). Every other
+candidate -- **including PhotoMaker-V2**, IP-Adapter FaceID, InstantID, PuLID,
+Arc2Face -- inherits InsightFace's non-commercial model-pack license through an
+ArcFace-class embedder and is therefore blocked for paid services, regardless of
+the adapter's own license header. Below is the evidence per component and the
+integration plan.
+
+**Correction notice (2026-06-04).** An earlier version of this doc claimed
+PhotoMaker-V2 was commercial-safe end-to-end. That was WRONG -- the V2 model card
+phrase *"id_encoder includes finetuned OpenCLIP-ViT-H-14 and a few fuse layers"*
+described one of TWO ID branches; the V2 source (model_v2.py) defines
+`PhotoMakerIDEncoder_CLIPInsightfaceExtendtoken` whose forward takes an
+ArcFace `id_embeds` from `insightface.app.FaceAnalysis`, and the upstream package
+`__init__.py` imports InsightFace at module load. A Modal cert sweep caught this
+empirically (`No module named 'insightface'` from `restore_faces_photomaker`). V1
+is the correct commercial-safe target: its `PhotoMakerIDEncoder` (model.py)
+forward takes only `(id_pixel_values, prompt_embeds, class_tokens_mask)` -- no
+ArcFace branch -- so identity is CLIP-only.
+
+**Status notice (2026-06-04, end of session).** Two commercial-safe paths were
+tried and abandoned:
+
+1. **PhotoMaker-V1** (commercial-safe by license but blocked by upstream compat).
+   The cert sweep hit a cascade of upstream compatibility issues with the diffusers
+   version we ship (0.38): missing `einops` declaration, missing `peft` declaration,
+   default `pm_version='v2'` that mis-loads V1 weights into the V2 encoder, custom
+   `id_encoder` left on CPU after `pipe.to(device)`, and a CFG-batch tensor-shape
+   mismatch in the denoising loop (`Expected size 2 but got size 1`). 7 cascading
+   fixes did not get the pipeline running end-to-end. The PhotoMaker `pipeline.py`
+   header notes it was forked from diffusers v0.29.1; SDXL prompt-encoder handling
+   changed significantly between 0.29 and 0.38.
+2. **GFPGAN on the diffusion-CLEANED image** (commercial-safe, but no identity
+   recovery). A one-line change made it SynthID-safe (input pixels are already
+   clean, so the partial blend cannot transport the watermark), but visual
+   inspection of the cert output showed it only polished the already-drifted face
+   without actually restoring identity. Trade-off was real and the value too low
+   to keep.
+
+**The shipped path is PhotoMaker-V2** (`photomaker_restore.py`, the `photomaker`
+extra). V2 uses a DUAL ID encoder (CLIP image features + ArcFace embedding),
+which delivers true identity-from-embedding face regeneration. The cost is that
+the ArcFace embedding comes from InsightFace's `antelopev2`/`buffalo_l` model
+packs, which are released under a non-commercial / research-only license. **So
+the shipped restore path is NON-COMMERCIAL.** raiw.cc and any other monetized
+deployment must NOT install the `photomaker` extra. The CLI flag and module
+docstring both call this out at every entry point.
+
+A future commercial-safe path would need either (a) the PhotoMaker upstream to
+land its diffusers 0.38 compat fix so V1 can run, or (b) an equally good
+ArcFace-class face-recognition model released under a permissive license that
+PhotoMaker-V2 can be retargeted to. Neither is on a near-term horizon as of
+this writing.
+
+## 1. Why identity-by-embedding (not by pixel) is the only SynthID-robust path
+
+The pipeline regenerates pixels to destroy SynthID. Any identity-restoration that
+is "faithful to the input pixels" (GFPGAN, CodeFormer, face-swap-by-blending, our
+previous restore-on-original pass) reproduces the watermark, because SynthID is
+engineered to be robust to fidelity-preserving transforms (resize, JPEG, partial
+blend). Oracle-confirmed on a real Gemini face: controlnet @ 0.20/0.25 WITH the
+GFPGAN restore pass left SynthID detected; the SAME controlnet @ 0.20 with
+`--no-restore-faces` cleared it (clean A/B, see `docs/synthid.md` 5.5 and
+`docs/controlnet-removal-pipeline-research.md`).
+
+The only mechanism that can preserve identity AND not re-introduce SynthID is to
+carry identity in a SEMANTIC EMBEDDING (a vector that encodes "who is in this
+picture") and use it to CONDITION a fresh generation -- the pixels are new, so
+the watermark is not transported. Two embedding families exist in practice:
+
+- **ArcFace-class face-recognition embeddings** (the InsightFace family). Used by
+  IP-Adapter FaceID, InstantID, PuLID, Arc2Face. Highest identity fidelity, but
+  the embedder weights are non-commercial.
+- **CLIP image embeddings of a face crop**. Used by PhotoMaker (and the original
+  IP-Adapter image variant). Lower identity fidelity at small scale than ArcFace,
+  but the encoder (OpenCLIP-ViT-H/14, MIT) is commercial-safe.
+
+## 2. License table (verified against primary sources, 2026-06-04)
+
+| stack | adapter weights | identity encoder | end-to-end commercial-safe? |
+|---|---|---|---|
+| **PhotoMaker-V1** | **Apache-2.0** ([HF][pmhf]) | **OpenCLIP-ViT-H/14 (MIT)** finetuned, identity from `PhotoMakerIDEncoder` (`model.py`); forward takes only ``(id_pixel_values, prompt_embeds, class_tokens_mask)`` -- no ArcFace branch | **YES** |
+| PhotoMaker-V2 | Apache-2.0 (adapter) ([HF][pm2hf]) | DUAL encoder: OpenCLIP-ViT-H/14 AND InsightFace antelopev2/buffalo_l -- `PhotoMakerIDEncoder_CLIPInsightfaceExtendtoken` (`model_v2.py`) forward takes `id_embeds` from `insightface.app.FaceAnalysis`, and `photomaker/__init__.py` imports InsightFace at module load | NO -- InsightFace pack is non-commercial |
+| IP-Adapter FaceID | non-commercial per model card: *"AS InsightFace pretrained models are available for non-commercial research purposes, IP-Adapter-FaceID models are released exclusively for research purposes and is not intended for commercial use"* ([HF][ipafhf]) | InsightFace antelopev2 (non-commercial for the model pack) | NO -- both layers block |
+| InstantID | Apache-2.0 (adapter only) ([HF][insthf]) | requires InsightFace antelopev2 face-analysis at runtime (`FaceAnalysis(name='antelopev2', ...)` per the README usage snippet, [HF][insthf]) | NO -- embedder pack is non-commercial |
+| PuLID | apache-2.0 (HF model metadata, [HF][pulidhf]) | depends on InsightFace face-analysis for ArcFace embedding (per the upstream README; PuLID's own card is sparse and the GitHub README documents the InsightFace install step) | NO -- same embedder issue as IP-Adapter FaceID |
+| Arc2Face | MIT (HF model metadata, [HF][arc2hf]) | uses `insightface.app.FaceAnalysis` to extract the ArcFace embedding ([HF][arc2hf]); also based on SD-v1-5 (NOT SDXL) | NO -- non-commercial embedder + not SDXL |
+
+**The crux is InsightFace.** InsightFace explicitly splits its license: *"Code is
+MIT licensed; models require separate commercial licensing"* and frames the
+pretrained packs as *"Commercial licensing for InsightFace's open-source model
+packages"* requiring users to *"obtain commercial usage rights for model
+packages"* ([insightface.ai][iflic]). antelopev2 and buffalo_l fall under the
+model-pack license, not MIT. So any stack that calls
+`insightface.app.FaceAnalysis(name='antelopev2', ...)` to compute its ArcFace
+embedding is blocked by default, REGARDLESS of the adapter's own Apache header
+above it. This is the same reason IP-Adapter FaceID's card flags itself
+non-commercial.
+
+(Note on PuLID's HF metadata: the model card declares apache-2.0 for the adapter
+weights but the upstream repo's quickstart requires the InsightFace package to
+extract the ID embedding. So PuLID's adapter license is permissive; the BLOCKER
+is the embedder it expects at runtime. This is the same trap as InstantID.)
+
+[pmhf]: https://huggingface.co/TencentARC/PhotoMaker
+[pm2hf]: https://huggingface.co/TencentARC/PhotoMaker-V2
+[ipafhf]: https://huggingface.co/h94/IP-Adapter-FaceID
+[insthf]: https://huggingface.co/InstantX/InstantID
+[pulidhf]: https://huggingface.co/guozinan/PuLID
+[arc2hf]: https://huggingface.co/FoivosPar/Arc2Face
+[iflic]: https://www.insightface.ai/solutions/face-recognition-licensing
+
+## 3. Is there a commercial-safe ArcFace replacement?
+
+Short answer: **no clean drop-in**. The widely deployed pretrained ArcFace packs
+(antelopev2, buffalo_l, glint360k) come from InsightFace and are non-commercial.
+ArcFace as an ARCHITECTURE is published in a paper, so retraining is legally fine,
+but you would need:
+
+- a commercial-licensed training dataset (the big public ones -- MS-Celeb-1M,
+  Glint360K, WebFace -- carry research-only or licensing-uncertain restrictions);
+- compute + time to train an ArcFace-class model on the legal dataset;
+- the result would be a one-off effort, not a maintained dependency.
+
+For a removal service this is a multi-month side project that delivers what
+PhotoMaker already gives us with one pip install. So the practical answer is to
+take the CLIP-embedding path (PhotoMaker-V1; V2 adds InsightFace and is non-commercial), accept the identity-fidelity
+trade-off, and revisit ArcFace later if quality is insufficient.
+
+## 4. Does an identity embedding leak SynthID?
+
+This is the load-bearing assumption of the whole approach. The argument:
+
+- SynthID is a low-amplitude, perceptually-invisible pixel watermark engineered
+  to be robust to "fidelity-preserving" transforms (it survives JPEG, resize,
+  crop, color, noise at >=99% TPR -- see arXiv:2510.09263 referenced in
+  `docs/synthid.md`).
+- A face-recognition / CLIP-image embedding is by design INVARIANT to such low-
+  amplitude pixel changes (compression, brightness, small noise should not change
+  "who is in the photo"). That is the whole training objective.
+- Therefore the embedding extracted from a watermarked face vs. the same face
+  cleaned should be ~identical -- the embedding cannot CARRY the watermark
+  pattern, only the identity, because the watermark sits in exactly the
+  dimensions the embedding learned to discard.
+
+**MEASURED 2026-06-04 — hypothesis confirmed.** Ran a low-amplitude
+perturbation sweep on 31 face crops (3 photoreal originals: gemini_3, gemini_4,
+openai_3 grid), comparing `cos(embedding(orig), embedding(perturbed))` for OpenCLIP-
+ViT-H/14 (laion2B-s32B-b79K, the same OpenCLIP-ViT-H/14 encoder PhotoMaker V1 and V2 both finetune for CLIP-side identity):
+
+| perturbation | mean cos | min | max |
+|---|---|---|---|
+| **synthid_proxy** (±2 LSB low-freq noise, σ=4 px Gaussian carrier — same regime SynthID hides in) | **0.9977** | 0.9937 | 0.9996 |
+| noise3 (Gaussian σ=3, full-spectrum) | 0.9541 | 0.9055 | 0.9825 |
+| jpeg90 (SynthID survives this) | 0.9280 | 0.8806 | 0.9566 |
+| blur1 (Gaussian σ=1) | 0.9139 | 0.8103 | 0.9875 |
+| jpeg70 | 0.8945 | 0.8125 | 0.9603 |
+| (self check: identical crop) | 1.0000 | 1.0000 | 1.0000 |
+
+The SynthID-magnitude perturbation moves the embedding by **0.002** (cosine 0.9977),
+an order of magnitude less than JPEG90 — which SynthID survives at >=99% TPR by
+design. So the embedding cannot carry the watermark pattern: its discriminative
+signal is in dimensions the SynthID payload does not occupy. PhotoMaker-V1
+conditioned on a watermarked face will see ~the same identity vector as if
+conditioned on a clean face of the same person, so the freshly generated face
+inherits the identity, not the watermark.
+
+A first, naive smoke run measured `cos(orig, SDXL-cleaned)` instead — that test is
+about diffusion drift, not watermark invariance (diffusion at strength 0.20-0.30 is a
+much larger perturbation than SynthID), so its 0.56-0.93 spread is the identity
+drift the PhotoMaker pipeline is meant to fix in the first place. The
+synthid_proxy result above is the one that actually answers the load-bearing
+question. Script: `/tmp/identity_smoke/test2_proxy.py` (not committed; reproducible
+from the test set + this doc).
+
+## 5. PhotoMaker-V1 properties for our pipeline
+
+- **SDXL-native.** PhotoMaker v1 and v2 target Stable Diffusion XL; the pipeline
+  is a stacked-ID embedding fused into SDXL's cross-attention via the fuse layers
+  bundled in the released weights.
+- **Identity from a SINGLE reference image works** but the method was designed
+  for "stacked" multi-reference; with one image identity fidelity is lower than
+  with 3-4, and a service has only one (the upload). This is the failure mode to
+  guard.
+- **Compatibility with img2img + canny ControlNet.** PhotoMaker is typically
+  exposed in txt2img workflows in the upstream demo. SDXL img2img + ControlNet
+  is the same denoising backbone, so the cross-attention injection works the same
+  way; community examples on Diffusers and ComfyUI confirm PhotoMaker stacks with
+  ControlNet. Validate this on a representative image before adopting.
+- **Failure modes to expect:**
+  - identity drift on small / multi-face groups (the 9-face grid case);
+  - "plastic" / over-smoothed faces if PhotoMaker's identity weighting is high
+    while the img2img strength is low;
+  - canny ControlNet conditioning can fight the ID embedding (edges of the
+    ORIGINAL face vs identity of the SAME person regenerated) -- expect to tune
+    `controlnet_conditioning_scale` down a notch on photoreal faces;
+  - PhotoMaker was trained on a celebrity-skew distribution; real-user faces
+    (especially non-white, non-Western, elderly, children) may have lower
+    fidelity. Measure on the real upload distribution.
+
+## 6. Integration cost (rough)
+
+- New deps: `diffusers` already in the gpu extra; PhotoMaker ships as a `.bin`
+  loaded via `pipeline.load_photomaker_adapter(...)`. The OpenCLIP encoder is the
+  same one diffusers already pulls. No new heavy pip dep.
+- Weight download: PhotoMaker-V1 weights are ~3 GB. Add to the Modal HF volume
+  alongside SDXL.
+- VRAM: SDXL + canny ControlNet + PhotoMaker-V1 fits comfortably in A100-40GB.
+- Latency: a few extra seconds on cold start (load PhotoMaker), negligible per
+  request after warm-up.
+- No InsightFace install: huge win for `restore` extra's basicsr/numpy hell --
+  this path simply does not touch that ecosystem.
+
+## 7. Recommended path
+
+1. **Embedding-invariance smoke test FIRST** (one afternoon, no codegen):
+   - For ~10 OpenAI / Gemini watermarked faces, compute OpenCLIP-ViT-H/14
+     embeddings; for the same images after our SDXL `default` pass at the
+     certified strength, compute the embeddings again; assert mean cosine
+     similarity > ~0.95.
+   - If yes -> the embedding does not carry SynthID, proceed.
+   - If no -> the assumption is wrong; PhotoMaker would re-introduce the
+     watermark. Stop and reconsider.
+2. **PhotoMaker-V1 prototype** in the existing `controlnet` pipeline:
+   - Mirror the `_load_controlnet_pipeline` path: add a PhotoMaker variant that
+     loads SDXL + canny ControlNet + PhotoMaker adapter on the same engine.
+   - Extract the OpenCLIP face embedding from the watermarked face crops (use
+     OpenCV YuNet, already bundled for `auto`, to find the face boxes).
+   - Pass the embedding as PhotoMaker's `id_embeds` to the SDXL pipeline; run
+     img2img at the certified strength (0.20 OpenAI, 0.30 Gemini-capped-1536)
+     with the canny edge map.
+3. **Oracle validation** on the cert sweep: run the new PhotoMaker variant
+   through `raiw-app/modal_cert.py` over the same 6 image set, certify on the
+   per-vendor oracles. Expected: SynthID cleared (the regeneration is the same)
+   AND identity recovered (the embedding adds it back).
+4. **Honest exit criteria.** Ship only if BOTH oracle reads clean AND a small
+   user-perception test on real uploads says "looks like me". If identity is
+   still too soft on small faces -> add stacked-reference (multiple crops of the
+   same upload at different scales) before reaching for a non-commercial
+   embedder.
+
+## 8. What we are NOT doing, and why
+
+- **No InsightFace.** Non-commercial for model packs (see License table).
+- **No CodeFormer.** Non-commercial.
+- **No GFPGAN on the original image.** It re-introduces SynthID
+  (oracle-confirmed).
+- **No GFPGAN on the cleaned image.** It cannot RECOVER identity that the
+  diffusion pass already drifted -- it can only smooth/sharpen whatever face is
+  already there. Useful as cosmetic polish, not as identity restoration.
+- **No retraining of an in-house ArcFace.** Out of scope for a removal service.
+
+---
+
+## Process note
+
+The deep-research harness was run but its verifier subagents failed to call
+`StructuredOutput` (same harness bug as the prior 2026-05-XX run), so its synthesis
+was unusable. The license claims above were verified by directly fetching the HF
+model cards and the InsightFace licensing page and quoting them; the
+embedding-invariance argument is mechanistic and explicitly flagged as not yet
+measured (it is the first integration step). Do not treat the deep-research
+output as ground truth for this file.

docs/synthid.md

@@ -0,0 +1,610 @@
+# SynthID-Image: technical reference
+
+This document covers how Google SynthID for images works mechanically, what it
+survives, what removes it, and the current deployment landscape. It is written
+for engineers working on watermark detection and removal -- specifically to
+inform decisions about strength settings, test methodology, and what oracle
+results mean.
+
+Primary sources are cited inline. Marketing-only claims are flagged separately
+from independently-verified results.
+
+---
+
+## 1. Mechanism
+
+### 1.1 Post-hoc, model-independent design
+
+SynthID-Image is **not** baked into a diffusion model's weights. It is a
+post-hoc, model-independent system: a separate encoder `f` is applied to an
+already-generated image, and a separate decoder `g` reads it back.
+
+> "We deliberately designed SynthID-Image as a post-hoc, model-independent
+> approach, a choice largely based on deployment considerations."
+> -- Gowal et al., arXiv:2510.09263
+
+The formal definition from the paper:
+
+> "A post-hoc watermarking scheme is a pair f, g consisting of an encoder
+> function f: X -> X, which adds an identification mark, and a decoder
+> function g: X -> {+-1}, which tries to detect if the mark is present."
+
+This is the key architectural fact: **the generative model (Imagen, Gemini's
+image model) is not modified**. The watermark is stamped onto the pixel output
+after generation, by a separate neural network. This means:
+
+- The watermark is in **pixel space**, not in the model's latent activations.
+- Replacing the generative model does not remove the watermarking capability.
+- The encoder/decoder pair can be updated independently of the generative model.
+
+The paper does not disclose the internal architecture of the encoder/decoder
+networks (layer types, capacity). The external variant SynthID-O is available
+to partners; the production internal variant is not published.
+
+### 1.2 How it differs from classical DWT-DCT watermarks
+
+The open watermarks used by Stable Diffusion / SDXL / FLUX (via the
+`imwatermark` library) use classical **DWT-DCT** frequency-domain embedding: a
+fixed bit pattern is added to specific frequency coefficients of the image's
+wavelet transform. This is fast, key-free, and locally detectable with a public
+decoder.
+
+SynthID-Image uses **jointly-trained deep learning models**:
+
+> "SynthID uses two deep learning models -- for watermarking and identifying --
+> that have been trained together on a diverse set of images. The combined model
+> is optimised on a range of objectives, including correctly identifying
+> watermarked content and improving imperceptibility by visually aligning the
+> watermark to the original content."
+> -- Google DeepMind blog, 2023
+
+The practical difference for robustness: the deep learning encoder learns to
+spread the signal across the image in a way that is optimized to survive a
+specific perturbation distribution seen during training. Classical DWT-DCT
+embeds in fixed, predictable frequency bins, making it brittle to any
+operation that hits those bins (e.g., JPEG re-quantization wipes it cleanly at
+quality <= 90).
+
+### 1.3 Payload capacity
+
+SynthID-O (the external/partnership variant) encodes:
+
+- **136 bits** within a **512x512 pixel image**
+
+For comparison (from the same paper):
+
+| Method      | Bits | Resolution |
+|-------------|------|------------|
+| SynthID-O   | 136  | 512x512    |
+| StegaStamp  | 100  | 400x400    |
+| TrustMark   | 100  | 256x256    |
+| WAM         | 32   | 256x256    |
+
+The payload carries an identification mark (not a user-readable secret). The
+paper separates watermark **detection** (is this watermarked?) from payload
+**recovery** (what does the payload say?): the detection path is what oracles
+like the Gemini app's "Verify with SynthID" exercise.
+
+### 1.4 Where in the pipeline it lives
+
+```
+[Diffusion model]
+       |
+  raw pixel output
+       |
+  [SynthID encoder f]   <-- separate neural net, stamps the watermark
+       |
+  watermarked image
+       |
+  [served / downloaded]
+       |
+  [SynthID decoder g]   <-- separate neural net, run by Google's verifier only
+       |
+  present / not present
+```
+
+The VAE decoder of the diffusion model is **not** involved in watermarking.
+Some in-generation watermark approaches (like the research method "Tree Ring")
+inject the signal into the initial noise latent so it propagates through the
+diffusion process and appears in the final image; SynthID-Image does not do
+this -- it is applied after the VAE has already decoded latents to pixels.
+
+---
+
+## 2. Robustness
+
+### 2.1 What the paper claims it survives (primary-source verified)
+
+The SynthID-Image paper (arXiv:2510.09263) evaluates SynthID-O against **30
+image transformations** grouped into 6 categories:
+
+| Category    | Examples                                      |
+|-------------|-----------------------------------------------|
+| Color       | brightness, contrast, saturation, hue shifts  |
+| Combination | combinations of multiple transforms           |
+| Noise       | Gaussian noise, impulse noise, median filter  |
+| Overlay     | text overlays, logos, stickers                |
+| Quality     | JPEG compression, WebP, format conversion     |
+| Spatial     | crop, resize, rotate, flip, padding           |
+
+**TPR at 0.1% FPR -- SynthID-O vs. baselines (resized to 512x512):**
+
+| Category         | SynthID-O | Best baseline (WAM) | Worst baseline (StegaStamp spatial) |
+|------------------|-----------|---------------------|--------------------------------------|
+| Identity (none)  | 100.00%   | 100.00%             | 100.00%                              |
+| Aggregated       | 99.98%    | 90.62%              | ~70%                                 |
+| Color            | 100.00%   | 81.29%              | ~75%                                 |
+| Combination      | 99.96%    | 96.08%              | ~22%                                 |
+| Noise            | 99.98%    | 100.00%             | ~92%                                 |
+| Overlay          | 100.00%   | 100.00%             | 100.00%                              |
+| Quality          | 99.99%    | --                  | ~89%                                 |
+| Spatial (worst)  | 99.97%    | 76.04%              | 15.25%                               |
+
+The "Spatial worst" row is the hardest case (aggressive crop + resize).
+SynthID-O retains 99.97% TPR; StegaStamp collapses to 15.25%. This is where
+the deep-learning approach gains the most over classical methods.
+
+Google's marketing page states the watermark is:
+
+> "designed to stand up to modifications like cropping, adding filters, changing
+> frame rates, or lossy compression."
+> -- deepmind.google/models/synthid/
+
+The marketing claim is broadly consistent with the paper's numbers for these
+specific categories.
+
+**JPEG and format conversion specifically** fall under the "Quality" category,
+where SynthID-O achieves 99.99% TPR. This is the empirical basis for the fact
+that **GitHub-recompressed JPEGs from issue attachments are valid SynthID test
+subjects**: the re-encoding does not remove the pixel watermark.
+
+### 2.2 Stated limits (vendor claim, not independently verified)
+
+> "SynthID isn't foolproof against extreme image manipulations."
+> -- Google DeepMind blog, 2023
+
+This is the only public failure-mode statement Google has made. No specific
+perturbation type, threshold, or quantitative boundary is named. The
+Limitations section of the paper (Section 10) was not recoverable from the
+public HTML version of arXiv:2510.09263v1 due to a rendering failure in the
+conversion (the body text of Section 10 is absent from the HTML).
+
+**What is known empirically from our own oracle-verified testing.**
+
+A controlled study (June 2026, clean v0.8.6 with text/face protection OFF,
+native resolution on this repo's default SDXL pipeline) measured the minimum
+img2img strength that removes the SynthID pixel watermark, verified per image on
+the vendor's own oracle (openai.com/verify for OpenAI, the Gemini app "Verify
+with SynthID" for Google). Each subject is archived in `data/synthid_corpus/` as a
+pos original plus its minimum-clearing cleaned output (manifest `verified_via` =
+`openai-verify` / `gemini-app`), EXCEPT one third-party image from issue #14, which
+was oracle-verified but is not committed (third-party content stays out of the
+public corpus).
+
+| Vendor | Images | Resolution(s) | Pipeline | Removed at |
+|--------|--------|---------------|----------|------------|
+| OpenAI (gpt-image) | n=4 (3 archived + 1 external-only) | 1024x1536 .. 1600x1600 | native | **0.05** |
+| Google (Gemini)    | n=4 | 2816x1536 -> capped 1536 | `--max-resolution 1536` | **0.15** (0.05 and 0.10 do NOT clear) |
+
+**Two findings, both oracle-verified:**
+
+1. **Vendor is the dominant factor, not resolution.** Google's SynthID is
+   roughly 3x more robust than OpenAI's: at a comparable (small) working
+   resolution, OpenAI clears at 0.05 while Google needs 0.15. This matches
+   Google having hardened SynthID more aggressively over time.
+
+2. **OpenAI SynthID removal is resolution-independent in the tested range.**
+   All four OpenAI images (including a 1600x1600) cleared at 0.05.
+
+**CORRECTION (supersedes the earlier "resolution dependence" claim).** A prior
+version of this doc and CLAUDE.md stated that strength 0.30 failed to remove
+SynthID on 1600x1600 gpt-image and that removal was resolution-dependent. That
+was a **measurement artifact of a since-removed per-region re-scrub step** (issue
+#14): on the dense-text infographics tested, that step could reconstitute SynthID
+in text regions. Re-running the *same* 1600x1600 image on the clean current
+pipeline removes SynthID at **0.05**. The "large images resist removal" conclusion
+was false; the resistance was that region-rescrub shielding, since removed.
+
+**Open / not locally testable:**
+
+- **Native large Gemini (2816x1536, ~4.3 MP).** The Gemini floor of 0.15 was
+  measured on the *capped* (`--max-resolution 1536`) path, which is the
+  practical local route on Apple-Silicon (native 2816 OOMs / falls back to slow
+  CPU on a 32 GB M-series). Native large Gemini was not measured here; the
+  vendor and resolution effects would stack, so it plausibly needs >= 0.30 or a
+  discrete GPU. Confirm on a CUDA box if needed.
+- **Heavy JPEG compression** (quality < ~50-60): not oracle-tested; the DL
+  approach is more robust than DWT-DCT but Google acknowledges limits at
+  "extreme" manipulation.
+
+### 2.3 Removal attacks and forensic detectability
+
+The paper arXiv:2605.09203 ("Removing the Watermark Is Not Enough",
+Goonatilake & Ateniese, 2026) evaluates 6 removal attacks against a ResNet-50
+forensic detector. All attacks defeat the watermark verifier but are detected
+by the forensic classifier:
+
+| Attack          | Family           | AUROC  | TPR @ 1% FPR | TPR @ 0.1% FPR |
+|-----------------|------------------|--------|--------------|----------------|
+| UnMarker        | Distortion       | 0.9994 | 99.81%       | 98.28%         |
+| WatermarkAttacker| Regeneration    | 0.9997 | 99.95%       | 99.38%         |
+| CtrlRegen+      | Regeneration     | 0.9999 | 99.97%       | 99.64%         |
+| NFPA            | Inversion/Pert.  | 0.9984 | 99.24%       | 62.10%         |
+| Boundary Leak.  | Inversion/Pert.  | 0.9991 | 99.24%       | 88.34%         |
+| WiTS            | Erosion          | 0.9999 | 99.80%       | 99.55%         |
+
+The forensic detector is a standard ResNet-50 fine-tuned end-to-end; no exotic
+architecture needed. The key finding:
+
+> "These removers do not return images to a clean forensic state. They often
+> trade an explicit watermark for an implicit watermark: a detectable artifact
+> introduced by the removal process itself."
+
+This means: even when our SDXL img2img pass defeats the SynthID pixel
+watermark (oracle reads negative), the output may still be classifiable as
+"an image that went through a removal pipeline" by an independent detector --
+even if that detector is not trained on SynthID specifically. **Defeating the
+verifier does not restore forensic deniability.**
+
+CtrlRegen+ is the most detectable removal method (AUROC 0.9999), which is
+notable because it is also the most powerful removal attack. The paper notes
+that diffusion regeneration "leaves a strong reconstruction signature from the
+diffusion prior."
+
+---
+
+## 3. Detectability and verifier access
+
+### 3.1 No public local detector
+
+The SynthID decoder is proprietary and not released:
+
+> "SynthID-Image has been used to watermark over ten billion images and video
+> frames across Google's services and its corresponding verification service is
+> available to trusted testers."
+> -- Gowal et al., arXiv:2510.09263
+
+There is no public API, no released decoder weights, and no reproducible
+algorithm for local detection. The verification service (SynthID Detector) is:
+
+> "a verification portal" in early testing with "journalists and media
+> professionals" on a waitlist
+> -- deepmind.google/models/synthid/
+
+The external variant SynthID-O is available "through partnerships" only. Our
+tool cannot locally detect SynthID presence or absence -- this is by design,
+not a gap we can fill.
+
+### 3.2 How our tool detects SynthID (metadata proxy)
+
+We detect SynthID indirectly: if the image's C2PA manifest is signed by a
+known SynthID-using issuer (Google, OpenAI), we infer SynthID is present. This
+is a **metadata proxy**, not a pixel watermark decode. It works while the C2PA
+manifest is intact, and is silent once the manifest is stripped or the image
+is re-encoded without C2PA (e.g., a screenshot, a social-media re-upload, or
+after `metadata --remove`).
+
+This is why:
+- `identify` on a GitHub-recompressed issue attachment returns Unknown (C2PA is
+  gone) even though the pixel SynthID is still present and detectable by
+  openai.com/verify.
+- A quiet `identify` output is not proof that SynthID was removed -- it only
+  means the metadata signal is gone.
+
+### 3.3 Oracle scope: each vendor detects only their own
+
+From openai.com/research/verify (verbatim, verified 2026-05-31):
+
+> "OpenAI generation signals will only be detected if the image was generated
+> with our tools."
+> "Content could also still be AI-generated by another company's model, which
+> the tool currently does not detect."
+
+SynthID technology is used by multiple vendors, but each verifier is keyed to
+its own payload:
+
+| Oracle                        | Detects          | Does NOT detect         |
+|-------------------------------|------------------|-------------------------|
+| Gemini app "Verify with SynthID" | Google SynthID | OpenAI SynthID          |
+| openai.com/research/verify    | OpenAI SynthID   | Google SynthID          |
+
+A Google-SynthID image reads clean on openai.com/verify. An OpenAI image reads
+clean in the Gemini oracle. They are different payloads within the same
+framework.
+
+---
+
+## 4. Adoption and current state (as of June 2026)
+
+### 4.1 Google products
+
+Google has watermarked **over 10 billion** images and video frames. The
+deployment split by surface matters for our tool:
+
+| Surface                              | SynthID pixel | C2PA metadata | Visible sparkle |
+|--------------------------------------|---------------|---------------|-----------------|
+| Gemini app (generated images)        | YES           | YES (Google)  | YES             |
+| Gemini API / AI Studio / Nano Banana | YES           | NO            | YES             |
+
+The Gemini API surface is a key blind spot: it embeds the pixel watermark and
+the visible sparkle but **no C2PA or IPTC at all**. Our `identify` returns
+Unknown on API-generated images unless the visible sparkle is detected (via
+`check_visible=True`) or the user runs the Gemini app oracle.
+
+### 4.2 OpenAI
+
+OpenAI confirmed SynthID adoption (Help Center, updated 2026-05-21):
+
+> "ChatGPT images include both C2PA metadata and SynthID watermarks."
+
+This is time-gated: pre-rollout ChatGPT/gpt-image images carry C2PA without
+SynthID. Our C2PA proxy therefore over-reports SynthID presence on old images
+(hence the `_OPENAI_CAVEAT` hedging flag in the codebase).
+
+### 4.3 Other vendors
+
+- **Kakao** (South Korea): SynthID adopter as of May 2026 (Google announcement)
+- **NVIDIA Cosmos**: SynthID for video (not still images; different pipeline)
+- **Meta AI**: does NOT use SynthID; uses IPTC `digitalSourceType` marker instead
+
+### 4.4 Version evolution (v1 vs v2 hardening)
+
+Google has not publicly documented version numbers for the SynthID image
+watermark in a way that maps to our testing observations. What is known
+empirically from oracle tests:
+
+- **Before May 2026 (Gemini)**: strength 0.05 removed the watermark
+- **May 2026 (Gemini)**: strength 0.05 insufficient; 0.10 required
+- **Current (Gemini, June 2026)**: on the capped 1536 path, 0.05 and 0.10 do
+  NOT clear; 0.15 clears (n=4, Gemini app oracle). See section 2.2.
+- **OpenAI (June 2026)**: clears at 0.05 across 1024-1600 (n=4, clean v0.8.6).
+  The earlier "0.30 still detected on 1600x1600" report (issue #14) was the
+  text-protection bug, not a hardening of the watermark -- see the correction in
+  section 2.2.
+
+Google has hardened SynthID relative to OpenAI's (vendor gap measured at ~3x
+strength), but the year-over-year "0.05 -> 0.10 -> 0.30" progression above
+conflates a real hardening trend with the now-debunked region-rescrub artifact;
+treat only the section 2.2 controlled numbers as authoritative.
+
+---
+
+## 5. Practical implications for this tool
+
+### 5.1 Preserving content means regenerating it, never copying it
+
+**Core rule:** SynthID is a pixel-amplitude pattern, so any approach that FREEZES
+or RESTORES original pixels in a region re-introduces the watermark there. Early
+region-based text/face "protection" (since removed) proved this: restoring the
+original face pixels guaranteed SynthID survived in faces, and even a per-region
+high-resolution re-scrub from an upscaled crop could be insufficient to destroy
+the payload, reconstituting SynthID in text. The lesson held and shaped the
+current design: **content is preserved by REGENERATING it under structural
+conditioning, never by copying original pixels.**
+
+- **Text + structure:** `--pipeline controlnet` (SDXL img2img + a canny ControlNet) is
+  **THE DEFAULT pipeline since 2026-06-09** (`--pipeline default` opts down to plain
+  SDXL img2img for inputs without text/faces). It conditions the regeneration on the
+  edge map, so text and structure stay sharp while every pixel is still regenerated. Text legibility is
+  better than plain img2img at the same strength (text stays readable where plain
+  garbles it). **BUT removal efficacy at the low vendor-adaptive strength is CONTENT ×
+  PIPELINE dependent and NEITHER pipeline clears all content -- oracle-validated
+  2026-06-04 (8 OpenAI images, strength 0.10/0.15, max-res 1536).** The survivors FLIP
+  by content type: **photoreal** (a 9-face grid, a bracelet product photo) SURVIVES
+  controlnet but CLEARS `default`; **flat graphic** (a logo/poster with large flat
+  color fills) SURVIVES `default` but CLEARS controlnet; a flat **text** card cleared
+  under both. Why: controlnet's dense edge map keeps the regen too close to the
+  original on photoreal (so SynthID survives) but freely repaints flat fills (so it
+  clears them); plain img2img at low strength perturbs photoreal texture enough but
+  barely touches flat fills. **Root cause = insufficient STRENGTH, not the pipeline:
+  the vendor-adaptive 0.10 is NOT universally sufficient (the June numbers below held
+  for the content they were measured on). The robust fix is a HIGHER strength,
+  oracle-revalidated per content type (controlnet can be cranked harder without losing
+  structure; a lower `controlnet_conditioning_scale` also frees the regen on
+  photoreal).** So neither `--pipeline controlnet` nor plain `default` is a drop-in
+  removal guarantee at today's strength -- pick by what you must PRESERVE (controlnet
+  for text/structure), then raise strength until the oracle reads clean. (The earlier
+  "reads clean on the oracle" claim held only for the one flat/text-background case it
+  was checked on; it does not generalize.) **UPDATE 2026-06-09: the default strengths
+  were raised and made pipeline-aware (controlnet ladder = the certified
+  0.20/0.30/0.30 floors, applied to BOTH pipelines as a single ladder -- see §5.2 for
+  why one ladder covers plain `sdxl` too) and controlnet is now the default pipeline.
+  The plain-SDXL profile was also renamed `default` -> `sdxl` (`default` stays as an
+  alias). The 0.10/0.15 numbers in this analysis are the PRE-raise values it was
+  measured at. See §5.2.**
+- **Face identity:** canny holds face *structure* but not *identity*. Shipped as the
+  optional `--restore-faces` GFPGAN post-pass (`face_restore.py`, the `restore`
+  extra, experimental/opt-in, off by default). It runs GFPGAN on the ORIGINAL
+  faces and feather-composites the restored face REGIONS into the cleaned image.
+  **WARNING (oracle-confirmed 2026-06-04): this pass can RE-INTRODUCE SynthID into
+  the face regions -- the earlier "GFPGAN re-synthesizes from a StyleGAN2 prior ->
+  scrubs SynthID -> oracle-confirmed clean" claim was WRONG.** At the default fidelity
+  weight `0.5` GFPGAN blends ~half the ORIGINAL (watermarked) face pixels with the
+  prior, and SynthID is robust to that partial blend, so the composited face carries
+  the watermark back in -- over the diffusion-cleaned face. Confirmed by a clean A/B:
+  `gemini_3` read SynthID-detected after controlnet @ 0.20/0.25 WITH restore, but
+  NOT-detected after the same controlnet @ 0.20 with `--no-restore-faces` (only
+  restore differed). Content-dependent (a second face image cleared WITH restore),
+  which is why a single-image check earlier read "clean". **Fix directions (not yet
+  done): run GFPGAN on the diffusion-CLEANED image not the original; or drop the
+  weight well below 0.5; or leave restore OFF for removal -- each needs oracle
+  re-validation.** Commercial-
+  safe (GFPGAN Apache-2.0 + RetinaFace MIT); the CodeFormer alternative is
+  NON-COMMERCIAL and is not shipped. (An IP-Adapter FaceID approach was tried and
+  REMOVED -- it needs high denoise strength and corrupts faces at removal strength;
+  see `docs/controlnet-removal-pipeline-research.md`.)
+
+### 5.2 Strength setting
+
+There is no single permanent correct strength, but the controlled June 2026
+study (section 2.2) gives empirical floors:
+
+- **OpenAI**: 0.05 clears across 1024-1600 (n=4) -- **but content-dependent, NOT
+  universal.** The follow-up oracle pass (2026-06-04, 8 images) found a flat-graphic
+  OpenAI logo/poster still SynthID-detected after `default` at 0.10, and photoreal
+  images still detected after controlnet at 0.10/0.15: at low strength the
+  low-change regions (large flat fills under `default`, dense edges under controlnet)
+  are not perturbed enough. So the 0.05 floor held only for the n=4 content it was
+  measured on; treat it as a lower bound, not a guarantee, and raise + oracle-recheck
+  per content type (see §5.1 controlnet bullet).
+- **Google (capped 1536)**: 0.15 (n=4); 0.05 and 0.10 do not clear.
+- **Google native 2816**: not locally measured; likely needs >= 0.30 (vendor +
+  resolution stack). Use a GPU or `--max-resolution 1536`.
+
+The default is **vendor-adaptive** (`watermark_profiles.resolve_strength` +
+`vendor_for_strength`): the tool reads the C2PA issuer on the original input and picks
+`OPENAI_STRENGTH` 0.20 / `GEMINI_STRENGTH` 0.30 / `UNKNOWN_STRENGTH` 0.30. **The SAME
+ladder applies to both pipelines** (`sdxl` and `controlnet`) -- these are the
+oracle-certified controlnet floors (§5.5, the 2026-06-04 Modal cert). Why one ladder
+covers plain `sdxl` too: the certification was run on controlnet and does NOT transfer
+by symmetry (the two pipelines have OPPOSITE hard cases -- controlnet leaves SynthID on
+photoreal, `sdxl` on flat graphics, the §5.1 content-x-pipeline table), BUT on its own
+hard case (flat fills) `sdxl` is the WEAKER remover (plain img2img barely perturbs a
+flat region at low strength), so it needs AT LEAST controlnet's strength -- the
+certified floor is therefore the right floor for `sdxl` too. This is a MARGIN argument
+for `sdxl`, not a separate certification (no local SynthID detector to self-verify).
+The higher strength costs little quality where it matters, because `controlnet` is now
+the default pipeline, so `sdxl` is reached only via an explicit `--pipeline sdxl` (a
+deliberate opt-down), where over-regeneration has no faces/text to damage.
+This uses the vendor signal we DO have locally (the C2PA SynthID proxy) to avoid the
+overkill of a single high default on OpenAI images, without needing a local pixel
+detector. An explicit `--strength` always wins. If the watermark still survives (e.g. a
+large native Gemini beyond the capped-1536 validation), raise toward 0.35-0.40 (0.40
+visibly corrupts dense text), using the lowest value that reads clean on the oracle.
+
+### 5.3 Test methodology
+
+- **GitHub-recompressed JPEGs from issue attachments are valid SynthID test
+  subjects.** JPEG re-encoding removes C2PA metadata but does NOT remove the
+  SynthID pixel watermark (verified June 2026 on issue #14 pic3). Do not
+  dismiss these as "not faithful originals" for SynthID-removal tests.
+- **The correct oracle for OpenAI images is openai.com/verify**, not the Gemini
+  app. The two oracles detect different payloads.
+- **A quiet `identify` output after processing is not proof of removal.** It
+  means the metadata proxy is gone. The pixel watermark state is unknown without
+  an oracle check.
+- **After removal, the output may carry forensic artifacts** detectable by an
+  independent classifier even if the vendor oracle reads negative. Defeating the
+  verifier is not the same as being forensically indistinguishable from clean
+  content (arXiv:2605.09203).
+
+### 5.4 Strength vs forensic detectability: the tradeoff
+
+Higher img2img strength removes the watermark but introduces detectable
+regeneration artifacts. The Goonatilake & Ateniese paper shows the strongest
+diffusion-based removers are simultaneously the most forensically detectable
+(AUROC up to 0.9999). The tradeoff is unavoidable with current diffusion-based
+approaches: defeating the vendor's verifier is not the same as being clean.
+
+### 5.5 Oracle validation log -- 2026-06-04 OpenAI pass
+
+Eight OpenAI `gpt-image` originals run through both pipelines and checked on
+openai.com/verify (the OpenAI SynthID oracle). `--max-resolution 1536`; strength
+is the vendor-adaptive default (`vendor_for_strength`): images with an OpenAI C2PA
+manifest get `OPENAI_STRENGTH` 0.10, the one without C2PA falls to
+`UNKNOWN_STRENGTH` 0.15. "detected" = SynthID still found (removal FAILED);
+"clean" = SynthID not detected.
+
+| image | content type | size | strength | `--auto`/controlnet | `default` |
+|---|---|---|---|---|---|
+| typography card | flat text | 1122x1402 | 0.10 | clean | clean |
+| raiw.cc poster | flat graphic (logo + flat fills) | 1024x1536 | 0.10 | clean | **detected** |
+| 9-face grid | photoreal | 1448x1086 | 0.10 | **detected** | clean |
+| bracelet product photo | photoreal | 1600x1600 | 0.15 | **detected** | clean |
+
+(The other four cleared under both and are omitted.) **Reading:** at this strength
+NEITHER pipeline removes SynthID on all content -- the survivors flip by content
+type. Photoreal survives controlnet / clears `default`; flat graphic survives
+`default` / clears controlnet; flat text clears both.
+
+**Follow-up: removal near the threshold is NON-DETERMINISTIC (seed-dependent).**
+Re-running the two photoreal survivors through controlnet at an explicit
+`--strength 0.15` (`--auto`, same `--max-resolution 1536`) cleared BOTH on the
+oracle (SynthID not detected). But the bracelet had SURVIVED controlnet at the
+SAME 0.15 in the first pass (it was the no-C2PA image, so its vendor-adaptive
+strength was already 0.15) -- same pipeline + strength + resolution, only the
+random (unset) seed differed between runs. So **0.15 is the borderline floor for
+controlnet photoreal, not a robust guarantee**: at the threshold the same
+image+settings can pass or fail run-to-run. img2img runs with `seed=None` (random)
+unless `--seed` is passed, so a removal SERVICE gets a coin-flip near threshold and
+has no local SynthID detector to self-verify.
+
+**Controlnet strength ladder on the two photoreal images (oracle, `--auto`,
+`--max-resolution 1536`):**
+
+| controlnet strength | 9-face grid | bracelet photo |
+|---|---|---|
+| 0.10 | detected | (was 0.15) |
+| 0.15 | clean | **non-deterministic** (survived pass 1, clean pass 2) |
+| **0.20** | **clean** | **clean** |
+
+**Recommended robust controlnet strength = 0.20** (0.05 of margin above the 0.15
+non-deterministic borderline); both photoreal survivors cleared at 0.20. Honest
+caveat: 0.20 is one confirming run WITH margin, not an N-run repeatability proof --
+for a removal service, add a little more margin or validate repeatability, since
+there is no local SynthID detector to self-check. **Implications:** (1) the
+content×pipeline table above conflates a borderline/non-deterministic 0.15 result
+with deterministic content behavior -- the photoreal-survives-controlnet effect is
+solid at 0.10 but at 0.15 it is near-threshold noise; (2) for reliable removal pick
+a strength with MARGIN above the borderline (controlnet >= 0.20), not exactly on
+it; (3) **engineering follow-up for raiw.cc: the controlnet pipeline should use a
+HIGHER vendor strength than `default` (it currently shares `resolve_strength`) --
+e.g. controlnet floor 0.20 -- calibrated per vendor/content on the GPU worker where
+batches are cheap. The shared 0.10/0.15 is tuned for `default`, not controlnet.**
+Source images are private (faces / product shots), not committed; reproduce on any
+photoreal + flat-graphic gpt-image pair, varying the seed, and re-checking the
+oracle.
+
+**Gemini pass + the face-restore re-introduction (2026-06-04).** Four Gemini
+originals via `--auto` (controlnet) at `--max-resolution 1024`, checked on the
+Gemini "Verify with SynthID" oracle (Google content needs the Google oracle, not
+openai.com/verify):
+- Most cleared at controlnet 0.15-0.25; `gemini_3` (a large central FACE, +restore)
+  stayed **SynthID-detected at controlnet 0.15, 0.20 AND 0.25** -- raising strength
+  did not crack it.
+- **Root cause was the face-restore pass, not strength/resolution.** `gemini_3` at
+  controlnet 0.20 with `--no-restore-faces` read **SynthID-NOT-detected** (clean
+  A/B, only restore differed). GFPGAN runs on the ORIGINAL watermarked face and at
+  weight 0.5 blends ~half its pixels back, re-introducing SynthID into the
+  composited face over the diffusion-cleaned result (see §5.1 face-identity bullet).
+- (Side note: reducing the processing resolution does NOT weaken SynthID -- it is
+  robust to downscaling by design, and the study's resolution trend says LOWER
+  processing res needs LESS strength, so 1024 was never the wall.)
+
+**Certified controlnet floors (Modal GPU sweep `raiw-app/modal_cert.py` + oracle,
+restore OFF, <= 1536, each vendor on its own oracle):** OpenAI **0.20** (2 photoreal x
+seed {1,2,3} = 6/6 clean; the 0.15-flipper is seed-robust at 0.20) and Gemini **0.30**
+(0.20 detected -> 0.30 clean on 2/2 seeds). OpenAI 0.20 transfers to prod
+(resolution-independent); Gemini 0.30 holds only <= 1536 -- Gemini is
+resolution-sensitive and raiw.cc runs NATIVE, so cap Gemini <= 1536 + use 0.30 or
+native-calibrate (~0.35+). See `docs/controlnet-removal-pipeline-research.md` for the
+table.
+
+**Net for raiw.cc:** (1) controlnet needs a higher, per-vendor strength than
+`default` -- CERTIFIED OpenAI 0.20 / Gemini 0.30 (above); add a controlnet-specific
+schedule to `resolve_strength`, do not reuse the default ladder; (2) the
+`--restore-faces` pass is now SynthID-safe by construction (the GFPGAN-on-original
+path that re-added SynthID was removed 2026-06-04; the shipped restore is
+PhotoMaker-V2, NON-COMMERCIAL, see `photomaker_restore.py`); (3)
+removal near threshold is seed-non-deterministic -> FIX the prod seed (kills the
+coin-flip; ship a deterministic certified config).
+
+---
+
+## References
+
+1. Gowal et al. (2025). **SynthID-Image: Image watermarking at internet scale.**
+   arXiv:2510.09263. https://arxiv.org/abs/2510.09263
+
+2. Google DeepMind. **Identifying AI-generated images with SynthID.** Blog post,
+   2023. https://deepmind.google/blog/identifying-ai-generated-images-with-synthid/
+
+3. Google DeepMind. **SynthID.** Product page.
+   https://deepmind.google/models/synthid/
+
+4. Goonatilake & Ateniese (2026). **Removing the Watermark Is Not Enough:
+   Forensic Stealth in Generative-AI Watermark Removal.** arXiv:2605.09203.
+   https://arxiv.org/abs/2605.09203
+
+5. OpenAI. **Verify tool for AI-generated images.** openai.com/research/verify.
+   Accessed 2026-05-31.

docs/text-protection-research.md

@@ -0,0 +1,140 @@
+# Text protection research: crisp text under a "watermark removed everywhere" constraint
+
+Date: 2026-05-29. Source: a deep-research run (104 agents, 5 search angles, sources
+fetched and 3-vote adversarially verified). Not committed automatically — saved as a
+research note for the next session.
+
+## The constraint that frames everything
+
+The invisible watermark (Google SynthID) must be removed **everywhere, including inside
+text regions**. Therefore any technique that keeps or composites the **original
+(watermarked) text pixels** is disqualified — the text must be *regenerated / freshly
+synthesized* enough to scrub the watermark, yet rendered crisply. This single rule is the
+filter applied to every candidate below.
+
+## Problem recap
+
+The `invisible` pipeline is SDXL base 1.0 img2img to defeat SynthID. The default
+strength has risen over time as Google hardens SynthID (0.05 -> 0.10 -> **~0.30**, the
+current threshold for fresh Gemini output); higher strength deforms text more, which is
+exactly why text protection matters. Text is protected via Differential Diffusion with a
+per-pixel change map (`preserve` ~0.9) driven by the PP-OCRv3 DB detector
+(`text_protector.py`). Large text survives; **small text (sub ~8 px strokes) softens or
+garbles** (issue #14, confirmed on real content).
+
+## Executive summary
+
+The fine-text softening is an **architectural consequence of latent-space processing, not
+a tuning problem**: SDXL's 4-channel VAE (~48x compression) discards high-frequency signal
+on encode, and Differential Diffusion blends in latent space with the change map
+downsampled by 8x, so any stroke under ~8 px sits inside one latent cell and cannot be
+preserved or edited cleanly **regardless of `preserve`** (the Differential Diffusion
+authors state this limit explicitly). Two structurally sound directions keep the
+"watermark removed everywhere" guarantee because they **synthesize fresh glyph pixels**
+rather than compositing originals: (1) glyph/text-conditioned diffusion re-render of
+detected text (AnyText2, EasyText), and (2) a two-stage architecture — global scrub, then
+a dedicated text-restoration / text-aware super-resolution pass over detected regions
+(TIGER, TextSR, TeReDiff/TAIR). **EasyText** and **TextSR** are the most promising for this
+CJK-first pipeline (both multilingual via DiT/ByT5, both regenerate from glyph or
+character-shape priors). The deepest fix — a 16-channel (SD3/FLUX) VAE — materially reduces
+the softening but means switching the base model, not a drop-in VAE swap.
+
+## Constraint reconciliation (important)
+
+The generic research "quick win: bump `preserve` toward 1.0" is **invalid under our hard
+constraint**: raising `preserve` freezes the text region, so SynthID there is **not
+scrubbed**. Likewise, pixel paste-back of the original text is disqualified. The only
+constraint-compatible quick win is **higher resolution / tiled diffusion** (strokes span
+more latent cells, less VAE softening, while the text is still fully regenerated and thus
+scrubbed). The real answer is **regenerate text crisply**, not freeze it.
+
+## Findings (with confidence and sources)
+
+### Finding 1 — confidence: high
+
+**Claim.** The small-text softening is an architectural latent-space limit, not a tuning issue. SDXL's VAE compressively encodes (losing exact color and fine detail on every round-trip), and Differential Diffusion blends in latent space with the change map downsampled to latent resolution (8x), so the method explicitly caps edit/preserve granularity at ~8 px under SD settings. Text strokes below one latent cell cannot be cleanly preserved even at preserve ~0.9.
+
+**Evidence.** Differential Diffusion's paper states a "cap on the resolution of the change map ... can limit the ability to precisely edit small objects (less than 8 pixels for Stable-Diffusion's settings)"; the official SDXL pipeline downsamples the map by `vae_scale_factor=8` and blends `latents = original*mask + latents*(1-mask)` in latent space. The VAE encode is "compressive ... exact color qualities and exact visual fine-details are lost." arXiv:2512.05198 confirms "resizing the pixel mask to latent resolution discards fine structure ... downsamples by 1/8" and that linear latent blending "cannot be pixel-equivalent." Higher compression = more high-frequency loss (arXiv:2305.02541).
+
+**Sources.** https://onlinelibrary.wiley.com/doi/10.1111/cgf.70040 · https://differential-diffusion.github.io/ · https://github.com/exx8/differential-diffusion · https://arxiv.org/abs/2512.05198 · https://omriavrahami.com/blended-latent-diffusion-page/ · https://arxiv.org/pdf/2305.02541
+
+### Finding 2 — confidence: low (do not build on it yet)
+
+**Claim.** Pixel-space differential / blended-latent variants exist as a research direction, but the specific full-resolution-mask solution (PELC/DecFormer, arXiv:2512.05198) was NOT verified to deliver its claimed seam/edge improvements.
+
+**Evidence.** arXiv:2512.05198 argues linear latent blending is not pixel-equivalent and proposes decoder-equivariant compositing; PixPerfect (arXiv:2512.03247) does pixel-space refinement of chromatic shifts at edit boundaries. But the specific PELC full-resolution-mask and DecFormer "53% error reduction" claims were **refuted on adversarial vote (0-3 and 1-2)**. Treat pixel-equivalent latent compositing as an emerging idea to watch, not a production fix.
+
+**Sources.** https://arxiv.org/abs/2512.05198 · https://arxiv.org/abs/2512.03247
+
+### Finding 3 — confidence: high
+
+**Claim.** Glyph/text-conditioned diffusion can re-render detected text as freshly synthesized pixels (not copied), which inherently scrubs any watermark in the text region while rendering glyphs crisply. AnyText/AnyText2 inject text-rendering into a pretrained T2I model and support generation AND editing of existing scene images; multilingual including CJK and English.
+
+**Evidence.** AnyText2 "enables precise control over multilingual text attributes in natural scene image generation and editing" (WriteNet+AttnX); +3.3% (Chinese) / +9.3% (English) accuracy over AnyText v1. AnyText "can be plugged into existing diffusion models ... for rendering or editing text" and synthesizes text latent features through diffusion (fresh pixels), supporting zh/en/ja/ko/ar/bn/hi. **Caveat:** both are SD1.5-based, so NOT a drop-in into the SDXL scrub (separate base model); AnyText's own limitation: "the inpainting manner ... impedes editing quality on small text," and it ranks weak on STRICT (EMNLP 2025) — small-text crispness not guaranteed.
+
+**Sources.** https://github.com/tyxsspa/AnyText2 · https://arxiv.org/abs/2411.15245 · https://arxiv.org/abs/2311.03054
+
+### Finding 4 — confidence: high
+
+**Claim.** EasyText is a strong glyph-conditioned re-render candidate: built on the FLUX-dev DiT framework with LoRA tuning, renders compact per-character glyph patches (64px-high adaptive for alphabetic, 64x64 for logographic) concatenated in latent space, supports 10+ languages including Chinese, Japanese, Korean, Thai, Vietnamese, Greek, and Latin.
+
+**Evidence.** AAAI 2025 + arXiv:2505.24417: "implemented based on the open-source FLUX-dev framework with LoRA-based parameter-efficient tuning," VAE and text encoder frozen, two-stage 512->1024 training. Glyph conditioning via "64-pixel-high images ... adaptive widths for alphabetic; fixed 64x64 for logographic," VAE-encoded and concatenated with denoised latents, "less than one-tenth the spatial size of layout-matching methods." FLUX-based (16-channel VAE, DiT) also sidesteps the SDXL 4-channel wall. Fresh-pixel generation preserves the watermark-removal guarantee. Cyrillic/Arabic crispness not separately benchmarked.
+
+**Sources.** https://arxiv.org/html/2505.24417 · https://ojs.aaai.org/index.php/AAAI/article/view/37697
+
+### Finding 5 — confidence: high
+
+**Claim.** A two-stage "global watermark scrub then text-restoration pass" architecture is validated by recent literature, and the restoration stage can synthesize glyph pixels from priors (no original-pixel reintroduction). TIGER reconstructs stroke geometry then injects it as guidance into full-image super-resolution; TextSR uses a detector + multilingual OCR to regenerate text from character-shape priors; TeReDiff/TAIR couples a jointly-trained text-spotter with diffusion.
+
+**Evidence.** TIGER (arXiv:2510.21590): "a diffusion-based local text refiner ... reconstructing fine-grained stroke geometry ... injected as conditional guidance into the subsequent full-image restoration." TextSR (arXiv:2505.23119, Google): "leverages a text detector ... then employs OCR to extract multilingual text," regenerating from "multilingual character-to-shape diffusion priors" that "produce character shapes solely based on text prompts, even without visual input" — fresh pixels. TAIR/TeReDiff (ICLR 2026): standard restoration "frequently generates plausible but incorrect textures"; TeReDiff feeds text-spotter outputs back as prompts. **Caveat:** TIGER orders text-first then global (reverse of scrub-then-text); these target degraded-input super-resolution, not watermark removal, so the SynthID-scrub of the restoration stage must be verified empirically (the stages are themselves diffusion-based, so fresh-pixel = no SynthID is plausible but unproven here).
+
+**Sources.** https://arxiv.org/html/2510.21590v1 · https://arxiv.org/html/2505.23119v1 · https://cvlab-kaist.github.io/TAIR/ · https://arxiv.org/abs/2506.09993
+
+### Finding 6 — confidence: high
+
+**Claim.** Switching to a 16-channel VAE (SD3/FLUX class) materially reduces small-text/latent softening vs SDXL's 4-channel VAE, but it requires switching the base model — not a drop-in latent swap into an SDXL UNet img2img pipeline. RAE approaches are DiT-native and likewise not drop-in.
+
+**Evidence.** SD3/FLUX moved from 4-channel (48x) to 16-channel (12x) VAEs specifically to preserve fine detail (diffusers Discussion #8713; madebyollin VAE notes; arXiv:2305.02541). RAE (arXiv:2510.11690) "should be the new default for diffusion transformer training" but produces high-dimensional latents needing a DiT wide-DDT head — NOT compatible with an SDXL 4-channel UNet. EasyText shows the practical path: adopt a FLUX-DiT base rather than retrofit SDXL. The VAE upgrade couples to a base-model migration.
+
+**Sources.** https://arxiv.org/abs/2510.11690 · https://arxiv.org/pdf/2305.02541 · https://arxiv.org/html/2505.24417
+
+## Recommendation
+
+Under the hard constraint, the correct architecture is **not "protect text during the
+scrub" (Differential Diffusion)** but **"scrub everywhere, then restore text crisply by
+regeneration"**:
+
+1. Global SDXL scrub with text protection OFF (text region is scrubbed too).
+2. On detected text regions, a **glyph-conditioned restoration** that re-renders the same
+   glyphs as fresh pixels (no original reused).
+
+This is the only path that delivers both "watermark everywhere" and crisp text.
+
+**Top-2 to prototype:**
+- **TextSR** — detector + multilingual OCR + character-shape diffusion priors; closest to
+  the existing detector-driven pipeline.
+- **EasyText** — FLUX-DiT glyph re-render, multilingual incl. CJK; also gets the 16-channel
+  VAE for free.
+
+**Honest costs / unknowns:** this is a re-architecture, not a quick fix. It needs a new
+**OCR-recognition** step (we currently only detect text; we must know *what* to re-render).
+Models are FLUX/DiT-class (heavy) -> serverless GPU. Maturity is research-grade; CJK is
+covered, Cyrillic/Arabic crispness is not separately benchmarked -> a prototype must
+measure real fidelity. The restoration stage being diffusion-based makes "fresh pixels =
+no SynthID" plausible but **must be verified empirically** (run the SynthID oracle on the
+restored output).
+
+**Constraint-compatible quick win to try first:** run the global scrub at **higher
+resolution / tiled** so strokes exceed the latent cell — less softening, full scrub, no
+freezing. Cheap to test; quantify recall/quality vs cost.
+
+**Do not pursue:** raising `preserve` toward 1.0 or pixel paste-back (both leave original
+watermarked pixels in text); PELC/DecFormer pixel-equivalent latent compositing (refuted,
+not production-ready).
+
+## Provenance
+
+Deep-research workflow run `wf_118b9a03-3eb` (2026-05-29). Findings adversarially verified
+(2/3 refutes required to kill a claim). This note records research only; no code change is
+implied until a prototype validates fidelity and the SynthID-scrub guarantee on the
+restored output.

pyproject.toml

@@ -1,30 +1,55 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.6.4"
+version = "0.10.0"
 description = "Remove visible and invisible AI watermarks from images (Gemini / Nano Banana, ChatGPT, Stable Diffusion)"
 readme = "README.md"
 requires-python = ">=3.10"
-license = {text = "MIT"}
+license = {text = "Apache-2.0"}
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
 dependencies = [
     "pillow>=10.0.0",
     "piexif>=1.1.3",
     "numpy>=1.24.0",
     "opencv-python-headless>=4.8.0",
     "click>=8.0.0",
-    "rich>=13.0.0",
     "python-dotenv>=1.0.0",
 ]
 
 [project.optional-dependencies]
 gpu = [
     "torch>=2.0.0",
+    # The default PyPI torch wheel is a CPU/CUDA build. To drive an Intel GPU
+    # (Arc / Data Center) via ``--device xpu`` you need an XPU-enabled torch
+    # from PyTorch's XPU wheel index (Linux/Windows only -- there is no macOS
+    # XPU build). Install that build first, then this extra (torch is then
+    # already satisfied and won't be re-pulled):
+    #   pip install torch --index-url https://download.pytorch.org/whl/xpu
+    #   pip install 'remove-ai-watermarks[gpu]'
+    # uv users can target the ``pytorch-xpu`` index declared under [tool.uv]:
+    #   uv pip install torch --index-url https://download.pytorch.org/whl/xpu
     "diffusers>=0.38.0",
-    "transformers>=4.35.0",
+    # diffusers 0.38's auto-pipeline registry imports ``Qwen3VLForConditional
+    # Generation`` (its ``nucleusmoe_image`` pipeline), which only exists in
+    # transformers 5.x -- so ``from diffusers import AutoPipelineForImage2Image``
+    # fails on transformers 4.x. The real SDXL-loading break was NOT transformers
+    # 5.x but the tokenizers *release candidate* (0.23.0rc0) that the global
+    # ``prerelease = "allow"`` drags in: its CLIP tokenizer raises
+    # ``RobertaProcessing.__new__() got an unexpected keyword argument 'cls'``.
+    # Cap tokenizers to the stable 0.22 line (transformers 5.x accepts
+    # >=0.22,<=0.23.0) so the rc is excluded while SDXL still loads.
+    "transformers>=5,<6",
+    "tokenizers>=0.22,<0.23",
     "accelerate>=0.25.0",
-    "controlnet-aux>=0.0.9",
     "safetensors",
-    "ultralytics>=8.0.0",
-    "color-matcher>=0.5.0",
 ]
 # Open invisible-watermark (imwatermark) decoder for detecting the DWT-DCT
 # watermarks embedded by Stable Diffusion / SDXL / FLUX. Optional because it
@@ -51,6 +76,18 @@ lama = [
     "onnxruntime>=1.16.0",
     "huggingface-hub>=0.20.0",
 ]
+# Optional pre-diffusion super-resolution for small inputs (Real-ESRGAN). Loaded via
+# spandrel (MIT) -- a pure model-loader with NO basicsr dependency (it pulls only
+# torch / torchvision / safetensors / numpy / einops).
+# The Real-ESRGAN weights (BSD-3-Clause) download on first use and are cached; they
+# are never bundled. CPU works but is slow on large inputs -- it is meant for the
+# pre-diffusion upscale of SMALL inputs (and the GPU worker). Guarded by
+# upscaler.is_available(); the default upscaler stays Lanczos (cv2, no deps). The
+# weights are fetched with torch.hub (bundled with spandrel's torch), so no extra
+# download dependency is needed.
+esrgan = [
+    "spandrel>=0.3.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-cov>=4.1.0",
@@ -67,6 +104,15 @@ all = ["remove-ai-watermarks[gpu,detect,trustmark,lama,dev]"]
 [tool.uv]
 prerelease = "allow"
 
+# PyTorch Intel-GPU (XPU) wheel index. ``explicit = true`` keeps it inert for
+# the default CPU/CUDA install: uv consults it only when a torch install
+# explicitly targets it (see the ``gpu`` extra comment), so it does not alter
+# the locked CPU/CUDA resolution. Linux/Windows only -- no macOS XPU build.
+[[tool.uv.index]]
+name = "pytorch-xpu"
+url = "https://download.pytorch.org/whl/xpu"
+explicit = true
+
 [project.scripts]
 remove-ai-watermarks = "remove_ai_watermarks.cli:main"
 
@@ -74,12 +120,30 @@ remove-ai-watermarks = "remove_ai_watermarks.cli:main"
 Repository = "https://github.com/wiltodelta/remove-ai-watermarks"
 
 [build-system]
-requires = ["hatchling"]
+# Pin hatchling < 1.31. hatchling 1.30.0 made Metadata-Version 2.5 (PEP 794) the
+# default, which the twine bundled in pypa/gh-action-pypi-publish@release/v1 rejects
+# ("'2.5' is not a valid Metadata-Version"), failing the v0.8.3 PyPI upload
+# (2026-06-01) when unpinned requires = ["hatchling"] pulled 1.30.0. hatchling 1.30.1
+# reverted the default to 2.4 ("kept at 2.4 until more tools support 2.5"), and
+# 1.27-1.29 were always 2.4 -- so < 1.31 keeps `uv build` on a 2.4-emitting hatchling
+# (it resolves to the latest allowed, 1.30.1). The publish workflow now uses
+# `uv publish`, whose uploader accepts 2.5, so this pin is belt-and-suspenders, not
+# load-bearing: keeping it makes the first uv-publish release ship 2.4 metadata
+# (isolating the uploader swap from the metadata-version bump). Drop to
+# `requires = ["hatchling"]` once that release confirms the path.
+requires = ["hatchling<1.31"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/remove_ai_watermarks"]
 
+[tool.hatch.build.targets.sdist]
+# Keep the source distribution small: ship the package + metadata, not the
+# committed test corpora / calibration captures under data/ (tens of MB --
+# synthid_corpus images + the visible-mark captures), which pushed the 0.8.0
+# sdist past PyPI's per-project file-size limit (the wheel ships only src/).
+exclude = ["/data"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
@@ -101,7 +165,6 @@ ignore = [
 "tests/*.py" = ["ANN", "S101", "S105", "S106", "S108"]
 "src/remove_ai_watermarks/noai/watermark_remover.py" = ["S603", "S606", "S607", "T201"]  # subprocess calls for auto-install/CUDA fix
 "src/remove_ai_watermarks/noai/c2pa.py" = ["S110"]  # try-except-pass for corrupt file handling
-"src/remove_ai_watermarks/noai/ctrlregen/engine.py" = ["S101", "S603"]  # assert for loaded state, subprocess for auto-install
 
 [tool.ruff.format]
 quote-style = "double"

scripts/_plain_console.py

@@ -0,0 +1,61 @@
+"""Minimal plain-text stand-ins for the rich Console/Table API.
+
+rich was dropped as a project dependency (see the CLI plain-text refactor), but
+the analysis scripts still printed through it. These shims keep the scripts
+runnable without rich: ``[bold]``/``[/]``-style markup is stripped and tables
+render as aligned plain text. Output goes through ``click.echo`` to match the
+package CLI (no bare ``print`` in tooling).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import click
+
+# Matches rich style tags: the bare close ``[/]`` and named open/close tags such
+# as ``[yellow]``, ``[bold yellow]``, ``[/green]``. Anchored to lowercase-letter
+# starts so numeric/data brackets (``[1024]``, ``[file.png]``) are left intact.
+_MARKUP = re.compile(r"\[(?:/|/?[a-z][a-z ]*)\]")
+
+
+def _strip(obj: Any) -> str:
+    return _MARKUP.sub("", str(obj))
+
+
+class Table:
+    """Drop-in for ``rich.table.Table`` covering add_column/add_row + render."""
+
+    def __init__(self, *args: Any, title: str | None = None, **kwargs: Any) -> None:
+        self.title = title
+        self._headers: list[str] = []
+        self._rows: list[list[str]] = []
+
+    def add_column(self, header: str = "", *args: Any, **kwargs: Any) -> None:
+        self._headers.append(_strip(header))
+
+    def add_row(self, *cells: Any) -> None:
+        self._rows.append([_strip(c) for c in cells])
+
+    def render(self) -> str:
+        all_rows = ([self._headers] if self._headers else []) + self._rows
+        cols = max((len(r) for r in all_rows), default=0)
+        widths = [0] * cols
+        for row in all_rows:
+            for i, cell in enumerate(row):
+                widths[i] = max(widths[i], len(cell))
+        lines: list[str] = []
+        if self.title:
+            lines.append(_strip(self.title))
+        if self._headers:
+            lines.append("  ".join(h.ljust(widths[i]) for i, h in enumerate(self._headers)))
+        lines.extend("  ".join(c.ljust(widths[i]) for i, c in enumerate(row)) for row in self._rows)
+        return "\n".join(lines)
+
+
+class Console:
+    """Drop-in for ``rich.console.Console`` covering ``print`` (with Table)."""
+
+    def print(self, *objects: Any, **kwargs: Any) -> None:
+        click.echo(" ".join(o.render() if isinstance(o, Table) else _strip(o) for o in objects))

scripts/controlnet_sweep.py

@@ -0,0 +1,348 @@
+"""ControlNet-as-removal-pipeline prototype sweep (issue #35 / Jacob).
+
+Research prototype, NOT a shipped pipeline. It tests whether a full-image
+SDXL-native ControlNet-conditioned img2img can REPLACE plain SDXL img2img as the
+watermark remover: a single structure-guided regeneration that scrubs an invisible
+robust watermark (SynthID) everywhere while keeping fine detail and small/CJK text
+legible. See docs/controlnet-removal-pipeline-research.md for the full rationale.
+
+The make-or-break tension (from the watermark-removal-attack literature): the
+denoise strength high enough to scrub the watermark deforms text, while the
+conditioning strong enough to keep text may spare the watermark. There is no local
+SynthID detector, so this script CANNOT decide removal on its own -- it produces
+one output per (control, strength, conditioning-scale) cell plus an index, and YOU
+verify each output by hand in the Gemini app ("Verify with SynthID") and judge text
+legibility visually. Fill the verdict columns in the emitted index, then read off
+the Pareto cell (oracle clean AND text legible).
+
+Pipeline: stabilityai/stable-diffusion-xl-base-1.0 +
+  - canny: xinsir/controlnet-canny-sdxl-1.0  (control = cv2.Canny(gray, 100, 200))
+  - tile:  xinsir/controlnet-tile-sdxl-1.0   (control = the resized original, no preproc)
+StableDiffusionXLControlNetImg2ImgPipeline (image=init, control_image=control).
+
+Needs the gpu extra (torch + diffusers) and cv2. Runs locally on 32 GB MPS in
+fp32 (MPS fp16 decodes to all-black NaN -- issue #29 -- so fp32 is the default on
+mps/cpu, fp16 only on cuda/xpu); a dedicated GPU is not required for 1024 px. Run:
+
+    uv run python scripts/controlnet_sweep.py path/to/watermarked.png -o sweep_out
+    uv run python scripts/controlnet_sweep.py img.png --control canny tile \\
+        --strength 0.3 0.5 0.7 1.0 --scale 0.6 1.0 --size 1024
+"""
+
+from __future__ import annotations
+
+# torch/diffusers/cv2 ship no usable types; relax the unknown-type + private-import
+# rules for this boundary script (mirrors scripts/visible_alpha_solve.py and the
+# cv2/torch engine modules). Pure-logic helpers here stay correct regardless.
+# 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, reportPrivateImportUsage=false
+import argparse
+import contextlib
+import csv
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from _plain_console import Console, Table
+
+if TYPE_CHECKING:
+    from PIL import Image
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+log = logging.getLogger(__name__)
+console = Console()
+
+BASE_MODEL = "stabilityai/stable-diffusion-xl-base-1.0"
+FP16_VAE = "madebyollin/sdxl-vae-fp16-fix"
+CONTROLNETS = {
+    "canny": "xinsir/controlnet-canny-sdxl-1.0",
+    "tile": "xinsir/controlnet-tile-sdxl-1.0",
+}
+
+# A neutral quality prompt: the goal is faithful regeneration, not creative edits.
+PROMPT = "best quality, high quality, sharp, detailed, photographic"
+NEGATIVE_PROMPT = "blurry, lowres, deformed, distorted text, garbled text, watermark, jpeg artifacts"
+
+
+def pick_device(requested: str) -> str:
+    """Resolve the inference device without the CUDA-reinstaller side effect.
+
+    Deliberately does NOT call the package ``get_device`` (which can trigger a
+    torch-CUDA reinstall+restart). A research script should never do that.
+    """
+    import torch
+
+    if requested != "auto":
+        return requested
+    if torch.cuda.is_available():
+        return "cuda"
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def resolve_dtype(device: str, requested: str) -> Any:
+    """fp16 only on cuda/xpu; fp32 on cpu AND mps, unless overridden.
+
+    MPS fp16 produces all-black NaN output here (the SDXL UNet/VAE overflows on
+    the Metal backend -- issue #29; even the fp16-fix VAE does not save it), so the
+    production pipeline runs fp32 on MPS and so do we. fp32 SDXL + an SDXL ControlNet
+    at 1024 fits 32 GB unified memory with vae-tiling + attention-slicing.
+    """
+    import torch
+
+    if requested == "fp16":
+        return torch.float16
+    if requested == "fp32":
+        return torch.float32
+    return torch.float16 if device in {"cuda", "xpu"} else torch.float32
+
+
+def fit_size(image: Image.Image, long_side: int) -> Image.Image:
+    """Resize so the long side is ``long_side``, each dim a multiple of 8 (SDXL)."""
+    from PIL import Image as PILImage
+
+    w, h = image.size
+    scale = long_side / max(w, h)
+    nw = max(8, round(w * scale) // 8 * 8)
+    nh = max(8, round(h * scale) // 8 * 8)
+    if (nw, nh) == (w, h):
+        return image
+    return image.resize((nw, nh), PILImage.Resampling.LANCZOS)
+
+
+def make_control_image(init: Image.Image, control: str) -> Image.Image:
+    """Build the ControlNet conditioning image for the given control type.
+
+    canny: cv2.Canny(gray, 100, 200) -> 3-channel edge map (xinsir canny recipe).
+    tile:  the init image itself, no preprocessing (xinsir tile recipe).
+    """
+    import cv2
+    import numpy as np
+    from PIL import Image as PILImage
+
+    if control == "tile":
+        return init
+    rgb = np.array(init.convert("RGB"))
+    gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+    edges = cv2.Canny(gray, 100, 200)
+    edges_rgb = np.stack([edges, edges, edges], axis=-1)
+    return PILImage.fromarray(edges_rgb)
+
+
+def psnr(a: Image.Image, b: Image.Image) -> float:
+    """Coarse global fidelity proxy vs the original (NOT a text or watermark metric)."""
+    import numpy as np
+
+    x = np.asarray(a.convert("RGB"), dtype=np.float64)
+    y = np.asarray(b.convert("RGB").resize(a.size), dtype=np.float64)
+    mse = float(np.mean((x - y) ** 2))
+    if mse == 0.0:
+        return 99.0
+    return float(10.0 * np.log10((255.0**2) / mse))
+
+
+def load_pipeline(control: str, device: str, dtype: Any) -> Any:
+    """Load SDXL base + the chosen SDXL ControlNet as an img2img pipeline."""
+    import torch
+    from diffusers import (
+        AutoencoderKL,
+        ControlNetModel,
+        StableDiffusionXLControlNetImg2ImgPipeline,
+    )
+
+    console.print(f"Loading {CONTROLNETS[control]} ({control}) ...")
+    controlnet = ControlNetModel.from_pretrained(CONTROLNETS[control], torch_dtype=dtype)
+    load_kwargs: dict[str, Any] = {"controlnet": controlnet, "torch_dtype": dtype}
+    if dtype == torch.float16:
+        # The stock SDXL VAE decodes to NaN/black in fp16; the fp16-fix VAE is the
+        # same swap the production pipeline uses (_SDXL_FP16_VAE_ID).
+        load_kwargs["vae"] = AutoencoderKL.from_pretrained(FP16_VAE, torch_dtype=dtype)
+    pipe = StableDiffusionXLControlNetImg2ImgPipeline.from_pretrained(BASE_MODEL, **load_kwargs)
+    pipe = pipe.to(device)
+    pipe.set_progress_bar_config(disable=True)
+    if device != "cpu":
+        # Keep the 1024 px + extra-ControlNet peak inside 32 GB unified memory.
+        with contextlib.suppress(Exception):
+            pipe.enable_vae_tiling()
+        with contextlib.suppress(Exception):
+            pipe.enable_attention_slicing()
+    return pipe
+
+
+def run_cell(
+    pipe: Any,
+    init: Image.Image,
+    control_image: Image.Image,
+    strength: float,
+    scale: float,
+    steps: int,
+    guidance: float,
+    seed: int,
+) -> Image.Image:
+    """Run one ControlNet img2img cell and return the regenerated image.
+
+    The generator is created on CPU intentionally: a CPU generator is portable
+    across the mps/cuda/cpu backends (diffusers rejects a device-mismatched one),
+    matching the production runner's fallback behavior.
+    """
+    import torch
+
+    generator = torch.Generator(device="cpu").manual_seed(seed)
+    result = pipe(
+        prompt=PROMPT,
+        negative_prompt=NEGATIVE_PROMPT,
+        image=init,
+        control_image=control_image,
+        controlnet_conditioning_scale=float(scale),
+        strength=float(strength),
+        num_inference_steps=steps,
+        guidance_scale=guidance,
+        generator=generator,
+    )
+    return result.images[0]
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="ControlNet-as-removal-pipeline prototype sweep.")
+    p.add_argument("image", type=Path, help="Watermarked input image.")
+    p.add_argument("-o", "--out", type=Path, default=Path("controlnet_sweep_out"), help="Output directory.")
+    p.add_argument("--control", nargs="+", choices=list(CONTROLNETS), default=["canny", "tile"])
+    p.add_argument("--strength", nargs="+", type=float, default=[0.3, 0.5, 0.7, 1.0])
+    p.add_argument("--scale", nargs="+", type=float, default=[0.6, 1.0], help="controlnet_conditioning_scale values.")
+    p.add_argument("--size", type=int, default=1024, help="Long-side resolution (multiple of 8).")
+    p.add_argument("--steps", type=int, default=30)
+    p.add_argument("--guidance", type=float, default=7.5)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--device", default="auto", choices=["auto", "mps", "cuda", "cpu"])
+    p.add_argument("--dtype", default="auto", choices=["auto", "fp16", "fp32"])
+    return p.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if not args.image.exists():
+        log.error("Input image not found: %s", args.image)
+        return 1
+
+    try:
+        from PIL import Image as PILImage
+    except ImportError:
+        log.error("Pillow is required. Install the gpu extra: uv sync --extra gpu --extra dev")
+        return 1
+    if importlib.util.find_spec("diffusers") is None or importlib.util.find_spec("torch") is None:
+        log.error("diffusers/torch are required. Install: uv sync --extra gpu --extra dev")
+        return 1
+
+    device = pick_device(args.device)
+    dtype = resolve_dtype(device, args.dtype)
+    console.print(f"Device: {device} | dtype: {str(dtype).split('.')[-1]}")
+
+    init_full = PILImage.open(args.image).convert("RGB")
+    init = fit_size(init_full, args.size)
+    console.print(f"Input: {args.image.name} {init_full.size[0]}x{init_full.size[1]} -> {init.size[0]}x{init.size[1]}")
+
+    args.out.mkdir(parents=True, exist_ok=True)
+    stem = args.image.stem
+    init_path = args.out / f"{stem}__INPUT.png"
+    init.save(init_path)
+
+    rows: list[dict[str, Any]] = []
+    table = Table(title="ControlNet sweep")
+    for col in ("control", "strength", "scale", "psnr_vs_input", "file"):
+        table.add_column(col)
+
+    # Group by control so SDXL + the ControlNet load once per control type.
+    for control in args.control:
+        pipe = load_pipeline(control, device, dtype)
+        control_image = make_control_image(init, control)
+        if control == "canny":
+            control_image.save(args.out / f"{stem}__canny_edges.png")
+        for strength in args.strength:
+            for scale in args.scale:
+                tag = f"{control}_s{strength:g}_c{scale:g}"
+                console.print(f"Running {tag} ...")
+                try:
+                    out = run_cell(
+                        pipe,
+                        init,
+                        control_image,
+                        strength,
+                        scale,
+                        args.steps,
+                        args.guidance,
+                        args.seed,
+                    )
+                except Exception as exc:
+                    log.warning("Cell %s failed: %s", tag, exc)
+                    continue
+                fname = f"{stem}__{tag}.png"
+                out.save(args.out / fname)
+                quality = psnr(init, out)
+                rows.append(
+                    {
+                        "control": control,
+                        "strength": strength,
+                        "scale": scale,
+                        "psnr_vs_input": round(quality, 2),
+                        "file": fname,
+                        "synthid_oracle": "",  # fill: clean / present
+                        "text_legible": "",  # fill: yes / no / partial
+                    }
+                )
+                table.add_row(control, f"{strength:g}", f"{scale:g}", f"{quality:.2f}", fname)
+        del pipe
+        _free_memory(device)
+
+    _write_index(args.out, stem, rows, init_path.name)
+    console.print(table)
+    console.print(f"\nWrote {len(rows)} cells to {args.out}/")
+    console.print(f"Next: open {args.out}/sweep_index.csv, run each PNG through the Gemini SynthID oracle,")
+    console.print("fill synthid_oracle (clean/present) + text_legible (yes/no/partial), find the Pareto cell.")
+    return 0
+
+
+def _free_memory(device: str) -> None:
+    import gc
+
+    gc.collect()
+    with contextlib.suppress(Exception):
+        import torch
+
+        if device == "cuda":
+            torch.cuda.empty_cache()
+        elif device == "mps" and hasattr(torch, "mps"):
+            torch.mps.empty_cache()
+
+
+def _write_index(out: Path, stem: str, rows: list[dict[str, Any]], input_name: str) -> None:
+    """Write the CSV index (with empty verdict columns) and a README."""
+    fields = ["control", "strength", "scale", "psnr_vs_input", "file", "synthid_oracle", "text_legible"]
+    with (out / "sweep_index.csv").open("w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=fields)
+        writer.writeheader()
+        writer.writerows(rows)
+    readme = (
+        f"# ControlNet sweep for {stem}\n\n"
+        f"Input (resized): {input_name}\n\n"
+        "Each row in sweep_index.csv is one (control, strength, scale) cell. PSNR vs the\n"
+        "resized input is a COARSE global-fidelity proxy only -- it does NOT measure text\n"
+        "legibility or watermark presence. Decide those two by hand:\n\n"
+        "1. synthid_oracle: open the PNG in the Gemini app, 'Verify with SynthID'. Mark\n"
+        "   'clean' if no SynthID is detected, 'present' if it still is. (No local detector\n"
+        "   exists; this manual check is the only valid SynthID oracle.)\n"
+        "2. text_legible: eyeball the small/CJK text. Mark yes / partial / no.\n\n"
+        "The Pareto cell is the one where synthid_oracle=clean AND text_legible=yes at the\n"
+        "lowest strength. If no cell satisfies both, the canny/tile-ControlNet middle path\n"
+        "is dead for text and a glyph re-render is required (see\n"
+        "docs/text-protection-research.md). Record the outcome in\n"
+        "docs/controlnet-removal-pipeline-research.md.\n"
+    )
+    (out / "sweep_README.md").write_text(readme, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/corpus_gap_scan.py

@@ -0,0 +1,214 @@
+"""Audit a local image corpus against the library's own ``identify`` detector.
+
+Two jobs in one pass:
+
+1. **Report** -- run ``identify`` over every image and write one CSV row per file
+   (verdict, platform, confidence, watermarks, signals, integrity clashes).
+2. **Gap audit** -- for every ``unknown``-verdict file, scan only its *metadata
+   region* (PNG text/eXIf chunks, JPEG APPn segments before SOS, or the file
+   head for other containers) for known provenance markers. A marker found there
+   on a file the detector calls ``unknown`` is a concrete lib gap: a serialization
+   or generator we do not yet parse. Scanning the metadata region -- not the whole
+   file -- is deliberate: short tokens collide randomly inside compressed PNG
+   ``IDAT`` / JPEG scan data, which produced false "xAI/Flux/AIGC" hits when the
+   first audit naively scanned the first megabyte.
+
+This is how new detector gaps get found (it is what surfaced the JPEG-EXIF
+``{"AIGC":{...}}`` form). Re-run after collecting a fresh corpus batch.
+
+Usage:
+    uv run python scripts/corpus_gap_scan.py --corpus data/spaces/originals
+    uv run python scripts/corpus_gap_scan.py --corpus data/spaces/originals \\
+        --report data/spaces/detector_report.csv
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+from collections import Counter
+from pathlib import Path
+
+import click
+from _plain_console import Console, Table
+
+from remove_ai_watermarks.identify import identify
+from remove_ai_watermarks.metadata import _png_late_metadata
+
+log = logging.getLogger(__name__)
+console = Console()
+
+# Distinctive, multi-byte provenance markers worth flagging when they appear in a
+# file the detector calls `unknown`. Kept long enough that a random collision in a
+# (non-scanned) compressed stream is implausible; the metadata-region restriction
+# below is the primary guard, this list is the second. Group: C2PA/JUMBF infra,
+# AI source-type / labeling schemes, and distinctive generator name strings.
+MARKERS: tuple[bytes, ...] = (
+    # C2PA / JUMBF infrastructure and AI source-type / labeling schemes.
+    b"c2pa",
+    b"jumbf",
+    b"contentauth",
+    b"trainedAlgorithmicMedia",
+    b"digitalSourceType",
+    b'"AIGC"',
+    b"<TC260:AIGC>",
+    b"TC260:AIGC",
+    b"tc260.org.cn",
+    b"AISystemUsed",
+    b"SynthID",
+    b"hf-job-id",
+    b"genAIType",
+    b"PhotoEditor_Re_Edit",
+    b"Signature:",
+    # Distinctive multi-word generator strings only. Bare single words (Luma,
+    # Gemini, Sora, ...) are omitted: they collide with unrelated metadata prose
+    # (e.g. "Luma" in Lightroom's EnhanceDenoiseLumaAmount), defeating precision.
+    b"Midjourney",
+    b"Stable Diffusion",
+    b"StableDiffusion",
+    b"ComfyUI",
+    b"Automatic1111",
+    b"DALL-E",
+    b"Ideogram AI",
+    b"Adobe Firefly",
+    b"Black Forest",
+    b"volcengine",
+    b"Doubao",
+    b"\xe8\xb1\x86\xe5\x8c\x85",
+    b"Nano Banana",
+    b"Stability AI",
+    b"Samsung Galaxy",
+)
+
+
+def _metadata_region(path: Path) -> bytes:
+    """Return only the bytes where provenance metadata can live, never the
+    compressed pixel stream (which produces random short-token collisions)."""
+    try:
+        head = path.read_bytes()
+    except OSError:
+        return b""
+    if head[:8] == b"\x89PNG\r\n\x1a\n":
+        # All ancillary metadata chunks (window=0), via the library's own walker.
+        return _png_late_metadata(path, 0)
+    if head[:2] == b"\xff\xd8":  # JPEG: APPn segments up to Start-Of-Scan
+        out = bytearray()
+        p = 2
+        n = len(head)
+        while p + 4 <= n and head[p] == 0xFF:
+            marker = head[p + 1]
+            if marker == 0xDA:  # SOS -> compressed scan data follows
+                break
+            seg_len = (head[p + 2] << 8) | head[p + 3]
+            out += head[p + 4 : p + 2 + seg_len]
+            p += 2 + seg_len
+        return bytes(out)
+    return head[:65536]  # webp/avif/heif/jxl: metadata sits near the head
+
+
+def _row(rep) -> dict[str, str]:  # noqa: ANN001 (ProvenanceReport)
+    return {
+        "path": "",  # filled by caller (relative)
+        "is_ai": str(rep.is_ai_generated),
+        "platform": rep.platform or "",
+        "confidence": rep.confidence,
+        "watermarks": "|".join(rep.watermarks),
+        "signals": "|".join(s.name for s in rep.signals),
+        "integrity_clashes": "|".join(rep.integrity_clashes),
+    }
+
+
+@click.command()
+@click.option(
+    "--corpus",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path("data/spaces/originals"),
+    show_default=True,
+    help="Directory of images to scan (recursively).",
+)
+@click.option(
+    "--report",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Write the per-file CSV here (default: <corpus>/../detector_report.csv).",
+)
+@click.option("--limit", type=int, default=0, help="Scan at most N files (0 = all).")
+def main(corpus: Path, report: Path | None, limit: int) -> None:
+    logging.basicConfig(level=logging.WARNING, format="%(message)s")
+    report = report or corpus.parent / "detector_report.csv"
+
+    files = sorted(p for p in corpus.rglob("*") if p.is_file())
+    if limit:
+        files = files[:limit]
+    console.print(f"Scanning [bold]{len(files)}[/bold] files under {corpus} ...")
+
+    verdicts: Counter[str] = Counter()
+    platforms: Counter[str] = Counter()
+    gap_tokens: Counter[str] = Counter()
+    gaps: list[tuple[str, list[str]]] = []
+    rows: list[dict[str, str]] = []
+    errors = 0
+
+    with click.progressbar(files, label="identify") as bar:
+        for p in bar:
+            rel = str(p.relative_to(corpus))
+            try:
+                rep = identify(p)
+            except Exception as exc:
+                log.warning("identify failed on %s: %s", rel, exc)
+                errors += 1
+                continue
+            row = _row(rep)
+            row["path"] = rel
+            rows.append(row)
+            if rep.is_ai_generated:
+                verdicts["ai"] += 1
+                platforms[rep.platform or "?"] += 1
+                continue
+            verdicts["unknown"] += 1
+            # A gap candidate is a file identify is *blind* to (no signal at all)
+            # yet whose metadata carries a known marker. A file that produced a
+            # signal but no AI verdict (e.g. an ASUS Gallery C2PA signer, which we
+            # attribute but do not call AI) is handled correctly -- not a gap.
+            if rep.signals:
+                continue
+            region = _metadata_region(p)
+            hits = sorted({m.decode("latin-1", "replace") for m in MARKERS if m in region})
+            if hits:
+                gaps.append((rel, hits))
+                gap_tokens.update(hits)
+
+    with report.open("w", newline="") as f:
+        writer = csv.DictWriter(
+            f,
+            fieldnames=["path", "is_ai", "platform", "confidence", "watermarks", "signals", "integrity_clashes"],
+        )
+        writer.writeheader()
+        writer.writerows(rows)
+    console.print(f"\nWrote [bold]{len(rows)}[/bold] rows -> {report}")
+
+    console.print(f"\n[bold]Verdicts:[/bold] AI {verdicts['ai']} | unknown {verdicts['unknown']} | errors {errors}")
+    plat = Table(title="AI platforms", show_header=False)
+    for name, n in platforms.most_common():
+        plat.add_row(str(n), name)
+    console.print(plat)
+
+    if gaps:
+        console.print(
+            f"\n[bold red]Gap candidates[/bold red]: {len(gaps)} unknown files carry a known "
+            f"marker in their metadata region (potential undetected serialization/generator):"
+        )
+        tok = Table(title="markers seen in unknown files")
+        tok.add_column("count", justify="right")
+        tok.add_column("marker")
+        for name, n in gap_tokens.most_common():
+            tok.add_row(str(n), name)
+        console.print(tok)
+        for rel, hits in gaps:
+            console.print(f"  {rel}  ->  {', '.join(hits)}")
+    else:
+        console.print("\n[green]No gap candidates: every unknown file is metadata-free.[/green]")
+
+
+if __name__ == "__main__":
+    main()

scripts/invisible_quality_audit.py

@@ -0,0 +1,117 @@
+"""Audit invisible-removal output quality by pairing originals with cleaned outputs.
+
+The spaces routine writes ``<hash>_src.<ext>`` originals and ``<hash>_clean.<ext>``
+cleaned outputs. For each pair this computes a structural-similarity score plus
+cheap content proxies (detail via Laplacian variance, resolution, aspect), so the
+WORST-preserved images can be surfaced and then visually classified.
+
+SSIM alone does NOT equal "bad": a high-texture image legitimately changes under
+the SDXL scrub. Use the ranked output to pick candidates, then look at them to
+name the failure classes (garbled text, deformed faces, over-smoothed detail).
+
+Operates on gitignored data only (data/spaces/...); writes nothing tracked.
+
+    uv run python scripts/invisible_quality_audit.py \
+        --originals data/spaces/originals/2026-06-03 \
+        --cleaned   data/spaces/results/2026-06-03 \
+        --out data/spaces/_quality_audit.csv --worst 25
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+from pathlib import Path
+
+import click
+import cv2
+import numpy as np
+
+from remove_ai_watermarks import image_io
+
+log = logging.getLogger(__name__)
+
+
+def _ssim(a: np.ndarray, b: np.ndarray) -> float:
+    """Grayscale SSIM (single-window Gaussian, the Wang et al. formulation)."""
+    a = a.astype(np.float64)
+    b = b.astype(np.float64)
+    c1, c2 = (0.01 * 255) ** 2, (0.03 * 255) ** 2
+    k = (11, 11)
+    mu_a = cv2.GaussianBlur(a, k, 1.5)
+    mu_b = cv2.GaussianBlur(b, k, 1.5)
+    mu_a2, mu_b2, mu_ab = mu_a * mu_a, mu_b * mu_b, mu_a * mu_b
+    sa = cv2.GaussianBlur(a * a, k, 1.5) - mu_a2
+    sb = cv2.GaussianBlur(b * b, k, 1.5) - mu_b2
+    sab = cv2.GaussianBlur(a * b, k, 1.5) - mu_ab
+    ssim_map = ((2 * mu_ab + c1) * (2 * sab + c2)) / ((mu_a2 + mu_b2 + c1) * (sa + sb + c2))
+    return float(ssim_map.mean())
+
+
+def _stem(name: str) -> str:
+    """Strip the _src/_clean suffix and extension to get the pairing key."""
+    base = name.rsplit(".", 1)[0]
+    for suf in ("_src", "_clean"):
+        if base.endswith(suf):
+            return base[: -len(suf)]
+    return base
+
+
+@click.command()
+@click.option("--originals", type=click.Path(exists=True, file_okay=False, path_type=Path), required=True)
+@click.option("--cleaned", type=click.Path(exists=True, file_okay=False, path_type=Path), required=True)
+@click.option("--out", type=click.Path(path_type=Path), default=Path("data/spaces/_quality_audit.csv"))
+@click.option("--worst", type=int, default=25, help="Print the N lowest-SSIM pairs.")
+def main(originals: Path, cleaned: Path, out: Path, worst: int) -> None:
+    logging.basicConfig(level=logging.WARNING, format="%(message)s")
+    src_by_key = {_stem(p.name): p for p in originals.iterdir() if p.is_file()}
+    clean_by_key = {_stem(p.name): p for p in cleaned.iterdir() if p.is_file()}
+    keys = sorted(src_by_key.keys() & clean_by_key.keys())
+    click.echo(f"Pairs: {len(keys)} ({len(src_by_key)} src, {len(clean_by_key)} clean)")
+
+    rows: list[dict[str, str]] = []
+    with click.progressbar(keys, label="ssim") as bar:
+        for key in bar:
+            a = image_io.imread(src_by_key[key], cv2.IMREAD_COLOR)
+            b = image_io.imread(clean_by_key[key], cv2.IMREAD_COLOR)
+            if a is None or b is None:
+                continue
+            if a.shape[:2] != b.shape[:2]:
+                b = cv2.resize(b, (a.shape[1], a.shape[0]), interpolation=cv2.INTER_LANCZOS4)
+            ga = cv2.cvtColor(a, cv2.COLOR_BGR2GRAY)
+            gb = cv2.cvtColor(b, cv2.COLOR_BGR2GRAY)
+            h, w = ga.shape
+            rows.append(
+                {
+                    "key": key,
+                    "ssim": f"{_ssim(ga, gb):.4f}",
+                    "laplacian_var": f"{cv2.Laplacian(ga, cv2.CV_64F).var():.1f}",
+                    "width": str(w),
+                    "height": str(h),
+                    "megapixels": f"{w * h / 1e6:.2f}",
+                    "aspect": f"{w / h:.2f}",
+                }
+            )
+
+    rows.sort(key=lambda r: float(r["ssim"]))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with out.open("w", newline="") as f:
+        wtr = csv.DictWriter(f, fieldnames=["key", "ssim", "laplacian_var", "width", "height", "megapixels", "aspect"])
+        wtr.writeheader()
+        wtr.writerows(rows)
+
+    ssims = [float(r["ssim"]) for r in rows]
+    if ssims:
+        arr = np.array(ssims)
+        click.echo(f"\nSSIM mean={arr.mean():.3f} p10={np.percentile(arr, 10):.3f} min={arr.min():.3f}")
+        click.echo(f"Pairs with SSIM < 0.70: {(arr < 0.70).sum()}  | < 0.60: {(arr < 0.60).sum()}")
+        click.echo(f"\nWorst {worst} (lowest SSIM):")
+        for r in rows[:worst]:
+            click.echo(
+                f"  ssim={r['ssim']}  lap={r['laplacian_var']:>8}  {r['megapixels']}MP {r['aspect']}  {r['key']}"
+            )
+    click.echo(f"\nReport: {out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/synthid_corpus.py

@@ -26,9 +26,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 import click
+from _plain_console import Console, Table
 from PIL import Image
-from rich.console import Console
-from rich.table import Table
 
 from remove_ai_watermarks.noai.c2pa import extract_c2pa_info
 

scripts/synthid_pixel_probe.py

@@ -30,8 +30,8 @@ from typing import TYPE_CHECKING
 
 import click
 import numpy as np
+from _plain_console import Console
 from PIL import Image
-from rich.console import Console
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray

scripts/visible_alpha_solve.py

@@ -0,0 +1,271 @@
+"""Rebuild the visible-watermark alpha assets from controlled captures.
+
+The committed, reproducible build of the bundled visible-mark assets -- the inputs
+live in ``data/<engine>_capture/captures/`` (committed solid-colour captures run
+through the generator). Re-run after re-capturing.
+
+**Doubao "豆包AI生成" strip and Jimeng "★ 即梦AI" wordmark** are fixed
+semi-transparent white overlays; the asset is their recovered per-pixel alpha map
+(``assets/<engine>_alpha.png``). The "careful" solve (issue #13) -- a naive build
+(max-over-channels, coarse background, blur, truncated halo, or a black-dominated
+least-squares fit) leaves a visible outline because the alpha is wrong at the glyph
+edges:
+
+1. Locate the mark on the BLACK capture (bright pixels in the bottom-right).
+2. Fit a smooth CUBIC background per channel over the GRAY capture's non-glyph
+   pixels (a cubic captures the gentle gradient without bleeding glyph values).
+3. Solve ``a = (I - B) / (255 - B)`` on the gray capture, AVERAGED over channels,
+   at FULL halo extent (down to a~0.02) and UNBLURRED. Gray (background ~130-200)
+   is the reference because the mark sits on bright photo content in real use, not
+   on black; the white capture only confirms the logo is white.
+
+**Gemini sparkle** is a different type: a single icon stamped on PURE BLACK, so the
+engine reads ``alpha = max(R,G,B)/255`` directly (no background fit). Its assets are
+the sparkle-on-black capture cropped to two fixed logo sizes (``gemini_bg_{96,48}.png``).
+
+Usage::
+
+    uv run python scripts/visible_alpha_solve.py doubao
+    uv run python scripts/visible_alpha_solve.py jimeng
+    uv run python scripts/visible_alpha_solve.py gemini
+    uv run python scripts/visible_alpha_solve.py all
+"""
+
+# cv2/numpy boundary: third-party libs ship no usable element types; relax the
+# unknown-type rules for this file only (mirrors the engine modules).
+# 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
+from __future__ import annotations
+
+import logging
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from remove_ai_watermarks import image_io
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+log = logging.getLogger(__name__)
+
+_ROOT = Path(__file__).resolve().parents[1]
+
+
+@dataclass(frozen=True)
+class EngineSpec:
+    """Per-engine capture inputs and the alpha asset to rebuild."""
+
+    name: str
+    capture_dir: Path
+    black: str
+    gray: str
+    asset: Path
+    native_width: int = 2048
+    corner: str = "br"  # which corner the mark sits in: "br" (Doubao/Jimeng) or "bl" (Samsung)
+
+
+_SPECS: dict[str, EngineSpec] = {
+    "doubao": EngineSpec(
+        "doubao",
+        _ROOT / "data" / "doubao_capture" / "captures",
+        "doubao_black_1x1_1.png",
+        "doubao_gray_1x1_1.png",
+        _ROOT / "src" / "remove_ai_watermarks" / "assets" / "doubao_alpha.png",
+    ),
+    "jimeng": EngineSpec(
+        "jimeng",
+        _ROOT / "data" / "jimeng_capture" / "captures",
+        "jimeng_cap_A.png",  # black seed
+        "jimeng_cap_C.png",  # gray seed
+        _ROOT / "src" / "remove_ai_watermarks" / "assets" / "jimeng_alpha.png",
+    ),
+    "samsung": EngineSpec(
+        "samsung",
+        _ROOT / "data" / "samsung_capture" / "captures",
+        "samsung_black_1.png",  # black flat edit (mark on true black, bottom-left)
+        "samsung_gray_1.png",  # gray flat edit
+        _ROOT / "src" / "remove_ai_watermarks" / "assets" / "samsung_alpha.png",
+        # The flat captures arrive at the phone's flat-edit size (1086 wide); the
+        # mark is a fixed FRACTION of width (~0.31), consistent with the 2958-wide
+        # real photos, so geometry is emitted relative to the capture width.
+        native_width=1086,
+        corner="bl",
+    ),
+}
+
+_CUBIC_BG_PAD = 30  # px of background margin around the mark for the cubic fit
+_GLYPH_BODY = 0.08  # alpha above this is the solid glyph body (for the bbox)
+_MIN_PART_AREA = 25  # drop connected glyph-mask blobs smaller than this (cubic-fit specks)
+_HALO_PAD = 7  # keep this many px of halo around the glyph body in the saved asset
+
+# Gemini is a different watermark TYPE: a single sparkle icon stamped on a
+# PURE-BLACK background (so the engine reads alpha = max(R,G,B)/255 directly, no
+# background fit). Its assets are the sparkle-on-black CAPTURE at two fixed logo
+# sizes (the engine interpolates between them), not an alpha map.
+_GEMINI_CAPTURE = _ROOT / "data" / "gemini_capture" / "captures" / "gemini_black_2048.png"
+_GEMINI_ASSETS: dict[int, Path] = {
+    96: _ROOT / "src" / "remove_ai_watermarks" / "assets" / "gemini_bg_96.png",
+    48: _ROOT / "src" / "remove_ai_watermarks" / "assets" / "gemini_bg_48.png",
+}
+
+
+def _union_bbox(mask: NDArray[np.uint8], err: str) -> tuple[int, int, int, int]:
+    """Union bbox ``(x0, x1, y0, y1)`` of ``mask``'s connected components with area
+    >= ``_MIN_PART_AREA``. The mark is several separate glyphs, so the union spans
+    the whole word while a stray small speck/blotch is dropped by the area filter.
+    Raises ``ValueError(err)`` if nothing qualifies."""
+    n, _labels, stats, _c = cv2.connectedComponentsWithStats(mask, connectivity=8)
+    parts = [i for i in range(1, n) if stats[i, cv2.CC_STAT_AREA] >= _MIN_PART_AREA]
+    if not parts:
+        raise ValueError(err)
+    x0 = min(int(stats[i, cv2.CC_STAT_LEFT]) for i in parts)
+    y0 = min(int(stats[i, cv2.CC_STAT_TOP]) for i in parts)
+    x1 = max(int(stats[i, cv2.CC_STAT_LEFT] + stats[i, cv2.CC_STAT_WIDTH]) for i in parts)
+    y1 = max(int(stats[i, cv2.CC_STAT_TOP] + stats[i, cv2.CC_STAT_HEIGHT]) for i in parts)
+    return x0, x1, y0, y1
+
+
+def _locate_on_black(black: NDArray[np.float32], corner: str = "br") -> tuple[int, int, int, int]:
+    """Bounding box of the white mark on the black capture, in the given corner.
+
+    Thresholds well above the blotchy near-black background, then unions the
+    sufficiently-large bright components so the box spans the whole word. ``corner``
+    is ``"br"`` (bottom-right, Doubao/Jimeng) or ``"bl"`` (bottom-left, Samsung).
+    The horizontal window is kept generous (the Samsung text strip is ~0.31 of the
+    width, so a corner *quarter* would clip it) while still excluding any centered
+    generated content the flat edit hallucinated.
+    """
+    h, w = black.shape[:2]
+    lum = black.mean(axis=2)
+    br = lum > 40  # comfortably above the ~5-30 background blotches
+    br[: h * 3 // 4, :] = False  # bottom quarter only
+    if corner == "bl":
+        br[:, w // 2 :] = False  # left half only
+    else:
+        br[:, : w * 3 // 4] = False  # right quarter only
+    bright = cv2.morphologyEx(br.astype(np.uint8) * 255, cv2.MORPH_CLOSE, np.ones((9, 9), np.uint8))
+    return _union_bbox(bright, f"no mark found on the black capture ({corner} corner is empty)")
+
+
+def _cubic_background(crop: NDArray[np.float32], glyph: NDArray[np.bool_]) -> NDArray[np.float32]:
+    """Per-channel cubic surface fit over the non-glyph pixels of ``crop``."""
+    h, w = crop.shape[:2]
+    yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+    yy /= h
+    xx /= w
+    terms = [np.ones_like(xx), xx, yy, xx * xx, xx * yy, yy * yy, xx**3, xx * xx * yy, xx * yy * yy, yy**3]
+    basis = np.stack(terms, axis=-1).reshape(-1, len(terms))
+    keep = (~glyph).reshape(-1)
+    out = np.zeros_like(crop)
+    for ch in range(3):
+        values = crop[..., ch].reshape(-1)
+        coef, *_ = np.linalg.lstsq(basis[keep], values[keep], rcond=None)
+        out[..., ch] = (basis @ coef).reshape(h, w)
+    return out
+
+
+def solve_alpha(spec: EngineSpec) -> NDArray[np.uint8]:
+    """Solve the careful gray-self alpha map for one engine (uint8, a*255)."""
+    black = image_io.imread(str(spec.capture_dir / spec.black), cv2.IMREAD_COLOR)
+    gray = image_io.imread(str(spec.capture_dir / spec.gray), cv2.IMREAD_COLOR)
+    if black is None or gray is None:
+        raise FileNotFoundError(f"missing captures in {spec.capture_dir} (expected {spec.black}, {spec.gray})")
+    black_f = black.astype(np.float32)
+    gray_f = gray.astype(np.float32)
+
+    img_h, img_w = black_f.shape[:2]
+    mx0, mx1, my0, my1 = _locate_on_black(black_f, spec.corner)
+    pad = _CUBIC_BG_PAD
+    rx0, rx1 = max(0, mx0 - pad), min(img_w, mx1 + pad)
+    ry0, ry1 = max(0, my0 - pad), min(img_h, my1 + pad)
+    cg = gray_f[ry0:ry1, rx0:rx1]
+    cb = black_f[ry0:ry1, rx0:rx1]
+
+    glyph = cv2.dilate((cb.mean(axis=2) > 8).astype(np.uint8), np.ones((9, 9), np.uint8)) > 0
+    bg = _cubic_background(cg, glyph)
+    alpha = np.clip((cg - bg).mean(axis=2) / np.clip(255.0 - bg.mean(axis=2), 1e-3, None), 0.0, 1.0)
+
+    # Crop to the UNION of the glyph parts (the mark is several disconnected
+    # glyphs), padded by _HALO_PAD -- this keeps the real anti-aliased halo while
+    # dropping the small cubic-fit specks at the crop edges (< _MIN_PART_AREA) that
+    # a bare a>floor box would otherwise inflate the asset with.
+    body = (alpha > _GLYPH_BODY).astype(np.uint8)
+    bx, bex, by, bey = _union_bbox(body, "solved alpha has no glyph body -- check the gray capture background")
+    cx0 = max(0, bx - _HALO_PAD)
+    cy0 = max(0, by - _HALO_PAD)
+    cx1 = min(alpha.shape[1], bex + _HALO_PAD)
+    cy1 = min(alpha.shape[0], bey + _HALO_PAD)
+    tight = alpha[cy0:cy1, cx0:cx1]
+    aw, ah = tight.shape[1], tight.shape[0]
+    # Absolute asset position in the capture, for the engine's geometry constants.
+    abs_x0, abs_y0 = rx0 + cx0, ry0 + cy0
+    # Horizontal margin depends on the anchor corner: left margin for "bl", right
+    # margin (distance from the right edge) for "br".
+    h_margin = abs_x0 if spec.corner == "bl" else img_w - (abs_x0 + aw)
+    log.info(
+        "%s: alpha %dx%d max %.3f | WIDTH_FRAC %.4f HEIGHT_FRAC %.4f "
+        "MARGIN_%s_FRAC %.4f MARGIN_BOTTOM_FRAC %.4f (native_width %d)",
+        spec.name,
+        aw,
+        ah,
+        float(tight.max()),
+        aw / spec.native_width,
+        ah / spec.native_width,
+        "LEFT" if spec.corner == "bl" else "RIGHT",
+        h_margin / spec.native_width,
+        (img_h - (abs_y0 + ah)) / spec.native_width,
+        spec.native_width,
+    )
+    return (np.clip(tight, 0.0, 1.0) * 255.0).astype(np.uint8)
+
+
+def solve_gemini() -> dict[int, NDArray[np.uint8]]:
+    """Extract the Gemini sparkle-on-black region from the black capture at each
+    bundled logo size (the bg-capture asset format; the engine derives the alpha).
+    Returns ``{size: bgr_image}``."""
+    black = image_io.imread(str(_GEMINI_CAPTURE), cv2.IMREAD_COLOR)
+    if black is None:
+        raise FileNotFoundError(f"missing Gemini capture {_GEMINI_CAPTURE}")
+    h, w = black.shape[:2]
+    bright = np.zeros((h, w), np.uint8)
+    reg = black.astype(np.float32).mean(axis=2) > 60  # sparkle is ~0.5*255 on black
+    reg[: h * 3 // 4, :] = False
+    reg[:, : w * 3 // 4] = False
+    bright[reg] = 255
+    bright = cv2.morphologyEx(bright, cv2.MORPH_CLOSE, np.ones((7, 7), np.uint8))
+    x0, x1, y0, y1 = _union_bbox(bright, "no sparkle found on the Gemini black capture")
+    crop = black[y0:y1, x0:x1]
+    log.info("gemini: sparkle %dx%d at margin_frac %.4f", x1 - x0, y1 - y0, (w - x1) / w)
+    return {size: cv2.resize(crop, (size, size), interpolation=cv2.INTER_AREA) for size in _GEMINI_ASSETS}
+
+
+@click.command()
+@click.argument("engine", type=click.Choice([*_SPECS, "gemini", "all"]))
+def main(engine: str) -> None:
+    """Rebuild the alpha asset(s) for ENGINE (doubao / jimeng / gemini / all)."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    def _write(path: Path, img: NDArray[np.uint8], label: str) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if not image_io.imwrite(str(path), img):
+            raise OSError(f"failed to write {path}")
+        log.info("%s: wrote %s", label, path.relative_to(_ROOT))
+
+    if engine in (*_SPECS, "all"):
+        specs = list(_SPECS.values()) if engine == "all" else [_SPECS[engine]]
+        for spec in specs:
+            _write(spec.asset, solve_alpha(spec), spec.name)
+    if engine in ("gemini", "all"):
+        for size, img in solve_gemini().items():
+            _write(_GEMINI_ASSETS[size], img, f"gemini-{size}")
+
+
+if __name__ == "__main__":
+    main()

scripts/visible_removal_audit.py

@@ -0,0 +1,138 @@
+"""Audit visible-watermark removal over a local image corpus.
+
+For every image the registry detects a known visible mark in, run that mark's
+removal and re-detect on the output, recording before/after confidence and
+whether the detector still fires. Also bucket the detected-positive originals
+into per-mark dataset dirs so the visible-mark corpora are reproducible.
+
+Detector-clean after removal is necessary but, for the Doubao/Jimeng text marks,
+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.
+
+Operates on gitignored data only (data/spaces/...); writes nothing tracked.
+
+    uv run python scripts/visible_removal_audit.py \
+        --corpus data/spaces/originals --out data/spaces/_visible_audit.csv \
+        --dataset-root data/spaces/_visible_datasets
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+import shutil
+from pathlib import Path
+
+import click
+
+from remove_ai_watermarks import image_io
+from remove_ai_watermarks.watermark_registry import detect_marks, get_mark
+
+log = logging.getLogger(__name__)
+
+_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".avif", ".heic"}
+
+
+def _rel(p: Path, corpus: Path) -> str:
+    try:
+        return str(p.relative_to(corpus))
+    except ValueError:
+        return p.name
+
+
+@click.command()
+@click.option(
+    "--corpus", type=click.Path(exists=True, file_okay=False, path_type=Path), default=Path("data/spaces/originals")
+)
+@click.option("--out", type=click.Path(path_type=Path), default=Path("data/spaces/_visible_audit.csv"))
+@click.option("--dataset-root", type=click.Path(path_type=Path), default=Path("data/spaces/_visible_datasets"))
+@click.option(
+    "--paths-file",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    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:
+    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()]
+    else:
+        files = sorted(p for p in corpus.rglob("*") if p.is_file() and p.suffix.lower() in _EXTS)
+    if limit:
+        files = files[:limit]
+    click.echo(f"Scanning {len(files)} files under {corpus} ...")
+
+    rows: list[dict[str, str]] = []
+    n_detected = 0
+    n_clean_after = 0
+    fails: list[tuple[str, str, float]] = []
+
+    with click.progressbar(files, label="audit") as bar:
+        for p in bar:
+            img = image_io.imread(p)
+            if img is None:
+                continue
+            for det in detect_marks(img, include_explicit=False):
+                if not det.detected:
+                    continue
+                n_detected += 1
+                mark = get_mark(det.key)
+                # Bucket the positive original into the per-mark dataset.
+                ddir = dataset_root / det.key
+                ddir.mkdir(parents=True, exist_ok=True)
+                if not (ddir / p.name).exists():
+                    shutil.copy2(p, ddir / p.name)
+                # Remove, then re-detect with the SAME mark's detector.
+                try:
+                    cleaned, _ = mark.remove(img)
+                    after = mark.detect(cleaned)
+                except Exception as exc:
+                    log.warning("remove failed on %s (%s): %s", p.name, det.key, exc)
+                    rows.append(
+                        {
+                            "path": _rel(p, corpus),
+                            "mark": det.key,
+                            "conf_before": f"{det.confidence:.3f}",
+                            "conf_after": "",
+                            "removed": "error",
+                        }
+                    )
+                    continue
+                removed = not after.detected
+                n_clean_after += int(removed)
+                if not removed:
+                    fails.append((_rel(p, corpus), det.key, after.confidence))
+                rows.append(
+                    {
+                        "path": _rel(p, corpus),
+                        "mark": det.key,
+                        "conf_before": f"{det.confidence:.3f}",
+                        "conf_after": f"{after.confidence:.3f}",
+                        "removed": str(removed),
+                    }
+                )
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with out.open("w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=["path", "mark", "conf_before", "conf_after", "removed"])
+        w.writeheader()
+        w.writerows(rows)
+
+    by_mark: dict[str, list[bool]] = {}
+    for r in rows:
+        if r["removed"] in ("True", "False"):
+            by_mark.setdefault(r["mark"], []).append(r["removed"] == "True")
+    click.echo(f"\nDetected positives: {n_detected}; detector-clean after removal: {n_clean_after}")
+    for k, v in sorted(by_mark.items()):
+        click.echo(f"  {k:8} removed {sum(v)}/{len(v)} ({100 * sum(v) // max(1, len(v))}%)")
+    if fails:
+        click.echo(f"\nDetector still fires after removal ({len(fails)}):")
+        for path, key, conf in fails[:30]:
+            click.echo(f"  {key:8} {conf:.3f}  {path}")
+    click.echo(f"\nReport: {out}  |  Datasets: {dataset_root}/<mark>/")
+
+
+if __name__ == "__main__":
+    main()

src/remove_ai_watermarks/__init__.py

@@ -1,3 +1,14 @@
 """Remove-AI-Watermarks: Unified tool for removing visible and invisible AI watermarks."""
 
-__version__ = "0.6.4"
+import os as _os
+import warnings as _warnings
+
+# transformers prints a noisy deprecation for the Siglip2ImageProcessorFast
+# alias when it is imported (by the optional GPU/ML path). Silence it before
+# any submodule pulls transformers in, so the CLI startup stays quiet. Uses
+# setdefault so a user-set TRANSFORMERS_VERBOSITY still wins.
+_os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+_warnings.filterwarnings("ignore", message=r".*ImageProcessorFast.*")
+
+
+__version__ = "0.10.0"

src/remove_ai_watermarks/_text_mark_engine.py

@@ -0,0 +1,349 @@
+"""Shared base for the reverse-alpha visible text-mark engines.
+
+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.
+
+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.
+
+Gemini stays a SEPARATE engine (``gemini_engine``): its multi-size fixed-slot 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
+# unknown-type rules for this file only.
+# 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 logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+import cv2
+import numpy as np
+
+from remove_ai_watermarks import image_io
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class TextMarkConfig:
+    """All per-mark tuning for a reverse-alpha text-mark engine."""
+
+    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)
+    margin_floor: int  # min margin in px for locate (4 for br marks, 2 for Samsung)
+    # locate geometry (fraction of image WIDTH)
+    width_frac: float
+    height_frac: float
+    margin_x_frac: float  # right margin (br) or left margin (bl)
+    margin_bottom_frac: float
+    # glyph appearance
+    max_saturation: float
+    logo_min_luma: float
+    tophat_delta: float
+    morph_open_size: int  # MORPH_OPEN kernel side (5 for br marks, 3 for Samsung)
+    # detection
+    detect_min_coverage: float
+    detect_ncc_threshold: float
+    # alpha-map geometry (fraction of WIDTH) emitted by scripts/visible_alpha_solve.py
+    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
+
+
+@dataclass
+class TextMarkLocation:
+    """Located watermark box, in absolute pixel coordinates."""
+
+    x: int
+    y: int
+    w: int
+    h: int
+    is_fallback: bool = True  # geometry anchor (no template match) -> always True for now
+
+    @property
+    def bbox(self) -> tuple[int, int, int, int]:
+        return self.x, self.y, self.w, self.h
+
+
+@dataclass
+class TextMarkDetection:
+    """Result of visible text-mark detection."""
+
+    detected: bool = False
+    confidence: float = 0.0
+    region: tuple[int, int, int, int] = (0, 0, 0, 0)
+    coverage: float = 0.0  # fraction of the box occupied by glyph pixels
+
+
+# Alpha / silhouette templates, cached per asset name (the originals cached per
+# module global; this keys by asset so the three engines share the loader without
+# re-reading). Only SUCCESSFUL loads are cached, so a missing asset is retried.
+_alpha_cache: dict[str, NDArray[Any]] = {}
+_silhouette_cache: dict[str, NDArray[Any]] = {}
+
+
+def load_alpha_template(asset_name: str) -> NDArray[Any] | None:
+    """Lazily load the bundled alpha template (float [0,1]) for ``asset_name``, or None."""
+    cached = _alpha_cache.get(asset_name)
+    if cached is not None:
+        return cached
+    path = Path(__file__).parent / "assets" / asset_name
+    img = image_io.imread(str(path), cv2.IMREAD_GRAYSCALE)
+    if img is None:
+        return None
+    _alpha_cache[asset_name] = img.astype(np.float32) / 255.0
+    return _alpha_cache[asset_name]
+
+
+def glyph_silhouette(asset_name: str) -> NDArray[Any] | None:
+    """Binary glyph silhouette (255 = glyph) from the bundled alpha map, or None."""
+    cached = _silhouette_cache.get(asset_name)
+    if cached is not None:
+        return cached
+    at = load_alpha_template(asset_name)
+    if at is None:
+        return None
+    _silhouette_cache[asset_name] = (at > 0.15).astype(np.uint8) * 255
+    return _silhouette_cache[asset_name]
+
+
+def template_match_score(box_mask: NDArray[Any], image_width: 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.
+    """
+    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)))
+    if gw < config.min_gw or gh < 4:
+        return 0.0
+    template = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_NEAREST)
+    return float(cv2.matchTemplate(box_mask, template, cv2.TM_CCOEFF_NORMED).max())
+
+
+class TextMarkEngine:
+    """Reverse-alpha visible text-mark remover (locate -> mask -> detect -> reverse-alpha)."""
+
+    def __init__(self, config: TextMarkConfig) -> None:
+        self.config = config
+
+    # ── Templates (delegate to the asset-keyed module cache) ────────────
+
+    def _alpha_template(self) -> NDArray[Any] | None:
+        return load_alpha_template(self.config.asset_name)
+
+    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)
+
+    # ── Locate ──────────────────────────────────────────────────────────
+
+    def locate(self, image: NDArray[Any]) -> TextMarkLocation:
+        """Anchor the watermark box in the configured bottom corner by geometry."""
+        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)
+        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)
+
+    # ── Mask ────────────────────────────────────────────────────────────
+
+    def extract_mask(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any]:
+        """Build a full-image uint8 mask (255 = watermark glyph) for the box.
+
+        Polarity-aware: the mark is a light, low-saturation gray rendered brighter
+        than the local background (white top-hat), so a white-paper document is left
+        untouched (nothing brighter than its surroundings is masked there).
+        """
+        c = self.config
+        h, w = image.shape[:2]
+        x, y, bw, bh = loc.bbox
+        # A degenerate ROI (a sliver from an extremely wide/short image) cannot hold
+        # the mark and would feed cv2's GaussianBlur/morphology a ~1-px-tall array,
+        # which can fault native code on some platforms. Skip the cv2 pipeline.
+        if bh < 16 or bw < 16:
+            return np.zeros((h, w), np.uint8)
+        # Normalize the ROI to 3-channel BGR (grayscale / BGRA would break axis=2).
+        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)
+        grayish = sat < c.max_saturation
+
+        # Local background model: a strong Gaussian blur (sigma ~ box height); the
+        # white top-hat (luma - local_bg) lights up bright thin strokes regardless
+        # of the absolute background level.
+        sigma = max(4.0, bh * 0.4)
+        local_bg = cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
+        tophat = luma - local_bg
+
+        cand = grayish & (tophat > c.tophat_delta) & (luma > c.logo_min_luma)
+        glyph = cand.astype(np.uint8) * 255
+        glyph = cv2.morphologyEx(glyph, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))
+        k = c.morph_open_size
+        glyph = cv2.morphologyEx(glyph, cv2.MORPH_OPEN, np.ones((k, k), np.uint8))
+
+        mask = np.zeros((h, w), np.uint8)
+        mask[y : y + bh, x : x + bw] = glyph
+        return mask
+
+    # ── Detect ──────────────────────────────────────────────────────────
+
+    def detect(self, image: NDArray[Any]) -> TextMarkDetection:
+        """Detect the mark by matching the alpha-template glyph silhouette against
+        the corner candidate (``TM_CCOEFF_NORMED``); keys on glyph SHAPE, not coverage."""
+        c = self.config
+        det = TextMarkDetection()
+        if image is None or image.size == 0:
+            return det
+        loc = self.locate(image)
+        mask = self.extract_mask(image, loc)
+        x, y, bw, bh = loc.bbox
+        box = mask[y : y + bh, x : x + bw]
+        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])
+            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)
+        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)."""
+        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)
+        amap = np.zeros((h, w), np.float32)
+        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh), interpolation=cv2.INTER_LINEAR)
+        return amap, (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 ``(alpha_map, glyph_bbox)`` or None."""
+        c = self.config
+        at = self._alpha_template()
+        sil = self._glyph_silhouette()
+        if at is None or sil is None:
+            return None
+        h, w = image.shape[:2]
+        loc = self.locate(image)
+        bx, by, bw, bh = loc.bbox
+        box_mask = self.extract_mask(image, loc)[by : by + bh, bx : bx + bw]
+        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
+        amap = np.zeros((h, w), np.float32)
+        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh), interpolation=cv2.INTER_LINEAR)
+        return amap, (ax, ay, gw, gh)
+
+    def _apply_reverse_alpha(self, image: NDArray[Any], amap: NDArray[Any]) -> NDArray[Any]:
+        """Invert the alpha blend with ``amap``: ``original = (wm - a*logo)/(1-a)``."""
+        a3 = np.clip(amap, 0.0, 1.0)[:, :, None]
+        logo = np.array(self.config.alpha_logo_bgr, np.float32)
+        return np.clip((image.astype(np.float32) - a3 * logo) / np.clip(1.0 - a3, 0.25, 1.0), 0, 255).astype(np.uint8)
+
+    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_residual = float("inf")
+        for amap, _region in maps:
+            out = self._apply_reverse_alpha(image, amap)
+            residual = self.detect(out).confidence
+            if residual < best_residual:
+                best_residual, best_out, best_amap = residual, out, amap
+        if best_out is None or best_amap is None:  # pragma: no cover - maps is non-empty
+            return image.copy()
+        if residual_inpaint:
+            kernel = np.ones((c.residual_dilate, c.residual_dilate), np.uint8)
+            rm = cv2.dilate((best_amap > c.residual_alpha_floor).astype(np.uint8) * 255, kernel)
+            best_out = cv2.inpaint(best_out, rm, c.residual_inpaint_radius, cv2.INPAINT_NS)
+        return best_out

src/remove_ai_watermarks/doubao_engine.py

@@ -1,245 +1,125 @@
 """Doubao visible watermark removal engine.
 
 Doubao (ByteDance) stamps every generated image with a visible "豆包AI生成"
-(Doubao AI generated) text strip in the bottom-right corner. This is the
-explicit AIGC label mandated by China's TC260 standard, rendered as a
-near-white / light-gray, low-saturation text overlay.
+(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.
 
-Unlike the Gemini sparkle (a fixed square logo removed by reverse alpha
-blending against a captured alpha map), the Doubao mark is a text strip whose
-exact alpha map we do not yet have. This engine therefore removes it by:
-
-    locate -> mask -> inpaint
-
-1. Locate: the mark scales with image WIDTH and sits in the bottom-right at a
-   fixed margin, so we anchor a generous box there (geometry only -- no bundled
-   template). Constants below are derived from measured Doubao output.
-2. Mask: within the box, extract the light, low-saturation glyph pixels with a
-   polarity-aware rule (the mark is brighter than dark backgrounds and a
-   distinct off-white gray against light backgrounds).
-3. Inpaint: cv2 inpainting (TELEA / NS) reconstructs the covered pixels.
-
-This is fast, offline, deterministic, and needs no GPU. A future upgrade path
-is per-pixel reverse alpha blending once a Doubao alpha map is captured on a
-controlled black background (see data/doubao_capture/), which would recover the
-true pixels instead of hallucinating them -- the same approach as the Gemini
-engine.
+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.
 """
+# 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 dataclasses import dataclass
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any
 
-import cv2
-import numpy as np
+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
 
-logger = logging.getLogger(__name__)
+# Locate geometry as a fraction of image WIDTH (the mark scales with width, anchored
+# bottom-right). The box is GENEROUSLY wider than the mark and reaches close to the
+# corner so a per-image re-rasterization shift stays inside the NCC alignment search.
+WM_WIDTH_FRAC = 0.22
+WM_HEIGHT_FRAC = 0.075
+MARGIN_RIGHT_FRAC = 0.004
+MARGIN_BOTTOM_FRAC = 0.004
 
-
-# Geometry as a fraction of image WIDTH. The Doubao mark scales with width and
-# is anchored bottom-right. The box is intentionally generous (the glyph mask
-# tightens it); values cover measured outputs across resolutions and aspect
-# ratios (square 2048, portrait, ultra-wide). Margins are width-relative too.
-WM_WIDTH_FRAC = 0.185
-WM_HEIGHT_FRAC = 0.065
-MARGIN_RIGHT_FRAC = 0.012
-MARGIN_BOTTOM_FRAC = 0.014
-
-# Glyph appearance: the label is a low-saturation light gray, rendered brighter
-# than the surrounding content (the common case: a generated photo/illustration).
-# We detect it as a local bright feature (white top-hat: brighter than a blurred
-# local background) intersected with the grayish + minimum-brightness tests.
-# This is polarity-correct for bright-on-darker backgrounds and, crucially,
-# leaves white-paper documents untouched (there the mark is not brighter than
-# its surroundings, so nothing is masked rather than damaging the document text).
+# Glyph appearance: a light, low-saturation gray rendered brighter than the local
+# background (white top-hat), so a white-paper document is left untouched.
 MAX_SATURATION = 55  # max channel spread to count a pixel as "grayish"
 LOGO_MIN_LUMA = 150  # glyphs are at least this bright in absolute terms
 TOPHAT_DELTA = 12  # glyph must exceed the local background by this many levels
 
-# Detection: a genuine label fills a meaningful fraction of the box. Measured
-# coverage is >=0.20 on real Doubao outputs; random/textured corners stay <=0.06
-# on large images but can spike to ~0.15 on tiny ones (small box -> high variance),
-# so the threshold sits above that spike and below the real-mark floor.
-DETECT_MIN_COVERAGE = 0.16
+# 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
 
-# Safety: a text strip fills a modest slice of the (generous) box. When the box
-# is over a dense-text / document background the mask explodes and cv2 inpainting
-# would smear the real content. Above this coverage we refuse to inpaint and
-# leave the image untouched -- that hard case needs the neural path, not a guess.
-MAX_INPAINT_COVERAGE = 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.
+_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_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",
+    asset_name="doubao_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,
+    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.
+DoubaoDetection = TextMarkDetection
 
 
-@dataclass(frozen=True)
-class DoubaoLocation:
-    """Located watermark box (bottom-right), in absolute pixel coordinates."""
-
-    x: int
-    y: int
-    w: int
-    h: int
-    is_fallback: bool = True  # geometry anchor (no template match) -> always True for now
-
-    @property
-    def bbox(self) -> tuple[int, int, int, int]:
-        return self.x, self.y, self.w, self.h
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled Doubao alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-@dataclass
-class DoubaoDetection:
-    """Result of visible Doubao watermark detection."""
-
-    detected: bool = False
-    confidence: float = 0.0
-    region: tuple[int, int, int, int] = (0, 0, 0, 0)
-    coverage: float = 0.0  # fraction of the box occupied by glyph pixels
+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)
 
 
-class DoubaoEngine:
-    """Remove the visible Doubao "豆包AI生成" watermark (locate -> mask -> inpaint)."""
-
-    def __init__(
-        self,
-        *,
-        width_frac: float = WM_WIDTH_FRAC,
-        height_frac: float = WM_HEIGHT_FRAC,
-        margin_right_frac: float = MARGIN_RIGHT_FRAC,
-        margin_bottom_frac: float = MARGIN_BOTTOM_FRAC,
-    ) -> None:
-        self.width_frac = width_frac
-        self.height_frac = height_frac
-        self.margin_right_frac = margin_right_frac
-        self.margin_bottom_frac = margin_bottom_frac
-
-    # ── Locate ────────────────────────────────────────────────────────
-
-    def locate(self, image: NDArray) -> DoubaoLocation:
-        """Anchor the watermark box in the bottom-right corner by geometry."""
-        h, w = image.shape[:2]
-        wm_w = max(40, int(w * self.width_frac))
-        wm_h = max(16, int(w * self.height_frac))
-        margin_r = max(4, int(w * self.margin_right_frac))
-        margin_b = max(4, int(w * self.margin_bottom_frac))
-        x = max(0, w - margin_r - wm_w)
-        y = max(0, h - margin_b - wm_h)
-        wm_w = min(wm_w, w - x)
-        wm_h = min(wm_h, h - y)
-        return DoubaoLocation(x=x, y=y, w=wm_w, h=wm_h, is_fallback=True)
-
-    # ── Mask ──────────────────────────────────────────────────────────
-
-    def extract_mask(self, image: NDArray, loc: DoubaoLocation) -> NDArray:
-        """Build a full-image uint8 mask (255 = watermark glyph) for the box.
-
-        Polarity-aware: the mark is a light, low-saturation gray. On a dark
-        background it is the bright region; on a light background it is the
-        off-white gray below paper-white. Both cases are captured by the logo
-        luminance band intersected with the grayish constraint, plus a
-        brighter-than-local-background test on dark backgrounds.
-        """
-        h, w = image.shape[:2]
-        x, y, bw, bh = loc.bbox
-        roi = image[y : y + bh, x : x + bw].astype(np.float32)
-
-        luma = roi.mean(axis=2)
-        sat = roi.max(axis=2) - roi.min(axis=2)
-        grayish = sat < MAX_SATURATION
-
-        # Local background model: a strong Gaussian blur (sigma ~ box height)
-        # approximates the content under the glyphs. The white top-hat
-        # (luma - local_bg) lights up bright thin strokes regardless of the
-        # absolute background level.
-        sigma = max(4.0, bh * 0.4)
-        local_bg = cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
-        tophat = luma - local_bg
-
-        cand = grayish & (tophat > TOPHAT_DELTA) & (luma > LOGO_MIN_LUMA)
-        glyph = cand.astype(np.uint8) * 255
-        # Connect glyph parts, then drop isolated specks (5x5 open clears the
-        # scattered grayish pixels that random/textured corners produce).
-        glyph = cv2.morphologyEx(glyph, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))
-        glyph = cv2.morphologyEx(glyph, cv2.MORPH_OPEN, np.ones((5, 5), np.uint8))
-
-        mask = np.zeros((h, w), np.uint8)
-        mask[y : y + bh, x : x + bw] = glyph
-        return mask
-
-    # ── Detect ────────────────────────────────────────────────────────
-
-    def detect(self, image: NDArray) -> DoubaoDetection:
-        """Detect the visible Doubao mark by glyph coverage in the corner box.
-
-        Heuristic: a genuine label fills a meaningful fraction of the box with
-        text-like glyph pixels. Coverage maps to a confidence score.
-        """
-        det = DoubaoDetection()
-        if image is None or image.size == 0:
-            return det
-        loc = self.locate(image)
-        mask = self.extract_mask(image, loc)
-        x, y, bw, bh = loc.bbox
-        box = mask[y : y + bh, x : x + bw]
-        coverage = float((box > 0).sum()) / float(max(1, bw * bh))
-        det.region = loc.bbox
-        det.coverage = coverage
-        # Map coverage to a 0-1 confidence: ~0.06 (noise floor) -> 0, ~0.26 -> 1.
-        det.confidence = float(max(0.0, min(1.0, (coverage - 0.06) / 0.20)))
-        det.detected = coverage >= DETECT_MIN_COVERAGE
-        logger.debug("Doubao detect: coverage=%.3f conf=%.3f", coverage, det.confidence)
-        return det
-
-    # ── Remove ────────────────────────────────────────────────────────
-
-    def remove_watermark(
-        self,
-        image: NDArray,
-        *,
-        inpaint_method: Literal["telea", "ns"] = "telea",
-        inpaint_radius: int = 6,
-        dilate: int = 3,
-    ) -> NDArray:
-        """Remove the visible Doubao watermark by inpainting the glyph mask.
-
-        Returns an unmodified copy when no glyph pixels are found (so we never
-        smear a clean corner). ``dilate`` grows the mask to cover anti-aliased
-        glyph edges before inpainting.
-        """
-        if image is None or image.size == 0:
-            return image
-        loc = self.locate(image)
-        mask = self.extract_mask(image, loc)
-        if not mask.any():
-            logger.debug("Doubao remove: no glyph pixels found; returning copy")
-            return image.copy()
-
-        x, y, bw, bh = loc.bbox
-        coverage = float((mask[y : y + bh, x : x + bw] > 0).sum()) / float(max(1, bw * bh))
-        if coverage > MAX_INPAINT_COVERAGE:
-            logger.warning(
-                "Doubao remove: box coverage %.2f exceeds %.2f (dense-text/document "
-                "background); leaving image untouched to avoid smearing content",
-                coverage,
-                MAX_INPAINT_COVERAGE,
-            )
-            return image.copy()
-
-        if dilate > 0:
-            k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * dilate + 1, 2 * dilate + 1))
-            mask = cv2.dilate(mask, k)
-
-        flag = cv2.INPAINT_TELEA if inpaint_method == "telea" else cv2.INPAINT_NS
-        return cv2.inpaint(image, mask, inpaint_radius, flag)
+def _template_match_score(box_mask: NDArray[Any], image_width: 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)
 
 
-def load_image_bgr(path: str | Path) -> NDArray:
+class DoubaoEngine(TextMarkEngine):
+    """Remove the visible Doubao "豆包AI生成" watermark (locate -> mask -> reverse-alpha)."""
+
+    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)."""
-    img = cv2.imread(str(path), cv2.IMREAD_COLOR)
+    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/face_protector.py

@@ -1,147 +0,0 @@
-"""YOLO-based face detection and soft-blend restoration for diffusion pipelines."""
-
-import logging
-from pathlib import Path
-
-import cv2
-import numpy as np
-
-try:
-    from ultralytics import YOLO
-
-    HAS_YOLO = True
-except ImportError:
-    HAS_YOLO = False
-
-logger = logging.getLogger(__name__)
-
-
-class FaceProtector:
-    """
-    Detects faces in an image and provides methods to seamlessly paste them back
-    onto the an upscaled/processed image to preserve facial details that may have
-    been destroyed by latent diffusion or other algorithms.
-    """
-
-    def __init__(self, use_yolo: bool = True, model_name: str = "yolov8n.pt") -> None:
-        self.use_yolo = use_yolo and HAS_YOLO
-        self.detector = None
-        self.haar_cascade = None
-
-        if self.use_yolo:
-            # Fix SSL certificate issues on macOS (fresh Python installs)
-            self._fix_ssl_certs()
-            logger.info("Loading YOLO model '%s' for face protection...", model_name)
-            self.detector = YOLO(model_name)
-        else:
-            if use_yolo and not HAS_YOLO:
-                logger.warning(
-                    "ultralytics YOLO is not installed. Falling back to OpenCV Haar "
-                    "Cascades. Install ultralytics with `pip install ultralytics` "
-                    "for better face detection."
-                )
-            logger.info("Loading OpenCV Haar Cascade for face protection...")
-            cascade_path = Path(cv2.__file__).parent / "data" / "haarcascade_frontalface_default.xml"
-            if not cascade_path.exists():
-                cascade_path = "haarcascade_frontalface_default.xml"
-            self.haar_cascade = cv2.CascadeClassifier(str(cascade_path))
-
-    def detect_face_bboxes(self, image: np.ndarray) -> list[tuple[int, int, int, int]]:
-        """
-        Detect faces and return bounding boxes as (x1, y1, x2, y2).
-        """
-        if self.use_yolo and self.detector is not None:
-            # For standard YOLOv8n, 'person' is class 0. We'll use person bounding boxes
-            # as a proxy for faces/people to protect them. If using a specific face model, adjust classes.
-            results = self.detector(image, verbose=False, classes=[0])
-            bboxes = []
-            for r in results:
-                boxes = r.boxes
-                for box in boxes:
-                    x1, y1, x2, y2 = box.xyxy[0].cpu().numpy()
-                    bboxes.append((int(x1), int(y1), int(x2), int(y2)))
-            return bboxes
-
-        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
-        faces = self.haar_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))
-        bboxes = []
-        for x, y, w, h in faces:
-            # Add a 20% margin around the haar cascade face box
-            margin_x = int(w * 0.2)
-            margin_y = int(h * 0.2)
-            x1 = max(0, x - margin_x)
-            y1 = max(0, y - int(margin_y * 1.5))  # more margin on top for hair
-            x2 = min(image.shape[1], x + w + margin_x)
-            y2 = min(image.shape[0], y + h + margin_y)
-            bboxes.append((x1, y1, x2, y2))
-        return bboxes
-
-    @staticmethod
-    def _fix_ssl_certs() -> None:
-        """Set SSL_CERT_FILE from certifi if not already set (macOS fix)."""
-        import os
-
-        if os.environ.get("SSL_CERT_FILE"):
-            return
-        try:
-            import certifi
-
-            os.environ["SSL_CERT_FILE"] = certifi.where()
-        except ImportError:
-            pass
-
-    def extract_faces(self, image: np.ndarray) -> list[tuple[tuple[int, int, int, int], np.ndarray]]:
-        """
-        Extract faces from the image.
-        Returns a list of (bbox, face_crop) tuples.
-        """
-        bboxes = self.detect_face_bboxes(image)
-        faces = []
-        for bbox in bboxes:
-            x1, y1, x2, y2 = bbox
-            faces.append((bbox, image[y1:y2, x1:x2].copy()))
-        return faces
-
-    def restore_faces(
-        self, processed_image: np.ndarray, original_faces: list[tuple[tuple[int, int, int, int], np.ndarray]]
-    ) -> np.ndarray:
-        """
-        Paste original faces back onto the processed image using seamless cloning
-        or soft blending so the edges don't show.
-        """
-        if not original_faces:
-            return processed_image
-
-        result = processed_image.copy()
-        for (x1, y1, x2, y2), face_crop in original_faces:
-            h, w = face_crop.shape[:2]
-
-            # If the processed image was resized, we'd need to resize face_crop, but
-            # pipeline ensures the output from InvisibleEngine is the same size or we resize it back before this.
-            if result.shape[:2] != processed_image.shape[:2]:
-                continue  # Safety bypass
-
-            try:
-                # Create a soft alpha mask for the face crop to smoothly blend it
-                mask = np.zeros((h, w), dtype=np.float32)
-
-                # Inner ellipse is pure white
-                cv2.ellipse(mask, (w // 2, h // 2), (int(w * 0.4), int(h * 0.4)), 0, 0, 360, 1.0, -1)
-
-                # Blur the mask heavily for soft edges
-                blur_size = max(w, h) // 4
-                if blur_size % 2 == 0:
-                    blur_size += 1
-                mask = cv2.GaussianBlur(mask, (blur_size, blur_size), 0)
-                mask = cv2.merge([mask, mask, mask])
-
-                # Blend
-                target_roi = result[y1:y2, x1:x2].astype(np.float32)
-                src_roi = face_crop.astype(np.float32)
-
-                blended = src_roi * mask + target_roi * (1.0 - mask)
-                result[y1:y2, x1:x2] = blended.astype(np.uint8)
-            except Exception as e:
-                logger.warning("Failed to restore face at %d,%d to %d,%d: %s", x1, y1, x2, y2, e)
-
-        return result

src/remove_ai_watermarks/gemini_engine.py

@@ -13,18 +13,26 @@ The alpha maps are derived from background captures of the Gemini watermark
 on pure-black backgrounds (48x48 for small images, 96x96 for large images).
 """
 
+# cv2/numpy boundary: cv2 and numpy ship no usable type info for the array ops
+# below, so strict pyright cannot know their element types. Relax the unknown-type
+# rules for this file only; the public signatures are still annotated with NDArray[Any].
+# 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 logging
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 import cv2
 import numpy as np
 
+from remove_ai_watermarks import image_io
+
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from numpy.typing import NDArray
 
 logger = logging.getLogger(__name__)
@@ -86,7 +94,7 @@ def get_watermark_size(width: int, height: int) -> WatermarkSize:
     return WatermarkSize.SMALL
 
 
-def _calculate_alpha_map(bg_capture: NDArray) -> NDArray:
+def _calculate_alpha_map(bg_capture: NDArray[Any]) -> NDArray[Any]:
     """Calculate alpha map from a background capture.
 
     The alpha map represents how much the watermark affects each pixel.
@@ -103,7 +111,7 @@ def _calculate_alpha_map(bg_capture: NDArray) -> NDArray:
     return gray / 255.0
 
 
-def _load_embedded_asset(name: str) -> NDArray:
+def _load_embedded_asset(name: str) -> NDArray[Any]:
     """Load an embedded PNG asset and decode it with OpenCV."""
     asset_path = Path(__file__).parent / "assets" / name
     if not asset_path.exists():
@@ -123,6 +131,93 @@ class GeminiEngine:
     This is a Python port of the GeminiWatermarkTool C++ engine.
     """
 
+    # 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
+
+    # 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
+
+    # 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
+    # or flat content (text, banners, hatching) can score >0.5 without that lift.
+    # Demote a detection that is BOTH low-confidence AND low core-ring brightness
+    # margin -- the joint signature of a content false positive (verified on the
+    # spaces corpus: of 16 demoted, 13 carried no AI metadata and the 3 AI-meta ones
+    # were visually FPs / a near-invisible white-on-white sparkle whose AI verdict is
+    # held by metadata anyway). Real sparkles escape via EITHER high confidence
+    # (white-bg sparkles score >=0.79 despite a low margin) OR high margin (dark/mid
+    # backgrounds, incl. the #36 faint-corner case, lift well clear), so both must
+    # fail to demote.
+    _SPARKLE_FP_CONF = 0.65
+    _SPARKLE_FP_MARGIN = 5.0
+
+    # 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
+
+    # Corner promotion (issue #36): the size weight that suppresses tiny-patch
+    # false positives also buries a small, near-perfect sparkle when a larger,
+    # mediocre match sits elsewhere (e.g. a bright collar in a portrait). A small
+    # faint sparkle on a busy background therefore loses the global argmax and the
+    # image reads as clean -- the regression osachub reported when the search
+    # window widened 256px -> 512px (v0.7.2's tighter window still found it).
+    # Remedy: if the bottom-right corner holds a very-high-fidelity raw-NCC match,
+    # trust it regardless of size, without reverting the wider window (which is
+    # needed for variant margins). The threshold sits midway between the worst
+    # real-photo corner match (~0.78 across native + downscaled real photos) and a
+    # genuine faint sparkle (~0.93), so it adds true detections without adding
+    # false ones; it only ever overrides a lower-fidelity global pick, so it cannot
+    # weaken an existing detection.
+    _CORNER_PROMOTE_NCC = 0.85
+    # Bottom-right corner side for the promotion search, as a fraction of the
+    # image's short side, clamped to an absolute pixel band. Relative so the corner
+    # stays a true corner at every scale: a fixed 256 px is a genuine corner on a
+    # large image but covers ~70% of a small portrait, where a busy real photo can
+    # then raw-match the star template at ~0.81 (only 0.04 below the promote gate).
+    # Scaling the side down on small images drops that worst case to ~0.69, while
+    # the upper clamp stops it ballooning on huge images (more corner area = more
+    # random texture to false-match -- a real photo reached ~0.83 at 512 px). The
+    # Gemini sparkle sits ~60-160 px from the corner (fixed margins, not
+    # proportional), and the [96, 384] band covers that at every measured size.
+    _CORNER_PROMOTE_FRAC = 0.20
+    _CORNER_PROMOTE_MIN = 96
+    _CORNER_PROMOTE_MAX = 384
+
     def __init__(self, logo_value: float = 255.0) -> None:
         """Initialize the engine with embedded alpha maps.
 
@@ -151,13 +246,13 @@ class GeminiEngine:
             self._alpha_large.shape,
         )
 
-    def get_alpha_map(self, size: WatermarkSize) -> NDArray:
+    def get_alpha_map(self, size: WatermarkSize) -> NDArray[Any]:
         """Get the base alpha map for a specific standard size."""
         if size == WatermarkSize.SMALL:
             return self._alpha_small
         return self._alpha_large
 
-    def get_interpolated_alpha(self, size_px: int) -> NDArray:
+    def get_interpolated_alpha(self, size_px: int) -> NDArray[Any]:
         """Create an interpolated alpha map dynamically scaled from the high-res 96x96 base."""
         source = self._alpha_large
         if size_px == source.shape[1]:
@@ -168,9 +263,27 @@ class GeminiEngine:
 
     # ── Detection ────────────────────────────────────────────────────
 
+    def _scan_scales(self, gray: NDArray[Any]) -> Iterator[tuple[int, float, tuple[int, int]]]:
+        """Yield ``(scale, max_ncc, max_loc)`` for the alpha template matched at each scale.
+
+        Shared multi-scale ``TM_CCOEFF_NORMED`` primitive over a normalized [0, 1]
+        grayscale region, used by both the size-weighted global search in
+        ``detect_watermark`` and the raw-NCC corner pass in ``_corner_promote`` --
+        each applies its own scoring/argmax to the yielded values. The 96x96
+        ``_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):
+            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)
+            _, max_val, _, max_loc = cv2.minMaxLoc(match_res)
+            yield scale, float(max_val), max_loc
+
     def detect_watermark(
         self,
-        image: NDArray,
+        image: NDArray[Any],
         force_size: WatermarkSize | None = None,
     ) -> DetectionResult:
         """Detect Gemini watermark using multi-scale Snap Engine logic (ported from C++ vendor algorithm)."""
@@ -179,15 +292,19 @@ class GeminiEngine:
         if image is None or image.size == 0:
             return result
 
+        # Normalize to 3-channel BGR: the multi-scale search tolerates grayscale, but
+        # the FP-gate / alpha-gain helpers (_core_and_bg) reduce over axis=2 and would
+        # crash on a 2D/BGRA input reaching this public entry point (e.g. via the
+        # registry detect adapter or the library API).
+        image = image_io.to_bgr(image)
         h, w = image.shape[:2]
         base_size = force_size or get_watermark_size(w, h)
         result.size = base_size
 
-        # Use large alpha template (96x96) as the high-quality source for downscaling
-        source_alpha = self._alpha_large
-
-        # Dynamically search bottom-right corner (search up to 256x256 region)
-        search_size = int(min(min(w, h), 256))
+        # Dynamically search bottom-right corner. 512 covers up to 512px from the
+        # corner -- enough for known Gemini margin variations (standard: 64+96=160px;
+        # observed variants up to ~300px). 256 was too tight and caused misses.
+        search_size = int(min(min(w, h), 512))
         sx1 = max(0, w - search_size)
         sy1 = max(0, h - search_size)
 
@@ -199,25 +316,15 @@ class GeminiEngine:
 
         gray_sr_f = gray_sr.astype(np.float32) / 255.0
 
-        # Phase 1 & 2: Multi-scale spatial NCC search
+        # Phase 1 & 2: multi-scale spatial NCC search, size-weighted argmax.
         best_scale = 0
         best_score = -1.0
         best_raw_ncc = -1.0
         best_loc = (0, 0)
-
-        # Search scales from 16 to 120 (covering aggressively downscaled or slightly upscaled logos)
-        for scale in range(16, 120, 2):
-            if scale > search_region.shape[0] or scale > search_region.shape[1]:
-                continue
-
-            tmpl = cv2.resize(source_alpha, (scale, scale), interpolation=cv2.INTER_AREA)
-            match_res = cv2.matchTemplate(gray_sr_f, tmpl, cv2.TM_CCOEFF_NORMED)
-            _, max_val, _, max_loc = cv2.minMaxLoc(match_res)
-
+        for scale, max_val, max_loc in self._scan_scales(gray_sr_f):
             # Size-adjusted score to overcome NCC bias toward tiny patches (mimics C++ weight)
             weight = min(1.0, (scale / 96.0) ** 0.5)
             adj_val = max_val * weight
-
             if adj_val > best_score:
                 best_score = adj_val
                 best_scale = scale
@@ -227,6 +334,14 @@ class GeminiEngine:
         # Exact dynamic location & size
         pos_x = sx1 + best_loc[0]
         pos_y = sy1 + best_loc[1]
+
+        # Corner promotion: a near-perfect but small sparkle in the bottom-right
+        # corner is otherwise outranked by a larger, mediocre size-weighted match
+        # (see _CORNER_PROMOTE_NCC). Override the global pick with it when present.
+        promoted = self._corner_promote(image, best_raw_ncc)
+        if promoted is not None:
+            best_scale, pos_x, pos_y, best_raw_ncc = promoted
+
         result.region = (pos_x, pos_y, best_scale, best_scale)
         result.spatial_score = float(best_raw_ncc)
 
@@ -286,6 +401,20 @@ class GeminiEngine:
 
         # ── Fusion ───────────────────────────────────────────────────
         confidence = result.spatial_score * 0.50 + result.gradient_score * 0.30 + var_score * 0.20
+
+        # False-positive gate: a low-confidence shape match whose core is NOT brighter
+        # than its surroundings is a content false positive, not a white sparkle overlay.
+        if confidence < self._SPARKLE_FP_CONF:
+            margin = self._core_ring_margin(image, self.get_interpolated_alpha(best_scale), (pos_x, pos_y))
+            if margin is not None and margin < self._SPARKLE_FP_MARGIN:
+                logger.debug(
+                    "Sparkle FP gate: conf=%.3f, core-ring margin=%.1f < %.1f; demoting.",
+                    confidence,
+                    margin,
+                    self._SPARKLE_FP_MARGIN,
+                )
+                confidence = min(confidence, 0.30)
+
         result.confidence = float(max(0.0, min(1.0, confidence)))
         result.detected = result.confidence >= 0.35
 
@@ -300,13 +429,49 @@ class GeminiEngine:
 
         return result
 
+    def _corner_promote(
+        self,
+        image: NDArray[Any],
+        current_raw_ncc: float,
+    ) -> tuple[int, int, int, float] | None:
+        """Search the bottom-right corner for a very-high-fidelity sparkle match.
+
+        Returns ``(scale, x, y, raw_ncc)`` when the corner holds a match with raw
+        NCC >= ``_CORNER_PROMOTE_NCC`` that beats the global pick's ``current_raw_ncc``,
+        else None. Used to rescue a small sparkle that the size weight buried under
+        a larger, lower-fidelity match elsewhere. See ``_CORNER_PROMOTE_NCC`` and
+        ``_CORNER_PROMOTE_FRAC`` for the corner sizing.
+        """
+        h, w = image.shape[:2]
+        side = max(
+            self._CORNER_PROMOTE_MIN, min(self._CORNER_PROMOTE_MAX, round(min(w, h) * self._CORNER_PROMOTE_FRAC))
+        )
+        cs = int(min(min(w, h), side))
+        cx1, cy1 = max(0, w - cs), max(0, h - cs)
+        corner = image[cy1:h, cx1:w]
+        gray = cv2.cvtColor(corner, cv2.COLOR_BGR2GRAY) if corner.ndim == 3 and corner.shape[2] >= 3 else corner
+        gray = gray.astype(np.float32) / 255.0
+
+        best_raw = -1.0
+        best_scale = 0
+        best_loc = (0, 0)
+        for scale, max_val, max_loc in self._scan_scales(gray):
+            if max_val > best_raw:
+                best_raw = max_val
+                best_scale = scale
+                best_loc = max_loc
+
+        if best_raw >= self._CORNER_PROMOTE_NCC and best_raw > current_raw_ncc:
+            return best_scale, cx1 + best_loc[0], cy1 + best_loc[1], float(best_raw)
+        return None
+
     # ── Removal ──────────────────────────────────────────────────────
 
     def remove_watermark(
         self,
-        image: NDArray,
+        image: NDArray[Any],
         force_size: WatermarkSize | None = None,
-    ) -> NDArray:
+    ) -> 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
@@ -323,18 +488,16 @@ class GeminiEngine:
             Cleaned BGR image as numpy array, or an unmodified copy when no
             watermark is detected.
         """
-        result = image.copy()
-
-        # Handle alpha channel
-        if result.shape[2] == 4:
-            result = cv2.cvtColor(result, cv2.COLOR_BGRA2BGR)
-        elif result.shape[2] == 1:
-            result = cv2.cvtColor(result, cv2.COLOR_GRAY2BGR)
+        # 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
-        detection = self.detect_watermark(image, force_size=size)
+        # 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(
@@ -345,6 +508,12 @@ class GeminiEngine:
 
         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],
@@ -354,14 +523,28 @@ class GeminiEngine:
             detection.confidence,
         )
 
-        self._reverse_alpha_blend(result, alpha_map, pos)
-        return result
+        # 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 remove_watermark_custom(
         self,
-        image: NDArray,
+        image: NDArray[Any],
         region: tuple[int, int, int, int],
-    ) -> NDArray:
+    ) -> NDArray[Any]:
         """Remove watermark from a custom region with interpolated alpha map.
 
         Args:
@@ -371,7 +554,9 @@ class GeminiEngine:
         Returns:
             Cleaned BGR image.
         """
-        result = image.copy()
+        # 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
@@ -388,32 +573,201 @@ class GeminiEngine:
         self._reverse_alpha_blend(result, alpha, (x, y))
         return result
 
+    def _footprint_indices(
+        self,
+        alpha_map: NDArray[Any],
+        position: tuple[int, int],
+        image_shape: tuple[int, ...],
+    ) -> tuple[NDArray[Any], tuple[int, int, int, int]] | None:
+        """Return (alpha_roi, (y1, y2, x1, x2)) for the placed footprint, or None.
+
+        Shared by the over-subtraction test and the inpaint mask so both operate on
+        exactly the same clipped, in-bounds region.
+        """
+        x, y = position
+        ah, aw = alpha_map.shape[:2]
+        ih, iw = image_shape[:2]
+        x1, y1 = max(0, x), max(0, y)
+        x2, y2 = min(iw, x + aw), min(ih, y + ah)
+        if x1 >= x2 or y1 >= y2:
+            return None
+        ax1, ay1 = x1 - x, y1 - y
+        alpha_roi = alpha_map[ay1 : ay1 + (y2 - y1), ax1 : ax1 + (x2 - x1)]
+        return alpha_roi, (y1, y2, x1, x2)
+
+    def _core_and_bg(
+        self,
+        image: NDArray[Any],
+        alpha_map: NDArray[Any],
+        position: tuple[int, int],
+    ) -> tuple[float, float, float] | None:
+        """Return ``(core_obs, bg, a_cap)`` for the placed sparkle, or None.
+
+        ``core_obs`` is the bright-core brightness (75th pct over the high-alpha
+        core), ``bg`` the local background ring median, ``a_cap`` the captured peak
+        alpha. Shared by the alpha-gain estimate and the false-positive margin gate.
+        None when the footprint or the background ring cannot be sampled.
+        """
+        placed = self._footprint_indices(alpha_map, position, image.shape)
+        if placed is None:
+            return None
+        alpha_roi, (y1, y2, x1, x2) = placed
+        a_cap = float(alpha_roi.max())
+        if a_cap < 0.2:
+            return None
+        gray = image.astype(np.float32).mean(axis=2)
+        core = alpha_roi >= a_cap * self._ALPHA_GAIN_CORE_FRAC
+        if not bool(core.any()):
+            return None
+        core_obs = float(np.percentile(gray[y1:y2, x1:x2][core], 75))
+        # Local background = a ring just outside the footprint box.
+        ih, iw = image.shape[:2]
+        pad = int((x2 - x1) * 0.7)
+        ry1, ry2 = max(0, y1 - pad), min(ih, y2 + pad)
+        rx1, rx2 = max(0, x1 - pad), min(iw, x2 + pad)
+        ring = gray[ry1:ry2, rx1:rx2]
+        ring_mask = np.ones(ring.shape, dtype=bool)
+        ring_mask[y1 - ry1 : y2 - ry1, x1 - rx1 : x2 - rx1] = False
+        if int(ring_mask.sum()) < 10:
+            return None
+        return core_obs, float(np.median(ring[ring_mask])), a_cap
+
+    def _core_ring_margin(
+        self,
+        image: NDArray[Any],
+        alpha_map: NDArray[Any],
+        position: tuple[int, int],
+    ) -> float | None:
+        """Bright-core brightness minus the local background ring (gray levels).
+
+        A real white sparkle overlay lifts its core above the surroundings; a
+        shape-only NCC false positive on ornate/flat content does not. None when the
+        background ring cannot be sampled.
+        """
+        cb = self._core_and_bg(image, alpha_map, position)
+        return None if cb is None else cb[0] - cb[1]
+
+    def _estimate_alpha_gain(
+        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 (issue #30).
+
+        Tests 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-estimates this image's opacity.
+        """
+        placed = self._footprint_indices(alpha_map, position, image.shape)
+        if placed is None:
+            return False
+        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())
+        return frac > self._OVERSUB_FOOTPRINT_FRAC
+
+    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.
+
+        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,
-        alpha_map: NDArray,
+        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)
         """
-        x, y = position
-        ah, aw = alpha_map.shape[:2]
-        ih, iw = image.shape[:2]
-
-        # Clip to bounds
-        x1 = max(0, x)
-        y1 = max(0, y)
-        x2 = min(iw, x + aw)
-        y2 = min(ih, y + ah)
-
-        if x1 >= x2 or y1 >= y2:
+        placed = self._footprint_indices(alpha_map, position, image.shape)
+        if placed is None:
             return
-
-        # Get ROIs
-        ax1, ay1 = x1 - x, y1 - y
-        alpha_roi = alpha_map[ay1 : ay1 + (y2 - y1), ax1 : ax1 + (x2 - x1)]
+        alpha_roi, (y1, y2, x1, x2) = placed
         image_roi = image[y1:y2, x1:x2].astype(np.float32)
 
         alpha_threshold = 0.002
@@ -442,13 +796,13 @@ class GeminiEngine:
 
     def inpaint_residual(
         self,
-        image: NDArray,
+        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:
+    ) -> NDArray[Any]:
         """Apply inpaint cleanup on residual artifacts after reverse alpha blend.
 
         Uses a sparse mask derived from alpha map gradient to repair only
@@ -556,7 +910,9 @@ def detect_sparkle_confidence(image_path: Path) -> float | None:
     (cv2 returns None for unsupported containers such as HEIC). Kept here so the
     cv2 dependency stays in this module; callers apply their own threshold.
     """
-    img = cv2.imread(str(image_path))
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(image_path)
     if img is None:
         return None
     return float(GeminiEngine().detect_watermark(img).confidence)

src/remove_ai_watermarks/humanizer.py

@@ -1,9 +1,14 @@
-"""Analog Humanizer: film grain and chromatic aberration injection.
+"""Post-processing filters for the cleaned output.
 
-Simulates analog film imperfections to defeat digital AI perfection
-classifiers. Ported from NeuralBleach.
+``apply_analog_humanizer`` injects film grain and chromatic aberration to defeat
+digital AI-perfection classifiers (ported from NeuralBleach); ``unsharp_mask``
+counters the soft, over-smoothed look that diffusion + face-restoration leave
+behind (itself a common "this is AI" tell).
 """
 
+# cv2/numpy boundary: third-party libs ship no usable element types; relax the
+# unknown-type rules for this file only.
+# 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
 import cv2
 import numpy as np
 from numpy.typing import NDArray
@@ -33,10 +38,14 @@ def apply_analog_humanizer(image: NDArray, grain_intensity: float = 4.0, chromat
     b, g, r = cv2.split(image)
 
     # 1. Chromatic Aberration
-    # Shift R channel left, B channel right
+    # 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]
 
     merged = cv2.merge((b, g, r))
 
@@ -49,3 +58,111 @@ def apply_analog_humanizer(image: NDArray, grain_intensity: float = 4.0, chromat
         humanized = merged
 
     return humanized
+
+
+def unsharp_mask(image: NDArray, amount: float = 0.5, sigma: float = 1.0) -> NDArray:
+    """Sharpen via unsharp masking: ``out = image + amount * (image - blur(image))``.
+
+    Counters the soft, over-smoothed look of the diffusion + GFPGAN passes, which
+    reads as an AI tell. ``amount`` 0 = no-op (returns an unchanged copy); ~0.5-0.8
+    is a safe range -- higher risks bright edge halos that are their own artifact.
+    ``sigma`` is the Gaussian radius of the unsharp kernel.
+
+    Args:
+        image: BGR image as numpy array (uint8).
+        amount: Sharpening strength (0 = off).
+        sigma: Gaussian blur sigma for the unsharp kernel.
+
+    Returns:
+        Sharpened BGR image (uint8).
+    """
+    if amount <= 0.0:
+        return image.copy()
+    img_f = image.astype(np.float32)
+    blurred = cv2.GaussianBlur(img_f, (0, 0), sigmaX=sigma, sigmaY=sigma)
+    sharpened = cv2.addWeighted(img_f, 1.0 + amount, blurred, -amount, 0.0)
+    return np.clip(sharpened, 0, 255).astype(np.uint8)
+
+
+# ── Adaptive polish (target the input's detail level; spare text) ──────────────
+# A capped unsharp scaled to the sharpness deficit, then edge-masked grain to close
+# the rest -- tunable constants. Validated 2026-06-03 on the spaces corpus: a soft
+# gemini_3 face/photo (lap-var 84 vs the 592 of its original) is pulled up to ~327
+# with full polish, while a sharp openai_1 text card (1175 vs 1644) gets near-zero
+# (the deficit is tiny) so text is left alone -- the polish self-limits on text.
+_ADAPTIVE_MAX_UNSHARP = 1.0
+_ADAPTIVE_UNSHARP_GAIN = 0.4  # unsharp amount per unit of (deficit - 1), before the cap
+_ADAPTIVE_MAX_GRAIN = 8.0
+_MASK_EDGE_PERCENTILE = 85.0  # local-energy percentile above which a pixel is an "edge/text"
+_MASK_EDGE_DILATE = 5  # grow the edge mask so grain is suppressed in a margin around text
+_MASK_GAMMA = 2.0  # push the smooth weight toward 0 except in genuinely flat areas
+
+
+def _to_gray(image: NDArray) -> NDArray:
+    """Single-channel grayscale; passes a 2D (already-gray) input through unchanged."""
+    return image if image.ndim == 2 else cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+
+def _laplacian_variance(image: NDArray) -> float:
+    """Variance of the Laplacian -- a cheap proxy for high-frequency detail/sharpness."""
+    return float(cv2.Laplacian(_to_gray(image), cv2.CV_64F).var())
+
+
+def _smooth_grain_mask(image: NDArray) -> NDArray:
+    """Per-pixel weight ~1 in flat/smooth regions, ~0 over text and hard edges.
+
+    Grain in smooth ("AI-plastic") regions reads as natural sensor noise; grain over
+    text/edges just speckles them, so this masks grain to the smooth regions only.
+    """
+    energy = cv2.GaussianBlur(np.abs(cv2.Laplacian(_to_gray(image).astype(np.float32), cv2.CV_32F)), (0, 0), sigmaX=2.0)
+    thr = float(np.percentile(energy, _MASK_EDGE_PERCENTILE))
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (_MASK_EDGE_DILATE, _MASK_EDGE_DILATE))
+    edges = cv2.dilate((energy > thr).astype(np.uint8), kernel)
+    mask = np.clip(1.0 - energy / (thr + 1e-6), 0.0, 1.0) ** _MASK_GAMMA
+    mask[edges > 0] = 0.0
+    return cv2.GaussianBlur(mask, (0, 0), sigmaX=1.5)
+
+
+def adaptive_polish(image: NDArray, reference: NDArray, seed: int | None = None) -> NDArray:
+    """Restore the detail level of ``reference`` in a softened ``image``, sparing text.
+
+    Diffusion + face restoration leave an over-smoothed "AI-plastic" look, worst on
+    photo/face regions. This targets the reference's Laplacian variance (the input's
+    detail level): a capped unsharp scaled to the deficit, then edge-masked grain
+    (smooth regions only) calibrated to close the remaining gap. **Self-limiting on
+    text/graphics** -- they are already high-frequency, so the deficit is small and
+    almost no polish is applied (text legibility is a generation-side concern, not a
+    filter one). No-op when the image already meets the reference's detail level.
+
+    Args:
+        image: the cleaned BGR output (uint8).
+        reference: the original input BGR at the same resolution (the detail target).
+        seed: optional RNG seed for reproducible grain.
+
+    Returns:
+        Polished BGR image (uint8).
+    """
+    target = _laplacian_variance(reference)
+    current = _laplacian_variance(image)
+    if target <= 0.0 or current >= target:
+        return image.copy()
+
+    deficit = target / max(current, 1.0)
+    amount = min(_ADAPTIVE_MAX_UNSHARP, _ADAPTIVE_UNSHARP_GAIN * (deficit - 1.0))
+    work = unsharp_mask(image, amount=amount, sigma=1.2) if amount > 0.0 else image.copy()
+    if _laplacian_variance(work) >= target:
+        return work
+
+    # Calibrate the grain sigma by a short search: its lap-var contribution depends on
+    # the per-pixel mask (no closed form), so step it up until the target is met. A few
+    # full-image Laplacians here are negligible against the diffusion pass that precedes.
+    mask = _smooth_grain_mask(work)
+    noise = np.random.default_rng(seed).normal(0.0, 1.0, work.shape[:2]).astype(np.float32) * mask
+    best = work
+    sigma = 2.0
+    while sigma <= _ADAPTIVE_MAX_GRAIN:
+        best = np.clip(work.astype(np.float32) + (noise * sigma)[:, :, np.newaxis], 0.0, 255.0).astype(np.uint8)
+        if _laplacian_variance(best) >= target:
+            break
+        sigma += 1.0
+    return best

src/remove_ai_watermarks/identify.py

@@ -8,7 +8,8 @@ Aggregates every locally-readable signal into a single :class:`ProvenanceReport`
 - **PNG text / EXIF generation parameters** (Stable Diffusion, ComfyUI, InvokeAI).
 - **SynthID metadata proxy** -- a C2PA companion from a SynthID-using vendor
   (Google / OpenAI) implies the invisible pixel watermark.
-- **Visible Gemini sparkle** (optional; needs cv2/numpy, no GPU).
+- **Visible marks** (optional; needs cv2/numpy, no GPU): the Gemini sparkle and
+  the ByteDance Doubao 豆包AI生成 / Jimeng 即梦AI text marks.
 
 Hard limit: a stripped image (re-encoded, screenshotted, social-media upload)
 loses all metadata, and the SynthID *pixel* watermark is not locally decodable
@@ -18,6 +19,7 @@ never as "clean". See CLAUDE.md "SynthID detection is metadata-only".
 
 from __future__ import annotations
 
+import itertools
 import logging
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
@@ -25,21 +27,26 @@ from typing import TYPE_CHECKING
 from remove_ai_watermarks.metadata import (
     AI_METADATA_KEYS,
     AIGC_MARKERS,
-    C2PA_UUID,
     IPTC_AI_FIELD_MARKERS,
     IPTC_AI_MARKERS,
     aigc_label,
+    c2pa_marker_in,
     exif_generator,
     get_ai_metadata,
+    huggingface_job,
     iptc_ai_system,
+    samsung_genai,
+    scan_head,
     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_ISSUERS
+from remove_ai_watermarks.noai.constants import C2PA_AI_TOOLS, C2PA_AI_VENDORS, C2PA_ISSUERS
 
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from remove_ai_watermarks.watermark_registry import MarkDetection
+
 log = logging.getLogger(__name__)
 
 # How much of a non-PNG container to binary-scan for the C2PA issuer.
@@ -52,17 +59,13 @@ _SCAN_BYTES = 1024 * 1024
 # signal (e.g. an OpenAI image scored 0.37 -- below threshold, correctly dropped).
 _SPARKLE_THRESHOLD = 0.5
 
-# Issuer (C2PA signer) -> human-readable generating platform. Ordered: when a
-# manifest names several issuers (Microsoft Designer signs as "OpenAI,
-# Microsoft"), the first match wins so the product, not the backend, is named.
-_ISSUER_PLATFORM: tuple[tuple[str, str], ...] = (
-    # Microsoft signs both Designer and Bing Image Creator; Bing now runs its
-    # own MAI-Image model (not DALL-E), so the label stays model-neutral.
-    ("Microsoft", "Microsoft (Bing Image Creator / Designer)"),
-    ("Adobe", "Adobe Firefly"),
-    ("OpenAI", "OpenAI (ChatGPT / gpt-image / DALL-E / Sora)"),
-    ("Google", "Google (Gemini / Imagen)"),
-    ("Stability AI", "Stability AI (Stable Image / DreamStudio)"),
+# Issuer (C2PA signer) -> human-readable generating platform, derived from the
+# single C2PA_AI_VENDORS registry. Ordered: when a manifest names several issuers
+# (Microsoft Designer signs as "OpenAI, Microsoft"), the first match wins so the
+# product, not the backend, is named -- the registry order encodes that priority.
+# Signing authorities without an AI platform (e.g. Truepic) are skipped here.
+_ISSUER_PLATFORM: tuple[tuple[str, str], ...] = tuple(
+    (v.needle, v.platform) for v in C2PA_AI_VENDORS if v.platform is not None and v.needle is not None
 )
 
 # PNG-text / EXIF keys that indicate a local diffusion pipeline (vs. a hosted
@@ -88,6 +91,17 @@ _INVISIBLE_WM_CAVEAT = (
     "The open invisible watermark is fragile: it does not survive JPEG re-encoding "
     "or resizing, so it confirms origin only on a pristine (un-re-encoded) file."
 )
+_HF_JOB_CAVEAT = (
+    "The hf-job-id tag marks a HuggingFace-hosted job (commonly diffusion "
+    "generation) but names neither the model nor the content type, so it is a "
+    "medium-confidence signal, not proof the pixels are AI-generated."
+)
+_SAMSUNG_GENAI_CAVEAT = (
+    "Samsung's genAIType marker shows a Galaxy AI editing tool (Generative Edit, "
+    "Sketch to Image, ...) touched the image; it is an undocumented proprietary "
+    "field, so it is a medium-confidence signal of AI editing, not proof the "
+    "whole image is AI-generated."
+)
 
 
 @dataclass
@@ -110,6 +124,11 @@ class ProvenanceReport:
     watermarks: list[str] = field(default_factory=list[str])
     signals: list[Signal] = field(default_factory=list["Signal"])
     caveats: list[str] = field(default_factory=list[str])
+    # Contradictions between independent provenance signals (e.g. two different
+    # AI vendors both claiming the image, or camera-capture credentials next to
+    # AI-generation markers). Non-empty means the provenance is internally
+    # inconsistent -- a strong tell of spoofed, transplanted, or laundered metadata.
+    integrity_clashes: list[str] = field(default_factory=list[str])
 
 
 def _issuers_in(data: bytes) -> list[str]:
@@ -139,7 +158,9 @@ def _ai_tools_in(data: bytes) -> list[str]:
 # assert is_ai on their own (the verdict still comes from the digital-source-type:
 # the Pixel sample carries `computationalCapture`, not `trainedAlgorithmicMedia`).
 # Only tokens verified against a real signed file are listed (Leica, Nikon,
-# Truepic, Google Pixel); add Sony/Canon/Samsung/Bria as real samples are captured.
+# Sony, Truepic, Google Pixel); add Canon/Bria as real samples are captured.
+# Samsung Galaxy is an AI-capable editing device, not a pure-capture camera, so
+# it lives in `_SIGNER_C2PA_PLATFORM` below (it must not feed the camera clash).
 _DEVICE_C2PA_PLATFORM: tuple[tuple[bytes, str], ...] = (
     (b"lc_c2pa", "Leica (camera, C2PA capture)"),
     (b"Leica Camera", "Leica (camera, C2PA capture)"),
@@ -165,17 +186,156 @@ def _device_platform(head: bytes) -> str | None:
     return None
 
 
-def _attribute_platform(issuers: list[str]) -> str | None:
-    """Map a set of C2PA issuer names to a human-readable generating platform."""
-    joined = " ".join(issuers)
-    for needle, platform in _ISSUER_PLATFORM:
-        if needle in joined:
+# C2PA signers that are an editing app or AI-capable device rather than a
+# verified-capture camera. Unlike `_DEVICE_C2PA_PLATFORM`, these do NOT feed the
+# camera-vs-AI integrity clash (rule 2 in `_integrity_clashes`): a Galaxy phone
+# legitimately stamps BOTH its device credentials AND a `trainedAlgorithmicMedia`
+# source type on a Generative-Edit image, so treating it as a "genuine camera
+# capture" would false-flag every Galaxy AI edit. They only resolve the platform
+# label; the AI verdict still comes from the digital-source-type / genAIType.
+# Tokens verified against real signed files (2026-05-29):
+#   Samsung Galaxy -- cert org on Galaxy S23 FE / S24 / S25 C2PA JPEGs/PNGs
+#     (distinct from the EXIF "SM-xxxx" model string on ordinary Samsung photos).
+#   com.asus.gallery -- ASUS Gallery claim_generator (a C2PA-signed edit, no AI
+#     source type or genAIType on the samples, so it never asserts is_ai).
+_SIGNER_C2PA_PLATFORM: tuple[tuple[bytes, str], ...] = (
+    (b"Samsung Galaxy", "Samsung Galaxy (C2PA)"),
+    (b"com.asus.gallery", "ASUS Gallery (C2PA signer)"),
+)
+
+
+def _signer_platform(head: bytes) -> str | None:
+    """Map a C2PA editing-app / AI-capable-device signer token to a platform."""
+    for token, platform in _SIGNER_C2PA_PLATFORM:
+        if token in head:
             return platform
+    return None
+
+
+def _attribute_platform(issuers: list[str], *, is_ai: bool = True) -> str | None:
+    """Map a set of C2PA issuer names to a human-readable generating platform.
+
+    A specific AI-generator platform (Adobe Firefly, OpenAI, ...) is named only
+    when the content is actually AI (``is_ai``, i.e. digital-source-type
+    ``trainedAlgorithmicMedia``). Otherwise an issuer-name byte match is likely
+    incidental -- e.g. an "Adobe XMP" toolkit string in a Canon/Sony camera
+    capture, or a "Google" cert org -- so we fall back to a neutral signer label
+    rather than mislabel a camera photo as "Adobe Firefly". Real Firefly/OpenAI/
+    Google AI output carries the AI source-type, so it is unaffected. ``is_ai``
+    defaults True so the issuer->platform mapping can still be unit-tested in
+    isolation; ``identify`` passes the file's actual ``c2pa_is_ai``.
+    """
+    joined = " ".join(issuers)
+    if is_ai:
+        for needle, platform in _ISSUER_PLATFORM:
+            if needle in joined:
+                return platform
     if issuers:  # e.g. Truepic alone -- a signing authority, not a generator
         return f"C2PA signer: {', '.join(issuers)} (no known AI generator named)"
     return None
 
 
+# Coarse origin-vendor normalization for integrity-clash detection. Two signals
+# that resolve to the SAME key are consistent (a C2PA "Google (Gemini)" issuer
+# and a SynthID-Google proxy, or Adobe Firefly + its Adobe TrustMark soft
+# binding); two DIFFERENT keys from independent generator stamps are a
+# contradiction (a C2PA OpenAI manifest on an image whose EXIF says "Ideogram
+# AI"). Substring match on the lowercased platform/detail string; first hit wins,
+# so order specific tokens before brand umbrellas where they overlap.
+_AI_VENDOR_TOKENS: tuple[tuple[str, str], ...] = (
+    ("gpt-image", "OpenAI"),
+    ("dall", "OpenAI"),
+    ("sora", "OpenAI"),
+    ("openai", "OpenAI"),
+    ("gemini", "Google"),
+    ("imagen", "Google"),
+    ("nano banana", "Google"),
+    ("google", "Google"),
+    ("firefly", "Adobe"),
+    ("adobe", "Adobe"),
+    ("bing", "Microsoft"),
+    ("designer", "Microsoft"),
+    ("microsoft", "Microsoft"),
+    ("stability", "Stability AI"),
+    ("stable diffusion", "Stability AI"),
+    ("sdxl", "Stability AI"),
+    ("ideogram", "Ideogram"),
+    ("grok", "xAI"),
+    ("aurora", "xAI"),
+    ("xai", "xAI"),
+)
+
+
+def _vendor_of(text: str | None) -> str | None:
+    """Normalize a platform/generator string to a coarse origin-vendor key, or None."""
+    if not text:
+        return None
+    low = text.lower()
+    for token, vendor in _AI_VENDOR_TOKENS:
+        if token in low:
+            return vendor
+    return None
+
+
+# Clash-detection provenance sources. Rule 1 (below) flags two AI vendors only
+# when they come from *independent* signals. The C2PA issuer attribution and the
+# SynthID proxy are NOT independent -- the proxy is inferred from the same C2PA
+# manifest -- so they share one source. A multi-actor manifest (a product wrapping
+# another vendor's engine, e.g. Microsoft+OpenAI or Microsoft+Google; or an edit
+# chain like Adobe over a Gemini original) legitimately names several vendors in
+# one valid chain and must not read as spoofing. Families not listed here are each
+# their own independent source (EXIF/XMP generator, IPTC AISystemUsed, AIGC, ...).
+_CLASH_SOURCE: dict[str, str] = {"c2pa": "c2pa_manifest", "synthid": "c2pa_manifest"}
+
+
+def _integrity_clashes(
+    ai_vendors: dict[str, str], camera_label: str | None, *, camera_has_ai_marker: bool
+) -> list[str]:
+    """Surface contradictions between independent provenance signals.
+
+    Args:
+        ai_vendors: family name -> normalized AI-origin vendor, one entry per
+            generator-stamped signal (C2PA issuer when the source is AI, SynthID
+            proxy, EXIF/XMP generator tag, IPTC AISystemUsed, xAI, AIGC label).
+        camera_label: a camera/verified-capture C2PA device platform, if one was
+            identified (Pixel, Leica, Sony, Nikon, Truepic), else None.
+        camera_has_ai_marker: True when an AI-generation stamp coexists with the
+            camera credentials.
+
+    Returns:
+        Human-readable clash descriptions; empty when the signals agree.
+    """
+    clashes: list[str] = []
+
+    # Rule 1: two genuinely INDEPENDENT signals naming different AI vendors. Two
+    # 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.
+    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)
+    )
+    if independent_conflict:
+        by_vendor: dict[str, list[str]] = {}
+        for family, vendor in ai_vendors.items():
+            by_vendor.setdefault(vendor, []).append(family)
+        parts = [f"{vendor} (via {', '.join(sorted(fams))})" for vendor, fams in sorted(by_vendor.items())]
+        clashes.append(
+            "Conflicting AI-origin attributions from independent signals: "
+            + " vs ".join(parts)
+            + " -- one provenance set was likely spoofed, transplanted, or laundered."
+        )
+
+    if camera_label and camera_has_ai_marker:
+        vendors = ", ".join(sorted(set(ai_vendors.values()))) or "present"
+        clashes.append(
+            f"Camera-capture C2PA credentials ({camera_label}) coexist with AI-generation markers "
+            f"({vendors}) -- a genuine camera capture is not AI-generated, so the provenance is inconsistent."
+        )
+
+    return clashes
+
+
 def _visible_sparkle(image_path: Path) -> float | None:
     """Visible Gemini-sparkle confidence in [0, 1], or None if unavailable.
 
@@ -191,6 +351,47 @@ def _visible_sparkle(image_path: Path) -> float | None:
     return detect_sparkle_confidence(image_path)
 
 
+# Visible text marks (registry keys) -> human-readable platform, mirroring the
+# Gemini-sparkle phrasing. These are the stripped-metadata visual fallback for
+# the China-served ByteDance generators (normally also caught by the TC260 AIGC
+# metadata label); the per-engine detection thresholds live in the registry.
+_VISIBLE_MARK_PLATFORM = {
+    "doubao": "ByteDance Doubao (visible 豆包AI生成 mark detected)",
+    "jimeng": "ByteDance Jimeng / Dreamina (visible 即梦AI mark detected)",
+    "samsung": "Samsung Galaxy AI (visible 'Contenuti generati dall'AI' mark detected)",
+}
+
+
+def _visible_text_marks(image_path: Path) -> list[MarkDetection]:
+    """Detected visible Doubao/Jimeng 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
+    each engine's calibrated NCC threshold via ``MarkDetection.detected``.
+    Optional: needs cv2/numpy; returns ``[]`` if the engines/assets are missing
+    or the image can't be read.
+    """
+    try:
+        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)
+        return []
+    image = imread(image_path)
+    if image is None:
+        return []
+    detections: list[MarkDetection] = []
+    for key in _VISIBLE_MARK_PLATFORM:
+        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)
+            continue
+        if det.detected:
+            detections.append(det)
+    return detections
+
+
 def _invisible_watermark(image_path: Path) -> str | None:
     """Open invisible-watermark scheme name (SD/SDXL/FLUX) or None.
 
@@ -218,7 +419,8 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
 
     Args:
         image_path: Path to the image (PNG, JPEG, WebP, or ISOBMFF container).
-        check_visible: Also run the visible Gemini-sparkle detector (cv2). Set
+        check_visible: Also run the visible-mark detectors (cv2) -- the Gemini
+            sparkle and the Doubao/Jimeng text marks from the registry. Set
             False for a pure-metadata, dependency-light scan.
         check_invisible: Also decode open invisible watermarks (SD/SDXL/FLUX) via
             the optional imwatermark library. No-op when it is not installed.
@@ -233,15 +435,24 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
 
     # First MB covers C2PA (PNG caBX, JPEG APP11, AVIF/HEIF/JXL uuid box) and
     # IPTC markers for the non-PNG path where extract_c2pa_info returns {}.
-    with open(image_path, "rb") as f:
-        head = f.read(_SCAN_BYTES)
+    # scan_head also seeks out late ISOBMFF provenance boxes (manifest after a
+    # large mdat in a streaming MP4) that a fixed first-MB read would miss.
+    head = scan_head(image_path, _SCAN_BYTES)
 
     signals: list[Signal] = []
     watermarks: list[str] = []
     caveats: list[str] = []
+    # One normalized origin vendor per generator-stamped signal, for integrity-
+    # clash detection (see _integrity_clashes). Visible sparkle and the open
+    # invisible watermark are deliberately excluded: the former is a fuzzy visual
+    # score, the latter can be a by-product of our own SDXL removal pass, so
+    # neither is a trustworthy "the generator stamped its identity" claim.
+    ai_vendor_claims: dict[str, str] = {}
+    camera_label = _device_platform(head)
+    signer_label = _signer_platform(head)
 
     # ── C2PA Content Credentials ────────────────────────────────────
-    has_c2pa = bool(info) or b"c2pa" in head.lower() or C2PA_UUID in head
+    has_c2pa = bool(info) or c2pa_marker_in(head)
     issuers = [info["issuer"]] if info.get("issuer") else _issuers_in(head)
     c2pa_is_ai = "trainedAlgorithmicMedia" in info.get("source_type", "") or any(
         m in head for m in (b"trainedAlgorithmicMedia", b"compositeWithTrainedAlgorithmicMedia")
@@ -256,24 +467,33 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         or (", ".join(tools) if (tools := _ai_tools_in(head)) else None)
     )
     # Platform: a distinctive device/camera token in the manifest wins (it is the
-    # signer/producer), with the issuer byte-scan only as fallback. The issuer
-    # scan alone mis-attributed real samples (Leica->Truepic timestamp authority,
-    # Nikon->Adobe namespace, Pixel->Google Gemini) -- the device scan fixes that.
-    platform = (_device_platform(head) or _attribute_platform(issuers)) if has_c2pa else None
+    # signer/producer), then an editing-app/AI-device signer (Samsung Galaxy,
+    # ASUS Gallery), with the issuer byte-scan only as fallback. The issuer scan
+    # alone mis-attributed real samples (Leica->Truepic timestamp authority,
+    # Nikon->Adobe namespace, Pixel->Google Gemini) -- the token scans fix that.
+    platform = (camera_label or signer_label or _attribute_platform(issuers, is_ai=c2pa_is_ai)) if has_c2pa else None
     if has_c2pa:
         detail = ", ".join(filter(None, [", ".join(issuers), generator, info.get("source_type")]))
         signals.append(Signal("c2pa", detail or "C2PA manifest present", "high"))
         watermarks.append(f"C2PA Content Credentials ({', '.join(issuers) or 'unknown signer'})")
+        # Record the AI-origin vendor for clash detection only when the source is
+        # actually AI -- classify the issuer attribution / generator, NOT the
+        # resolved `platform` (which may be a camera device token whose label,
+        # e.g. "Google Pixel", would mis-normalize to an AI vendor).
+        if c2pa_is_ai and (v := (_vendor_of(_attribute_platform(issuers, is_ai=True)) or _vendor_of(generator))):
+            ai_vendor_claims["c2pa"] = v
 
     # ── SynthID metadata proxy ──────────────────────────────────────
     # get_ai_metadata already sets synthid_watermark for both PNG (caBX parser)
     # and non-PNG (its own synthid_source fallback), so no extra scan is needed.
     synthid = meta.get("synthid_watermark")
     if synthid:
-        watermarks.append(f"SynthID pixel watermark ({synthid})")
+        watermarks.append(f"SynthID watermark, inferred from C2PA metadata ({synthid})")
         caveats.append(_SYNTHID_CAVEAT)
-        if "OpenAI" in (" ".join(issuers) + synthid):
+        if _vendor_of(synthid) == "OpenAI":
             caveats.append(_OPENAI_CAVEAT)
+        if v := _vendor_of(synthid):
+            ai_vendor_claims["synthid"] = v
 
     # ── C2PA soft-binding: a named forensic/third-party watermark vendor ─
     # (Adobe TrustMark, Digimarc, Imatag, ...). Present in the manifest even when
@@ -303,15 +523,23 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         watermarks.append(f"IPTC 2025.1 AI disclosure ({system})" if named else "IPTC 2025.1 AI disclosure fields")
         if platform is None and named:
             platform = f"{system} (IPTC AISystemUsed)"
+        if named and (v := _vendor_of(system)):
+            ai_vendor_claims["iptc_ai_system"] = v
 
     # ── China TC260 AIGC label (Doubao and other China-served gens) ──
-    aigc = any(m in head for m in AIGC_MARKERS)
+    # Fire on either the namespaced byte marker (``TC260:AIGC`` / the TC260 ns
+    # URL, present in XMP and as a laundering tell even when the JSON payload is
+    # truncated) OR the parsed label, which additionally catches the raw-JSON
+    # PNG ``AIGC`` tEXt chunk that carries no namespaced marker at all.
+    aigc_data = aigc_label(image_path)
+    aigc = aigc_data is not None or any(m in head for m in AIGC_MARKERS)
     if aigc:
-        producer = (aigc_label(image_path) or {}).get("ContentProducer", "")
+        producer = (aigc_data or {}).get("ContentProducer", "")
         signals.append(Signal("aigc", f"TC260 AIGC label{f' (producer {producer})' if producer else ''}", "high"))
         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)"
 
     # ── Local diffusion parameters (Stable Diffusion / ComfyUI) ──────
     local_keys = sorted(k for k in meta if k.lower() in _LOCAL_GEN_KEYS)
@@ -328,6 +556,8 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         watermarks.append(f"Embedded generator tag: {generator_tag}")
         if platform is None:
             platform = f"{generator_tag} (EXIF/XMP generator tag)"
+        if v := _vendor_of(generator_tag):
+            ai_vendor_claims["exif_generator"] = v
 
     # ── xAI / Grok EXIF signature scheme (no C2PA/SynthID/IPTC) ──────
     # Grok's only provenance signal: EXIF ImageDescription "Signature: <base64>"
@@ -338,6 +568,35 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         watermarks.append("xAI/Grok EXIF signature")
         if platform is None:
             platform = "xAI (Grok / Aurora)"
+        ai_vendor_claims["xai"] = "xAI"
+
+    # ── HuggingFace-hosted job marker (hf-job-id PNG text chunk) ─────
+    # Marks the hosting job, not a model -- medium confidence (commonly diffusion
+    # output). Like the visible sparkle, it lifts an otherwise-Unknown verdict to
+    # a tentative AI, but never overrides a high-confidence metadata signal.
+    hf_job = huggingface_job(image_path)
+    if hf_job:
+        signals.append(Signal("hf_job", f"HuggingFace job {hf_job}", "medium"))
+        watermarks.append("HuggingFace-hosted job (hf-job-id)")
+        caveats.append(_HF_JOB_CAVEAT)
+        if platform is None:
+            platform = "HuggingFace-hosted job (model not identified)"
+
+    # ── Samsung Galaxy AI editing marker (genAIType) ─────────────────
+    # Galaxy AI tools stamp a proprietary genAIType in PhotoEditor_Re_Edit_Data.
+    # Medium confidence: it co-occurs with the C2PA trainedAlgorithmicMedia type
+    # on Galaxy files that record one, and is the SOLE AI marker on a Galaxy S24
+    # sample that omits the source type -- so it lifts an otherwise-Unknown
+    # verdict, but the field is undocumented, so it never overrides a high-
+    # confidence signal. The platform is usually already "Samsung Galaxy" via the
+    # signer-token scan; the fallback covers a future file without the cert org.
+    samsung_genai_type = samsung_genai(image_path)
+    if samsung_genai_type is not None:
+        signals.append(Signal("samsung_genai", f"Samsung genAIType={samsung_genai_type}", "medium"))
+        watermarks.append("Samsung Galaxy AI editing marker (genAIType)")
+        caveats.append(_SAMSUNG_GENAI_CAVEAT)
+        if platform is None:
+            platform = "Samsung Galaxy (Galaxy AI editing)"
 
     # ── Open invisible watermark (SD / SDXL / FLUX, dwtDct) ──────────
     # Public decoder, no key -- a definitive embedded signal on pristine files.
@@ -380,18 +639,32 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         if platform is None:
             platform = "Google Gemini family (visible sparkle detected)"
 
-    visible_only = any(s.name == "visible_sparkle" for s in signals) and not ai_from_metadata
+    # ── 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):
+            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]
+
+    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
+    samsung_only = samsung_genai_type is not None and not ai_from_metadata
 
     if ai_from_metadata:
         is_ai: bool | None = True
         confidence = "high"
-    elif visible_only:
+    elif visible_only or hf_only or samsung_only:
         is_ai = True
         confidence = "medium"
     else:
         is_ai = None
         confidence = "none"
 
+    # ── Integrity clashes: contradictions between independent signals ─
+    clashes = _integrity_clashes(ai_vendor_claims, camera_label, camera_has_ai_marker=bool(ai_vendor_claims))
+
     caveats.append(_STRIP_CAVEAT)
     # De-duplicate while preserving order.
     caveats = list(dict.fromkeys(caveats))
@@ -404,4 +677,5 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         watermarks=watermarks,
         signals=signals,
         caveats=caveats,
+        integrity_clashes=clashes,
     )

src/remove_ai_watermarks/image_io.py

@@ -0,0 +1,89 @@
+"""Unicode-safe cv2 image IO (issue #17).
+
+``cv2.imread`` / ``cv2.imwrite`` pass the path to the platform C runtime, which
+on Windows uses the narrow (ANSI) code-page API and therefore fails on paths
+containing non-ASCII characters (Chinese, Cyrillic, ...). The symptom is a
+``can't open/read file`` warning and a ``None`` decode even though the file
+exists.
+
+These wrappers route through numpy buffers instead: ``np.fromfile`` /
+``ndarray.tofile`` open the path in Python (full Unicode), and
+``cv2.imdecode`` / ``cv2.imencode`` do the codec work. The decoded/encoded
+bytes are byte-for-byte identical to ``imread`` / ``imwrite``. On macOS/Linux
+cv2 already accepts UTF-8 paths, so the wrappers are behavior-neutral there.
+
+cv2/numpy are imported lazily inside the functions so importing this module
+stays cheap in a bare environment (matching the rest of the package).
+"""
+
+# cv2 ships no type stubs; mirror the pragma used by the other cv2-using modules.
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def imread(path: str | Path, flags: int | None = None) -> NDArray[Any] | None:
+    """Unicode-safe ``cv2.imread``.
+
+    ``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.
+    """
+    import cv2
+    import numpy as np
+
+    if flags is None:
+        flags = cv2.IMREAD_COLOR
+    try:
+        data = np.fromfile(str(path), dtype=np.uint8)
+    except OSError:
+        return None
+    if data.size == 0:
+        return None
+    return cv2.imdecode(data, flags)
+
+
+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.
+    Centralizes the shape coercion that was inlined across the engines. A 3-channel
+    input is returned unchanged (no copy).
+    """
+    import cv2
+
+    if image.ndim == 2 or image.shape[2] == 1:
+        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+    if image.shape[2] == 4:
+        return cv2.cvtColor(image, cv2.COLOR_BGRA2BGR)
+    return image
+
+
+def imwrite(path: str | Path, img: NDArray[Any]) -> bool:
+    """Unicode-safe ``cv2.imwrite``.
+
+    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).
+    """
+    import cv2
+
+    ext = Path(path).suffix or ".png"
+    ok, buf = cv2.imencode(ext, img)
+    if not ok:
+        return False
+    try:
+        buf.tofile(str(path))
+    except OSError:
+        return False
+    return True

src/remove_ai_watermarks/invisible_engine.py

@@ -7,13 +7,17 @@ This module requires the 'gpu' extra dependencies:
     uv pip install 'remove-ai-watermarks[gpu]'
 """
 
+# cv2/torch boundary: this engine wraps cv2 (resize/imwrite/cvtColor) and the
+# humanizer, none of which carry usable element types; relax the unknown-type
+# rules for this file only.
+# 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 logging
 import os
 import warnings
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -33,30 +37,37 @@ logger = logging.getLogger(__name__)
 
 def is_available() -> bool:
     """Check if invisible watermark removal dependencies are installed."""
-    try:
-        import diffusers  # noqa: F401
-        import torch  # noqa: F401
+    import importlib.util
 
-        return True
-    except ImportError:
-        return False
+    return importlib.util.find_spec("diffusers") is not None and importlib.util.find_spec("torch") is not None
 
 
-def _target_size(width: int, height: int, max_resolution: int) -> tuple[int, int] | None:
-    """Compute the downscaled (width, height) for a long-side cap, or None for native.
+def _target_size(width: int, height: int, max_resolution: int, min_resolution: int = 0) -> tuple[int, int] | None:
+    """Compute the (width, height) to process at, or None for native.
 
-    Returns None when no pre-downscale is needed: ``max_resolution <= 0`` (native
-    resolution, the default that matches the raiw.cc backend -- see issue #10) or
-    the long side already fits the cap. Otherwise scales the long side down to
-    ``max_resolution`` preserving aspect ratio (integer-truncated, matching the
-    PIL ``resize`` call site). Pure function so the native-vs-downscale decision
-    is unit-testable without loading the diffusion model.
+    Two opposite long-side adjustments, in precedence order:
+
+    - ``max_resolution`` (cap): if the long side exceeds it, scale DOWN to it
+      (integer-truncated, matching the PIL ``resize`` call site). 0/negative = no
+      cap. Set only to bound GPU/MPS memory on very large inputs (issue #10).
+    - ``min_resolution`` (floor): else if the long side is below it, scale UP to it
+      (rounded) so SDXL img2img runs near its ~1024 training resolution instead of
+      degrading on a tiny latent (a 381x512 portrait distorts badly at native).
+      The output is restored to the original size by the caller, so the floor is a
+      transparent quality boost. 0 = no floor. Skipped on a ``min > max`` misconfig.
+
+    Returns None when neither applies (native resolution). Pure function so the
+    resolution decision is unit-testable without loading the diffusion model.
     """
-    if max_resolution > 0 and max(width, height) > max_resolution:
-        ratio = max_resolution / max(width, height)
+    long_side = max(width, height)
+    if max_resolution > 0 and long_side > max_resolution:
+        ratio = max_resolution / long_side
         # Clamp the short side to >=1: extreme aspect ratios (e.g. 5000x3 capped
         # at 1024) would otherwise truncate it to 0 and crash image.resize().
         return (max(1, int(width * ratio)), max(1, int(height * ratio)))
+    if min_resolution > 0 and long_side < min_resolution and (max_resolution <= 0 or min_resolution <= max_resolution):
+        ratio = min_resolution / long_side
+        return (max(1, round(width * ratio)), max(1, round(height * ratio)))
     return None
 
 
@@ -70,44 +81,45 @@ class InvisibleEngine:
     to break watermark patterns, and reconstructs via reverse diffusion.
     """
 
-    # SDXL base is the default since May 2026: empirically defeats SynthID v2
-    # at strength=0.05 / steps=50 / native ~1024px. See CLAUDE.md "Known
-    # limitations" for the regression evidence ruling out SD-1.5 pipelines.
+    # SDXL base is the default since May 2026; the vendor-adaptive strength
+    # removes the current SynthID (see watermark_profiles + docs/synthid.md).
     DEFAULT_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
-    CTRLREGEN_MODEL_ID = "yepengliu/ctrlregen"
 
     def __init__(
         self,
         model_id: str | None = None,
         device: str | None = None,
-        pipeline: str = "default",
+        pipeline: str = "controlnet",
         hf_token: str | None = None,
         progress_callback: Callable[[str], None] | None = None,
+        controlnet_conditioning_scale: float = 1.0,
     ) -> None:
         """Initialize the invisible watermark removal engine.
 
         Args:
-            model_id: HuggingFace model ID. None = use default for pipeline.
-            device: Device for inference (auto/cpu/mps/cuda). None = auto.
-            pipeline: Pipeline profile. "default" (SDXL base, defeats SynthID
-                v2) or "ctrlregen" (CtrlRegen).
+            model_id: HuggingFace model ID. None = use the SDXL base default.
+            device: Device for inference (auto/cpu/mps/cuda/xpu). None = auto.
+            pipeline: Pipeline profile. "controlnet" (DEFAULT; SDXL + canny ControlNet
+                that preserves text/face structure via edge conditioning while removing
+                SynthID) or "sdxl" (plain SDXL img2img, lighter but leaves SynthID on
+                flat-graphic content). "default" is a back-compat alias for "sdxl".
             hf_token: HuggingFace API token.
             progress_callback: Optional callback for progress messages.
+            controlnet_conditioning_scale: ControlNet structure-preservation
+                strength (controlnet pipeline only).
         """
 
         from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover
 
-        effective_model = model_id
-        if pipeline == "ctrlregen" and model_id is None:
-            effective_model = self.CTRLREGEN_MODEL_ID
-        elif model_id is None:
-            effective_model = self.DEFAULT_MODEL_ID
+        effective_model = model_id or self.DEFAULT_MODEL_ID
 
         self._remover = WatermarkRemover(
             model_id=effective_model,
             device=device,
             progress_callback=progress_callback,
             hf_token=hf_token,
+            pipeline=pipeline,
+            controlnet_conditioning_scale=controlnet_conditioning_scale,
         )
         self._progress_callback = progress_callback
 
@@ -115,6 +127,32 @@ class InvisibleEngine:
         """Eagerly load the pipeline so download progress is visible."""
         self._remover.preload()
 
+    def _esrgan_upscale(self, image: Any, target: tuple[int, int]) -> Any:
+        """Upscale a PIL image to ``target`` with Real-ESRGAN, else Lanczos.
+
+        Runs Real-ESRGAN at its native factor (on the remover's device, CPU fallback),
+        then resizes to the exact ``target`` with Lanczos. Falls back to a plain Lanczos
+        resize when the ``esrgan`` extra is absent or the model errors.
+        """
+        import cv2
+        import numpy as np
+        from PIL import Image
+
+        from remove_ai_watermarks import upscaler
+
+        if not upscaler.is_available():
+            logger.debug("esrgan upscaler requested but the extra is absent; using Lanczos")
+            return image.resize(target, Image.Resampling.LANCZOS)
+        try:
+            bgr = cv2.cvtColor(np.array(image.convert("RGB")), cv2.COLOR_RGB2BGR)
+            big = upscaler.upscale(bgr, device=self._remover.device)
+            if (big.shape[1], big.shape[0]) != target:
+                big = cv2.resize(big, target, interpolation=cv2.INTER_LANCZOS4)
+            return Image.fromarray(cv2.cvtColor(big, cv2.COLOR_BGR2RGB))
+        except Exception as e:  # never let an optional upscaler break removal
+            logger.warning("Real-ESRGAN upscale failed (%s); using Lanczos", e)
+            return image.resize(target, Image.Resampling.LANCZOS)
+
     def remove_watermark(
         self,
         image_path: Path,
@@ -124,25 +162,47 @@ class InvisibleEngine:
         guidance_scale: float | None = None,
         seed: int | None = None,
         humanize: float = 0.0,
-        protect_faces: bool = True,
         max_resolution: int = 0,
+        min_resolution: int = 1024,
+        vendor: str | None = None,
+        unsharp: float = 0.0,
+        adaptive_polish: bool = False,
+        upscaler: str = "lanczos",
     ) -> Path:
         """Remove invisible watermark from an image.
 
         Args:
             image_path: Path to the watermarked image.
             output_path: Output path (None = overwrite source).
-            strength: Denoising strength (0.0-1.0). Default 0.04.
+            strength: Denoising strength (0.0-1.0). None -> the vendor-adaptive
+                default.
             steps: Number of denoising steps.
             guidance_scale: Classifier-free guidance scale.
             seed: Random seed for reproducibility.
             humanize: Intensity of Analog Humanizer film grain (0 = off).
-            protect_faces: Boolean to extract and restore faces intact.
+            unsharp: Final unsharp-mask sharpening strength (0 = off, default).
+                Applied last to counter the soft / over-smoothed look of the
+                diffusion pass; ~0.5-0.8 is a safe range, higher risks edge halos.
+            adaptive_polish: When True (the CLI default), restore the input's detail
+                level in the softened output: a capped unsharp + edge-masked grain
+                targeting the input's Laplacian variance. Self-limiting -- a no-op when
+                the output already meets the input's detail level (text/flat graphics),
+                so it only acts on over-smoothed photo/face texture. Runs LAST.
             max_resolution: Cap the long side (px) before diffusion. 0 (default)
-                = native resolution, no pre-downscale -- matches the hosted
-                raiw.cc backend. Set a positive value only to bound GPU/MPS
-                memory on very large inputs (it reintroduces a lossy
-                downscale->upscale round-trip).
+                = no cap. Set a positive value only to bound GPU/MPS memory on
+                very large inputs (it reintroduces a lossy downscale->upscale
+                round-trip).
+            min_resolution: Upscale the long side UP to this (px) before diffusion
+                when the input is smaller, so SDXL runs near its ~1024 training
+                resolution (small inputs degrade/distort badly at native). 1024
+                (default) = on; 0 = off. The output is restored to the original
+                input size, so this is a transparent quality boost; it adds time
+                and memory on small inputs. Ignored on a min > max misconfig.
+            upscaler: How to upscale a small input to the ``min_resolution`` floor:
+                ``"lanczos"`` (default, cv2, no deps) or ``"esrgan"`` (Real-ESRGAN
+                via the ``esrgan`` extra). Only applies when UPscaling (the floor
+                case); a ``max_resolution`` downscale always uses Lanczos. Falls back
+                to Lanczos if the extra is absent.
 
         Returns:
             Path to the cleaned image.
@@ -151,26 +211,35 @@ class InvisibleEngine:
 
         from PIL import Image, ImageOps
 
-        # Process at native resolution by default (max_resolution=0). The hosted
-        # raiw.cc backend (fal fast-sdxl) does NO pre-downscale either, and at
-        # strength ~0.05 SDXL img2img does not need the input shrunk to ~1024 --
-        # the old forced downscale->upscale round-trip was the main quality loss
-        # (see issue #10). A positive max_resolution caps the long side only to
-        # bound GPU/MPS memory on very large inputs.
+        # Resolution policy: a max_resolution cap (0 = none) bounds memory on huge
+        # inputs, and a min_resolution floor (1024 = default) upscales tiny inputs so
+        # 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.
         image = Image.open(image_path)
         image = ImageOps.exif_transpose(image)
         orig_size = image.size  # (width, height)
+        # Full-res original, kept for the adaptive-polish detail target (image is
+        # reassigned to the resized copy below; PIL resize returns a new object).
+        reference_pil = image
 
-        # Optional long-side downscale; native resolution by default (issue #10).
-        target = _target_size(image.width, image.height, max_resolution)
+        target = _target_size(image.width, image.height, max_resolution, min_resolution)
         if target is not None:
+            upscaling = max(target) > max(image.width, image.height)
             if self._progress_callback:
-                self._progress_callback(
-                    f"Downscaling {image.width}x{image.height} "
-                    f"to {target[0]}x{target[1]} "
-                    f"(max-resolution cap {max_resolution}px)..."
+                reason = (
+                    f"min-resolution floor {min_resolution}px"
+                    if upscaling
+                    else f"max-resolution cap {max_resolution}px"
                 )
-            image = image.resize(target, Image.Resampling.LANCZOS)
+                verb = "Upscaling" if upscaling else "Downscaling"
+                self._progress_callback(f"{verb} {image.width}x{image.height} to {target[0]}x{target[1]} ({reason})...")
+            # Real-ESRGAN only helps when UPscaling (the floor case); a downscale cap
+            # always uses Lanczos. _esrgan_upscale falls back to Lanczos if the extra is absent.
+            if upscaling and upscaler == "esrgan":
+                image = self._esrgan_upscale(image, target)
+            else:
+                image = image.resize(target, Image.Resampling.LANCZOS)
 
         # Always persist to a temp file, even without downscaling: WatermarkRemover
         # reloads by path, so the EXIF-transposed pixels must be saved or rotation
@@ -182,27 +251,6 @@ class InvisibleEngine:
         image_path = _tmp_path
 
         try:
-            # Optional: Face protection (Phase 1 - Extraction)
-            original_faces = []
-            if protect_faces:
-                try:
-                    import cv2
-
-                    from remove_ai_watermarks.face_protector import FaceProtector
-
-                    if self._progress_callback:
-                        self._progress_callback("Detecting and extracting faces (protect-faces)...")
-                    # Convert PIL to CV2 BGR
-                    import numpy as np
-
-                    cv_img = cv2.cvtColor(np.array(image), cv2.COLOR_RGB2BGR)
-                    protector = FaceProtector(use_yolo=True)
-                    original_faces = protector.extract_faces(cv_img)
-                    if self._progress_callback:
-                        self._progress_callback(f"Extracted {len(original_faces)} face(s) for protection.")
-                except Exception as e:
-                    logger.error("Failed to extract faces: %s", e)
-
             out_path = self._remover.remove_watermark(
                 image_path=image_path,
                 output_path=output_path,
@@ -210,22 +258,24 @@ class InvisibleEngine:
                 num_inference_steps=num_inference_steps,
                 guidance_scale=guidance_scale,
                 seed=seed,
+                vendor=vendor,
             )
 
-            # Optional: Face restoration & Humanizer (Phase 2 - Post-processing)
-            if protect_faces or humanize > 0.0:
+            # Post-processing chain: decode the diffusion output ONCE, apply the
+            # optional stages in memory in order (humanize -> restore original
+            # resolution -> unsharp -> adaptive polish), and write ONCE. Previously
+            # each stage independently imread/imwrote the full-res output, so a run
+            # with several stages PNG-decoded+re-encoded the same image 2-4 times.
+            # PNG is lossless, so the single-write output is byte-identical.
+            needs_restore = target is not None  # the input was resized before diffusion
+            if humanize > 0.0 or unsharp > 0.0 or adaptive_polish or needs_restore:
                 import cv2
-                import numpy as np
 
-                out_cv = cv2.imread(str(out_path), cv2.IMREAD_COLOR)
+                from remove_ai_watermarks import image_io
 
-                if protect_faces and original_faces:
-                    if self._progress_callback:
-                        self._progress_callback("Restoring protected faces with soft blending...")
-                    from remove_ai_watermarks.face_protector import FaceProtector
-
-                    protector = FaceProtector(use_yolo=True)
-                    out_cv = protector.restore_faces(out_cv, original_faces)
+                out_cv = image_io.imread(out_path, cv2.IMREAD_COLOR)
+                if out_cv is None:
+                    return out_path
 
                 if humanize > 0.0:
                     if self._progress_callback:
@@ -234,29 +284,36 @@ class InvisibleEngine:
 
                     out_cv = apply_analog_humanizer(out_cv, grain_intensity=humanize, chromatic_shift=1)
 
-                # Restore original resolution
+                # Restore original resolution if the input was resized for diffusion.
                 if (out_cv.shape[1], out_cv.shape[0]) != orig_size:
                     if self._progress_callback:
                         self._progress_callback(
                             f"Upscaling result back to original resolution {orig_size[0]}x{orig_size[1]}..."
                         )
-                    # Using INTER_LANCZOS4 for high-quality upscaling back to original
                     out_cv = cv2.resize(out_cv, orig_size, interpolation=cv2.INTER_LANCZOS4)
 
-                cv2.imwrite(str(out_path), out_cv)
-
-            else:
-                # Even if no protect_faces or humanize, we must restore original size if needed
-                import cv2
-
-                out_cv = cv2.imread(str(out_path), cv2.IMREAD_COLOR)
-                if out_cv is not None and (out_cv.shape[1], out_cv.shape[0]) != orig_size:
+                if unsharp > 0.0:
                     if self._progress_callback:
-                        self._progress_callback(
-                            f"Upscaling result back to original resolution {orig_size[0]}x{orig_size[1]}..."
-                        )
-                    out_cv = cv2.resize(out_cv, orig_size, interpolation=cv2.INTER_LANCZOS4)
-                    cv2.imwrite(str(out_path), out_cv)
+                        self._progress_callback(f"Sharpening (unsharp mask: {unsharp})...")
+                    from remove_ai_watermarks.humanizer import unsharp_mask
+
+                    out_cv = unsharp_mask(out_cv, amount=unsharp)
+
+                # Adaptive polish (CLI default): restore the input's detail level in the
+                # softened output, sparing text/edges. Self-limiting where no deficit.
+                if adaptive_polish:
+                    import numpy as np
+
+                    from remove_ai_watermarks import humanizer
+
+                    ref = cv2.cvtColor(np.array(reference_pil.convert("RGB")), cv2.COLOR_RGB2BGR)
+                    if (ref.shape[1], ref.shape[0]) != (out_cv.shape[1], out_cv.shape[0]):
+                        ref = cv2.resize(ref, (out_cv.shape[1], out_cv.shape[0]), interpolation=cv2.INTER_LANCZOS4)
+                    if self._progress_callback:
+                        self._progress_callback("Adaptive polish (sharpen + grain to the input's detail level)...")
+                    out_cv = humanizer.adaptive_polish(out_cv, ref, seed=seed)
+
+                image_io.imwrite(out_path, out_cv)
 
             return out_path
         finally:
@@ -268,7 +325,7 @@ class InvisibleEngine:
         self,
         input_dir: Path,
         output_dir: Path,
-        strength: float = 0.04,
+        strength: float | None = None,
         steps: int = 50,
     ) -> list[Path]:
         """Remove invisible watermarks from all images in a directory."""

src/remove_ai_watermarks/invisible_watermark.py

@@ -78,10 +78,11 @@ def detect_invisible_watermark(image_path: Path) -> str | None:
     """
     if not is_available():
         return None
-    import cv2
     from imwatermark import WatermarkDecoder
 
-    img = cv2.imread(str(image_path))
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(image_path)
     if img is None:
         return None
 

src/remove_ai_watermarks/jimeng_engine.py

@@ -0,0 +1,109 @@
+"""Jimeng / Dreamina visible watermark removal engine.
+
+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
+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.
+"""
+# 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 numpy.typing import NDArray
+
+# Locate geometry as a fraction of image WIDTH (mark scales with width, bottom-right).
+WM_WIDTH_FRAC = 0.27
+WM_HEIGHT_FRAC = 0.092
+MARGIN_RIGHT_FRAC = 0.008
+MARGIN_BOTTOM_FRAC = 0.010
+
+# Glyph appearance: a light, low-saturation gray brighter than the local background.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+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.
+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.
+_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_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",
+    asset_name="jimeng_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,
+    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
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled Jimeng 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], image_width: 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)
+
+
+class JimengEngine(TextMarkEngine):
+    """Remove the visible Jimeng "★ 即梦AI" watermark (locate -> mask -> reverse-alpha)."""
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)

src/remove_ai_watermarks/metadata.py

@@ -9,9 +9,11 @@ For metadata-only operations, the heavy ML dependencies are NOT required.
 from __future__ import annotations
 
 import contextlib
+import functools
 import logging
 import re
-from typing import TYPE_CHECKING
+import struct
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -65,6 +67,22 @@ AI_KEYWORDS: tuple[str, ...] = (
 # Reference: https://spec.c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html
 C2PA_UUID: bytes = bytes.fromhex("d8fec3d61b0e483c92975828877ec481")
 
+
+def c2pa_marker_in(data: bytes) -> bool:
+    """True if ``data`` carries a real C2PA manifest marker, not just an
+    incidental 4-byte ``c2pa`` substring.
+
+    A bare ``c2pa`` byte match false-positives on compressed pixel data -- a
+    recompressed PNG IDAT (or any large binary) can contain the bytes ``c2pa``
+    by chance (verified 2026-05-29: 4 cleaned PNGs re-flagged this way after
+    their manifest was correctly stripped). Every real manifest is JUMBF-wrapped
+    (the ``jumb`` box FourCC accompanies the ``c2pa`` content type) or uses the
+    standalone C2PA ``uuid`` box in ISOBMFF, so we require one of those: the
+    joint ``jumb`` + ``c2pa`` match has negligible random-collision probability.
+    """
+    return C2PA_UUID in data or (b"jumb" in data and b"c2pa" in data.lower())
+
+
 # IPTC ``digitalSourceType`` values (IPTC 2025.1) that flag AI provenance.
 # Used by Instagram, Facebook, X (Twitter) to show "Made with AI" labels.
 IPTC_AI_MARKERS: tuple[bytes, ...] = (
@@ -108,6 +126,27 @@ AIGC_MARKERS: tuple[bytes, ...] = (
     b"TC260:AIGC",
 )
 
+# TC260 AIGC-label JSON fields (the standard's labeling object). Doubao writes
+# the same object as a PNG ``tEXt`` chunk keyed ``AIGC`` (raw JSON, not XMP), so
+# a JSON object carrying at least one of these is accepted as a valid TC260
+# label even when the namespaced XMP element is absent.
+_TC260_FIELDS: frozenset[str] = frozenset(
+    {
+        "Label",
+        "ContentProducer",
+        "ProduceID",
+        "ContentPropagator",
+        "PropagateID",
+        "ReservedCode1",
+        "ReservedCode2",
+    }
+)
+
+# HuggingFace-hosted GPU jobs (Jobs / Spaces) stamp generated PNGs with this
+# ``tEXt`` chunk key holding the job UUID. It marks the hosting job, not a
+# specific model -- a medium-confidence AI signal (commonly diffusion output).
+_HF_JOB_KEY: str = "hf-job-id"
+
 STANDARD_METADATA_KEYS: frozenset[str] = frozenset(
     [
         "Author",
@@ -132,6 +171,105 @@ def _is_ai_key(key: str) -> bool:
     return any(kw in key_lower for kw in AI_KEYWORDS)
 
 
+# PNG ancillary chunks that can carry provenance metadata (XMP, EXIF, text).
+# Never IDAT -- that is the compressed pixel stream.
+_PNG_META_CHUNKS: frozenset[bytes] = frozenset({b"tEXt", b"iTXt", b"zTXt", b"eXIf", b"iCCP"})
+
+
+def _png_late_metadata(image_path: Path, window: int) -> bytes:
+    """Payloads of PNG metadata chunks that start *beyond* the first ``window``
+    bytes, found by seeking past the (large) ``IDAT`` pixel stream.
+
+    A PNG encoder may append the XMP/EXIF packet after the image data, so a
+    fixed first-``size`` read misses it (e.g. a TC260 AIGC label in an XMP
+    ``iTXt`` chunk at ~2.7 MB). This is the PNG analogue of the ISOBMFF
+    late-box scan in :func:`scan_head`. Returns only chunks past ``window`` so
+    bytes already in the head are not duplicated; empty when there are none.
+    """
+    out = bytearray()
+    try:
+        with open(image_path, "rb") as f:
+            if f.read(8) != b"\x89PNG\r\n\x1a\n":
+                return b""
+            f.seek(0, 2)
+            file_size = f.tell()
+            pos = 8
+            while True:
+                f.seek(pos)
+                header = f.read(8)
+                if len(header) < 8:
+                    break
+                (length,) = struct.unpack(">I", header[:4])
+                chunk_type = header[4:8]
+                if chunk_type == b"IEND":
+                    break
+                data_start = pos + 8
+                # Clamp the attacker-controlled 32-bit length to the bytes that
+                # actually remain, so a malformed huge length can't allocate GBs.
+                safe_length = max(0, min(length, file_size - data_start))
+                if chunk_type in _PNG_META_CHUNKS and data_start >= window:
+                    f.seek(data_start)
+                    out += f.read(safe_length)
+                # Advance by the CLAMPED length: a malformed/inflated `length` that
+                # overshoots EOF must not push `pos` past the file and abort the scan
+                # (which would silently skip a genuine AI-label chunk after it).
+                pos = data_start + safe_length + 4  # data + CRC
+    except OSError as exc:
+        logger.debug("PNG late-metadata scan failed on %s: %s", image_path, exc)
+        return b""
+    return bytes(out)
+
+
+def scan_head(image_path: Path, size: int = 1024 * 1024) -> bytes:
+    """First ``size`` bytes of the file, plus the payloads of any provenance
+    metadata found beyond that window: ISOBMFF ``uuid`` / ``jumb`` boxes (seeking
+    past large boxes like ``mdat``) and PNG ``tEXt`` / ``iTXt`` / ``eXIf`` chunks
+    (seeking past ``IDAT``).
+
+    This is the shared input for every C2PA / AIGC / IPTC byte scan. The
+    extensions catch a manifest or XMP packet placed AFTER the media data -- a
+    non-faststart MP4 manifest, or a PNG XMP packet appended after the pixels --
+    which a fixed first-MB read would miss. For other inputs, and for files that
+    fit within ``size``, it is exactly ``f.read(size)`` -- behavior-neutral.
+
+    The result is memoized per (path, size, mtime): one ``identify``/``get_ai_metadata``
+    call fans out to ~8 byte-scan detectors that each call this on the same file, so
+    the cache turns those repeated reads into one. The mtime key invalidates the entry
+    when the file changes; the small ``maxsize`` bounds memory to a few MB.
+    """
+    try:
+        mtime = image_path.stat().st_mtime_ns
+    except OSError:
+        # No stat (e.g. a pipe, or a race): read uncached rather than fail.
+        return _scan_head_impl(image_path, size)
+    return _scan_head_cached(str(image_path), size, mtime)
+
+
+@functools.lru_cache(maxsize=8)
+def _scan_head_cached(path_str: str, size: int, _mtime_ns: int) -> bytes:
+    """Cache shim: ``_mtime_ns`` is part of the key only (invalidates on change)."""
+    from pathlib import Path as _Path
+
+    return _scan_head_impl(_Path(path_str), size)
+
+
+def _scan_head_impl(image_path: Path, size: int) -> bytes:
+    with open(image_path, "rb") as f:
+        head = f.read(size)
+    # Lazy import: isobmff imports this module's constants at top level.
+    from remove_ai_watermarks.noai import isobmff
+
+    if isobmff.is_isobmff(head):
+        region = isobmff.scan_c2pa_region(image_path)
+        if region:
+            head += region
+    elif head[:8] == b"\x89PNG\r\n\x1a\n" and len(head) == size:
+        # len(head) == size means the file is at least `size` bytes, so metadata
+        # chunks may lie beyond the window; otherwise the whole PNG is in `head`.
+        head += _png_late_metadata(image_path, size)
+    return head
+
+
 def has_ai_metadata(image_path: Path) -> bool:
     """Check if an image contains AI-generation metadata.
 
@@ -143,14 +281,13 @@ def has_ai_metadata(image_path: Path) -> bool:
     """
     from PIL import Image
 
-    # PIL may not handle AVIF/HEIF/JPEG-XL without the optional plugins
-    # (ultralytics also monkey-patches Image.open in a way that can raise
-    # ModuleNotFoundError when pi_heif autoload fails), so any open failure
-    # falls through to the binary scan.
+    # PIL may not handle AVIF/HEIF/JPEG-XL without the optional plugins, and a
+    # third-party plugin autoload can raise a non-OSError (e.g. ModuleNotFoundError),
+    # so any open failure falls through to the binary scan.
     try:
         with Image.open(image_path) as img:
             for key in img.info:
-                if _is_ai_key(key):
+                if isinstance(key, str) and _is_ai_key(key):
                     return True
     except Exception as exc:
         logger.debug("PIL could not open %s for metadata scan: %s", image_path, exc)
@@ -159,7 +296,8 @@ def has_ai_metadata(image_path: Path) -> bool:
     # binary scan that also catches AVIF/HEIF/JPEG-XL containers (PIL doesn't
     # expose their metadata uniformly).
     try:
-        from c2pa import has_c2pa_metadata
+        # optional official lib, not a declared dep -> falls back to the binary scan
+        from c2pa import has_c2pa_metadata  # pyright: ignore[reportMissingImports, reportUnknownVariableType]
 
         if has_c2pa_metadata(image_path):
             return True
@@ -167,12 +305,9 @@ def has_ai_metadata(image_path: Path) -> bool:
         pass
 
     # Binary scan covers C2PA (PNG caBX, JPEG APP11, AVIF/HEIF/JXL uuid boxes)
-    # and IPTC AI markers in XMP. Read only the first 512KB to bound memory.
-    with open(image_path, "rb") as f:
-        data = f.read(512 * 1024)
-    if b"c2pa" in data.lower() or b"C2PA" in data:
-        return True
-    if C2PA_UUID in data:
+    # and IPTC AI markers in XMP. First 512KB (plus late ISOBMFF provenance boxes).
+    data = scan_head(image_path, 512 * 1024)
+    if c2pa_marker_in(data):
         return True
     if any(marker in data for marker in AIGC_MARKERS):
         return True
@@ -181,32 +316,150 @@ def has_ai_metadata(image_path: Path) -> bool:
     # IPTC 2025.1 AI-disclosure XMP properties (their presence flags AI content).
     if any(marker in data for marker in IPTC_AI_FIELD_MARKERS):
         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):
+        return True
+    # HuggingFace-hosted job marker (hf-job-id PNG text chunk).
+    if huggingface_job(image_path):
+        return True
     # xAI / Grok: no C2PA/IPTC/XMP -- only the EXIF Signature + UUID-Artist pair.
     return xai_signature(image_path)
 
 
 def aigc_label(image_path: Path) -> dict[str, str] | None:
-    """Parse a China TC260 ``<TC260:AIGC>`` AI-labeling block, if present.
+    """Parse a China TC260 AI-labeling block, if present.
+
+    Three serializations are recognized:
+
+    - a PNG ``tEXt``/``iTXt`` chunk keyed ``AIGC`` carrying the raw JSON object
+      (as written by Doubao / ByteDance), read via PIL;
+    - an XMP ``<TC260:AIGC>{...}</TC260:AIGC>`` block (HTML-entity encoded text),
+      found by a container-agnostic raw-byte scan (PNG/JPEG/WebP alike); and
+    - a raw-JSON ``{"AIGC":{...}}`` block with no namespace, as embedded in JPEG
+      EXIF (UserComment) by some China-served generators, brace-matched from the
+      scan head.
 
     Returns the decoded JSON (e.g. ``{"Label": "1", "ContentProducer": ...}``)
-    or None. The block is XMP text (HTML-entity encoded), so it is found by a
-    container-agnostic raw-byte scan and works for PNG/JPEG/WebP alike.
+    or None. The generic forms (the PNG-chunk key ``AIGC`` and the bare
+    ``{"AIGC":...}`` object) are accepted only if they carry at least one known
+    TC260 field (``_TC260_FIELDS``); the namespaced XMP element is unambiguous,
+    so any JSON object is accepted.
     """
     import html
     import json
-    import re
+    from typing import cast
 
-    with open(image_path, "rb") as f:
-        data = f.read(1024 * 1024)
-    match = re.search(rb"<TC260:AIGC>(.*?)</TC260:AIGC>", data, re.DOTALL)
-    if not match:
-        return None
-    raw = html.unescape(match.group(1).decode("utf-8", "replace"))
+    def _parse(text: str, *, require_tc260_field: bool) -> dict[str, str] | None:
+        try:
+            parsed = json.loads(text)
+        except ValueError:
+            return None
+        if not isinstance(parsed, dict):
+            return None
+        fields = {str(k): str(v) for k, v in cast("dict[object, object]", parsed).items()}
+        if require_tc260_field and not (_TC260_FIELDS & fields.keys()):
+            return None
+        return fields
+
+    # PNG tEXt chunk keyed "AIGC" with raw JSON (Doubao and other China gens).
+    # The key is generic, so require a TC260 field to avoid a false positive.
     try:
-        parsed = json.loads(raw)
-    except ValueError:
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            value = img.info.get("AIGC")
+    except Exception as exc:
+        logger.debug("PIL could not open %s for AIGC chunk scan: %s", image_path, exc)
+        value = None
+    if isinstance(value, str) and (result := _parse(value, require_tc260_field=True)):
+        return result
+
+    # XMP TC260:AIGC, namespaced (unambiguous) in either serialization RDF allows:
+    # an element  <TC260:AIGC>{...}</TC260:AIGC>  or an attribute  TC260:AIGC="{...}"
+    # (the attribute form is what PicWish writes). Both are HTML-entity encoded.
+    data = scan_head(image_path)
+    match = re.search(
+        rb'<TC260:AIGC>(.*?)</TC260:AIGC>|TC260:AIGC\s*=\s*"(.*?)"',
+        data,
+        re.DOTALL,
+    )
+    if match:
+        body = match.group(1) if match.group(1) is not None else match.group(2)
+        return _parse(html.unescape(body.decode("utf-8", "replace")), require_tc260_field=False)
+
+    # Raw-JSON {"AIGC":{...}} block (no namespace), as written into JPEG EXIF
+    # (UserComment) by some China-served generators -- the PNG-chunk and XMP
+    # paths above both miss it. The bytes pre-check keeps the common (no-AIGC)
+    # path off the full-buffer decode; raw_decode then brace-matches the inner
+    # object (respecting nested braces / quoted strings) and `_parse` applies the
+    # same dict coercion + TC260-field gate as the generic PNG-chunk path.
+    if b'"AIGC"' in data:
+        text = data.decode("latin-1")
+        brace = text.find("{", text.find('"AIGC"') + len('"AIGC"'))
+        if brace != -1:
+            try:
+                _, end = json.JSONDecoder().raw_decode(text, brace)
+            except ValueError:
+                return None
+            return _parse(text[brace:end], require_tc260_field=True)
+    return None
+
+
+def huggingface_job(image_path: Path) -> str | None:
+    """Return the HuggingFace job id if the image carries an ``hf-job-id`` PNG
+    text chunk, else None.
+
+    HuggingFace-hosted GPU jobs (Jobs / Spaces) stamp generated PNGs with an
+    ``hf-job-id`` ``tEXt`` chunk holding the job's UUID. It identifies the
+    *hosting job*, not a specific model, and is most commonly seen on diffusion-
+    generation output -- a medium-confidence AI signal, not proof of AI pixels
+    on its own.
+    """
+    try:
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            value = img.info.get(_HF_JOB_KEY)
+    except Exception as exc:
+        logger.debug("PIL could not open %s for hf-job-id scan: %s", image_path, exc)
         return None
-    return {str(k): str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else None
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+# Samsung Galaxy AI editing marker. Galaxy AI tools (Generative Edit, Sketch to
+# Image, Portrait Studio, Drawing Assist, ...) record their re-edit data as a
+# proprietary ``PhotoEditor_Re_Edit_Data`` JSON that carries a ``genAIType``
+# field; a non-zero value flags that a generative-AI tool produced or altered
+# the pixels. The field is undocumented by Samsung (verified 2026-05-29: absent
+# from the C2PA spec and Samsung's public docs/forums), so detection is
+# empirical -- on real Galaxy S23/S24/S25 files it co-occurs with the C2PA
+# ``trainedAlgorithmicMedia`` source type (3/3 of the verified files that record
+# that type), and on a Galaxy S24 sample it is the *only* AI marker (the C2PA
+# source type was absent there). Medium confidence: it signals Galaxy AI editing
+# without proving the whole image is AI-generated. Scoped to the Samsung editor
+# container to avoid matching a stray ``genAIType`` token elsewhere.
+_SAMSUNG_GENAI_RE = re.compile(rb'genAIType"\s*:\s*(-?\d+)')
+_SAMSUNG_EDITOR_MARKER = b"PhotoEditor_Re_Edit_Data"
+
+
+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.
+    """
+    head = scan_head(image_path, 512 * 1024)
+    if _SAMSUNG_EDITOR_MARKER not in head:
+        return None
+    m = _SAMSUNG_GENAI_RE.search(head)
+    if m is None:
+        return None
+    return int(m.group(1)) or None
 
 
 def iptc_ai_system(image_path: Path) -> str | None:
@@ -219,8 +472,7 @@ def iptc_ai_system(image_path: Path) -> str | None:
     extractable, otherwise the literal ``"fields present"``. Container-agnostic
     raw-byte scan; handles both XMP element and attribute serializations.
     """
-    with open(image_path, "rb") as f:
-        data = f.read(1024 * 1024)
+    data = scan_head(image_path)
     if not any(marker in data for marker in IPTC_AI_FIELD_MARKERS):
         return None
     match = re.search(rb"AISystemUsed[=:\s]*[\"'>]\s*([^<\"']{1,120})", data)
@@ -259,9 +511,8 @@ def synthid_source(image_path: Path) -> str | None:
     # Non-PNG containers (JPEG APP11, WebP, AVIF/HEIF/JXL uuid box) keep the
     # C2PA manifest where the PNG parser can't reach it. Binary-scan for the
     # same signal: a C2PA manifest from a SynthID-using issuer on AI content.
-    with open(image_path, "rb") as f:
-        data = f.read(1024 * 1024)
-    has_c2pa = b"c2pa" in data.lower() or C2PA_UUID in data
+    data = scan_head(image_path)
+    has_c2pa = c2pa_marker_in(data)
     # Matches both "trainedAlgorithmicMedia" and "compositeWithTrainedAlgorithmicMedia".
     ai_source = b"trainedAlgorithmicMedia" in data or b"TrainedAlgorithmicMedia" in data
     if not (has_c2pa and ai_source):
@@ -311,8 +562,7 @@ def exif_generator(image_path: Path) -> str | None:
 
     # XMP CreatorTool: text, container-agnostic (covers HEIF/JXL via raw scan).
     try:
-        with open(image_path, "rb") as f:
-            head = f.read(1024 * 1024)
+        head = scan_head(image_path)
         for match in re.finditer(rb"CreatorTool[>\"'=\s]{1,4}([^<\"']{1,80})", head):
             candidates.append(match.group(1).decode("latin1", "replace"))
     except Exception as exc:
@@ -336,7 +586,7 @@ def _is_xai_signature_pair(description: str, artist: str) -> bool:
     return _XAI_SIGNATURE_RE.match(description) is not None and _UUID_RE.fullmatch(artist) is not None
 
 
-def _exif_text(ifd: dict, tag: int) -> str:
+def _exif_text(ifd: dict[int, Any], tag: int) -> str:
     """Decode a piexif 0th-IFD byte tag to a stripped string ('' if absent)."""
     value = ifd.get(tag)
     return value.decode("latin1", "replace").strip() if isinstance(value, bytes) else ""
@@ -372,7 +622,7 @@ def xai_signature(image_path: Path) -> bool:
     )
 
 
-def _scrub_ai_exif(exif_dict: dict) -> list[str]:
+def _scrub_ai_exif(exif_dict: dict[str, Any]) -> list[str]:
     """Delete AI-provenance tags from a piexif dict's ``0th`` IFD, in place.
 
     Removes (a) the xAI/Grok signature pair (``ImageDescription`` "Signature: ..."
@@ -430,13 +680,13 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
 
     result: dict[str, str] = {}
 
-    # PIL may not open AVIF/HEIF/JPEG-XL without optional plugins (and
-    # ultralytics' Image.open patch can raise ModuleNotFoundError); fall through
-    # to the C2PA/binary path on any open failure. See CLAUDE.md.
+    # PIL may not open AVIF/HEIF/JPEG-XL without optional plugins (and a
+    # third-party plugin autoload can raise a non-OSError); fall through to the
+    # C2PA/binary path on any open failure. See CLAUDE.md.
     try:
         with Image.open(image_path) as img:
             for key, value in img.info.items():
-                if _is_ai_key(key):
+                if isinstance(key, str) and _is_ai_key(key):
                     if isinstance(value, bytes):
                         result[key] = f"<binary {len(value)} bytes>"
                     elif isinstance(value, str) and len(value) > 200:
@@ -467,8 +717,7 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
     if "synthid_watermark" not in result and (vendor := synthid_source(image_path)):
         result.setdefault("synthid_watermark", synthid_verdict(vendor))
     if "soft_binding" not in result:
-        with open(image_path, "rb") as f:
-            head = f.read(1024 * 1024)
+        head = scan_head(image_path)
         if vendors := soft_binding_vendors_in(head):
             result["soft_binding"] = ", ".join(vendors)
 
@@ -484,6 +733,13 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
     # IPTC 2025.1 AI-disclosure XMP fields (Iptc4xmpExt:AISystemUsed etc.).
     if system := iptc_ai_system(image_path):
         result.setdefault("ai_system", f"IPTC 2025.1 AI disclosure ({system})")
+
+    # HuggingFace-hosted job marker (hf-job-id PNG text chunk).
+    if job := huggingface_job(image_path):
+        result.setdefault("huggingface_job", f"HuggingFace-hosted job ({job})")
+    # Samsung Galaxy AI editing marker (genAIType in PhotoEditor_Re_Edit_Data).
+    if (genai := samsung_genai(image_path)) is not None:
+        result.setdefault("samsung_genai", f"Samsung Galaxy AI editing marker (genAIType={genai})")
     return result
 
 
@@ -507,10 +763,18 @@ def _strip_with_ffmpeg(source_path: Path, output_path: Path) -> Path:
         )
     output_path.parent.mkdir(parents=True, exist_ok=True)
     cmd = [
-        ffmpeg, "-y", "-loglevel", "error",
-        "-i", str(source_path),
-        "-map_metadata", "-1", "-map_chapters", "-1",
-        "-c", "copy",
+        ffmpeg,
+        "-y",
+        "-loglevel",
+        "error",
+        "-i",
+        str(source_path),
+        "-map_metadata",
+        "-1",
+        "-map_chapters",
+        "-1",
+        "-c",
+        "copy",
         str(output_path),
     ]
     result = subprocess.run(cmd, capture_output=True, text=True, check=False)  # noqa: S603
@@ -551,16 +815,25 @@ def remove_ai_metadata(
     # codestream bit-for-bit. MP4/MOV/M4A are ISOBMFF too, so the same top-level
     # uuid/jumb box walker applies. Route by suffix OR by an ``ftyp`` content
     # sniff, so a correctly-shaped container is handled whatever its extension.
-    from remove_ai_watermarks.noai.isobmff import is_isobmff, strip_c2pa_boxes
+    from remove_ai_watermarks.noai.isobmff import blank_ai_xmp_packets, is_isobmff, strip_c2pa_boxes
 
     with open(source_path, "rb") as f:
         head = f.read(12)
     if source_path.suffix.lower() in _ISOBMFF_EXTS or is_isobmff(head):
         data = source_path.read_bytes()
+        # Top-level uuid/jumb boxes (C2PA + AI-label XMP), then AI-label XMP that
+        # lives inside a meta-box ``mime`` item (HEIF/AVIF) -- blanked in place so
+        # box sizes and iloc offsets stay valid and the coded image is untouched.
         cleaned, stripped = strip_c2pa_boxes(data)
+        cleaned, blanked = blank_ai_xmp_packets(cleaned)
         output_path.parent.mkdir(parents=True, exist_ok=True)
         output_path.write_bytes(cleaned)
-        logger.info("Stripped %d AI-provenance box(es) → %s", stripped, output_path)
+        logger.info(
+            "Stripped %d AI-provenance box(es), blanked %d meta-box XMP packet(s) → %s",
+            stripped,
+            blanked,
+            output_path,
+        )
         return output_path
 
     # Non-ISOBMFF audio/video (WebM/Matroska EBML, MP3 ID3, WAV/FLAC/OGG): the
@@ -574,11 +847,23 @@ def remove_ai_metadata(
         img = img.copy()
         fmt = output_path.suffix.lower()
 
-        save_kwargs: dict = {}
+        save_kwargs: dict[str, Any] = {}
         if fmt in (".jpg", ".jpeg"):
             save_kwargs["format"] = "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.
+            save_kwargs["quality"] = 95
+            save_kwargs["subsampling"] = 0
             if img.mode in ("RGBA", "P"):
                 img = img.convert("RGB")
+        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"
 
@@ -587,6 +872,8 @@ def remove_ai_metadata(
         exif_data = None
 
         for key, value in img.info.items():
+            if not isinstance(key, str):
+                continue
             if _is_ai_key(key):
                 continue
             if key == "exif":

src/remove_ai_watermarks/noai/__init__.py

@@ -1,9 +1,36 @@
 """Vendored noai-watermark code for invisible watermark removal.
 
 Original: https://github.com/mertizci/noai-watermark (MIT License)
+
+The public API (``WatermarkRemover`` / ``remove_watermark`` / ``remove_ai_metadata``)
+is exposed **lazily** via PEP 562 ``__getattr__``: importing a light submodule
+(e.g. ``noai.c2pa`` / ``noai.constants`` from ``identify``) must NOT eagerly pull
+``watermark_remover``, which imports torch + diffusers at module top. Keeping this
+lazy is what lets ``import remove_ai_watermarks.identify`` stay cheap (~36 MB, no
+torch) even in a full install where the ``gpu``/``detect`` extras are present --
+otherwise the mere presence of torch in the env inflated identify to ~420 MB and
+risked OOM on a 512 MB host.
 """
 
-from remove_ai_watermarks.noai.cleaner import remove_ai_metadata
-from remove_ai_watermarks.noai.watermark_remover import WatermarkRemover, remove_watermark
+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.noai.watermark_remover import WatermarkRemover, remove_watermark
 
 __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
+
+        return remove_ai_metadata
+    if name in ("WatermarkRemover", "remove_watermark"):
+        from remove_ai_watermarks.noai import watermark_remover
+
+        return getattr(watermark_remover, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/remove_ai_watermarks/noai/c2pa.py

@@ -55,6 +55,9 @@ def has_c2pa_metadata(image_path: Path) -> bool:
             if signature != PNG_SIGNATURE:
                 return False
 
+            file_size = f.seek(0, 2)
+            f.seek(8)
+
             while True:
                 chunk_header = f.read(8)
                 if len(chunk_header) < 8:
@@ -62,9 +65,12 @@ def has_c2pa_metadata(image_path: Path) -> bool:
 
                 length = struct.unpack(">I", chunk_header[:4])[0]
                 chunk_type = chunk_header[4:8]
+                # Clamp the attacker-controlled 32-bit length to the bytes that
+                # actually remain, so a malformed huge length can't allocate GBs.
+                safe_length = max(0, min(length, file_size - f.tell()))
 
                 if chunk_type == C2PA_CHUNK_TYPE:
-                    chunk_data = f.read(length)
+                    chunk_data = f.read(safe_length)
                     # Check for any C2PA signature
                     for sig in C2PA_SIGNATURES:
                         if sig in chunk_data:
@@ -74,7 +80,7 @@ def has_c2pa_metadata(image_path: Path) -> bool:
                         return True
                     f.read(4)
                 else:
-                    f.read(length + 4)
+                    f.seek(safe_length + 4, 1)
 
                 if chunk_type == b"IEND":
                     break
@@ -108,6 +114,9 @@ def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
             if signature != PNG_SIGNATURE:
                 return c2pa_info
 
+            file_size = f.seek(0, 2)
+            f.seek(8)
+
             while True:
                 chunk_header = f.read(8)
                 if len(chunk_header) < 8:
@@ -115,13 +124,16 @@ def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
 
                 length = struct.unpack(">I", chunk_header[:4])[0]
                 chunk_type = chunk_header[4:8]
+                # Clamp the attacker-controlled 32-bit length to the bytes that
+                # actually remain, so a malformed huge length can't allocate GBs.
+                safe_length = max(0, min(length, file_size - f.tell()))
 
                 if chunk_type == C2PA_CHUNK_TYPE:
-                    chunk_data = f.read(length)
+                    chunk_data = f.read(safe_length)
                     _parse_c2pa_chunk(chunk_data, c2pa_info)
                     f.read(4)
                 else:
-                    f.read(length + 4)
+                    f.seek(safe_length + 4, 1)
 
                 if chunk_type == b"IEND":
                     break
@@ -278,6 +290,9 @@ def extract_c2pa_chunk(image_path: Path) -> bytes | None:
             if signature != PNG_SIGNATURE:
                 return None
 
+            file_size = f.seek(0, 2)
+            f.seek(8)
+
             while True:
                 chunk_header = f.read(8)
                 if len(chunk_header) < 8:
@@ -285,9 +300,12 @@ def extract_c2pa_chunk(image_path: Path) -> bytes | None:
 
                 length = struct.unpack(">I", chunk_header[:4])[0]
                 chunk_type = chunk_header[4:8]
+                # Clamp the attacker-controlled 32-bit length to the bytes that
+                # actually remain, so a malformed huge length can't allocate GBs.
+                safe_length = max(0, min(length, file_size - f.tell()))
 
                 if chunk_type == C2PA_CHUNK_TYPE:
-                    chunk_data = f.read(length)
+                    chunk_data = f.read(safe_length)
                     crc = f.read(4)
 
                     # Check for any C2PA signature
@@ -299,7 +317,7 @@ def extract_c2pa_chunk(image_path: Path) -> bytes | None:
                     if b"jumb" in chunk_data.lower() or b"c2pa" in chunk_data.lower():
                         return chunk_header + chunk_data + crc
                 else:
-                    f.read(length + 4)
+                    f.seek(safe_length + 4, 1)
 
                 if chunk_type == b"IEND":
                     break

src/remove_ai_watermarks/noai/cleaner.py

@@ -94,6 +94,8 @@ def _extract_non_ai_metadata(source_path: Path, keep_standard: bool) -> dict[str
 
         # Extract non-AI metadata
         for key, value in img.info.items():
+            if not isinstance(key, str):
+                continue
             if _is_ai_metadata_key(key):
                 continue
 
@@ -127,7 +129,7 @@ def _is_ai_metadata_key(key: str) -> bool:
 
 def _prepare_clean_png_kwargs(save_kwargs: dict[str, Any], metadata: dict[str, Any]) -> dict[str, Any]:
     """Prepare save kwargs for clean PNG."""
-    pnginfo = {}
+    pnginfo: dict[str, Any] = {}
     exclude_keys = ["exif", "exif_raw", "dpi", "gamma"]
 
     for key, value in metadata.items():

src/remove_ai_watermarks/noai/constants.py

@@ -4,6 +4,8 @@ All modules reference these constants rather than hard-coding values,
 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"}
 
@@ -78,17 +80,56 @@ C2PA_SIGNATURES = [
     b"manifest",
 ]
 
-# C2PA known issuers
-C2PA_ISSUERS = {
-    b"Google": "Google LLC",
-    b"Adobe": "Adobe",
-    b"Microsoft": "Microsoft",
-    b"OpenAI": "OpenAI",
-    b"Truepic": "Truepic",
+
+# Single source of truth for every C2PA-signing vendor. The three per-vendor
+# facts that used to live in separate tables -- the issuer byte signature
+# (C2PA_ISSUERS), the SynthID pairing (SYNTHID_C2PA_ISSUERS), and the human
+# platform label (identify._ISSUER_PLATFORM) -- are all fields here, so adding a
+# new C2PA vendor is a single append below; the views derive automatically.
+class C2paAiVendor(NamedTuple):
+    issuer: bytes  # distinctive byte signature scanned in the manifest (cert org / signer)
+    org: str  # resolved issuer/cert-org display name (the old C2PA_ISSUERS value)
+    # Human platform label for identify; None marks a signing authority / non-generator
+    # (e.g. Truepic), which never names an AI platform on its own.
+    platform: str | None
+    # Substring matched against the joined issuer-org names for platform attribution
+    # (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
+
+
+# C2PA known vendors, ORDERED for first-match-wins platform attribution: when a
+# manifest names several issuers (Microsoft Designer signs as "OpenAI, Microsoft"),
+# the earlier entry wins so the product, not the backend engine, is named.
+# Used by Google Imagen, Adobe Firefly, Microsoft Designer, OpenAI, etc.
+C2PA_AI_VENDORS: tuple[C2paAiVendor, ...] = (
+    # Microsoft signs both Designer and Bing Image Creator; Bing now runs its own
+    # MAI-Image model (not DALL-E), so the label stays model-neutral.
+    C2paAiVendor(b"Microsoft", "Microsoft", "Microsoft (Bing Image Creator / Designer)", "Microsoft"),
+    C2paAiVendor(b"Adobe", "Adobe", "Adobe Firefly", "Adobe"),
+    C2paAiVendor(b"OpenAI", "OpenAI", "OpenAI (ChatGPT / gpt-image / DALL-E / Sora)", "OpenAI", synthid=True),
+    C2paAiVendor(b"Google", "Google LLC", "Google (Gemini / Imagen)", "Google", synthid=True),
     # Stability AI signs C2PA as "Stability AI" (cert org "Stability AI Ltd").
     # Verified on a live Brand Studio (DreamStudio successor) output, 2026-05-24.
-    b"Stability AI": "Stability AI",
-}
+    C2paAiVendor(b"Stability AI", "Stability AI", "Stability AI (Stable Image / DreamStudio)", "Stability AI"),
+    # Black Forest Labs (FLUX) API output: claim_generator_info "Black Forest
+    # Labs API" + a c2pa.ai_generated_content assertion + trainedAlgorithmicMedia.
+    # Verified on a real signed FLUX JPEG, 2026-05-29.
+    C2paAiVendor(b"Black Forest Labs", "Black Forest Labs", "Black Forest Labs (FLUX)", "Black Forest Labs"),
+    # ByteDance's Volcano Engine (Volcengine) signs its AI image output with a
+    # cert from certificate_center@volcengine.com -- the platform behind Doubao /
+    # Jimeng. Verified on two real signed JPEGs, 2026-05-29.
+    C2paAiVendor(
+        b"volcengine", "ByteDance (Volcano Engine)", "ByteDance (Doubao / Jimeng / Volcano Engine)", "ByteDance"
+    ),
+    # Truepic is a C2PA signing authority, not an AI generator: no platform label,
+    # never asserts is_ai (the verdict comes from the digital-source-type).
+    C2paAiVendor(b"Truepic", "Truepic", None, None),
+)
+
+# Derived view -- add a vendor to C2PA_AI_VENDORS above, not here.
+# 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}
 
 # C2PA issuers whose signed outputs also carry an invisible SynthID pixel
 # watermark -- a metadata proxy for "SynthID is in the pixels":
@@ -109,7 +150,8 @@ C2PA_ISSUERS = {
 # C2PA manifest alone is not a SynthID signal -- the issuer is. The pixel
 # watermark is not locally detectable (proprietary decoder); the C2PA companion
 # is the proxy, and only while the manifest is intact.
-SYNTHID_C2PA_ISSUERS = frozenset({b"Google", b"OpenAI"})
+# Derived from the `synthid` flag on C2PA_AI_VENDORS -- set it there, not here.
+SYNTHID_C2PA_ISSUERS: frozenset[bytes] = frozenset(v.issuer for v in C2PA_AI_VENDORS if v.synthid)
 
 # C2PA known AI tools
 C2PA_AI_TOOLS = {

src/remove_ai_watermarks/noai/ctrlregen/__init__.py

@@ -1,18 +0,0 @@
-"""CtrlRegen watermark removal via controllable regeneration.
-
-Implements the pipeline from "Image Watermarks Are Removable Using
-Controllable Regeneration from Clean Noise" (ICLR 2025) by Liu et al.
-
-This sub-package uses a ControlNet for spatial guidance (canny edges)
-and a DINOv2-based IP Adapter for semantic guidance to regenerate
-watermarked images from partially noised latents.
-
-Attribution:
-    Based on https://github.com/yepengliu/CtrlRegen .
-"""
-
-from __future__ import annotations
-
-from remove_ai_watermarks.noai.ctrlregen.engine import CtrlRegenEngine, is_ctrlregen_available
-
-__all__ = ["CtrlRegenEngine", "is_ctrlregen_available"]

src/remove_ai_watermarks/noai/ctrlregen/color.py

@@ -1,40 +0,0 @@
-"""Color matching post-processing for CtrlRegen output.
-
-After diffusion-based regeneration, the output image may have slight
-color shifts.  This module uses histogram-based color transfer to
-align the regenerated image's color distribution back to the original.
-
-Attribution:
-    Adapted from https://github.com/yepengliu/CtrlRegen .
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from color_matcher import ColorMatcher
-from color_matcher.normalizer import Normalizer
-from PIL import Image
-
-
-def color_match(reference: Image.Image, source: Image.Image) -> Image.Image:
-    """Transfer the color distribution of *reference* onto *source*.
-
-    Uses a two-pass histogram matching approach (``hm-mkl-hm``) that
-    preserves fine-grained color relationships while correcting global
-    shifts introduced by the regeneration pipeline.
-
-    Args:
-        reference: The original (watermarked) image whose colors should
-            be preserved.
-        source: The regenerated image whose colors will be adjusted.
-
-    Returns:
-        A new PIL Image with the structure of *source* but the color
-        palette of *reference*.
-    """
-    cm = ColorMatcher()
-    ref_np = Normalizer(np.asarray(reference)).type_norm()
-    src_np = Normalizer(np.asarray(source)).type_norm()
-    result = cm.transfer(src=src_np, ref=ref_np, method="hm-mkl-hm")
-    result = Normalizer(result).uint8_norm()
-    return Image.fromarray(result)

src/remove_ai_watermarks/noai/ctrlregen/engine.py

@@ -1,365 +0,0 @@
-"""CtrlRegen engine — orchestrates the full watermark removal pipeline.
-
-Loads the base SD 1.5 model with a ControlNet (spatial control from
-canny edges) and a DINOv2-based IP Adapter (semantic control), then
-runs controllable regeneration with optional color matching.
-
-Attribution:
-    Based on https://github.com/yepengliu/CtrlRegen .
-"""
-
-from __future__ import annotations
-
-import contextlib
-import logging
-import os
-import sys
-import time
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-import torch
-from PIL import Image
-
-from remove_ai_watermarks.noai.progress import make_pipeline_progress
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Availability checks — these imports are optional.
-# ---------------------------------------------------------------------------
-
-_HAS_CONTROLNET_AUX = False
-_HAS_COLOR_MATCHER = False
-_HAS_DIFFUSERS = False
-
-try:
-    from diffusers import AutoencoderKL, ControlNetModel, UniPCMultistepScheduler
-
-    from remove_ai_watermarks.noai.ctrlregen.pipeline import CustomCtrlRegenPipeline
-
-    _HAS_DIFFUSERS = True
-except ImportError:
-    AutoencoderKL = None  # type: ignore[assignment,misc]
-    ControlNetModel = None  # type: ignore[assignment,misc]
-    UniPCMultistepScheduler = None  # type: ignore[assignment,misc]
-    CustomCtrlRegenPipeline = None  # type: ignore[assignment,misc]
-
-try:
-    from controlnet_aux import CannyDetector
-
-    _HAS_CONTROLNET_AUX = True
-except ImportError:
-    CannyDetector = None  # type: ignore[assignment,misc]
-
-try:
-    from remove_ai_watermarks.noai.ctrlregen.color import color_match
-
-    _HAS_COLOR_MATCHER = True
-except ImportError:
-    color_match = None  # type: ignore[assignment]
-
-CTRLREGEN_HF_REPO = "yepengliu/ctrlregen"
-SPATIAL_SUBFOLDER = "spatialnet_ckp/spatial_control_ckp_14000"
-SEMANTIC_SUBFOLDER = "semanticnet_ckp/models"
-SEMANTIC_WEIGHT_NAME = "semantic_control_ckp_435000.bin"
-
-DEFAULT_BASE_MODEL = "SG161222/Realistic_Vision_V4.0_noVAE"
-CUSTOM_VAE_ID = "stabilityai/sd-vae-ft-mse"
-
-PROCESS_SIZE = 512
-DEFAULT_GUIDANCE_SCALE = 2.0
-QUALITY_PROMPT = "best quality, high quality"
-NEGATIVE_PROMPT = "monochrome, lowres, bad anatomy, worst quality, low quality"
-
-CANNY_LOW_THRESHOLD = 100
-CANNY_HIGH_THRESHOLD = 150
-
-TILE_SIZE = 512
-TILE_OVERLAP = 192
-
-
-def is_ctrlregen_available() -> bool:
-    """Return True when all CtrlRegen-specific dependencies are installed."""
-    return _HAS_DIFFUSERS and _HAS_CONTROLNET_AUX and _HAS_COLOR_MATCHER
-
-
-class CtrlRegenEngine:
-    """End-to-end CtrlRegen watermark removal engine.
-
-    Handles model loading, canny edge extraction, controlled denoising,
-    and color-matched post-processing in a single ``run()`` call.
-    """
-
-    def __init__(
-        self,
-        base_model_id: str | None = None,
-        device: str = "cpu",
-        torch_dtype: torch.dtype | None = None,
-        hf_token: str | None = None,
-        progress_callback: Callable[[str], None] | None = None,
-    ) -> None:
-        if not is_ctrlregen_available():
-            missing: list[str] = []
-            if not _HAS_DIFFUSERS:
-                missing.extend(["diffusers", "transformers", "accelerate"])
-            if not _HAS_CONTROLNET_AUX:
-                missing.append("controlnet-aux")
-            if not _HAS_COLOR_MATCHER:
-                missing.append("color-matcher")
-            logger.info("Auto-installing missing dependencies: %s", missing)
-            import subprocess
-
-            try:
-                subprocess.check_call(
-                    [sys.executable, "-m", "pip", "install", *missing],
-                    stdout=subprocess.DEVNULL,
-                    stderr=subprocess.DEVNULL,
-                )
-            except (subprocess.CalledProcessError, FileNotFoundError) as exc:
-                raise ImportError(
-                    "Failed to auto-install missing dependencies: "
-                    + ", ".join(missing)
-                    + ". Try manually: pip install --force-reinstall noai-watermark"
-                ) from exc
-
-        self.base_model_id = base_model_id or DEFAULT_BASE_MODEL
-        self.device = device
-        self.torch_dtype = torch_dtype or (torch.float32 if device in ("cpu", "mps") else torch.float16)
-        self.hf_token: str | None = hf_token or os.environ.get("HF_TOKEN")
-        self._progress_callback = progress_callback
-        self._pipeline: CustomCtrlRegenPipeline | None = None  # type: ignore[assignment]
-        self._canny_detector: CannyDetector | None = None  # type: ignore[assignment]
-
-    def _set_progress(self, message: str) -> None:
-        if self._progress_callback is None:
-            return
-        with contextlib.suppress(Exception):
-            self._progress_callback(message)
-
-    # ------------------------------------------------------------------
-    # Loading
-    # ------------------------------------------------------------------
-
-    def load(self) -> None:
-        """Download and assemble the full CtrlRegen pipeline."""
-        if self._pipeline is not None:
-            return
-
-        token_kwargs: dict[str, Any] = {}
-        if self.hf_token:
-            token_kwargs["token"] = self.hf_token
-
-        self._set_progress(f"Loading CtrlRegen spatial ControlNet from {CTRLREGEN_HF_REPO}...")
-        logger.info("Loading ControlNet from %s/%s", CTRLREGEN_HF_REPO, SPATIAL_SUBFOLDER)
-        controlnet = [
-            ControlNetModel.from_pretrained(
-                CTRLREGEN_HF_REPO,
-                subfolder=SPATIAL_SUBFOLDER,
-                torch_dtype=self.torch_dtype,
-                **token_kwargs,
-            )
-        ]
-
-        self._set_progress(f"Loading SD base model ({self.base_model_id}) for CtrlRegen pipeline...")
-        logger.info("Loading base pipeline from %s", self.base_model_id)
-        pipe = CustomCtrlRegenPipeline.from_pretrained(
-            self.base_model_id,
-            controlnet=controlnet,
-            torch_dtype=self.torch_dtype,
-            safety_checker=None,
-            requires_safety_checker=False,
-            **token_kwargs,
-        )
-
-        self._set_progress(f"Loading CtrlRegen semantic IP-Adapter + DINOv2 from {CTRLREGEN_HF_REPO}...")
-        logger.info("Loading IP-Adapter from %s/%s", CTRLREGEN_HF_REPO, SEMANTIC_SUBFOLDER)
-        pipe.load_ctrlregen_ip_adapter(
-            CTRLREGEN_HF_REPO,
-            subfolder=SEMANTIC_SUBFOLDER,
-            weight_name=SEMANTIC_WEIGHT_NAME,
-            **token_kwargs,
-        )
-
-        from transformers import AutoImageProcessor, AutoModel
-
-        pipe.image_encoder = AutoModel.from_pretrained("facebook/dinov2-giant").to(self.device, dtype=self.torch_dtype)
-        pipe.feature_extractor = AutoImageProcessor.from_pretrained("facebook/dinov2-giant")
-
-        self._set_progress(f"Loading custom VAE ({CUSTOM_VAE_ID})...")
-        logger.info("Loading VAE from %s", CUSTOM_VAE_ID)
-        pipe.vae = AutoencoderKL.from_pretrained(
-            CUSTOM_VAE_ID,
-            torch_dtype=self.torch_dtype,
-            **token_kwargs,
-        )
-
-        self._set_progress("Configuring UniPC scheduler...")
-        pipe.scheduler = UniPCMultistepScheduler.from_config(pipe.scheduler.config)
-        pipe.set_ip_adapter_scale(1.0)
-
-        self._set_progress(f"Moving CtrlRegen pipeline to {self.device}...")
-        pipe = pipe.to(self.device)
-
-        if hasattr(pipe, "enable_xformers_memory_efficient_attention"):
-            with contextlib.suppress(Exception):
-                pipe.enable_xformers_memory_efficient_attention()
-
-        self._pipeline = pipe
-        self._canny_detector = CannyDetector()
-        self._set_progress("CtrlRegen pipeline ready.")
-        logger.info("CtrlRegen pipeline loaded on %s", self.device)
-
-    # ------------------------------------------------------------------
-    # Inference — public entry point
-    # ------------------------------------------------------------------
-
-    def run(
-        self,
-        image: Image.Image,
-        strength: float = 0.5,
-        num_inference_steps: int = 50,
-        guidance_scale: float = DEFAULT_GUIDANCE_SCALE,
-        seed: int | None = None,
-    ) -> Image.Image:
-        """Run CtrlRegen watermark removal on a single image.
-
-        Images that fit within ``TILE_SIZE`` (512) are processed as a
-        single pass.  Larger images are split into overlapping tiles.
-        """
-        self.load()
-        assert self._pipeline is not None
-        assert self._canny_detector is not None
-
-        orig_w, orig_h = image.size
-        orig_image = image
-        t0 = time.monotonic()
-
-        needs_tiling = orig_w > TILE_SIZE or orig_h > TILE_SIZE
-
-        if needs_tiling:
-            from remove_ai_watermarks.noai.ctrlregen.tiling import resize_center_crop, run_tiled
-
-            aligned_w = orig_w // 8 * 8
-            aligned_h = orig_h // 8 * 8
-            if aligned_w != orig_w or aligned_h != orig_h:
-                image = image.resize((aligned_w, aligned_h), Image.LANCZOS)
-            regen_image = run_tiled(
-                pipeline=self._pipeline,
-                canny_detector=self._canny_detector,
-                image=image,
-                strength=strength,
-                num_inference_steps=num_inference_steps,
-                guidance_scale=guidance_scale,
-                seed=seed,
-                tile_size=TILE_SIZE,
-                tile_overlap=TILE_OVERLAP,
-                quality_prompt=QUALITY_PROMPT,
-                negative_prompt=NEGATIVE_PROMPT,
-                canny_low=CANNY_LOW_THRESHOLD,
-                canny_high=CANNY_HIGH_THRESHOLD,
-                device=self.device,
-                set_progress=self._set_progress,
-                ip_adapter_image=orig_image,
-            )
-        else:
-            from remove_ai_watermarks.noai.ctrlregen.tiling import resize_center_crop
-
-            proc_image = resize_center_crop(image, PROCESS_SIZE)
-            self._set_progress(f"Preprocessed {orig_w}x{orig_h}px → {proc_image.size[0]}x{proc_image.size[1]}px")
-            regen_image = self._run_single(
-                proc_image,
-                strength,
-                num_inference_steps,
-                guidance_scale,
-                seed,
-            )
-
-        if regen_image.size != (orig_w, orig_h):
-            self._set_progress(f"Resizing {regen_image.size[0]}x{regen_image.size[1]}px → {orig_w}x{orig_h}px...")
-            regen_image = regen_image.resize((orig_w, orig_h), Image.LANCZOS)
-
-        self._set_progress(f"Applying color matching at {orig_w}x{orig_h}px...")
-        output = color_match(reference=orig_image, source=regen_image)
-
-        self._set_progress(f"✓ CtrlRegen done · {orig_w}x{orig_h}px · {time.monotonic() - t0:.0f}s total")
-        return output
-
-    # ------------------------------------------------------------------
-    # Single-image path (image <= 512x512)
-    # ------------------------------------------------------------------
-
-    def _run_single(
-        self,
-        image: Image.Image,
-        strength: float,
-        num_inference_steps: int,
-        guidance_scale: float,
-        seed: int | None,
-    ) -> Image.Image:
-        """Process a single 512x512 image through the CtrlRegen pipeline."""
-        w, h = image.size
-        effective_steps = max(1, int(num_inference_steps * strength))
-
-        self._set_progress(
-            f"Extracting canny edges ({w}x{h}px, thresholds {CANNY_LOW_THRESHOLD}/{CANNY_HIGH_THRESHOLD})..."
-        )
-        control_image = self._canny_detector(
-            image,
-            low_threshold=CANNY_LOW_THRESHOLD,
-            high_threshold=CANNY_HIGH_THRESHOLD,
-        )
-
-        generator = torch.manual_seed(seed if seed is not None else 0)
-
-        self._set_progress(
-            f"Config: strength={strength}, steps={num_inference_steps} "
-            f"(~{effective_steps} effective), guidance={guidance_scale}"
-        )
-
-        step_cb, first_step, pipeline_done, start_updater = make_pipeline_progress(
-            effective_steps,
-            self.device,
-            self._set_progress,
-            label="CtrlRegen denoising",
-        )
-        start_updater()
-
-        try:
-            result = self._pipeline(
-                prompt=QUALITY_PROMPT,
-                negative_prompt=NEGATIVE_PROMPT,
-                image=[image],
-                control_image=[control_image],
-                controlnet_conditioning_scale=1.0,
-                ip_adapter_image=[image],
-                strength=strength,
-                num_inference_steps=num_inference_steps,
-                guidance_scale=guidance_scale,
-                generator=generator,
-                control_guidance_start=0.0,
-                control_guidance_end=1.0,
-                callback=step_cb,
-                callback_steps=1,
-            )
-        except TypeError:
-            first_step.set()
-            result = self._pipeline(
-                prompt=QUALITY_PROMPT,
-                negative_prompt=NEGATIVE_PROMPT,
-                image=[image],
-                control_image=[control_image],
-                controlnet_conditioning_scale=1.0,
-                ip_adapter_image=[image],
-                strength=strength,
-                num_inference_steps=num_inference_steps,
-                guidance_scale=guidance_scale,
-                generator=generator,
-            )
-        finally:
-            first_step.set()
-            pipeline_done.set()
-
-        return result.images[0]

src/remove_ai_watermarks/noai/ctrlregen/ip_adapter.py

@@ -1,149 +0,0 @@
-"""Custom IP-Adapter mixin using DINOv2 as the image encoder.
-
-The standard diffusers ``IPAdapterMixin`` uses a CLIP image encoder.
-CtrlRegen replaces it with ``facebook/dinov2-giant`` for richer
-semantic features.  This mixin provides ``load_ctrlregen_ip_adapter``
-which handles the custom weight format and encoder swap.
-
-Attribution:
-    Adapted from https://github.com/yepengliu/CtrlRegen .
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-import torch
-from diffusers.models.modeling_utils import _LOW_CPU_MEM_USAGE_DEFAULT
-from diffusers.utils import (
-    _get_model_file,
-    is_accelerate_available,
-    is_torch_version,
-)
-from diffusers.utils import (
-    logging as diffusers_logging,
-)
-from huggingface_hub.utils import validate_hf_hub_args
-from safetensors import safe_open
-from transformers import AutoImageProcessor, AutoModel
-
-logger = logging.getLogger(__name__)
-_diffusers_logger = diffusers_logging.get_logger(__name__)
-
-DINOV2_MODEL_ID = "facebook/dinov2-giant"
-
-
-class CustomIPAdapterMixin:
-    """Mixin that adds ``load_ctrlregen_ip_adapter`` to a diffusers pipeline."""
-
-    @validate_hf_hub_args
-    def load_ctrlregen_ip_adapter(
-        self,
-        pretrained_model_name_or_path_or_dict: str | list[str] | dict[str, torch.Tensor],
-        subfolder: str | list[str],
-        weight_name: str | list[str],
-        image_encoder_folder: str | None = "image_encoder",
-        **kwargs: Any,
-    ) -> None:
-        """Load CtrlRegen IP-Adapter weights and DINOv2 image encoder.
-
-        Parameters mirror ``IPAdapterMixin.load_ip_adapter`` but the
-        image encoder is always ``facebook/dinov2-giant`` regardless of
-        the ``image_encoder_folder`` value in the checkpoint.
-        """
-        if not isinstance(weight_name, list):
-            weight_name = [weight_name]
-        if not isinstance(pretrained_model_name_or_path_or_dict, list):
-            pretrained_model_name_or_path_or_dict = [pretrained_model_name_or_path_or_dict]
-        if len(pretrained_model_name_or_path_or_dict) == 1:
-            pretrained_model_name_or_path_or_dict = pretrained_model_name_or_path_or_dict * len(weight_name)
-        if not isinstance(subfolder, list):
-            subfolder = [subfolder]
-        if len(subfolder) == 1:
-            subfolder = subfolder * len(weight_name)
-
-        if len(weight_name) != len(pretrained_model_name_or_path_or_dict):
-            raise ValueError("`weight_name` and `pretrained_model_name_or_path_or_dict` must have the same length.")
-        if len(weight_name) != len(subfolder):
-            raise ValueError("`weight_name` and `subfolder` must have the same length.")
-
-        cache_dir = kwargs.pop("cache_dir", None)
-        force_download = kwargs.pop("force_download", False)
-        kwargs.pop("resume_download", None)
-        proxies = kwargs.pop("proxies", None)
-        local_files_only = kwargs.pop("local_files_only", None)
-        token = kwargs.pop("token", None)
-        revision = kwargs.pop("revision", None)
-        low_cpu_mem_usage = kwargs.pop("low_cpu_mem_usage", _LOW_CPU_MEM_USAGE_DEFAULT)
-
-        if low_cpu_mem_usage and not is_accelerate_available():
-            low_cpu_mem_usage = False
-            _diffusers_logger.warning(
-                "Cannot initialize model with low cpu memory usage because "
-                "`accelerate` was not found. Defaulting to "
-                "`low_cpu_mem_usage=False`."
-            )
-
-        if low_cpu_mem_usage is True and not is_torch_version(">=", "1.9.0"):
-            raise NotImplementedError("Low memory initialization requires torch >= 1.9.0.")
-
-        user_agent = {
-            "file_type": "attn_procs_weights",
-            "framework": "pytorch",
-        }
-
-        state_dicts: list[dict] = []
-        for path_or_dict, wn, sf in zip(pretrained_model_name_or_path_or_dict, weight_name, subfolder, strict=False):
-            if not isinstance(path_or_dict, dict):
-                model_file = _get_model_file(
-                    path_or_dict,
-                    weights_name=wn,
-                    cache_dir=cache_dir,
-                    force_download=force_download,
-                    proxies=proxies,
-                    local_files_only=local_files_only,
-                    token=token,
-                    revision=revision,
-                    subfolder=sf,
-                    user_agent=user_agent,
-                )
-                if wn.endswith(".safetensors"):
-                    state_dict: dict = {"image_proj": {}, "ip_adapter": {}}
-                    with safe_open(model_file, framework="pt", device="cpu") as f:
-                        for key in f.keys():  # noqa: SIM118
-                            if key.startswith("image_proj."):
-                                state_dict["image_proj"][key.replace("image_proj.", "")] = f.get_tensor(key)
-                            elif key.startswith("ip_adapter."):
-                                state_dict["ip_adapter"][key.replace("ip_adapter.", "")] = f.get_tensor(key)
-                else:
-                    state_dict = torch.load(model_file, map_location="cpu")
-            else:
-                state_dict = path_or_dict
-
-            keys = list(state_dict.keys())
-            if keys != ["image_proj", "ip_adapter"]:
-                raise ValueError("Required keys (`image_proj` and `ip_adapter`) missing from the state dict.")
-            state_dicts.append(state_dict)
-
-        # Always use DINOv2-giant as the image encoder.
-        has_encoder_attr = hasattr(self, "image_encoder") and getattr(self, "image_encoder", None) is None
-        if has_encoder_attr and image_encoder_folder is not None:
-            logger.info("Loading DINOv2-giant image encoder for CtrlRegen")
-            enc_dtype = getattr(self, "dtype", torch.float32)  # type: ignore[attr-defined]
-            image_encoder = AutoModel.from_pretrained(DINOV2_MODEL_ID).to(
-                self.device,
-                dtype=enc_dtype,  # type: ignore[attr-defined]
-            )
-            self.register_modules(image_encoder=image_encoder)  # type: ignore[attr-defined]
-
-        if hasattr(self, "feature_extractor") and getattr(self, "feature_extractor", None) is None:
-            feature_extractor = AutoImageProcessor.from_pretrained(DINOV2_MODEL_ID)
-            self.register_modules(feature_extractor=feature_extractor)  # type: ignore[attr-defined]
-
-        unet = (
-            getattr(self, self.unet_name)  # type: ignore[attr-defined]
-            if not hasattr(self, "unet")
-            else self.unet  # type: ignore[attr-defined]
-        )
-        unet._load_ip_adapter_weights(state_dicts, low_cpu_mem_usage=low_cpu_mem_usage)

src/remove_ai_watermarks/noai/ctrlregen/pipeline.py

@@ -1,35 +0,0 @@
-"""Custom Stable Diffusion ControlNet Img2Img pipeline for CtrlRegen.
-
-Extends ``StableDiffusionControlNetImg2ImgPipeline`` with the
-``load_ctrlregen_ip_adapter`` method (via ``CustomIPAdapterMixin``)
-that swaps in DINOv2-giant as the image encoder and loads the
-CtrlRegen semantic-control adapter weights.
-
-No ``encode_image`` override is needed — the CtrlRegen checkpoint
-creates an ``IPAdapterPlusImageProjection`` which tells diffusers to
-call ``encode_image`` with ``output_hidden_states=True``.  The
-default implementation then uses ``hidden_states[-2]`` from DINOv2,
-which is exactly what the projection was trained on.
-
-Attribution:
-    Adapted from https://github.com/yepengliu/CtrlRegen .
-"""
-
-from __future__ import annotations
-
-from diffusers import StableDiffusionControlNetImg2ImgPipeline
-
-from remove_ai_watermarks.noai.ctrlregen.ip_adapter import CustomIPAdapterMixin
-
-
-class CustomCtrlRegenPipeline(
-    StableDiffusionControlNetImg2ImgPipeline,
-    CustomIPAdapterMixin,
-):
-    """SD ControlNet Img2Img pipeline with DINOv2 IP-Adapter support.
-
-    MRO mirrors the original CtrlRegen repository: the base diffusers
-    pipeline comes first so all standard methods are resolved from it,
-    while ``CustomIPAdapterMixin`` only adds the
-    ``load_ctrlregen_ip_adapter`` method.
-    """

src/remove_ai_watermarks/noai/ctrlregen/tiling.py

@@ -1,177 +0,0 @@
-"""Tile-based processing for large images in the CtrlRegen pipeline.
-
-Extracted from ``ctrlregen.engine`` to keep the engine focused on
-single-image inference and model orchestration.
-"""
-
-from __future__ import annotations
-
-import math
-import time
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-import numpy as np
-import torch
-from PIL import Image
-
-
-def tile_positions(total: int, tile: int, overlap: int) -> list[int]:
-    """Compute evenly-spaced tile start positions covering *total* pixels."""
-    if total <= tile:
-        return [0]
-    n = max(2, math.ceil((total - overlap) / (tile - overlap)))
-    stride = (total - tile) / (n - 1)
-    return [round(i * stride) for i in range(n)]
-
-
-def make_blend_weight(h: int, w: int, overlap: int) -> np.ndarray:
-    """2-D weight mask: 1.0 in center, cosine ramp in overlap margins."""
-    wy = np.ones(h, dtype=np.float64)
-    wx = np.ones(w, dtype=np.float64)
-    if overlap > 0:
-        ramp = 0.5 - 0.5 * np.cos(np.linspace(0, np.pi, overlap))
-        wy[:overlap] = np.minimum(wy[:overlap], ramp)
-        wy[-overlap:] = np.minimum(wy[-overlap:], ramp[::-1])
-        wx[:overlap] = np.minimum(wx[:overlap], ramp)
-        wx[-overlap:] = np.minimum(wx[-overlap:], ramp[::-1])
-    return np.outer(wy, wx)
-
-
-def resize_center_crop(image: Image.Image, size: int = 512) -> Image.Image:
-    """Resize shortest edge to *size*, then center-crop to a square.
-
-    Matches the ``transforms.Resize(512) + CenterCrop(512)`` pipeline
-    used in the original CtrlRegen repository.
-    """
-    w, h = image.size
-    short = min(w, h)
-    scale = size / short
-    new_w, new_h = round(w * scale), round(h * scale)
-    image = image.resize((new_w, new_h), Image.BILINEAR)
-    left = (new_w - size) // 2
-    top = (new_h - size) // 2
-    return image.crop((left, top, left + size, top + size))
-
-
-def run_tiled(
-    pipeline: Any,
-    canny_detector: Any,
-    image: Image.Image,
-    strength: float,
-    num_inference_steps: int,
-    guidance_scale: float,
-    seed: int | None,
-    *,
-    tile_size: int,
-    tile_overlap: int,
-    quality_prompt: str,
-    negative_prompt: str,
-    canny_low: int,
-    canny_high: int,
-    device: str,
-    set_progress: Callable[[str], None],
-    ip_adapter_image: Image.Image | None = None,
-) -> Image.Image:
-    """Split a large image into overlapping tiles, process each, blend."""
-    w, h = image.size
-    xs = tile_positions(w, tile_size, tile_overlap)
-    ys = tile_positions(h, tile_size, tile_overlap)
-    n_tiles = len(xs) * len(ys)
-    grid = f"{len(xs)}x{len(ys)}"
-    effective_steps = max(1, int(num_inference_steps * strength))
-
-    set_progress(f"Tiling {w}x{h}px → {n_tiles} tiles ({grid} grid, {tile_size}px, overlap {tile_overlap}px)")
-
-    canvas = np.zeros((h, w, 3), dtype=np.float64)
-    weight_sum = np.zeros((h, w), dtype=np.float64)
-    blend_w = make_blend_weight(tile_size, tile_size, tile_overlap)
-
-    t0 = time.monotonic()
-    bar_len = 20
-    tile_idx = 0
-
-    for ty in ys:
-        for tx in xs:
-            tile_idx += 1
-            prefix = f"[Tile {tile_idx}/{n_tiles}]"
-
-            tile = image.crop((tx, ty, tx + tile_size, ty + tile_size))
-
-            set_progress(f"{prefix} Extracting canny edges...")
-            control = canny_detector(
-                tile,
-                low_threshold=canny_low,
-                high_threshold=canny_high,
-            )
-
-            gen = None
-            if seed is not None:
-                gen = torch.Generator(device=device).manual_seed(seed + tile_idx)
-
-            tile_t0 = time.monotonic()
-
-            def _make_cb(
-                _prefix: str = prefix,
-                _t0: float = tile_t0,
-                _es: int = effective_steps,
-            ) -> Callable:
-                def _cb(step: int, timestep: int, latents: Any) -> None:
-                    elapsed = time.monotonic() - _t0
-                    cur = step + 1
-                    per = elapsed / max(1, cur)
-                    rem = per * max(0, _es - cur)
-                    filled = int(bar_len * cur / max(1, _es))
-                    bar = "█" * filled + "░" * (bar_len - filled)
-                    set_progress(f"{_prefix} [{bar}] {cur}/{_es} | {elapsed:.0f}s, ~{rem:.0f}s left")
-
-                return _cb
-
-            sem_image = ip_adapter_image if ip_adapter_image is not None else tile
-
-            try:
-                result = pipeline(
-                    prompt=quality_prompt,
-                    negative_prompt=negative_prompt,
-                    image=[tile],
-                    control_image=[control],
-                    controlnet_conditioning_scale=1.0,
-                    ip_adapter_image=[sem_image],
-                    strength=strength,
-                    num_inference_steps=num_inference_steps,
-                    guidance_scale=guidance_scale,
-                    generator=gen,
-                    control_guidance_start=0.0,
-                    control_guidance_end=1.0,
-                    callback=_make_cb(),
-                    callback_steps=1,
-                )
-            except TypeError:
-                result = pipeline(
-                    prompt=quality_prompt,
-                    negative_prompt=negative_prompt,
-                    image=[tile],
-                    control_image=[control],
-                    controlnet_conditioning_scale=1.0,
-                    ip_adapter_image=[sem_image],
-                    strength=strength,
-                    num_inference_steps=num_inference_steps,
-                    guidance_scale=guidance_scale,
-                    generator=gen,
-                )
-
-            proc_arr = np.array(result.images[0], dtype=np.float64)
-            th, tw = proc_arr.shape[:2]
-            mask = blend_w[:th, :tw]
-            canvas[ty : ty + th, tx : tx + tw] += proc_arr * mask[..., None]
-            weight_sum[ty : ty + th, tx : tx + tw] += mask
-
-            tile_time = time.monotonic() - tile_t0
-            total_elapsed = time.monotonic() - t0
-            set_progress(f"{prefix} Done ({tile_time:.0f}s) · Total: {total_elapsed:.0f}s")
-
-    set_progress(f"Blending {n_tiles} tiles → {w}x{h}px...")
-    canvas /= np.maximum(weight_sum[..., None], 1e-8)
-    return Image.fromarray(np.clip(canvas, 0, 255).astype(np.uint8))

src/remove_ai_watermarks/noai/extractor.py

@@ -6,7 +6,7 @@ human-readable summary without modifying the source file.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -46,6 +46,8 @@ def extract_metadata(source_path: Path) -> dict[str, Any]:
 
         # Extract all other metadata including AI-specific
         for key, value in img.info.items():
+            if not isinstance(key, str):
+                continue
             if key not in metadata and key not in ["exif"]:
                 metadata[key] = value
 
@@ -83,6 +85,8 @@ def extract_ai_metadata(source_path: Path) -> dict[str, Any]:
                 ai_metadata[key] = img.info[key]
 
         for key, value in img.info.items():
+            if not isinstance(key, str):
+                continue
             key_lower = key.lower()
             if key not in ai_metadata and any(kw in key_lower for kw in AI_KEYWORDS):
                 ai_metadata[key] = value
@@ -138,7 +142,7 @@ def get_ai_metadata_summary(source_path: Path) -> str:
             continue
         if key == "c2pa" and isinstance(value, dict):
             lines.append("C2PA Metadata:")
-            for ck, cv in value.items():
+            for ck, cv in cast("dict[str, Any]", value).items():
                 lines.append(f"  {ck}: {cv}")
         elif isinstance(value, str) and len(value) > 100:
             value = value[:100] + "..."

src/remove_ai_watermarks/noai/img2img_runner.py

@@ -29,8 +29,14 @@ def run_img2img(
     generator: Any,
     device: str,
     set_progress: Callable[[str], None],
+    extra_kwargs: dict[str, Any] | None = None,
 ) -> Image.Image:
-    """Execute img2img with live progress and return the generated image."""
+    """Execute img2img with live progress and return the generated image.
+
+    ``extra_kwargs`` overlays additional pipeline arguments (e.g. the ControlNet
+    ``control_image`` / ``controlnet_conditioning_scale`` and a non-empty prompt),
+    so a ControlNet img2img pass reuses the same progress + fallback machinery.
+    """
     effective_steps = max(1, int(num_inference_steps * strength))
 
     step_cb, first_step, done_ev, start_updater = make_pipeline_progress(
@@ -42,26 +48,23 @@ def run_img2img(
 
     try:
         result = _call_pipeline(
-            pipeline,
-            image,
-            strength,
-            num_inference_steps,
-            guidance_scale,
-            generator,
-            step_cb,
+            pipeline, image, strength, num_inference_steps, guidance_scale, generator, step_cb, extra_kwargs
         )
         done_ev.set()
         return result.images[0]
-    except TypeError:
+    except TypeError as exc:
+        # The only TypeError we retry is the deprecated-callback case: `_call_pipeline`
+        # passes the legacy `callback`/`callback_steps` kwargs, and a diffusers version
+        # that removed them raises TypeError("... unexpected keyword argument
+        # 'callback'"). We then re-run once WITHOUT the progress callback. Any OTHER
+        # TypeError (e.g. a bad control_image/dtype in the forward pass) is a real error
+        # -- re-raise it instead of silently re-running the whole diffusion pass and
+        # masking the cause.
+        if "callback" not in str(exc):
+            raise
         first_step.set()
         result = _call_pipeline(
-            pipeline,
-            image,
-            strength,
-            num_inference_steps,
-            guidance_scale,
-            generator,
-            None,
+            pipeline, image, strength, num_inference_steps, guidance_scale, generator, None, extra_kwargs
         )
         done_ev.set()
         return result.images[0]
@@ -81,11 +84,13 @@ def run_img2img_with_mps_fallback(
     set_progress: Callable[[str], None],
     *,
     reload_on_cpu: Callable[[], Any],
+    extra_kwargs: dict[str, Any] | None = None,
 ) -> tuple[Image.Image, str]:
     """Run img2img; on MPS error, fall back to CPU.
 
-    Returns:
-        (result_image, final_device) — device may change to ``"cpu"`` on fallback.
+    ``extra_kwargs`` overlays extra pipeline arguments (used by the ControlNet
+    path). Returns ``(result_image, final_device)`` — device may change to
+    ``"cpu"`` on fallback.
     """
     pipeline = load_pipeline()
 
@@ -99,23 +104,17 @@ def run_img2img_with_mps_fallback(
             generator,
             device,
             set_progress,
+            extra_kwargs,
         )
         return img, device
     except RuntimeError as error:
         if device == "mps" and is_mps_error(error):
             logger.warning("MPS error detected: %s. Falling back to CPU.", error)
             set_progress("MPS error! Clearing cache and retrying on CPU...")
-            _try_clear_mps_cache()
+            try_empty_device_cache("mps")
             pipeline = reload_on_cpu()
             img = run_img2img(
-                pipeline,
-                image,
-                strength,
-                num_inference_steps,
-                guidance_scale,
-                None,
-                "cpu",
-                set_progress,
+                pipeline, image, strength, num_inference_steps, guidance_scale, None, "cpu", set_progress, extra_kwargs
             )
             return img, "cpu"
         raise
@@ -129,6 +128,7 @@ def _call_pipeline(
     guidance_scale: float,
     generator: Any,
     step_callback: Any,
+    extra_kwargs: dict[str, Any] | None = None,
 ) -> Any:
     kwargs: dict[str, Any] = {
         "prompt": "",
@@ -138,15 +138,24 @@ def _call_pipeline(
         "guidance_scale": guidance_scale,
         "generator": generator,
     }
+    if extra_kwargs:
+        kwargs.update(extra_kwargs)
     if step_callback is not None:
         kwargs["callback"] = step_callback
         kwargs["callback_steps"] = 1
     return pipeline(**kwargs)
 
 
-def _try_clear_mps_cache() -> None:
+def try_empty_device_cache(device: str) -> None:
+    """Best-effort free of cached GPU/MPS/XPU memory for ``device``.
+
+    ``torch.<device>.empty_cache()`` exists for cuda/mps/xpu but not cpu (the
+    hasattr guard skips the cpu no-op). Never raises -- callers use it as cleanup
+    (the MPS->CPU fallback here, and the batch loop in watermark_remover).
+    """
     with contextlib.suppress(Exception):
         import torch
 
-        if hasattr(torch, "mps"):
-            torch.mps.empty_cache()  # type: ignore[attr-defined]
+        backend = getattr(torch, device, None)
+        if backend is not None and hasattr(backend, "empty_cache"):
+            backend.empty_cache()  # type: ignore[attr-defined]

src/remove_ai_watermarks/noai/isobmff.py

@@ -17,11 +17,14 @@ Reference: ISO/IEC 14496-12 (ISOBMFF) and C2PA 2.1 spec §11.
 
 from __future__ import annotations
 
+import logging
+import re
 import struct
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
+    from pathlib import Path
 
 from remove_ai_watermarks.metadata import (
     AIGC_MARKERS,
@@ -30,6 +33,8 @@ from remove_ai_watermarks.metadata import (
     IPTC_AI_MARKERS,
 )
 
+log = 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
 # are always stripped (JPEG-XL uses them exclusively for JUMBF).
@@ -42,6 +47,12 @@ C2PA_BOX_TYPES: frozenset[bytes] = frozenset({b"uuid", b"jumb"})
 # XMP (copyright, camera info) is kept.
 _AI_LABEL_MARKERS: tuple[bytes, ...] = AIGC_MARKERS + IPTC_AI_MARKERS + IPTC_AI_FIELD_MARKERS
 
+# Adobe XMP packet delimiters (XMP spec part 3). In HEIF/AVIF the XMP packet
+# sits inside a ``meta``-box ``mime`` item whose bytes live in ``mdat`` / ``idat``,
+# out of reach of the top-level box stripper, so an AI-label packet there is
+# blanked in place (see ``blank_ai_xmp_packets``).
+_XMP_PACKET_RE = re.compile(rb"<\?xpacket begin=.*?<\?xpacket end=[^>]*?\?>", re.DOTALL)
+
 
 def _iter_top_level_boxes(data: bytes) -> Iterator[tuple[int, int, bytes, int]]:
     """Yield ``(start, end, type, payload_offset)`` for each top-level box.
@@ -78,6 +89,60 @@ def is_isobmff(data: bytes) -> bool:
     return len(data) >= 8 and data[4:8] == b"ftyp"
 
 
+def scan_c2pa_region(path: str | Path, *, max_total: int = 4 * 1024 * 1024) -> bytes:
+    """Concatenated payloads of top-level ``uuid`` / ``jumb`` boxes in an ISOBMFF
+    file, found by seeking past other boxes (``mdat`` etc.) by size.
+
+    C2PA manifests and XMP packets (incl. AI labels) live in top-level ``uuid``
+    boxes; JPEG-XL uses ``jumb``. In a streaming / non-faststart MP4 the manifest
+    sits AFTER a multi-megabyte ``mdat``, so a fixed first-MB read misses it. This
+    walks box headers (8-16 bytes each) and seeks past payloads it does not need,
+    so it never loads ``mdat`` into memory and works on multi-GB files. Returns
+    the relevant box payloads (capped at ``max_total``), or ``b""`` for a
+    non-ISOBMFF file or on any read error.
+    """
+    collected = bytearray()
+    try:
+        with open(path, "rb") as f:
+            sniff = f.read(8)
+            if len(sniff) < 8 or sniff[4:8] != b"ftyp":
+                return b""
+            f.seek(0, 2)
+            file_size = f.tell()
+            pos = 0
+            while pos + 8 <= file_size and len(collected) < max_total:
+                f.seek(pos)
+                header = f.read(8)
+                if len(header) < 8:
+                    break
+                size32 = struct.unpack(">I", header[:4])[0]
+                box_type = header[4:8]
+                payload_off = pos + 8
+                if size32 == 1:
+                    ext = f.read(8)
+                    if len(ext) < 8:
+                        break
+                    size = struct.unpack(">Q", ext)[0]
+                    payload_off = pos + 16
+                elif size32 == 0:
+                    size = file_size - pos
+                else:
+                    size = size32
+                if size < (payload_off - pos) or pos + size > file_size:
+                    # Detection-only: a malformed box halts the walk, so a manifest
+                    # placed after it is missed (best-effort scan; no resync).
+                    break
+                if box_type in C2PA_BOX_TYPES:
+                    f.seek(payload_off)
+                    to_read = min(pos + size - payload_off, max_total - len(collected))
+                    if to_read > 0:
+                        collected += f.read(to_read)
+                pos += size
+    except OSError:
+        return b""
+    return bytes(collected)
+
+
 def strip_c2pa_boxes(data: bytes) -> tuple[bytes, int]:
     """Return ``(cleaned_bytes, stripped_count)`` with AI-provenance boxes removed.
 
@@ -92,16 +157,19 @@ def strip_c2pa_boxes(data: bytes) -> tuple[bytes, int]:
     All other boxes (incl. ``mdat`` / codestream) are emitted verbatim, so pixel
     and audio data is preserved bit-for-bit. Non-ISOBMFF input is returned
     unchanged. Despite the name this also covers MP4/MOV/M4A video and audio
-    (all ISOBMFF). NOTE: EXIF/XMP stored as *items inside the ``meta`` box*
-    (typical for AVIF/HEIF images) is not removed -- that needs meta-box surgery
-    and is a documented limitation.
+    (all ISOBMFF). NOTE: this drops only top-level boxes. An AI-label XMP packet
+    stored as an *item inside the ``meta`` box* (typical for AVIF/HEIF) is handled
+    separately by :func:`blank_ai_xmp_packets`; an ``Exif`` meta-box item is still
+    not removed (would need meta-box surgery) and remains a documented limitation.
     """
     if not is_isobmff(data):
         return data, 0
 
     out = bytearray()
     stripped = 0
+    consumed = 0
     for start, end, box_type, payload_off in _iter_top_level_boxes(data):
+        consumed = end
         if box_type == b"uuid":
             # uuid boxes carry the 16-byte UUID immediately after the type.
             is_c2pa = payload_off + 16 <= end and data[payload_off : payload_off + 16] == C2PA_UUID
@@ -113,4 +181,45 @@ def strip_c2pa_boxes(data: bytes) -> tuple[bytes, int]:
             stripped += 1
             continue
         out.extend(data[start:end])
+
+    # Fail-safe: the walker returns early on a malformed box (bad size, or a box
+    # that runs past EOF), so anything after it was never visited. Emitting `out`
+    # 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(
+            "ISOBMFF box walk stopped at offset %d of %d (malformed box); "
+            "returning input unchanged to avoid truncation",
+            consumed,
+            len(data),
+        )
+        return data, 0
+
     return bytes(out), stripped
+
+
+def blank_ai_xmp_packets(data: bytes) -> tuple[bytes, int]:
+    """Overwrite (with spaces, in place) any XMP packet carrying an AI-label
+    marker; return ``(data, blanked_count)``.
+
+    HEIF/AVIF store XMP as a ``meta``-box ``mime`` item whose bytes live in
+    ``mdat`` / ``idat``, which ``strip_c2pa_boxes`` cannot remove without
+    meta-box surgery (``iinf`` / ``iloc`` rewrite). Instead, the XMP packet is
+    located by its ``<?xpacket begin ... end?>`` delimiters and, when it carries
+    an AI-label marker (TC260 AIGC / IPTC / IPTC-2025.1), overwritten with spaces.
+    Because the replacement is the **same length**, every box size and ``iloc``
+    offset stays valid and the coded image data is untouched -- only the AI label
+    content is destroyed. Packets without an AI marker (plain copyright / camera
+    XMP) are left intact, mirroring the top-level XMP-``uuid`` content match.
+    """
+    blanked = 0
+
+    def _scrub(match: re.Match[bytes]) -> bytes:
+        nonlocal blanked
+        packet = match.group()
+        if any(marker in packet for marker in _AI_LABEL_MARKERS):
+            blanked += 1
+            return b" " * len(packet)
+        return packet
+
+    return _XMP_PACKET_RE.sub(_scrub, data), blanked

src/remove_ai_watermarks/noai/progress.py

@@ -259,7 +259,7 @@ def make_pipeline_progress(
     label: str = "Denoising",
     pre_phases: list[tuple[int, str]] | None = None,
     post_phases: list[tuple[int, str]] | None = None,
-) -> tuple[Callable, threading.Event, threading.Event, Callable[[], threading.Thread]]:
+) -> tuple[Callable[..., None], threading.Event, threading.Event, Callable[[], threading.Thread]]:
     """Create step callback and background updater for a diffusion pipeline.
 
     Returns:

src/remove_ai_watermarks/noai/watermark_profiles.py

@@ -1,51 +1,120 @@
-"""Watermark removal model profiles, strength presets, and profile detection.
+"""Watermark removal model profiles and the default strength.
 
 Pure configuration and lookup functions with no ML dependencies.
 """
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
 DEFAULT_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
-CTRLREGEN_MODEL_ID = "yepengliu/ctrlregen"
 
-LOW_STRENGTH = 0.04
-MEDIUM_STRENGTH = 0.35
-HIGH_STRENGTH = 0.7
-
-_HIGH_PERTURBATION = ("stegasamp", "stegastamp", "treering", "ringid")
-_LOW_PERTURBATION = ("stablesignature", "dwtectsvd", "rivagan", "ssl", "hidden")
+# Canonical pipeline-profile names + the back-compat alias. The plain SDXL img2img
+# profile is ``sdxl``; ``default`` is kept as an accepted alias (it was the profile's
+# name before ``controlnet`` became the default-selected pipeline, 2026-06-09).
+SDXL_PROFILE = "sdxl"
+_PROFILE_ALIASES = {"default": SDXL_PROFILE}
 
 
-def get_model_id_for_profile(profile: str) -> str:
-    """Map CLI model profile names to concrete Hugging Face model IDs."""
+def normalize_profile(profile: str) -> str:
+    """Canonicalize a pipeline-profile name, resolving the ``default`` -> ``sdxl`` alias."""
     normalized = profile.strip().lower()
-    if normalized == "default":
-        return DEFAULT_MODEL_ID
-    if normalized == "ctrlregen":
-        return CTRLREGEN_MODEL_ID
-    raise ValueError(f"Unknown model profile '{profile}'. Use one of: default, ctrlregen.")
+    return _PROFILE_ALIASES.get(normalized, normalized)
 
 
-def detect_model_profile(model_id: str) -> str:
-    """Infer model profile from model identifier."""
-    if "ctrlregen" in model_id.lower():
-        return "ctrlregen"
-    return "default"
+# The SDXL-native canny ControlNet used by the ``controlnet`` pipeline. The
+# ControlNet is an add-on to the SDXL base checkpoint (DEFAULT_MODEL_ID), not a
+# separate base model, so both the ``sdxl`` and ``controlnet`` profiles load the
+# same base weights and share the same vendor-adaptive strength ladder (see below).
+CONTROLNET_CANNY_MODEL = "xinsir/controlnet-canny-sdxl-1.0"
+
+# Vendor-adaptive default denoising strength for the SDXL img2img scrub, overridable
+# from the CLI (`--strength`). The right strength depends on which vendor's SynthID is
+# present (detected from the C2PA issuer, metadata.synthid_source). The SAME ladder
+# applies to BOTH pipelines (`sdxl` plain img2img and `controlnet`) -- see "why one
+# ladder" below.
+#
+# Data basis (see docs/synthid.md sections 2.2 / 5.5): the values are the ORACLE-
+# CERTIFIED controlnet floors (2026-06-04, isolated Modal cert app, each vendor on its
+# own verifier): OpenAI 0.20 (2 photoreal x 3 seeds = 6/6 clean, resolution-independent),
+# Google 0.30 (clean on 2/2 seeds, validated ONLY at <= 1536 -- Gemini is resolution-
+# sensitive, native ~2816 likely needs ~0.35+). Unknown vendor gets the Google (more
+# robust watermark) value: safe-by-default.
+#
+# Why ONE ladder for both pipelines (2026-06-09): the certification was run on
+# controlnet, and it does NOT transfer to `sdxl` by symmetry -- the two pipelines have
+# OPPOSITE hard cases (controlnet leaves SynthID on photoreal, `sdxl` leaves it on flat
+# graphics; the content-x-pipeline table in docs/synthid.md §5.1). BUT on its OWN hard
+# case (flat fills) `sdxl` is the WEAKER remover -- plain img2img at low strength barely
+# perturbs a flat region -- so it needs AT LEAST as much strength as controlnet, not
+# less. Hence the certified controlnet floor is the right floor for `sdxl` too. The
+# higher strength costs little quality where it matters: `controlnet` is now the default
+# pipeline, so `sdxl` is reached only for structure-less inputs (via `--auto`) or an
+# explicit `--pipeline sdxl`, where over-regeneration has no faces/text to damage. NOTE:
+# this is a MARGIN argument for `sdxl`, not a fresh certification -- there is no local
+# SynthID detector, so if an oracle still reads SynthID on a flat `sdxl` output, raise
+# `--strength`.
+OPENAI_STRENGTH = 0.20
+GEMINI_STRENGTH = 0.30
+UNKNOWN_STRENGTH = 0.30
+# Backwards-compatible alias: the vendor-unknown value (what a caller gets without a
+# detected vendor). Kept as DEFAULT_STRENGTH for existing references.
+DEFAULT_STRENGTH = UNKNOWN_STRENGTH
+
+# Detected-vendor -> default strength. Vendor strings come from `vendor_for_strength`.
+_VENDOR_STRENGTH = {"openai": OPENAI_STRENGTH, "google": GEMINI_STRENGTH}
 
 
-def get_recommended_strength(watermark_type: str) -> float:
-    """Get recommended strength for different watermark types.
+def strength_default_help() -> str:
+    """One-line description of the vendor-adaptive default, derived from the constants.
 
-    Args:
-        watermark_type: Type of watermark. One of: 'low', 'medium', 'high',
-                        or specific names like 'stegastamp', 'treering', etc.
-
-    Returns:
-        Recommended strength value.
+    Single source of truth for the CLI ``--strength`` help so the numbers can never
+    drift from the actual ladder (they did once when the per-pipeline split was unified).
     """
-    wt = watermark_type.lower()
-    if any(name in wt for name in _HIGH_PERTURBATION):
-        return HIGH_STRENGTH
-    if any(name in wt for name in _LOW_PERTURBATION):
-        return LOW_STRENGTH
-    return MEDIUM_STRENGTH
+    return (
+        f"vendor-adaptive (OpenAI {OPENAI_STRENGTH} / Google {GEMINI_STRENGTH} / "
+        f"unknown {UNKNOWN_STRENGTH}, from the C2PA issuer; same ladder for both pipelines)"
+    )
+
+
+def resolve_strength(strength: float | None, vendor: str | None = None) -> float:
+    """Resolve the denoising strength, applying the vendor default when unset.
+
+    ``None`` means "the user did not pass ``--strength``", which resolves
+    **vendor-adaptively**: ``vendor`` (``"openai"`` / ``"google"`` / None, from
+    ``vendor_for_strength``) selects ``OPENAI_STRENGTH`` / ``GEMINI_STRENGTH`` /
+    ``UNKNOWN_STRENGTH``. The same ladder applies to both pipelines (see the module
+    comment for why one ladder is correct). An explicit value always wins (including
+    ``0.0`` -- the check is ``is None``, not falsiness). Shared by the CLI (for display)
+    and the engine (for execution) so the two never disagree -- both must pass the SAME
+    ``vendor``.
+    """
+    if strength is not None:
+        return strength
+    return _VENDOR_STRENGTH.get(vendor or "", UNKNOWN_STRENGTH)
+
+
+def vendor_for_strength(image_path: Path) -> Literal["openai", "google"] | None:
+    """Detect the SynthID vendor for strength selection: ``"openai"`` / ``"google"`` / None.
+
+    Reads the C2PA SynthID proxy (``metadata.synthid_source``) on the ORIGINAL input,
+    so it must run before any pass that strips metadata. When both issuers appear (a
+    rare multi-sign anomaly) Google wins -- the more-robust watermark -> safer (higher)
+    strength. Returns None when metadata is stripped or the issuer is neither vendor,
+    which maps to ``UNKNOWN_STRENGTH``. Lazy-imports ``metadata`` to keep this module
+    dependency-light.
+    """
+    try:
+        from remove_ai_watermarks.metadata import synthid_source
+
+        src = (synthid_source(image_path) or "").lower()
+    except Exception:  # metadata unreadable -> treat as unknown vendor
+        return None
+    if "google" in src:
+        return "google"
+    if "openai" in src:
+        return "openai"
+    return None

src/remove_ai_watermarks/noai/watermark_remover.py

@@ -1,15 +1,22 @@
 """Watermark removal using diffusion model regeneration attack.
 
-Based on the paper "Image Watermarks Are Removable Using Controllable
-Regeneration from Clean Noise" (ICLR 2025).
-
-This module implements a simple regeneration attack that:
-1. Encodes the watermarked image to latent space
-2. Adds noise via forward diffusion process
-3. Denoises via reverse diffusion process
-4. Decodes back to pixel space
+Two pipelines:
+1. ``controlnet`` (DEFAULT) -- SDXL img2img with a canny ControlNet. The watermark
+   REMOVAL still comes from the img2img regeneration (``strength``); the ControlNet
+   only PRESERVES structure (text/faces) by conditioning on the edge map. No original
+   pixels are ever copied or frozen. Because the edge map keeps the regeneration
+   closer to the original, it needs a higher ``strength`` floor than ``default`` to
+   destroy SynthID (the certified controlnet ladder; see ``watermark_profiles``).
+   ``controlnet_conditioning_scale`` is the preservation knob.
+2. ``default`` -- plain SDXL img2img. Partial-noise regeneration scrubs the
+   invisible watermark; ``strength`` controls how much is regenerated. Lighter (no
+   ControlNet weights), but at the low default strength it leaves SynthID on
+   flat-graphic content -- use it for inputs without text/faces.
 """
 
+# torch/diffusers/cv2 boundary: these libs ship no usable types for the tensor and
+# array ops below; relax the unknown-type rules for this file only.
+# 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 contextlib
@@ -26,12 +33,11 @@ if TYPE_CHECKING:
 from PIL import Image
 
 from remove_ai_watermarks.noai.watermark_profiles import (
-    CTRLREGEN_MODEL_ID,
+    CONTROLNET_CANNY_MODEL,
     DEFAULT_MODEL_ID,
-    HIGH_STRENGTH,
-    LOW_STRENGTH,
-    MEDIUM_STRENGTH,
-    detect_model_profile,
+    DEFAULT_STRENGTH,
+    normalize_profile,
+    resolve_strength,
 )
 
 logger = logging.getLogger(__name__)
@@ -60,6 +66,46 @@ def is_watermark_removal_available() -> bool:
     return _HAS_TORCH and _HAS_DIFFUSERS
 
 
+# Drop-in fp16-safe replacement for the SDXL VAE. The stock SDXL VAE overflows
+# to NaN in fp16 and decodes to an all-black image (issue #29: the raiw.cc black
+# result on a CUDA fp16 backend). This community VAE is numerically rescaled to
+# stay in fp16 range. SDXL-architecture only.
+_SDXL_FP16_VAE_ID = "madebyollin/sdxl-vae-fp16-fix"
+
+
+def _needs_fp16_vae_fix(model_id: str, default_model_id: str, is_fp16: bool) -> bool:
+    """Whether the plain img2img pipeline must swap in the fp16-fixed SDXL VAE.
+
+    Gated to the default SDXL checkpoint running in fp16: cpu/mps run fp32 (the
+    stock VAE is fine there) and the differential pipeline upcasts the VAE on its
+    own, so only this path on a fp16 GPU (CUDA/XPU) hits the NaN/black decode.
+    A custom non-SDXL ``model_id`` keeps its own VAE (the fix is SDXL-specific).
+    """
+    return is_fp16 and model_id == default_model_id
+
+
+# An fp16 VAE/UNet overflow decodes to NaN, which diffusers' postprocess casts to 0
+# -> a uniform all-black frame (issues #29, #41). The VAE swap above prevents it for
+# the default checkpoint, but a custom model_id, a stale install, or a fal/custom
+# loader can still bypass it. Detecting a degenerate output and retrying in fp32 (the
+# path verified clean) is the model-agnostic safety net: never hand back a black image.
+# One threshold serves both guards: a NaN->0 collapse drives mean and variance to ~0.
+_DEGENERATE_THRESHOLD = 1.0
+
+
+def _is_degenerate_image(image: Image.Image) -> bool:
+    """True if a generated image collapsed to an all-black/NaN frame (#29/#41).
+
+    A NaN fp16 decode casts to 0, so the output is a uniform near-zero image: an
+    extremely low mean AND near-zero variance. The variance guard keeps a
+    legitimately dark-but-textured photo (low mean, real detail) from being flagged.
+    """
+    import numpy as np
+
+    arr = np.asarray(image.convert("RGB"), dtype=np.float32)
+    return float(arr.mean()) < _DEGENERATE_THRESHOLD and float(arr.std()) < _DEGENERATE_THRESHOLD
+
+
 _CUDA_FIX_ENV_KEY = "NOAI_CUDA_FIXED"
 
 
@@ -219,6 +265,19 @@ def get_device() -> str:
             return "cuda"
         except (AssertionError, RuntimeError):
             pass
+    # Intel GPU (Arc / Data Center) via the torch XPU backend. The torch.xpu
+    # namespace exists in stock wheels, but is_available() is only True on an
+    # XPU-enabled build (download.pytorch.org/whl/xpu), so this is inert on the
+    # default CPU/CUDA install. Checked before the nvidia-smi path so an Intel
+    # box never triggers the CUDA reinstaller.
+    if hasattr(torch, "xpu") and torch.xpu.is_available():  # type: ignore
+        try:
+            t = torch.tensor([1.0], device="xpu")
+            _ = t + t
+            del t
+            return "xpu"
+        except (AssertionError, RuntimeError):
+            pass
     if _has_nvidia_gpu() and not os.environ.get(_CUDA_FIX_ENV_KEY):
         _reinstall_torch_cuda_and_restart()
     if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
@@ -226,8 +285,28 @@ def get_device() -> str:
     return "cpu"
 
 
-# Keep legacy name available for backwards compatibility
-_detect_model_profile_from_id = detect_model_profile
+def _make_seed_generator(device: str, seed: int) -> Any:
+    """Build a seeded ``torch.Generator``, falling back to a CPU generator.
+
+    Some backends have no device-side RNG (notably certain torch-xpu builds),
+    so ``torch.Generator(device="xpu")`` can raise. A CPU generator is
+    backend-agnostic and still seeds the pipeline reproducibly, so fall back to
+    it rather than failing the run when ``--seed`` is used on such a device.
+    """
+    try:
+        return torch.Generator(device=device).manual_seed(seed)  # type: ignore
+    except (RuntimeError, TypeError):
+        return torch.Generator().manual_seed(seed)  # type: ignore
+
+
+# Canny edge thresholds for the ControlNet control image (xinsir canny recipe:
+# cv2.Canny(gray, 100, 200) -> a 3-channel edge map).
+_CANNY_LOW = 100
+_CANNY_HIGH = 200
+
+# A neutral quality prompt: the goal is faithful regeneration, not creative edits.
+_CONTROLNET_PROMPT = "best quality, high quality, sharp, detailed, photographic"
+_CONTROLNET_NEGATIVE = "blurry, lowres, deformed, distorted text, garbled text, watermark, jpeg artifacts"
 
 
 class WatermarkRemover:
@@ -235,14 +314,12 @@ class WatermarkRemover:
 
     Attributes:
         model_id: HuggingFace model ID for the diffusion model.
-        device: Device to run inference on (cuda, mps, or cpu).
+        device: Device to run inference on (cuda, xpu, mps, or cpu).
     """
 
     DEFAULT_MODEL_ID = DEFAULT_MODEL_ID
-    CTRLREGEN_MODEL_ID = CTRLREGEN_MODEL_ID
-    LOW_STRENGTH = LOW_STRENGTH
-    MEDIUM_STRENGTH = MEDIUM_STRENGTH
-    HIGH_STRENGTH = HIGH_STRENGTH
+    DEFAULT_STRENGTH = DEFAULT_STRENGTH
+    CONTROLNET_CANNY_MODEL = CONTROLNET_CANNY_MODEL
 
     def __init__(
         self,
@@ -251,17 +328,23 @@ class WatermarkRemover:
         torch_dtype: Any = None,
         progress_callback: Callable[[str], None] | None = None,
         hf_token: str | None = None,
+        pipeline: str = "controlnet",
+        controlnet_conditioning_scale: float = 1.0,
     ) -> None:
         self.model_id = model_id or self.DEFAULT_MODEL_ID
-        self.model_profile = detect_model_profile(self.model_id)
+        # The pipeline profile is threaded explicitly (not inferred from model_id):
+        # both "sdxl" and "controlnet" use the same SDXL base checkpoint. Normalize so
+        # the legacy "default" alias resolves to "sdxl".
+        self.model_profile = normalize_profile(pipeline)
+        self.controlnet_conditioning_scale = controlnet_conditioning_scale
 
         if not is_watermark_removal_available():
             _ensure_watermark_deps()
         self.device = (device or get_device()).lower()
         if self.device == "auto":
             self.device = get_device()
-        if self.device not in {"cpu", "mps", "cuda"}:
-            raise ValueError(f"Unsupported device '{device}'. Use one of: auto, cpu, mps, cuda.")
+        if self.device not in {"cpu", "mps", "cuda", "xpu"}:
+            raise ValueError(f"Unsupported device '{device}'. Use one of: auto, cpu, mps, cuda, xpu.")
         if torch_dtype is None:
             if self.device == "cpu" or self.device == "mps":
                 self.torch_dtype = torch.float32  # type: ignore
@@ -271,7 +354,7 @@ class WatermarkRemover:
             self.torch_dtype = torch_dtype
 
         self._pipeline: AutoImg2ImgPipeline | None = None
-        self._ctrlregen_engine: Any = None
+        self._controlnet_pipeline: Any = None
         self._progress_callback = progress_callback
         self.hf_token: str | None = hf_token or os.environ.get("HF_TOKEN")
 
@@ -286,44 +369,59 @@ class WatermarkRemover:
 
     def preload(self) -> None:
         """Eagerly load the pipeline so download progress bars are visible."""
-        if self.model_profile == "ctrlregen":
-            self._run_ctrlregen_preload()
+        if self.model_profile == "controlnet":
+            self._load_controlnet_pipeline()
         else:
             self._load_pipeline()
 
-    def _run_ctrlregen_preload(self) -> None:
-        """Ensure the CtrlRegen engine and all its models are loaded."""
-        from remove_ai_watermarks.noai.ctrlregen import is_ctrlregen_available
-
-        if not is_ctrlregen_available():
-            missing_pkgs = ["controlnet-aux", "color-matcher", "safetensors"]
-            logger.info("Auto-installing missing CtrlRegen dependencies: %s", missing_pkgs)
-            if not _auto_install(missing_pkgs):
-                raise ImportError(
-                    f"Failed to auto-install missing dependencies: {', '.join(missing_pkgs)}. "
-                    "Try manually: pip install --force-reinstall noai-watermark"
-                )
-        if self._ctrlregen_engine is None:
-            self._ctrlregen_engine = self._make_ctrlregen_engine()
-        self._ctrlregen_engine.load()
-
-    def _make_ctrlregen_engine(self) -> Any:
-        """Create a new CtrlRegenEngine with current settings."""
-        from remove_ai_watermarks.noai.ctrlregen import CtrlRegenEngine
-
-        base_model = self.model_id if self.model_id != self.CTRLREGEN_MODEL_ID else None
-        return CtrlRegenEngine(
-            base_model_id=base_model,
-            device=self.device,
-            torch_dtype=self.torch_dtype,
-            hf_token=self.hf_token,
-            progress_callback=self._progress_callback,
-        )
-
     # ── Pipeline loading ─────────────────────────────────────────────
 
+    def _maybe_add_fp16_vae(self, load_kwargs: dict[str, Any]) -> None:
+        """Swap in the fp16-fixed SDXL VAE for the default checkpoint on a fp16 GPU.
+
+        The stock SDXL VAE overflows to NaN in fp16 and decodes to an all-black
+        image (issue #29). Shared by both pipeline loaders; a no-op on fp32 (cpu/mps)
+        or a non-SDXL checkpoint.
+        """
+        if _needs_fp16_vae_fix(self.model_id, self.DEFAULT_MODEL_ID, self.torch_dtype == torch.float16):
+            from diffusers import AutoencoderKL
+
+            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)
+
+    def _move_to_device_and_optimize(self, pipeline: Any) -> Any:
+        """Move a freshly-loaded pipeline to ``self.device`` + enable memory opts.
+
+        Shared by both loaders. On a CUDA move failure (missing CUDA torch build),
+        trigger the torch-CUDA reinstall+restart. Returns the moved pipeline.
+        """
+        self._set_progress(f"Moving model to device: {self.device}")
+        try:
+            pipeline = pipeline.to(self.device)
+        except (RuntimeError, AssertionError) as exc:
+            if self.device == "cuda" and not os.environ.get(_CUDA_FIX_ENV_KEY):
+                self._set_progress("CUDA failed. Reinstalling torch with CUDA support...")
+                _reinstall_torch_cuda_and_restart()
+            raise RuntimeError(
+                f"Failed to move model to {self.device} ({exc}). "
+                "Install CUDA-enabled PyTorch manually:\n"
+                f"  pip install torch --index-url {_detect_cuda_index_url()}"
+            ) from exc
+
+        if hasattr(pipeline, "enable_xformers_memory_efficient_attention"):
+            with contextlib.suppress(Exception):
+                self._set_progress("Enabling memory optimizations...")
+                pipeline.enable_xformers_memory_efficient_attention()
+
+        # Mac Float32 memory slicing
+        if self.device == "mps" and hasattr(pipeline, "enable_attention_slicing"):
+            with contextlib.suppress(Exception):
+                pipeline.enable_attention_slicing("max")
+
+        return pipeline
+
     def _load_pipeline(self) -> AutoImg2ImgPipeline:
-        """Load the diffusion pipeline lazily."""
+        """Load the plain SDXL img2img pipeline lazily."""
         if self._pipeline is None:
             logger.info("Loading model %s on %s...", self.model_id, self.device)
             self._set_progress(f"Loading model weights: {self.model_id}")
@@ -335,40 +433,47 @@ class WatermarkRemover:
             }
             if self.hf_token:
                 load_kwargs["token"] = self.hf_token
+            self._maybe_add_fp16_vae(load_kwargs)
 
-            self._pipeline = AutoImg2ImgPipeline.from_pretrained(  # type: ignore
-                self.model_id,
-                **load_kwargs,
-            )
-
-            self._set_progress(f"Moving model to device: {self.device}")
-            try:
-                self._pipeline = self._pipeline.to(self.device)  # type: ignore
-            except (RuntimeError, AssertionError) as exc:
-                if self.device == "cuda" and not os.environ.get(_CUDA_FIX_ENV_KEY):
-                    self._set_progress("CUDA failed. Reinstalling torch with CUDA support...")
-                    _reinstall_torch_cuda_and_restart()
-                raise RuntimeError(
-                    f"Failed to move model to {self.device} ({exc}). "
-                    "Install CUDA-enabled PyTorch manually:\n"
-                    f"  pip install torch --index-url {_detect_cuda_index_url()}"
-                ) from exc
-
-            if hasattr(self._pipeline, "enable_xformers_memory_efficient_attention"):
-                with contextlib.suppress(Exception):
-                    self._set_progress("Enabling memory optimizations...")
-                    self._pipeline.enable_xformers_memory_efficient_attention()  # type: ignore
-
-            # Mac Float32 memory slicing
-            if self.device == "mps" and hasattr(self._pipeline, "enable_attention_slicing"):
-                with contextlib.suppress(Exception):
-                    self._pipeline.enable_attention_slicing("max")
+            pipeline = AutoImg2ImgPipeline.from_pretrained(self.model_id, **load_kwargs)  # type: ignore
+            self._pipeline = self._move_to_device_and_optimize(pipeline)
 
             logger.info("Model loaded successfully")
             self._set_progress("Model initialized. Preparing input image...")
 
         return self._pipeline  # type: ignore
 
+    def _load_controlnet_pipeline(self) -> Any:
+        """Load the SDXL + canny-ControlNet img2img pipeline lazily.
+
+        Mirrors ``_load_pipeline`` (same fp16-fix VAE, device move, attention
+        slicing via the shared helpers) but loads the canny ControlNet on top of
+        the SDXL base. The ControlNet only preserves structure via the edge map;
+        removal still comes from the img2img regeneration (``strength``).
+        """
+        if self._controlnet_pipeline is None:
+            from diffusers import ControlNetModel, StableDiffusionXLControlNetImg2ImgPipeline
+
+            logger.info("Loading SDXL + ControlNet (%s) on %s...", CONTROLNET_CANNY_MODEL, self.device)
+            self._set_progress(f"Loading ControlNet: {CONTROLNET_CANNY_MODEL}")
+            controlnet = ControlNetModel.from_pretrained(CONTROLNET_CANNY_MODEL, torch_dtype=self.torch_dtype)
+
+            load_kwargs: dict[str, Any] = {"controlnet": controlnet, "torch_dtype": self.torch_dtype}
+            if self.hf_token:
+                load_kwargs["token"] = self.hf_token
+            self._maybe_add_fp16_vae(load_kwargs)
+
+            self._set_progress(f"Loading model weights: {self.model_id}")
+            pipeline = StableDiffusionXLControlNetImg2ImgPipeline.from_pretrained(self.model_id, **load_kwargs)
+            pipeline = self._move_to_device_and_optimize(pipeline)
+            with contextlib.suppress(Exception):
+                pipeline.set_progress_bar_config(disable=True)
+
+            logger.info("ControlNet model loaded successfully")
+            self._controlnet_pipeline = pipeline
+
+        return self._controlnet_pipeline
+
     # ── Core removal ─────────────────────────────────────────────────
 
     def remove_watermark(
@@ -379,16 +484,23 @@ class WatermarkRemover:
         num_inference_steps: int = 50,
         guidance_scale: float | None = None,
         seed: int | None = None,
+        vendor: str | None = None,
     ) -> Path:
         """Remove watermark from an image using regeneration attack.
 
         Args:
             image_path: Path to the watermarked image.
             output_path: Path for the cleaned image. If None, modifies in place.
-            strength: Denoising strength (0.0-1.0).
+            strength: Denoising strength (0.0-1.0). None -> the vendor-adaptive
+                default (see ``vendor``).
             num_inference_steps: Number of denoising steps.
             guidance_scale: Classifier-free guidance scale.
             seed: Random seed for reproducibility.
+            vendor: SynthID vendor (``"openai"`` / ``"google"`` / None) used to pick the
+                default strength when ``strength`` is None. Detect it from the ORIGINAL
+                input with ``watermark_profiles.vendor_for_strength`` before processing
+                strips the metadata; the caller passes it down so display and execution
+                agree.
 
         Returns:
             Path to the cleaned image.
@@ -403,13 +515,13 @@ class WatermarkRemover:
         if output_path is None:
             output_path = image_path
 
-        strength = strength or self.LOW_STRENGTH
+        strength = resolve_strength(strength, vendor)
 
         if not 0.0 <= strength <= 1.0:
             raise ValueError(f"Strength must be between 0.0 and 1.0, got {strength}")
 
         if guidance_scale is None:
-            guidance_scale = 2.0 if self.model_profile == "ctrlregen" else 7.5
+            guidance_scale = 7.5
 
         self._set_progress("Loading and preprocessing input image...")
         init_image = Image.open(image_path).convert("RGB")
@@ -419,7 +531,7 @@ class WatermarkRemover:
         generator = None
         if seed is not None and _HAS_TORCH:
             self._set_progress(f"Setting reproducible seed: {seed}")
-            generator = torch.Generator(device=self.device).manual_seed(seed)  # type: ignore
+            generator = _make_seed_generator(self.device, seed)
 
         effective_steps = max(1, int(num_inference_steps * strength))
         self._set_progress(
@@ -429,22 +541,25 @@ class WatermarkRemover:
 
         _total_start = time.monotonic()
 
-        if self.model_profile == "ctrlregen":
-            cleaned_image = self._run_ctrlregen(
-                init_image,
-                strength,
-                num_inference_steps,
-                guidance_scale,
-                generator,
-            )
-        else:
-            cleaned_image = self._run_img2img(
-                init_image,
-                strength,
-                num_inference_steps,
-                guidance_scale,
-                generator,
-            )
+        def _generate() -> Image.Image:
+            if self.model_profile == "controlnet":
+                return self._run_controlnet(init_image, strength, num_inference_steps, guidance_scale, generator)
+            return self._run_img2img(init_image, strength, num_inference_steps, guidance_scale, generator)
+
+        cleaned_image = _generate()
+
+        # Safety net for the fp16 all-black/NaN decode (#29/#41): if an fp16 run
+        # produced a degenerate (uniform black) frame -- the VAE swap did not engage
+        # for this model/version -- retry once in fp32 on the same device (verified
+        # clean) so the user never gets a black image. Skipped when an MPS->CPU
+        # fallback already moved us to fp32.
+        if self.torch_dtype == torch.float16 and _is_degenerate_image(cleaned_image):
+            logger.warning("fp16 output was degenerate (all-black/NaN, #29/#41); retrying in fp32 on %s.", self.device)
+            self._set_progress("Output was black (fp16 overflow); retrying in fp32...")
+            self.torch_dtype = torch.float32
+            self._pipeline = None
+            self._controlnet_pipeline = None
+            cleaned_image = _generate()
 
         self._set_progress(f"Regeneration complete · Output: {w}x{h}px {cleaned_image.mode}")
 
@@ -520,9 +635,25 @@ class WatermarkRemover:
         self._pipeline = None
         return self._load_pipeline()
 
-    # ── CtrlRegen runner ─────────────────────────────────────────────
+    # ── ControlNet runner ────────────────────────────────────────────
 
-    def _run_ctrlregen(
+    def _build_canny_control_image(self, init_image: Image.Image) -> Image.Image:
+        """Build the canny ControlNet conditioning image (xinsir recipe).
+
+        cv2.Canny on the RGB->gray array, stacked to 3 channels, wrapped as a PIL
+        image. The edge map only PRESERVES structure; it never copies pixels.
+        ``init_image`` is already RGB (``remove_watermark`` converts on load).
+        """
+        import cv2
+        import numpy as np
+
+        rgb = np.array(init_image)
+        gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+        edges = cv2.Canny(gray, _CANNY_LOW, _CANNY_HIGH)
+        edges_rgb = np.stack([edges, edges, edges], axis=-1)
+        return Image.fromarray(edges_rgb)
+
+    def _run_controlnet(
         self,
         init_image: Image.Image,
         strength: float,
@@ -530,54 +661,50 @@ class WatermarkRemover:
         guidance_scale: float,
         generator: Any,
     ) -> Image.Image:
-        """Run CtrlRegen pipeline with MPS fallback."""
-        from remove_ai_watermarks.noai.ctrlregen import is_ctrlregen_available
-        from remove_ai_watermarks.noai.progress import is_mps_error
+        """Run the SDXL + canny-ControlNet img2img pass.
 
-        if not is_ctrlregen_available():
-            missing_pkgs = ["controlnet-aux", "color-matcher", "safetensors"]
-            logger.info("Auto-installing missing CtrlRegen dependencies: %s", missing_pkgs)
-            if not _auto_install(missing_pkgs):
-                raise ImportError(
-                    f"Failed to auto-install missing dependencies: {', '.join(missing_pkgs)}. "
-                    "Try manually: pip install --force-reinstall noai-watermark"
-                )
+        Removal still comes from the img2img regeneration (``strength``); the canny
+        ControlNet only PRESERVES text and face STRUCTURE via the edge map. No
+        original pixels are copied/frozen, so SynthID does not survive (canny holds
+        structure, not face identity). ``controlnet_conditioning_scale`` is the
+        structure-preservation knob. Shares the img2img runner (live progress +
+        MPS->CPU fallback) with ``_run_img2img``; the only delta is the extra
+        ControlNet kwargs (canny control image + conditioning scale + a non-empty
+        prompt) overlaid via ``extra_kwargs``.
+        """
+        from remove_ai_watermarks.noai.img2img_runner import run_img2img_with_mps_fallback
 
-        if self._ctrlregen_engine is None:
-            self._ctrlregen_engine = self._make_ctrlregen_engine()
+        extra_kwargs = {
+            "prompt": _CONTROLNET_PROMPT,
+            "negative_prompt": _CONTROLNET_NEGATIVE,
+            "control_image": self._build_canny_control_image(init_image),
+            "controlnet_conditioning_scale": float(self.controlnet_conditioning_scale),
+        }
+        result_image, final_device = run_img2img_with_mps_fallback(
+            load_pipeline=self._load_controlnet_pipeline,
+            image=init_image,
+            strength=strength,
+            num_inference_steps=num_inference_steps,
+            guidance_scale=guidance_scale,
+            generator=generator,
+            device=self.device,
+            set_progress=self._set_progress,
+            reload_on_cpu=self._reload_controlnet_on_cpu,
+            extra_kwargs=extra_kwargs,
+        )
 
-        seed = None
-        if generator is not None and hasattr(generator, "initial_seed"):
-            seed = generator.initial_seed()
+        if final_device != self.device:
+            self.device = final_device
+            self.torch_dtype = torch.float32  # type: ignore[assignment]
 
-        try:
-            return self._ctrlregen_engine.run(
-                image=init_image,
-                strength=strength,
-                num_inference_steps=num_inference_steps,
-                guidance_scale=guidance_scale,
-                seed=seed,
-            )
-        except RuntimeError as error:
-            if self.device == "mps" and is_mps_error(error):
-                logger.warning("MPS out of memory during CtrlRegen. Falling back to CPU.")
-                self._set_progress("MPS out of memory! Retrying CtrlRegen on CPU...")
-                with contextlib.suppress(Exception):
-                    if _HAS_TORCH and hasattr(torch, "mps"):
-                        torch.mps.empty_cache()  # type: ignore[attr-defined]
+        return result_image
 
-                self.device = "cpu"
-                self.torch_dtype = torch.float32  # type: ignore[assignment]
-                self._ctrlregen_engine = self._make_ctrlregen_engine()
-
-                return self._ctrlregen_engine.run(
-                    image=init_image,
-                    strength=strength,
-                    num_inference_steps=num_inference_steps,
-                    guidance_scale=guidance_scale,
-                    seed=seed,
-                )
-            raise
+    def _reload_controlnet_on_cpu(self) -> Any:
+        """Reload the controlnet pipeline on CPU after an MPS failure."""
+        self.device = "cpu"
+        self.torch_dtype = torch.float32  # type: ignore[assignment]
+        self._controlnet_pipeline = None
+        return self._load_controlnet_pipeline()
 
     # ── Batch ────────────────────────────────────────────────────────
 
@@ -596,6 +723,9 @@ class WatermarkRemover:
         output_dir.mkdir(parents=True, exist_ok=True)
         cleaned_paths: list[Path] = []
 
+        # Lazy import keeps this module torch-optional; frees device cache per image.
+        from remove_ai_watermarks.noai.img2img_runner import try_empty_device_cache
+
         for ext in extensions:
             for image_path in input_dir.glob(f"*{ext}"):
                 output_path = output_dir / image_path.name
@@ -609,6 +739,7 @@ class WatermarkRemover:
                     cleaned_paths.append(result_path)
                 except Exception as e:
                     logger.error("Failed to process %s: %s", image_path, e)
+                try_empty_device_cache(self.device)
 
         return cleaned_paths
 
@@ -619,15 +750,23 @@ class WatermarkRemover:
 def remove_watermark(
     image_path: Path,
     output_path: Path | None = None,
-    strength: float = 0.04,
+    strength: float | None = None,
     model_id: str | None = None,
     device: str | None = None,
     hf_token: str | None = None,
 ) -> Path:
-    """Convenience function to remove watermark from an image."""
+    """Convenience function to remove watermark from an image.
+
+    ``strength=None`` lets the profile pick its vendor-adaptive SDXL default
+    (0.10 OpenAI / 0.15 Google / 0.15 unknown, from the C2PA SynthID proxy on the
+    input). Pass a value to override.
+    """
+    from remove_ai_watermarks.noai.watermark_profiles import vendor_for_strength
+
     remover = WatermarkRemover(model_id=model_id, device=device, hf_token=hf_token)
     return remover.remove_watermark(
         image_path=image_path,
         output_path=output_path,
         strength=strength,
+        vendor=vendor_for_strength(image_path),
     )

src/remove_ai_watermarks/region_eraser.py

@@ -15,10 +15,14 @@ Backends:
     huggingface_hub; it is never bundled in this repo.
 """
 
+# cv2/numpy boundary: cv2 ships no usable type info, so strict pyright cannot know
+# its array element types. Relax the unknown-type rules for this file only; the
+# public signatures are still annotated with NDArray[Any].
+# 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 logging
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 import cv2
 import numpy as np
@@ -41,7 +45,7 @@ def boxes_to_mask(
     shape: tuple[int, int],
     boxes: list[tuple[int, int, int, int]],
     dilate: int = 3,
-) -> NDArray:
+) -> NDArray[Any]:
     """Build a uint8 mask (255 inside boxes) from ``(x, y, w, h)`` rectangles."""
     h, w = shape
     mask = np.zeros((h, w), np.uint8)
@@ -57,25 +61,30 @@ def boxes_to_mask(
 
 
 def erase_cv2(
-    image_bgr: NDArray,
-    mask: NDArray,
+    image_bgr: NDArray[Any],
+    mask: NDArray[Any],
     *,
     method: Literal["telea", "ns"] = "telea",
     radius: int = 6,
-) -> NDArray:
-    """Inpaint ``mask`` with classical cv2 inpainting (CPU, no extra deps)."""
+) -> NDArray[Any]:
+    """Inpaint ``mask`` with classical cv2 inpainting (CPU, no extra deps).
+
+    Accepts 1-/3-channel BGR (passed straight to ``cv2.inpaint``) and 4-channel
+    BGRA: ``cv2.inpaint`` rejects 4 channels, so the alpha plane is split off,
+    the BGR is inpainted, and alpha is re-attached unchanged.
+    """
     flag = cv2.INPAINT_TELEA if method == "telea" else cv2.INPAINT_NS
+    if image_bgr.ndim == 3 and image_bgr.shape[2] == 4:
+        bgr = cv2.inpaint(image_bgr[:, :, :3], mask, radius, flag)
+        return np.dstack([bgr, image_bgr[:, :, 3]])
     return cv2.inpaint(image_bgr, mask, radius, flag)
 
 
 def lama_available() -> bool:
     """True when the optional LaMa-ONNX backend can run (onnxruntime installed)."""
-    try:
-        import onnxruntime  # noqa: F401
+    import importlib.util
 
-        return True
-    except ImportError:
-        return False
+    return importlib.util.find_spec("onnxruntime") is not None
 
 
 def _get_lama_session() -> object:
@@ -93,13 +102,25 @@ def _get_lama_session() -> object:
     return _lama_session
 
 
-def erase_lama(image_bgr: NDArray, mask: NDArray) -> NDArray:
+def erase_lama(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
     """Inpaint ``mask`` with big-LaMa via onnxruntime (CPU).
 
     LaMa runs at a fixed square input size. To preserve full-image resolution we
     crop a padded region around the mask, inpaint that crop at the model size,
     and paste only the masked pixels back -- so untouched areas stay pixel-exact.
+
+    Like ``erase_cv2``, accepts 1-channel (grayscale) and 4-channel (BGRA) input:
+    LaMa runs on 3-channel BGR, so grayscale is promoted to BGR (result demoted
+    back) and a BGRA alpha plane is split off and re-attached unchanged. Without
+    this the ``cv2.cvtColor(..., BGR2RGB)`` below would crash on grayscale and
+    silently drop alpha on BGRA.
     """
+    if image_bgr.ndim == 2:
+        bgr = erase_lama(cv2.cvtColor(image_bgr, cv2.COLOR_GRAY2BGR), mask)
+        return cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
+    if image_bgr.ndim == 3 and image_bgr.shape[2] == 4:
+        bgr = erase_lama(np.ascontiguousarray(image_bgr[:, :, :3]), mask)
+        return np.dstack([bgr, image_bgr[:, :, 3]])
     session = _get_lama_session()
     inp = session.get_inputs()  # type: ignore[attr-defined]
     img_name = inp[0].name
@@ -147,15 +168,15 @@ def erase_lama(image_bgr: NDArray, mask: NDArray) -> NDArray:
 
 
 def erase(
-    image_bgr: NDArray,
+    image_bgr: NDArray[Any],
     *,
     boxes: list[tuple[int, int, int, int]] | None = None,
-    mask: NDArray | None = None,
+    mask: NDArray[Any] | None = None,
     backend: Backend = "cv2",
     dilate: int = 3,
     cv2_method: Literal["telea", "ns"] = "telea",
     cv2_radius: int = 6,
-) -> NDArray:
+) -> NDArray[Any]:
     """Erase the given boxes (or mask) via the chosen inpainting backend.
 
     Provide either ``boxes`` (list of ``(x, y, w, h)``) or a precomputed ``mask``

src/remove_ai_watermarks/samsung_engine.py

@@ -0,0 +1,116 @@
+"""Samsung Galaxy AI visible watermark removal engine.
+
+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.
+
+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 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.
+"""
+# 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 numpy.typing import NDArray
+
+# Locate geometry as a fraction of image WIDTH (mark scales with width, bottom-LEFT).
+WM_WIDTH_FRAC = 0.40
+WM_HEIGHT_FRAC = 0.060
+MARGIN_LEFT_FRAC = 0.004
+MARGIN_BOTTOM_FRAC = 0.002
+
+# Glyph appearance: a light, low-saturation gray. LOGO_MIN_LUMA is lower than Jimeng's
+# because the mark is faint (peak alpha ~0.38), so on a mid/dark background its glyph
+# luma is lower; a white-paper document is still left untouched.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 110
+TOPHAT_DELTA = 8
+
+# Shape-consistent detection. Threshold 0.40; real marks ~0.79, and Doubao/Jimeng score
+# 0.0 here (and Samsung 0.0 on theirs) -- no cross-fire (the corner also differs).
+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).
+_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_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",
+    asset_name="samsung_alpha.png",
+    corner="bl",
+    margin_floor=2,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_LEFT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=3,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    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
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """The bundled Samsung alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "Contenuti generati dall'AI" silhouette (255 = glyph), or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
+
+
+def _template_match_score(box_mask: NDArray[Any], image_width: 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)
+
+
+class SamsungEngine(TextMarkEngine):
+    """Remove the visible Samsung Galaxy AI text mark (locate -> mask -> reverse-alpha)."""
+
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)

src/remove_ai_watermarks/trustmark_detector.py

@@ -22,6 +22,7 @@ signal, not proof of AI origin.
 from __future__ import annotations
 
 import logging
+import threading
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -32,7 +33,9 @@ log = logging.getLogger(__name__)
 # Adobe ships Variant P in production (com.adobe.trustmark.P).
 _MODEL_TYPE = "P"
 # Lazily constructed singleton -- model load + first-use download is expensive.
+# Guarded by a lock so concurrent callers don't double-construct/double-download.
 _tm: Any = None
+_tm_lock = threading.Lock()
 
 
 def is_available() -> bool:
@@ -45,18 +48,39 @@ def is_available() -> bool:
 def _decoder() -> Any:
     global _tm
     if _tm is None:
-        from trustmark import TrustMark
+        with _tm_lock:
+            if _tm is None:
+                from trustmark import TrustMark
 
-        _tm = TrustMark(verbose=False, model_type=_MODEL_TYPE)
+                _tm = TrustMark(verbose=False, model_type=_MODEL_TYPE)
     return _tm
 
 
+# JPEG quality for the false-positive durability gate (see detect_trustmark).
+# Deliberately mild: a genuine TrustMark survives far harsher, while every
+# observed false positive collapsed even at this quality.
+_REENCODE_QUALITY = 95
+
+
 def detect_trustmark(image_path: Path) -> str | None:
-    """Return a TrustMark scheme note if a TrustMark watermark is decoded, else None.
+    """Return a TrustMark scheme note if a *durable* TrustMark watermark is
+    decoded, else None.
 
     Returns e.g. ``"Adobe TrustMark (variant P, schema 0)"`` when the decoder
-    reports the watermark present, or None if it is absent, the optional
-    ``trustmark`` package is not installed, or the image cannot be read/decoded.
+    reports the watermark present AND it survives a mild JPEG re-encode, or None
+    if it is absent, the optional ``trustmark`` package is not installed, or the
+    image cannot be read/decoded.
+
+    **False-positive gate.** TrustMark's ``wm_present`` flag is a BCH
+    error-correction validity check, which spuriously validates on a small
+    fraction of un-watermarked images -- content-correlated, so AI-generated
+    textures trip it more often than camera photos (verified 2026-05-29 on real
+    files: the false "detections" were on Gemini / OpenAI / Doubao output that
+    cannot carry Adobe's watermark, and decoded a random-bytes secret). A genuine
+    TrustMark is a *durable* soft binding engineered to survive re-encoding (that
+    is its entire purpose once C2PA is stripped), so we re-decode after a mild
+    JPEG round-trip and require the same schema both times. Every observed false
+    positive collapsed under this gate.
     """
     if not is_available():
         return None
@@ -65,8 +89,30 @@ def detect_trustmark(image_path: Path) -> str | None:
 
         with Image.open(image_path) as img:
             cover = img.convert("RGB")
-        _wm_secret, wm_present, wm_schema = _decoder().decode(cover)
+        decoder = _decoder()
+        _wm_secret, wm_present, wm_schema = decoder.decode(cover)
+        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)
+            return None
     except Exception as exc:  # model download / decode failure / unreadable image
         log.debug("TrustMark decode failed for %s: %s", image_path, exc)
         return None
-    return f"Adobe TrustMark (variant {_MODEL_TYPE}, schema {wm_schema})" if wm_present else None
+    return f"Adobe TrustMark (variant {_MODEL_TYPE}, schema {wm_schema})"
+
+
+def _survives_reencode(decoder: Any, cover: Any, schema: int) -> bool:
+    """True if the watermark re-decodes with the same schema after a mild JPEG
+    round-trip -- the durability a genuine TrustMark guarantees, which a BCH
+    false positive (content noise) does not."""
+    import io
+
+    from PIL import Image
+
+    buffer = io.BytesIO()
+    cover.save(buffer, "JPEG", quality=_REENCODE_QUALITY)
+    buffer.seek(0)
+    with Image.open(buffer) as reencoded:
+        _secret, present, reencoded_schema = decoder.decode(reencoded.convert("RGB"))
+    return bool(present) and reencoded_schema == schema

src/remove_ai_watermarks/upscaler.py

@@ -0,0 +1,125 @@
+"""Optional pre-diffusion super-resolution for small inputs (Real-ESRGAN via spandrel).
+
+Mirrors ``region_eraser``'s optional-backend pattern: ``is_available()`` guards the
+``spandrel`` import, a lazy singleton (double-checked lock) holds the loaded model, and
+the weights download on first use (cached by ``torch.hub``) -- they are never bundled.
+
+The DEFAULT upscaler stays Lanczos (cv2, no deps); this is opt-in via the ``esrgan``
+extra and feeds the ``--upscaler esrgan`` path. ``spandrel`` is a pure model-loader
+(MIT) with NO basicsr dependency -- it pulls only torch/torchvision/safetensors/numpy/
+einops -- so it sidesteps the basicsr / ``torchvision.transforms.functional_tensor``
+breakage that the ``restore`` (GFPGAN) extra has to shim. Real-ESRGAN weights are
+BSD-3-Clause.
+
+CPU works but is slow on large inputs, so this is meant for the pre-diffusion upscale of
+SMALL inputs (and the GPU worker). On a memory-constrained host it is a no-op (the extra
+is absent), and the caller falls back to Lanczos.
+"""
+
+# torch/spandrel boundary: these libs ship no usable element types; relax the
+# unknown-type rules for this file only.
+# 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, reportAttributeAccessIssue=false, reportPrivateImportUsage=false
+from __future__ import annotations
+
+import importlib.util
+import logging
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+# Real-ESRGAN x2plus (BSD-3-Clause), official release. x2 is the right native factor for
+# the pre-diffusion floor upscale (small inputs ~512 -> ~1024); spandrel infers the
+# architecture and scale from the checkpoint, so swapping the URL is enough to change it.
+_MODEL_URL = "https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.1/RealESRGAN_x2plus.pth"
+_MODEL_FILENAME = "RealESRGAN_x2plus.pth"
+
+_model: Any = None  # lazy singleton (spandrel ImageModelDescriptor)
+_model_device: str = "cpu"
+_lock = threading.Lock()
+
+
+def is_available() -> bool:
+    """True if the ``esrgan`` extra (spandrel + torch) is importable."""
+    return importlib.util.find_spec("spandrel") is not None and importlib.util.find_spec("torch") is not None
+
+
+def _model_cache_path() -> Path:
+    """Path the weights are cached at (the torch.hub checkpoints dir)."""
+    import torch
+
+    cache_dir = Path(torch.hub.get_dir()) / "checkpoints"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir / _MODEL_FILENAME
+
+
+def _get_model(device: str) -> Any:
+    """Load the Real-ESRGAN model once (downloading the weights on first use)."""
+    global _model, _model_device
+    if _model is not None and _model_device == device:
+        return _model
+    with _lock:
+        if _model is None:
+            import torch
+            from spandrel import ImageModelDescriptor, ModelLoader
+
+            dst = _model_cache_path()
+            if not dst.exists():
+                logger.info("Downloading Real-ESRGAN weights to %s", dst)
+                torch.hub.download_url_to_file(_MODEL_URL, str(dst), progress=False)
+            model = ModelLoader().load_from_file(str(dst))
+            if not isinstance(model, ImageModelDescriptor):
+                raise RuntimeError(f"Unexpected spandrel model type: {type(model).__name__}")
+            _model = model.eval()
+        if _model_device != device:
+            _model.to(device)
+            _model_device = device
+    return _model
+
+
+def scale() -> int:
+    """The model's native upscale factor (e.g. 2 for x2plus). Loads the model if needed."""
+    return int(_get_model("cpu").scale)
+
+
+def upscale(image: NDArray[Any], device: str | None = None) -> NDArray[Any]:
+    """Upscale a BGR uint8 image by the model's native factor with Real-ESRGAN.
+
+    Returns a BGR uint8 array. Falls back to CPU if the requested device errors (an
+    MPS/CUDA OOM or unsupported-op on the small pre-diffusion input), mirroring the
+    diffusion engine's MPS->CPU fallback.
+
+    Raises:
+        RuntimeError: if the ``esrgan`` extra is not installed (guard with
+            ``is_available()`` first).
+    """
+    if not is_available():
+        raise RuntimeError("Real-ESRGAN upscaler needs the 'esrgan' extra (spandrel). Install it or use Lanczos.")
+    import cv2
+    import numpy as np
+    import torch
+
+    target_device = (device or "cpu").lower()
+    if target_device not in {"cpu", "mps", "cuda", "xpu"}:
+        target_device = "cpu"
+    rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+    tensor = torch.from_numpy(rgb).permute(2, 0, 1).float().div(255.0).unsqueeze(0)
+
+    def _run(dev: str) -> NDArray[Any]:
+        model = _get_model(dev)
+        with torch.no_grad():
+            out = model(tensor.to(dev))
+        arr = out.clamp(0.0, 1.0).squeeze(0).permute(1, 2, 0).cpu().numpy() * 255.0
+        return cv2.cvtColor(arr.round().astype(np.uint8), cv2.COLOR_RGB2BGR)
+
+    try:
+        return _run(target_device)
+    except Exception as e:  # GPU OOM / unsupported op: fall back to CPU
+        if target_device == "cpu":
+            raise
+        logger.warning("Real-ESRGAN on %s failed (%s); retrying on CPU", target_device, e)
+        return _run("cpu")

src/remove_ai_watermarks/watermark_registry.py

@@ -0,0 +1,235 @@
+"""Registry of known visible watermarks.
+
+A single catalog that ties each known visible mark to (a) where it usually sits,
+(b) how to recognize it there, and (c) how to remove it. One pass over the
+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.
+
+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.
+  - ``samsung`` -- Samsung Galaxy AI "Contenuti generati dall'AI" strip, bottom-left.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    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"]
+Region = tuple[int, int, int, int]
+
+
+@dataclass(frozen=True)
+class MarkDetection:
+    """Uniform detection result for a known mark (across heterogeneous engines)."""
+
+    key: str
+    label: str
+    location: str
+    detected: bool
+    confidence: float
+    region: Region
+
+
+@dataclass(frozen=True)
+class KnownMark:
+    """A known visible watermark: where it lives, how to find and remove it."""
+
+    key: str
+    label: str
+    location: str  # usual place, human-readable ("bottom-right")
+    in_auto: bool  # participate in `--mark auto` scanning
+    recovery: str  # removal strategy (all reverse-alpha today)
+    _detect: Callable[[NDArray[Any]], MarkDetection]
+    _remove: Callable[..., tuple[NDArray[Any], Region | None]]
+
+    def detect(self, image: NDArray[Any]) -> MarkDetection:
+        return self._detect(image)
+
+    def remove(
+        self,
+        image: NDArray[Any],
+        *,
+        inpaint_method: InpaintMethod = "ns",
+        inpaint: bool = True,
+        inpaint_strength: float = 0.85,
+        force: bool = False,
+    ) -> tuple[NDArray[Any], Region | None]:
+        """Remove this mark by reverse-alpha; 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.
+
+        ``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).
+        """
+        return self._remove(image, inpaint_method, inpaint, inpaint_strength, force)
+
+
+# Gemini-sparkle confidence above which the registry treats it as a confident
+# detection for arbitration. Matches identify's corpus-validated sparkle
+# threshold (0.5): the gemini engine's own detect flag uses a looser internal
+# threshold and weakly fires (~0.36) on unrelated bottom-right text (e.g. the
+# Doubao mark), which would otherwise let it hijack `--mark auto`. 0.5 gives 0
+# false positives on the corpus.
+_GEMINI_AUTO_MIN_CONF = 0.5
+
+# ── Engine adapters (lazy singletons; engines are cv2-only, no model load) ──
+
+_engines: dict[str, Any] = {}
+
+
+def _engine(key: str) -> Any:
+    if key not in _engines:
+        if key == "gemini":
+            from remove_ai_watermarks.gemini_engine import GeminiEngine
+
+            _engines[key] = GeminiEngine()
+        elif key == "doubao":
+            from remove_ai_watermarks.doubao_engine import DoubaoEngine
+
+            _engines[key] = DoubaoEngine()
+        elif key == "jimeng":
+            from remove_ai_watermarks.jimeng_engine import JimengEngine
+
+            _engines[key] = JimengEngine()
+        elif key == "samsung":
+            from remove_ai_watermarks.samsung_engine import SamsungEngine
+
+            _engines[key] = SamsungEngine()
+        else:  # pragma: no cover - guarded by the registry keys
+            raise KeyError(key)
+    return _engines[key]
+
+
+def _gemini_detect(image: NDArray[Any]) -> MarkDetection:
+    d = _engine("gemini").detect_watermark(image)
+    detected = bool(d.detected) and d.confidence >= _GEMINI_AUTO_MIN_CONF
+    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
+
+
+# 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)
+        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
+
+    return remove
+
+
+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)
+    )
+
+
+_REGISTRY: tuple[KnownMark, ...] = (
+    KnownMark("gemini", "Google Gemini sparkle", "bottom-right", True, "reverse-alpha", _gemini_detect, _gemini_remove),
+    _text_mark("doubao", "Doubao 豆包AI生成 text", "bottom-right"),
+    _text_mark("jimeng", "Jimeng 即梦AI wordmark", "bottom-right"),
+    _text_mark("samsung", "Samsung Galaxy AI text", "bottom-left"),
+)
+
+
+def known_marks() -> tuple[KnownMark, ...]:
+    """All registered known visible watermarks."""
+    return _REGISTRY
+
+
+def mark_keys() -> list[str]:
+    """Keys of all registered marks (for CLI choices)."""
+    return [m.key for m in _REGISTRY]
+
+
+def get_mark(key: str) -> KnownMark:
+    """Look up a known mark by key (raises KeyError if unknown)."""
+    for m in _REGISTRY:
+        if m.key == key:
+            return m
+    raise KeyError(key)
+
+
+def detect_marks(image: NDArray[Any], *, include_explicit: bool = True) -> 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]
+
+
+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

tests/test_cli.py

@@ -198,15 +198,17 @@ class TestVisibleCommand:
         # which doesn't overlap the centre square at 200x200).
         assert out[100, 100, 3] == 255
 
-    def test_visible_clears_alpha_in_watermark_region(self, runner, tmp_path):
-        """When inpainting an RGBA image, the watermark region must be cleared
-        in the alpha channel so the sparkle area becomes transparent, not opaque-black.
+    def test_visible_keeps_alpha_opaque_in_watermark_region(self, runner, tmp_path):
+        """Regression for issue #30 (white box): on an opaque RGBA image, the
+        watermark region must stay OPAQUE. Reverse-alpha recovers real pixels
+        there, so zeroing alpha would punch a transparent hole that renders as a
+        solid white box on any non-transparent viewer.
         """
         rgba = np.full((200, 200, 4), 255, dtype=np.uint8)  # fully opaque white
         src = tmp_path / "rgba_full.png"
         cv2.imwrite(str(src), rgba)
 
-        output = tmp_path / "rgba_cleared.png"
+        output = tmp_path / "rgba_kept.png"
         result = runner.invoke(
             main,
             ["visible", str(src), "-o", str(output), "--no-detect"],
@@ -215,13 +217,15 @@ class TestVisibleCommand:
         assert result.exit_code == 0, result.output
         out = cv2.imread(str(output), cv2.IMREAD_UNCHANGED)
         assert out.shape[2] == 4
-        # Default sparkle position is in the bottom-right; alpha there must be 0.
+        # Default sparkle position is in the bottom-right; alpha there must stay 255.
         from remove_ai_watermarks.gemini_engine import get_watermark_config
 
         cfg = get_watermark_config(200, 200)
         px, py = cfg.get_position(200, 200)
         size = cfg.logo_size
-        assert out[py + size // 2, px + size // 2, 3] == 0, "alpha in the watermark region was not cleared"
+        assert out[py + size // 2, px + size // 2, 3] == 255, "watermark region alpha was zeroed (white-box regression)"
+        # No pixel anywhere should have been forced transparent.
+        assert int((out[:, :, 3] == 0).sum()) == 0, "spurious transparent pixels introduced"
 
     def test_visible_rgb_input_stays_rgb(self, runner, sample_png, tmp_path):
         """Regression: a plain RGB PNG must NOT gain a spurious alpha channel."""
@@ -249,6 +253,7 @@ class TestInvisibleCommand:
         mock_cls, mock_engine = _mock_invisible_engine()
         output = tmp_path / "clean.png"
         with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
             patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
             patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
         ):
@@ -263,6 +268,7 @@ class TestInvisibleCommand:
     def test_invisible_default_output(self, runner, sample_png):
         mock_cls, _mock_engine = _mock_invisible_engine()
         with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
             patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
             patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
         ):
@@ -271,6 +277,72 @@ class TestInvisibleCommand:
         expected = sample_png.with_stem(sample_png.stem + "_clean")
         assert expected.exists()
 
+    def test_invisible_adaptive_polish_on_by_default(self, runner, sample_png):
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png)])
+        assert result.exit_code == 0, result.output
+        # adaptive_polish is ON by default (self-gating, so a no-op where not needed).
+        assert mock_engine.remove_watermark.call_args.kwargs["adaptive_polish"] is True
+        # Default model is None (the SDXL base) and CFG is None (the library's 7.5).
+        assert mock_cls.call_args.kwargs["model_id"] is None
+        assert mock_engine.remove_watermark.call_args.kwargs["guidance_scale"] is None
+
+    def test_invisible_no_adaptive_polish_disables(self, runner, sample_png):
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png), "--no-adaptive-polish"])
+        assert result.exit_code == 0, result.output
+        assert mock_engine.remove_watermark.call_args.kwargs["adaptive_polish"] is False
+
+    def test_invisible_model_and_guidance_scale_flow_to_engine(self, runner, sample_png):
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(
+                main,
+                ["invisible", str(sample_png), "--model", "org/custom-sdxl", "--guidance-scale", "5.5"],
+            )
+        assert result.exit_code == 0, result.output
+        assert mock_cls.call_args.kwargs["model_id"] == "org/custom-sdxl"
+        assert mock_engine.remove_watermark.call_args.kwargs["guidance_scale"] == 5.5
+
+    def test_pipeline_default_alias_warns_and_maps_to_sdxl(self, runner, sample_png):
+        mock_cls, _mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png), "--pipeline", "default"])
+        assert result.exit_code == 0, result.output
+        # The legacy value warns and is normalized to "sdxl" before the engine is built.
+        assert "deprecated" in result.output.lower()
+        assert mock_cls.call_args.kwargs["pipeline"] == "sdxl"
+
+    def test_pipeline_sdxl_does_not_warn(self, runner, sample_png):
+        mock_cls, _mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png), "--pipeline", "sdxl"])
+        assert result.exit_code == 0, result.output
+        assert "deprecated" not in result.output.lower()
+        assert mock_cls.call_args.kwargs["pipeline"] == "sdxl"
+
     def test_invisible_nonexistent_file(self, runner):
         result = runner.invoke(main, ["invisible", "/nonexistent/file.png"])
         assert result.exit_code != 0
@@ -302,6 +374,21 @@ class TestAllCommand:
         result = runner.invoke(main, ["all", "/nonexistent/file.png"])
         assert result.exit_code != 0
 
+    def test_all_visible_step_uses_registry(self, runner, sample_png, tmp_path):
+        """Regression (#1): the `all` visible step must route through the registry
+        (best_auto_mark), so Doubao/Jimeng/Samsung text marks are handled -- not just
+        the Gemini sparkle via a hardcoded GeminiEngine."""
+        mock_cls, _mock_engine = _mock_invisible_engine()
+        output = tmp_path / "clean.png"
+        with (
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+            patch("remove_ai_watermarks.watermark_registry.best_auto_mark", return_value=None) as mock_best,
+        ):
+            result = runner.invoke(main, ["all", str(sample_png), "-o", str(output)])
+        assert result.exit_code == 0, result.output
+        mock_best.assert_called()  # the registry auto-detector drove the visible pass
+
     def test_all_preserves_rgba_across_invisible_step(self, runner, tmp_path):
         """Regression: ``all`` must keep transparency even when the invisible
         step writes a 3-channel result (as the real diffusion engine does).
@@ -375,6 +462,14 @@ class TestIdentifyCommand:
         assert result.exit_code == 0
         assert "unknown" in result.output
 
+    def test_identify_unknown_explains_why(self, runner, tmp_clean_png):
+        # An unknown verdict must explain itself inline (issue #22: users read a bare
+        # "unknown" as the tool being broken) rather than only in the caveats section.
+        result = runner.invoke(main, ["identify", str(tmp_clean_png), "--no-visible"])
+        assert result.exit_code == 0
+        assert "No locally-readable AI signal found" in result.output
+        assert "not the same as 'clean'" in result.output
+
     def test_identify_ai_png_reports_platform(self, runner, tmp_png_with_ai_metadata):
         result = runner.invoke(main, ["identify", str(tmp_png_with_ai_metadata), "--no-visible"])
         assert result.exit_code == 0
@@ -500,6 +595,29 @@ class TestBatchCommand:
         assert out[0, 0, 3] == 0
         assert out[100, 100, 3] == 255
 
+    def test_batch_auto_is_deprecated_and_enables_polish(self, runner, tmp_path):
+        """--auto is retired: it warns and just enables the adaptive polish (the
+        pipeline is always the default controlnet now)."""
+        input_dir = _make_batch_dir(tmp_path, count=2)
+        output_dir = tmp_path / "output"
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+            patch("remove_ai_watermarks.cli.invisible_available", return_value=True, create=True),
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+        ):
+            result = runner.invoke(
+                main,
+                ["batch", str(input_dir), "-o", str(output_dir), "--mode", "invisible", "--auto"],
+            )
+        assert result.exit_code == 0, result.output
+        assert "2 processed" in result.output
+        assert "deprecated" in result.output.lower()
+        # Pipeline stays the default controlnet; --auto only turned the polish on.
+        assert mock_cls.call_args.kwargs["pipeline"] == "controlnet"
+        assert mock_engine.remove_watermark.call_args.kwargs["adaptive_polish"] is True
+
     def test_batch_default_output_dir(self, runner, tmp_path):
         input_dir = _make_batch_dir(tmp_path)
         result = runner.invoke(
@@ -509,3 +627,96 @@ class TestBatchCommand:
         assert result.exit_code == 0
         expected_dir = tmp_path / "input_clean"
         assert expected_dir.exists()
+
+
+class TestGpuHintMarkup:
+    """The GPU-extra install hint must reach the user with the ``[gpu]`` token
+    intact (plain output prints it verbatim, with no markup parsing)."""
+
+    def test_invisible_install_hint_keeps_gpu_extra(self, runner, sample_png):
+        with patch("remove_ai_watermarks.invisible_engine.is_available", return_value=False):
+            result = runner.invoke(main, ["invisible", str(sample_png)])
+        assert result.exit_code != 0
+        assert "remove-ai-watermarks[gpu]" in result.output
+
+    def test_all_install_hint_keeps_gpu_extra(self, runner, sample_png):
+        # The `all` pipeline skips the invisible step with a warning that carries
+        # the same hint; it must keep the [gpu] extra too.
+        with patch("remove_ai_watermarks.invisible_engine.is_available", return_value=False):
+            result = runner.invoke(main, ["all", str(sample_png)])
+        assert "remove-ai-watermarks[gpu]" in result.output
+
+
+class TestEraseCommand:
+    """Tests for the 'erase' universal region eraser subcommand."""
+
+    def test_erase_help(self, runner):
+        result = runner.invoke(main, ["erase", "--help"])
+        assert result.exit_code == 0
+        assert "--region" in result.output
+        assert "--backend" in result.output
+
+    def test_erase_single_region(self, runner, sample_png, tmp_path):
+        output = tmp_path / "erased.png"
+        result = runner.invoke(
+            main,
+            ["erase", str(sample_png), "--region", "10,10,40,40", "-o", str(output)],
+        )
+        assert result.exit_code == 0, result.output
+        assert output.exists()
+
+    def test_erase_two_regions(self, runner, sample_png, tmp_path):
+        output = tmp_path / "erased2.png"
+        result = runner.invoke(
+            main,
+            [
+                "erase",
+                str(sample_png),
+                "--region",
+                "10,10,30,30",
+                "--region",
+                "120,120,30,30",
+                "-o",
+                str(output),
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        assert output.exists()
+        # The banner reports the region count it processed.
+        assert "2 region(s)" in result.output
+
+    def test_erase_default_output_name(self, runner, sample_png):
+        result = runner.invoke(main, ["erase", str(sample_png), "--region", "10,10,40,40"])
+        assert result.exit_code == 0, result.output
+        assert sample_png.with_stem(sample_png.stem + "_clean").exists()
+
+    def test_erase_malformed_region_exits_nonzero(self, runner, sample_png, tmp_path):
+        output = tmp_path / "x.png"
+        # Only three values: click.BadParameter -> non-zero exit, no output file.
+        result = runner.invoke(
+            main,
+            ["erase", str(sample_png), "--region", "1,2,3", "-o", str(output)],
+        )
+        assert result.exit_code != 0
+        assert not output.exists()
+
+    def test_erase_nonexistent_file(self, runner):
+        result = runner.invoke(main, ["erase", "/nonexistent/file.png", "--region", "0,0,10,10"])
+        assert result.exit_code != 0
+
+    def test_erase_lama_backend_without_onnxruntime(self, runner, sample_png, tmp_path):
+        # The LaMa backend needs onnxruntime; without it the CLI must surface a
+        # clear error and exit non-zero rather than crash. When onnxruntime IS
+        # installed there is no missing-dep path to exercise, so skip.
+        from remove_ai_watermarks.region_eraser import lama_available
+
+        if lama_available():
+            pytest.skip("onnxruntime installed; missing-dep error path not reachable")
+        output = tmp_path / "y.png"
+        result = runner.invoke(
+            main,
+            ["erase", str(sample_png), "--region", "10,10,40,40", "--backend", "lama", "-o", str(output)],
+        )
+        assert result.exit_code != 0
+        assert "onnxruntime" in result.output.lower()
+        assert not output.exists()

tests/test_doubao_engine.py

@@ -1,4 +1,4 @@
-"""Tests for the Doubao visible-watermark engine."""
+"""Tests for the Doubao visible-watermark engine (reverse-alpha only)."""
 
 from __future__ import annotations
 
@@ -8,91 +8,206 @@ import cv2
 import numpy as np
 import pytest
 
-from remove_ai_watermarks.doubao_engine import DoubaoEngine, load_image_bgr
+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,
+    DoubaoEngine,
+    _alpha_template,
+    _glyph_silhouette,
+    _template_match_score,
+    load_image_bgr,
+)
 
 SAMPLE = Path(__file__).resolve().parents[1] / "data" / "samples" / "doubao-1.png"
 
 
-# ── Locate ──────────────────────────────────────────────────────────
-
-
 class TestLocate:
     def test_box_anchored_bottom_right(self):
         eng = DoubaoEngine()
         img = np.zeros((2048, 2048, 3), np.uint8)
         loc = eng.locate(img)
-        # right and bottom edges sit close to the image corner (within margins)
         assert 2048 - (loc.x + loc.w) < int(2048 * 0.03)
         assert 2048 - (loc.y + loc.h) < int(2048 * 0.03)
-        assert loc.is_fallback  # geometry anchor, no bundled template yet
 
     def test_box_scales_with_width(self):
         eng = DoubaoEngine()
         small = eng.locate(np.zeros((1024, 1024, 3), np.uint8))
         large = eng.locate(np.zeros((2048, 2048, 3), np.uint8))
-        # width-relative geometry: 2x wider image -> ~2x wider box
         assert large.w == pytest.approx(small.w * 2, rel=0.1)
 
 
-# ── Detect + remove on the real sample ──────────────────────────────
+# ── Detection: alpha-template NCC ───────────────────────────────────
+
+
+class TestDetect:
+    def test_clean_gradient_not_detected(self):
+        eng = DoubaoEngine()
+        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):
+        """A bright blob is not the glyph shape -> low correlation, not detected."""
+        eng = DoubaoEngine()
+        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_match_score_shape_sensitive(self):
+        """The glyph silhouette correlates with itself, not with a filled block."""
+        sil = _glyph_silhouette()
+        h, w = sil.shape
+        # box that contains the silhouette -> high score
+        box = np.zeros((h + 8, int(w / _ALPHA_WIDTH_FRAC * 0.2) + w), np.uint8)
+        box[4 : 4 + h, 4 : 4 + w] = sil
+        assert _template_match_score(box, _ALPHA_NATIVE_WIDTH) >= DETECT_NCC_THRESHOLD
+        # a uniformly filled box has no glyph structure -> low score
+        solid = np.full_like(box, 255)
+        assert _template_match_score(solid, _ALPHA_NATIVE_WIDTH) < DETECT_NCC_THRESHOLD
 
 
 @pytest.mark.skipif(not SAMPLE.exists(), reason="sample image not present")
 class TestRealSample:
     def test_detects_watermark(self):
-        eng = DoubaoEngine()
-        det = eng.detect(load_image_bgr(SAMPLE))
+        det = DoubaoEngine().detect(load_image_bgr(SAMPLE))
         assert det.detected
-        assert det.confidence > 0.0
-        assert det.coverage > 0.04
+        assert det.confidence >= DETECT_NCC_THRESHOLD
 
-    def test_remove_reduces_glyph_coverage(self):
+    def test_reverse_alpha_removes_mark(self):
         eng = DoubaoEngine()
         img = load_image_bgr(SAMPLE)
-        before = eng.detect(img).coverage
-        out = eng.remove_watermark(img)
-        after = eng.detect(out).coverage
-        # the inpaint should clear most glyph pixels from the corner box
-        assert after < before * 0.5
+        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
 
-    def test_pixels_outside_box_untouched(self):
+    def test_far_region_untouched(self):
         eng = DoubaoEngine()
         img = load_image_bgr(SAMPLE)
-        out = eng.remove_watermark(img)
-        # top-left quadrant is far from the bottom-right mark: must be identical
+        out = eng.remove_watermark_reverse_alpha(img)
         h, w = img.shape[:2]
         assert np.array_equal(img[: h // 2, : w // 2], out[: h // 2, : w // 2])
 
 
-# ── Negative + safety guard ─────────────────────────────────────────
+# ── Reverse-alpha (exact recovery) ──────────────────────────────────
 
 
-class TestNegativeAndGuard:
-    def test_clean_image_not_detected(self):
+class TestReverseAlpha:
+    def test_alpha_asset_loads(self):
+        at = _alpha_template()
+        assert at is not None
+        assert at.dtype.kind == "f"
+        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()
-        # smooth gradient, no watermark
-        ramp = np.tile(np.linspace(0, 255, 1024, dtype=np.uint8), (1024, 1))
-        img = cv2.cvtColor(ramp, cv2.COLOR_GRAY2BGR)
-        det = eng.detect(img)
-        assert not det.detected
+        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))
 
-    def test_clean_image_returned_unchanged(self):
-        eng = DoubaoEngine()
-        ramp = np.tile(np.linspace(0, 255, 1024, dtype=np.uint8), (1024, 1))
-        img = cv2.cvtColor(ramp, cv2.COLOR_GRAY2BGR)
-        out = eng.remove_watermark(img)
-        assert np.array_equal(img, out)
+    @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
 
-    def test_document_background_guard(self):
-        """A dense high-frequency corner (document-like) trips the coverage
-        guard, so the image is left untouched rather than smeared."""
+    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()
-        rng = np.random.default_rng(0)
-        img = np.full((1024, 1024, 3), 255, np.uint8)
-        # fill the bottom-right box area with random grayish text-like noise
-        loc = eng.locate(img)
-        x, y, bw, bh = loc.bbox
-        noise = rng.integers(150, 246, size=(bh, bw), dtype=np.uint8)
-        img[y : y + bh, x : x + bw] = noise[:, :, None]
-        out = eng.remove_watermark(img)
-        assert np.array_equal(img, out)
+        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
+
+    @pytest.mark.parametrize(
+        ("w", "h", "max_err"),
+        [
+            (_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH, 5.0),  # captured width
+            (1773, 2364, 8.0),  # 3:4 portrait -> NCC alignment generalizes the single capture
+        ],
+    )
+    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)
+        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
+
+
+class TestDegenerateAndChannelInputs:
+    """Removal 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."""
+        eng = DoubaoEngine()
+        img = np.zeros((h, w, 3), np.uint8)
+        out = eng.remove_watermark_reverse_alpha(img)
+        assert out.shape == img.shape
+
+    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)
+
+    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)

tests/test_face_protector.py

@@ -1,63 +0,0 @@
-import numpy as np
-
-from remove_ai_watermarks.face_protector import FaceProtector
-
-
-def test_face_protector_initialization():
-    # Will fallback to Haar cascade if ultralytics is missing
-    fp = FaceProtector(use_yolo=False)
-    assert fp.use_yolo is False
-    assert fp.haar_cascade is not None
-
-
-def test_face_protector_lifecycle():
-    fp = FaceProtector(use_yolo=False)
-
-    # Create dummy black image
-    img = np.zeros((200, 200, 3), dtype=np.uint8)
-
-    # Since it's a black image, haar cascade should find 0 faces
-    faces = fp.extract_faces(img)
-    assert isinstance(faces, list)
-    assert len(faces) == 0
-
-    # Restoring 0 faces should result in strictly equal image
-    restored = fp.restore_faces(img, faces)
-    assert np.array_equal(img, restored)
-
-
-def test_face_protector_restore_bypass_on_size_mismatch():
-    fp = FaceProtector(use_yolo=False)
-    img_small = np.zeros((100, 100, 3), dtype=np.uint8)
-
-    # Manually mock a face that is OUT OF BOUNDS for img_small
-    mock_bbox = (80, 80, 130, 130)
-    mock_crop = np.ones((50, 50, 3), dtype=np.uint8) * 255
-    mock_faces = [(mock_bbox, mock_crop)]
-
-    # Attempt to restore onto an image too small for this box
-    restored = fp.restore_faces(img_small, mock_faces)
-
-    # Should safely skip restoring and not crash
-    assert np.array_equal(restored, img_small)
-
-
-def test_face_protector_restore_blending():
-    fp = FaceProtector(use_yolo=False)
-    # Background is black
-    img_target = np.zeros((100, 100, 3), dtype=np.uint8)
-
-    # Face crop is white
-    mock_bbox = (25, 25, 75, 75)
-    mock_crop = np.ones((50, 50, 3), dtype=np.uint8) * 255
-    mock_faces = [(mock_bbox, mock_crop)]
-
-    restored = fp.restore_faces(img_target, mock_faces)
-
-    # The center of the face should be perfectly white (255)
-    assert restored[50, 50, 0] >= 254
-    # The corner of the target should remain perfectly black (0)
-    assert restored[0, 0, 0] == 0
-    # We should have a blending gradient between them due to the gaussian blur mask
-    # For example, around (30, 30) or similar
-    assert 0 <= restored[28, 28, 0] <= 255

tests/test_gemini_engine.py

@@ -124,6 +124,19 @@ class TestGeminiEngine:
         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.
+        gray = np.full((300, 300), 100, dtype=np.uint8)
+        result = self.engine.detect_watermark(gray)
+        assert result is not None
+
+    def test_remove_on_bgra_returns_3_channel(self):
+        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))
@@ -230,3 +243,316 @@ class TestInpainting:
         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
+
+
+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
+    demoted below the detection threshold. Real sparkles escape via high confidence
+    or a bright core-ring margin.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _setup_engine(self):
+        self.engine = GeminiEngine()
+
+    def _composite_sparkle(self, bg_value: int, alpha_scale: float, size: int = 1400):
+        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_bright_core_has_high_margin(self):
+        image, (x, y, w, _h) = self._composite_sparkle(bg_value=60, alpha_scale=1.0)
+        margin = self.engine._core_ring_margin(image, self.engine.get_interpolated_alpha(w), (x, y))
+        assert margin is not None
+        assert margin > self.engine._SPARKLE_FP_MARGIN
+
+    def test_flat_region_has_low_margin(self):
+        """A uniform region (no white sparkle) has ~zero core-ring margin."""
+        flat = np.full((1400, 1400, 3), 128, dtype=np.uint8)
+        config = get_watermark_config(1400, 1400)
+        pos = config.get_position(1400, 1400)
+        alpha = self.engine.get_interpolated_alpha(96)
+        margin = self.engine._core_ring_margin(flat, alpha, pos)
+        assert margin is not None
+        assert abs(margin) < self.engine._SPARKLE_FP_MARGIN
+
+    def test_strong_sparkle_not_demoted(self):
+        image, _ = self._composite_sparkle(bg_value=60, alpha_scale=1.0)
+        det = self.engine.detect_watermark(image)
+        assert det.detected
+        assert det.confidence >= 0.5
+
+    def test_strong_sparkle_on_white_kept(self):
+        """A real sparkle on a near-white background has a LOW core-ring margin (the
+        white overlay barely lifts white) but a HIGH NCC confidence, so the gate must
+        NOT demote it -- high confidence is the escape hatch."""
+        image, (x, y, w, _h) = self._composite_sparkle(bg_value=251, alpha_scale=1.0)
+        margin = self.engine._core_ring_margin(image, self.engine.get_interpolated_alpha(w), (x, y))
+        assert margin is not None
+        assert margin < self.engine._SPARKLE_FP_MARGIN  # low margin
+        det = self.engine.detect_watermark(image)
+        assert det.detected
+        assert det.confidence >= 0.65  # but kept via high confidence
+
+    def test_low_margin_blurred_blob_is_demoted(self):
+        """A heavily-blurred faint near-white blob NCC-matches the sparkle shape (the
+        stage scores fuse above the 0.5 promote bar) but has no bright core (low
+        margin), so the gate demotes the returned confidence below it -- the content
+        false-positive case."""
+        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), 247, dtype=np.float32)
+        a = np.clip(alpha * 0.5, 0.0, 1.0)[:, :, None]
+        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), (31, 31), 0)
+        det = self.engine.detect_watermark(img)
+        # The raw stage scores fuse above 0.5 (would be promoted)...
+        pre = det.spatial_score * 0.5 + det.gradient_score * 0.3 + det.variance_score * 0.2
+        assert pre > 0.5
+        # ...but the no-bright-core gate caps the returned confidence below the bar.
+        assert det.confidence < 0.5
+        assert not det.detected
+
+
+class TestCornerPromotion:
+    """Issue #36: a small sparkle in the corner must not be lost to a larger decoy.
+
+    The size weight that suppresses tiny-patch false positives also lets a larger,
+    mediocre match elsewhere outrank a small, near-perfect sparkle in the corner --
+    so a faint sparkle on a busy background (e.g. a portrait whose bright collar
+    out-scores it) reads as clean. The corner-promotion override rescues it.
+    """
+
+    _W, _H = 400, 520
+    _CORNER = (_W - 40 - 20, _H - 40 - 20, 20)  # bottom-right small sparkle (x, y, scale)
+    _DECOY = (15, 210, 92)  # large decoy: inside the search window, left of the corner
+
+    @pytest.fixture(autouse=True)
+    def _setup_engine(self):
+        self.engine = GeminiEngine()
+
+    def _paste(self, img: np.ndarray, scale: int, x: int, y: int, alpha_scale: float) -> None:
+        tmpl = cv2.resize(self.engine._alpha_large, (scale, scale), interpolation=cv2.INTER_AREA)
+        a = (tmpl * alpha_scale)[:, :, None]
+        roi = img[y : y + scale, x : x + scale]
+        img[y : y + scale, x : x + scale] = a * 255.0 + (1.0 - a) * roi
+
+    def _scene(self, bg_value: int = 40) -> np.ndarray:
+        """Dark scene with a large decoy on the left and a small sparkle in the corner.
+
+        Without the corner-promotion fix the global, size-weighted search locks onto
+        the larger decoy; with it the small corner sparkle wins.
+        """
+        img = np.full((self._H, self._W, 3), bg_value, dtype=np.float32)
+        self._paste(img, self._DECOY[2], self._DECOY[0], self._DECOY[1], 0.55)
+        self._paste(img, self._CORNER[2], self._CORNER[0], self._CORNER[1], 0.55)
+        return np.clip(img, 0, 255).astype(np.uint8)
+
+    def _in_bottom_right(self, region: tuple[int, int, int, int]) -> bool:
+        x, y = region[0], region[1]
+        return x >= self._W * 0.6 and y >= self._H * 0.6
+
+    def test_small_corner_sparkle_is_detected_and_localized(self):
+        det = self.engine.detect_watermark(self._scene())
+        assert det.detected
+        # Must localize to the planted corner sparkle, not the larger left-side decoy.
+        assert self._in_bottom_right(det.region), f"localized to decoy, not corner: {det.region}"
+        assert abs(det.region[0] - self._CORNER[0]) < 16
+        assert abs(det.region[1] - self._CORNER[1]) < 16
+
+    def test_promotion_is_what_rescues_it(self, monkeypatch):
+        """Guard the mechanism: disabling the override mislocalizes to the decoy.
+
+        Proves the scene genuinely needs the override (so the localization test above
+        is not a fluke): with the gate set unreachable the larger decoy wins.
+        """
+        scene = self._scene()
+        assert self._in_bottom_right(self.engine.detect_watermark(scene).region)
+        monkeypatch.setattr(GeminiEngine, "_CORNER_PROMOTE_NCC", 2.0)
+        assert not self._in_bottom_right(self.engine.detect_watermark(scene).region), (
+            "decoy expected to win without the override"
+        )
+
+    def test_no_promotion_on_clean_flat_image(self):
+        """A flat image with no sparkle yields no corner match to promote."""
+        flat = np.full((self._H, self._W, 3), 40, dtype=np.uint8)
+        assert self.engine._corner_promote(flat, -1.0) is None

tests/test_humanizer.py

@@ -1,6 +1,6 @@
 import numpy as np
 
-from remove_ai_watermarks.humanizer import apply_analog_humanizer
+from remove_ai_watermarks.humanizer import apply_analog_humanizer, unsharp_mask
 
 
 def test_humanizer_does_not_modify_original_if_disabled():
@@ -50,3 +50,100 @@ def test_invalid_shape():
     img[0, 0] = 50
     result = apply_analog_humanizer(img)
     assert np.array_equal(img, result)
+
+
+def test_chromatic_shift_does_not_wrap_opposite_edge():
+    # On a horizontal gradient (dark left, bright right), a circular np.roll
+    # would wrap the bright right edge into the R channel's left border and the
+    # dark left edge into the B channel's right border, producing a colored
+    # fringe. After the fix the border columns must replicate their own edge.
+    ramp = np.linspace(0, 255, 64, dtype=np.uint8)
+    gray = np.broadcast_to(ramp, (32, 64))
+    img = np.stack([gray, gray, gray], axis=2).copy()  # B, G, R
+
+    shift = 3
+    result = apply_analog_humanizer(img, grain_intensity=0.0, chromatic_shift=shift)
+
+    # B (index 0) rolled right -> its left border must stay dark (near 0),
+    # NOT wrap the bright right edge.
+    assert result[:, :shift, 0].max() < 60
+    # R (index 2) rolled left -> its right border must stay bright (near 255),
+    # NOT wrap the dark left edge.
+    assert result[:, -shift:, 2].min() > 195
+
+
+def test_unsharp_disabled_returns_unchanged_copy():
+    img = np.full((20, 20, 3), 128, dtype=np.uint8)
+    img[10, 10] = [100, 150, 200]
+    result = unsharp_mask(img, amount=0.0)
+    assert np.array_equal(result, img)
+    assert result is not img  # a fresh copy, never the same array
+
+
+def test_unsharp_overshoots_at_an_edge():
+    # A vertical step (left 100, right 150). Unsharp masking overshoots at the
+    # boundary, pushing pixels above the bright level and below the dark level.
+    img = np.full((20, 20, 3), 100, dtype=np.uint8)
+    img[:, 10:] = 150
+    result = unsharp_mask(img, amount=1.0, sigma=1.5)
+    assert int(result.max()) > 150  # bright-side overshoot
+    assert int(result.min()) < 100  # dark-side undershoot
+
+
+def test_unsharp_preserves_shape_and_dtype():
+    img = np.full((15, 25, 3), 120, dtype=np.uint8)
+    result = unsharp_mask(img, amount=0.6)
+    assert result.shape == img.shape
+    assert result.dtype == np.uint8
+
+
+def test_unsharp_flat_image_is_a_noop():
+    # No edges -> blur equals the image -> unsharp cancels to the original.
+    img = np.full((30, 30, 3), 128, dtype=np.uint8)
+    result = unsharp_mask(img, amount=0.8, sigma=1.0)
+    assert np.array_equal(result, img)
+
+
+class TestAdaptivePolish:
+    """Adaptive polish: target the reference's detail level, sparing text/edges."""
+
+    def test_noop_when_already_sharp(self):
+        from remove_ai_watermarks.humanizer import adaptive_polish
+
+        rng = np.random.default_rng(1)
+        sharp = rng.integers(0, 256, (120, 120, 3), dtype=np.uint8)  # high detail
+        soft_ref = np.full((120, 120, 3), 128, dtype=np.uint8)  # flat -> low target
+        out = adaptive_polish(sharp, soft_ref)
+        assert np.array_equal(out, sharp)  # current >= target -> unchanged copy
+
+    def test_sharpens_a_soft_image_toward_reference(self):
+        import cv2
+
+        from remove_ai_watermarks.humanizer import _laplacian_variance, adaptive_polish
+
+        rng = np.random.default_rng(2)
+        reference = rng.integers(0, 256, (160, 160, 3), dtype=np.uint8)  # very high detail
+        soft = cv2.GaussianBlur(reference, (0, 0), sigmaX=4.0)  # blurred -> low detail
+        out = adaptive_polish(soft, reference, seed=0)
+        assert _laplacian_variance(out) > _laplacian_variance(soft)  # moved toward the target
+
+    def test_mask_spares_edges(self):
+        from remove_ai_watermarks.humanizer import _smooth_grain_mask
+
+        img = np.full((100, 100, 3), 128, dtype=np.uint8)
+        img[:, 50:] = 30  # a hard vertical edge down the middle
+        mask = _smooth_grain_mask(img)
+        # Flat far-left region keeps grain; the column at the edge is suppressed.
+        assert mask[:, :15].mean() > mask[:, 45:55].mean()
+
+    def test_deterministic_with_seed(self):
+        import cv2
+
+        from remove_ai_watermarks.humanizer import adaptive_polish
+
+        rng = np.random.default_rng(3)
+        reference = rng.integers(0, 256, (140, 140, 3), dtype=np.uint8)
+        soft = cv2.GaussianBlur(reference, (0, 0), sigmaX=3.0)
+        a = adaptive_polish(soft, reference, seed=7)
+        b = adaptive_polish(soft, reference, seed=7)
+        assert np.array_equal(a, b)