chore(release): v0.8.4

identify previously ran only the Gemini sparkle as a visible detector, so a
Doubao/Jimeng image with stripped TC260 metadata had no visible fallback. Add
`_visible_text_marks` (registry-backed) so the ByteDance Doubao 豆包AI生成 and
Jimeng 即梦AI marks are detected too, each gated by its own engine NCC threshold
via MarkDetection.detected. New signals `visible_doubao` / `visible_jimeng`
(medium), same stripped-metadata fallback role as the sparkle; excluded from
integrity-clash vendor claims; set platform only when no harder signal did.

Also make `noai/__init__` lazy (PEP 562 __getattr__): importing the light
`noai.c2pa` / `noai.constants` submodules (which identify needs) no longer
eagerly pulls `watermark_remover`, which imports torch + diffusers at module
top. `import remove_ai_watermarks.identify` drops from ~420 MB to ~21 MB in a
full gpu/detect install (torch not loaded), so it fits a 512 MB host; the
removal API resolves lazily on first access. Guarded by TestIdentifyImportIsLight.

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/FUNDING.yml

@@ -0,0 +1,2 @@
+# Enables the "Sponsor" button on the repository page.
+github: wiltodelta

.github/workflows/publish.yml

@@ -13,9 +13,19 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v6
+      - 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

.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

@@ -21,6 +21,10 @@ Thumbs.db
 # Test results
 data/results/
 
+# SynthID corpus reference fills (synthetic black/white calibration tiles,
+# regenerable; the labeled pos/neg/cleaned images ARE tracked, see README)
+data/synthid_corpus/refs/
+
 # Reference materials
 _refs/
 
@@ -30,3 +34,15 @@ yolov8n.pt
 
 # Claude Code local settings
 .claude/settings.local.json
+.claude/scheduled_tasks.lock
+
+# 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/jimeng_capture/seeds/
+data/jimeng_capture/captures/jimeng_content_*.png
+data/gemini_capture/seeds/
+data/gemini_capture/captures/gemini_content_*.png

CLAUDE.md

@@ -5,8 +5,84 @@ 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>` — 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, and the Jimeng "★ 即梦AI" wordmark; `--mark gemini` / `--mark doubao` / `--mark jimeng` force one. Gemini/Doubao recover pixels exactly with no inpaint at native; **Jimeng adds an always-on residual inpaint over the glyph footprint** (its mark re-rasterizes 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 same `--strength`/`--steps`/`--pipeline`/`--device`/`--max-resolution`/`--seed`/`--hf-token` knobs as `invisible`, `--inpaint/--no-inpaint` for the visible pass, and `--humanize` for the Analog Humanizer
+
+## 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. **Release flow:** bump the version in `pyproject.toml` + `src/remove_ai_watermarks/__init__.py` + `uv.lock` (the project's own `[[package]]` entry, ~line 2868), 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 (synthid_corpus images ~65 MB + 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.28`** (`[build-system] requires`): hatchling 1.28+ emits **Metadata-Version 2.5** (PEP 639), 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). 1.27.x emits 2.4, which uploads fine (0.8.2 shipped on it). The pin is unpinned `requires = ["hatchling"]` no longer safe because `uv build` pulls the latest hatchling. Lift the pin only once the publish action's twine is ≥ 6.1.0 (2.5-aware) or the workflow moves to `uv publish`.
+- `bash maintain.sh` — uv-outdated, uv-secure, ruff check/fix, ruff format, pyright, pytest -n auto
+- **Strict pyright is clean across `src/` (0 errors).** The cv2/torch/diffusers boundary files (`gemini_engine`, `region_eraser`, `doubao_engine`, `face_protector`, `humanizer`, `invisible_engine`, `noai/watermark_remover`, and the whole `noai/ctrlregen/` subpackage) carry a documented per-file `# pyright:` relax pragma (or, for `ctrlregen`, a `tool.pyright.executionEnvironments` entry) 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.)
+- **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.
 
 ## Configuration
 
 - GPU/ML modules (invisible_engine, ctrlregen, watermark_remover) are optional — guard imports with `is_available()` checks
-- Tests for ML modules are limited to availability checks (require multi-GB downloads)
+- 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` (now raises `ValueError` when not `0 <= overlap < tile`)/`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.
+
+## 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). 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, 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` — `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. `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.
+- `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 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`): 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 reuse the registry detectors (`_visible_text_marks` → `watermark_registry`), each gated by its own engine NCC threshold via `MarkDetection.detected` (Doubao 0.4, Jimeng 0.45). Doubao/Jimeng are normally also caught by the TC260 AIGC metadata label, 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` (scanned after `_device_platform`, before the issuer fallback), NOT in `_DEVICE_C2PA_PLATFORM`** — verified on real signed files 2026-05-29. Reason: a Galaxy phone stamps BOLine 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 and Jimeng both 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生成"), and `jimeng` (bottom-right "★ 即梦AI"). `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 NCC detectors don't cross-fire (jimeng scores ~0.22 on the Doubao strip, well under its 0.45 threshold), so `auto` picks the right one on a Doubao vs Jimeng image. `cli.cmd_visible` is registry-driven: `--mark auto` → `best_auto_mark`, `--mark <key>` → that mark; `--mark` choices come from `mark_keys()`. `_doubao_remove`/`_jimeng_remove` apply reverse-alpha only when the mark is detected AND `reverse_alpha_available`; outside that, removal is **skipped** (not inpainted). Add a new visible mark = one `KnownMark` entry + its engine (with a captured alpha map); do not re-add per-mark `if` branches in the CLI. **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. **Removal is reverse-alpha with NO inpaint** (`remove_watermark` → `_reverse_alpha_blend`): the sparkle alpha is computed (`alpha = max(R,G,B)/255`) from the bundled sparkle-on-black captures `assets/gemini_bg_{96,48}.png`, which are PURE-BLACK so the alpha is near-exact — re-verified clean on `demo_banana_before.png` 2026-05-31 (the registry's optional `inpaint_residual` is a no-op on a clean removal; an earlier "Gemini smears" read was a misjudged soft-fur original, not an artifact). **The bg assets are now rebuilt from OUR OWN controlled captures** (`data/gemini_capture/captures/`, committed) by `scripts/visible_alpha_solve.py gemini`, which locates the 96px sparkle on the black capture and crops it to the two logo sizes; our capture matched the previously third-party-sourced `gemini_bg_96.png` to **NCC 0.9998**, validating the asset and making it reproducible. Gemini's multi-size fixed-slot model is genuinely different from the Doubao/Jimeng text-strip engines (so it stays a separate engine, not part of the shared-base refactor).
+- `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), `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` — visible Jimeng / Dreamina "★ 即梦AI" remover/detector (cv2/numpy, no GPU), built 2026-05-30 from issue #13's solid captures (@powersee). Mirrors `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.
+- `region_eraser.py` — universal region eraser (`erase` CLI). `erase(image, boxes=|mask=, backend=)` normalizes grayscale (2D) and RGBA (4-channel) inputs up front (`erase_cv2` splits off any alpha plane and re-attaches it on the result): `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 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.
+- `text_protector.py` — text-region protection for the `invisible` SDXL img2img pass (issue #21: CJK/small text deforms at watermark-removal strengths). `is_available()` gates on `cv2.dnn.TextDetectionModel_DB`; `TextProtector.detect_text_boxes(bgr)` runs the **PP-OCRv3 DB** ONNX detector (~2.4 MB, Apache-2.0, opencv_zoo, returns rotated quad polygons) — downloaded+cached to `~/.cache/remove-ai-watermarks` on first use via atomic temp-rename, never bundled, **no torch (cv2.dnn only)**. **Detection is script-agnostic** (DB segments text *regions*, not characters), so Latin / Cyrillic / CJK / Hangul / Arabic / digits all detect identically — language was never the recall lever, **resolution was**. `_detection_input_size(h, w)` (pure, unit-tested) detects at the **native long side capped at `_DET_MAX_LONG_SIDE` (1536), never upscaled**: the old fixed 736 downscaled large canvases so small text fell below the detector and was missed (issue #14, e.g. ~16 px text on a 2048 image). `scripts/text_detection_benchmark.py` measures recall across scripts × sizes × canvas: the cap fix lifts overall hit-rate 0.91 → 1.00 (worst cell 2048/16 px: 0.06 → 1.00) at ~100 ms CPU. Very large canvases with tiny text may still need tiling (documented limit, not built). `build_change_map(boxes, h, w, preserve=0.9, feather=15)` paints a Differential-Diffusion change map. **Polarity (verified empirically):** white(1.0)=PRESERVE original pixels, black(0.0)=MAX change; map is black bg + `preserve` inside text polygons, Gaussian-feathered edges, clipped to [0,1]. `preserve` stays below a hard 1.0 freeze by default so text still scrubs lightly (SynthID survives cropping). **Default text protection is `watermark_remover._run_region_hires`, NOT the differential change map.** Differential Diffusion froze text in latent space (`preserve`<1.0), so the watermark survived *inside* text — violating the "remove SynthID everywhere" requirement; and the SDXL VAE's 8px latent cell softens sub-8px strokes regardless of `preserve` (architectural limit, confirmed by the DD authors — see `docs/text-protection-research.md`). `_run_region_hires` instead: (1) scrubs the whole image (plain img2img), (2) RE-scrubs each detected text block at HIGH resolution and feather-composites it back. `merge_text_regions(boxes,h,w)` groups boxes into local blocks; each crop is upscaled by `_REGION_HIRES_SCALE` 3.0 (applied as an integer factor via int(...), capped so a region stays under `_REGION_MAX_MEGAPIXELS` 1.3 to avoid OOM; skipped if it can't reach 2x — very large text areas then fall back to the global scrub, tiling is the future fix), img2img-scrubbed, downscaled, **phase-correlated back to the original crop to null the ~1-2px round-trip offset** (the shift is applied only on a confident, small correlation -- `response > 0.3` and `|shift| < 4` -- so a spurious large offset on a flat crop no longer garbles the composite; and after a CPU fallback the generator is dropped before the per-region passes to avoid an MPS-vs-CPU generator device mismatch) (a sub-pixel shift garbles the composite even when text is crisp; integer scale alone did NOT fix it because the diffusion pipeline rounds dims to a multiple of 8), then `feather_paste`d. Every pixel is regenerated, so the watermark is removed everywhere AND small text stays crisp (high-res strokes span >1 latent cell). Validated on synthetic 18px multilingual text: text-region SSIM 0.28 (plain) → 0.48 (region-hires), visually garbled → readable across Latin/Cyrillic/CJK, residual shift ~0.5px. Gated to the SDXL `DEFAULT_MODEL_ID` + detector (`_can_protect_text`); no text → plain global scrub (text-free inputs pay only the cheap cv2 detection). CLI off-switch `--no-protect-text` on `invisible`/`all`. `merge_text_regions` + `feather_paste` are pure, unit-tested without a model (`tests/test_text_protector.py`). **MUST still be confirmed by the SynthID oracle** (openai.com/verify / Gemini app) that a region-rescrubbed text zone reads watermark-free before trusting it in prod. The legacy `_run_differential` / `build_change_map` / `_load_differential_pipeline` (community `pipeline_stable_diffusion_xl_differential_img2img`, `custom_revision="0.38.0"`) remain in the file but are no longer the default; the diff pipeline upcasts the VAE to fp32 internally, so do **not** add `upcast_vae()`/`enable_attention_slicing` there (NaN/black on fp16 MPS). `build_change_map` is still unit-tested.
+- `face_protector.py` — YOLO detect + soft-blend pattern; mirror this for any "protect region during diffusion" features. The expensive extract+blend already runs only when a face is found, but the YOLO detector itself always loads+runs to decide; CLI off-switch `--no-protect-faces` on `invisible`/`all` skips it entirely (mirrors `--no-protect-text`), for images known to have no people.
+- `humanizer.py` — optional post-process "humanize" effects (cv2/numpy). The chromatic-shift step replicates the border instead of wrapping opposite-edge pixels, so a shifted channel no longer bleeds the far edge into the near one.
+- `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). cv2/numpy are imported lazily inside the functions, so the module is cheap to import in a bare env.
+
+### Doubao clean-reverse-alpha distillation (re-investigated 2026-05-29)
+
+**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). **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). **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` 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). **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 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. **ctrlregen is compute-bound, not memory-bound, on MPS:** the clean-noise profile tiles to 512px (e.g. ~12 tiles for a 1122x1402 image) and runs the full step count per tile (strength 1.0 -> ~50 effective steps/tile), so on a base-tier Apple-GPU laptop it is ~25-30 min/image after the one-time DINOv2-giant download, regardless of having 32 GB -- a discrete CUDA GPU (fp16, no tiling) is the right place for ctrlregen, while the default SDXL pass is comfortable on a 32 GB Mac. 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.
+- **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` now swaps 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), and the **differential / region-hires** pipeline already upcasts the VAE itself (see the `text_protector` bullet). 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 and was NOT verifiable on this MPS machine -- confirm on the backend / an NVIDIA box.
+- 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`.
+- **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 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. 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" 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:** **CORRECTION (2026-05-31, oracle-verified GPU study, SUPERSEDES the 0.10 claim below): the current Gemini SynthID survives 0.10/0.15/0.2 and is REMOVED only at strength 0.3** (Modal A100, native res, Gemini-app "Verify with SynthID", n=3 FRESH Gemini images, `protect_text`/`faces` OFF; 0.2 still present, 0.3 removed). `DEFAULT_STRENGTH` was raised **0.10 -> 0.30** to match. The "0.10 removes it" finding below was n=1 and is now stale -- the threshold has climbed 0.05 -> 0.10 -> ~0.3 as Google hardens SynthID, so re-test against fresh Gemini periodically (moving target). 0.3 costs SSIM ~0.97 vs original (modest) but softens dense/fine typography, and is **overkill for non-SynthID sources** (OpenAI/ChatGPT carry C2PA, NOT Google SynthID -- their pixels read negative on the Gemini verifier at every strength, so 0.10 is plenty there; a per-source strength via `identify` was considered and deferred in favour of the simpler single 0.3 default). **`protect_text` does NOT block SynthID removal and is recommended ON (corrected 2026-05-31 by A/B tests at 0.3, reversing an earlier wrong claim):** verified on a GENUINE Gemini-SynthID image (`gemini_633uuy`, a photo with a Chinese-text sign) AND an OpenAI infographic (`qw1212ss_pic3`), both with protect_text ON and OFF -- the Gemini-subject run is the load-bearing one (Gemini-oracle verified; the OpenAI image is not a valid SynthID subject). SynthID is a GLOBAL watermark, so regenerating the non-text regions at 0.3 destroys the payload whether protect_text is on or off -- it clears in BOTH. protect_text additionally SALVAGES text fidelity (medium headings/body stay readable; with it off the same text garbles), at ~3x runtime. Only the very smallest text still softens at 0.3 (0.3 is inherently aggressive). **Recommended SynthID config: strength ~0.3 + protect_text ON (the default).** The earlier "protect_text shields the watermark, use `--no-protect-text`" claim was wrong -- it mistook a strength failure (0.10 too weak) for a protection effect. **Oracle scope (load-bearing):** the Gemini app "Verify with SynthID" is the ONLY valid SynthID oracle (it detects Google's mark on any image); `openai.com/verify` is scoped to OpenAI provenance (its own C2PA) and is **NOT** a SynthID oracle, so a negative there is meaningless for SynthID and the older "OpenAI cleared at 0.05 on openai.com/verify" notes below are about provenance, not a pixel-SynthID measurement. **CORRECTION (2026-05-30): strength 0.05 does NOT remove the CURRENT Google SynthID (Nano Banana / Gemini 3).** Re-verified via the Gemini "Verify with SynthID" oracle on a real image: at 0.05 SynthID is still detected; at **0.10 it is removed** (OpenAI's SynthID was already cleared at 0.05). So the default strength was raised 0.05 -> **0.10** (`DEFAULT_STRENGTH` in `watermark_profiles.py`; CLI `--strength` defaults to 0.10), and that higher strength is exactly why text protection (`_run_region_hires`) runs by default (text deforms more at 0.10). Caveat: n=1 Google + n=1 OpenAI image so far -- broad oracle validation across the corpus is pending (different images may need a different strength). **Resolution dependence confirmed by a user report (#14, qw1212ss, 2026-05-31):** on 1600x1600 gpt-image outputs checked via openai.com/verify, 0.05 left SynthID detected on **7/8** images, while small images (376x429) cleared at ~100% -- so "OpenAI cleared at 0.05" was a low-resolution result; a larger canvas carries a stronger watermark and needs more strength. **Policy (do NOT chase a single magic number or build resolution/vendor-adaptive defaults): 0.10 is the default because it is what clears the watermark today; if the oracle still reads SynthID, the guidance is simply to raise `--strength` (0.12, then 0.15), using the lowest value that verifies clean.** There is no local SynthID detector, so the tool cannot self-check and auto-tune; both vendors tighten the watermark over time, so any fixed value is a moving target. README "Removing SynthID" documents the strength-ladder guidance for users. The original claim below (0.05 defeats SynthID v2) held for the specific May-2026 Gemini output tested then but is stale for current Google SynthID. **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 defaultLine truncated
+- **CtrlRegen profile uses a clean-noise default strength, NOT the SDXL 0.10 (fixed 2026-05-31).** **CORRECTION (2026-05-31, same oracle-verified GPU study): ctrlregen at its clean-noise strength DESTROYS real images** -- smooth/background regions fill with hallucinated micro-text garbage; the pipeline is binary (low strength = no-op, high = destroy, no usable middle) and heavy (~8.5 min / ~$0.30 vs ~25 s / ~$0.02 for SDXL). So the literature's "clean-noise is the lever" (detailed below) did NOT survive empirical testing on real content. ctrlregen is now flagged **EXPERIMENTAL** (CLI `--pipeline` help, README, and the `watermark_profiles` comment) and is **NOT for production** -- SDXL img2img at ~0.3 is the shippable path. The clean-noise-default plumbing below is kept (so the profile at least does real work if anyone opts in), but do not recommend ctrlregen. `--pipeline ctrlregen` no longer inherits the SDXL img2img `--strength` default. `resolve_strength(strength, profile)` (`watermark_profiles.py`, pure + unit-tested in `test_platform.py::TestResolveStrength`) resolves an unset `--strength` to `CTRLREGEN_DEFAULT_STRENGTH` (**1.0**) for ctrlregen and `DEFAULT_STRENGTH` (0.10) for the SDXL default; an explicit `--strength` always wins (including `0.0` -- the resolver checks `is None`, not falsiness, so it does not repeat the old `strength or DEFAULT` bug). CLI `--strength` for `invisible`/`all` now defaults to **None** (batch already did); the display (`cli.py`) and the engine (`watermark_remover.remove_watermark`) both route through `resolve_strength` so they never disagree. **Why (deep-research pass 2026-05-31, primary sources):** CtrlRegen's removal power comes from regenerating from (near) clean Gaussian noise, not the light partial-noise img2img the SDXL pass uses. CtrlRegen (ICLR 2025, arXiv:2410.05470) diagnoses verbatim that prior partial-noise regeneration "struggles with high-perturbation watermarks" because a small noise step "retains" watermark info that diffuses back into the output; the fix is a clean-noise start, which with `StableDiffusionControlNetImg2ImgPipeline` maps to strength ~1.0 (image structure held by the canny ControlNet + DINOv2 IP-Adapter, not by the watermarked latent). **Before the fix `--pipeline ctrlregen` ran at 0.10** -- a near-identity pass that loaded ControlNet + DINOv2-giant and then barely changed the image (a removal no-op). **NOT yet oracle-verified** that clean-noise ctrlregen clears the stubborn high-texture gpt-image class that 0.20 SDXL img2img could not (issue #14, qw1212ss: pic3/6/7 survived SynthID through 0.05->0.20); that is the pending controlled test (via openai.com/verify with the IP-country rate-limit bypass). **Forensic-stealth caveat applies harder here:** regeneration-family removal is the MOST detectable as "an image that went through a removal pipeline" (CtrlRegen+ 99.97% TPR@1%FPR, arXiv:2605.09203). **Two #14-investigation hypotheses the literature did NOT confirm:** (1) our "VAE round-trip drives removal, denoising strength does not" framing is only PARTIALLY supported -- arXiv:2510.09263 confirms SynthID was hardened against *weak* VAE re-generation (explaining survival) but does not name the VAE round-trip as the removal vector; (2) our "survival correlates with high-frequency CONTENT texture (Laplacian 466 vs 236)" is unconfirmed by any primary source -- the literature establishes *watermark-perturbation-strength* dependence (a different axis), so the texture correlation stays our own unverified observation, not a literature-backed fact.

README.md

@@ -4,18 +4,29 @@ Remove **visible** and **invisible** AI watermarks from images generated by Goog
 
 Strips SynthID, C2PA Content Credentials, EXIF/XMP "Made with AI" labels, and visible sparkle overlays — all in one command.
 
+> ## Try it online: [raiw.cc](https://raiw.cc)
+>
+> 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 via reverse alpha blending (fast, offline, deterministic)
-- **Invisible watermark removal** — SynthID, StableSignature, TreeRing via diffusion-based regeneration
-- **AI metadata stripping** — EXIF, PNG text chunks, C2PA provenance manifests, 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
+- **Visible watermark removal** — a registry of known marks in their usual places: the Gemini / Nano Banana sparkle, the Doubao "豆包AI生成" text strip, and the Jimeng "★ 即梦AI" wordmark. 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; the Doubao and Jimeng 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, **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
 - **Smart Face Protection** — automatic extraction and blending of human faces to prevent AI distortion
 - **Batch processing** — process entire directories
 - **Detection** — three-stage NCC watermark detection with confidence scoring
-
-> **Try it online** — don't want to install anything? Use [raiw.cc](https://raiw.cc), a free web service powered by this library.
+- **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" 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
 
@@ -27,15 +38,27 @@ Strips SynthID, C2PA Content Credentials, EXIF/XMP "Made with AI" labels, and vi
 
 | AI model | Visible watermark | Invisible watermark | Metadata | Our approach |
 | --- | --- | --- | --- | --- |
-| **Google Gemini / Nano Banana** | ✅ Sparkle logo | ✅ SynthID | ✅ C2PA + EXIF | Alpha reversal + diffusion + metadata strip |
+| **Google Gemini / Nano Banana / Gemini 3 Pro** | ✅ Sparkle logo | ✅ SynthID v1 + v2 (default SDXL pipeline, native resolution) | ✅ C2PA + EXIF | Alpha reversal + diffusion + metadata strip |
 | **OpenAI DALL-E 3 / ChatGPT** | — | — | ✅ C2PA manifest | Metadata strip |
-| **Stable Diffusion (AUTOMATIC1111, ComfyUI)** | — | ✅ DWT / steganographic | ✅ PNG text chunks | Diffusion regeneration + metadata strip |
+| **OpenAI ChatGPT Images 2.0** (gpt-image-2) | — | ✅ SynthID + content-specific pixel watermark (since May 2026; no local decoder, openai.com/verify oracle) | ✅ C2PA manifest (verified) | Diffusion regeneration + metadata strip |
+| **Stable Diffusion / SDXL (AUTOMATIC1111, ComfyUI)** | — | ✅ DWT-DCT (imwatermark — locally detectable) | ✅ PNG text chunks | Diffusion regeneration + metadata strip |
+| **Black Forest Labs FLUX** | — | ✅ DWT-DCT (imwatermark — locally detectable) | ✅ C2PA (FLUX.2 Pro) | Diffusion regeneration + metadata strip |
 | **Adobe Firefly** | — | — | ✅ Content Credentials (C2PA) | Metadata strip |
+| **Stability AI** (DreamStudio / Stable Image) | — | — | ✅ C2PA ("Stability AI Ltd") | Metadata strip |
+| **Microsoft Designer / Bing Image Creator** | — | ✅ SynthID via DALL-E backend (Designer) | ✅ C2PA (Bing runs MAI-Image, signed "Microsoft") | Metadata strip |
+| **xAI Grok (Aurora)** | — | — | ✅ EXIF signature scheme (no C2PA): `Signature:` blob + UUID `Artist` | Detected (`identify`); metadata strip |
 | **Midjourney** | — | — | ✅ EXIF + XMP (prompt, model, seed) | Metadata strip |
+| **Meta AI** | — | — | ✅ IPTC "Made with AI" (digitalSourceType) | Metadata strip (removes the label) |
+| **Doubao** (ByteDance) / China AIGC generators | ✅ "豆包AI生成" text strip (bottom-right) | — | ✅ TC260 AIGC label (`<TC260:AIGC>` XMP, `AIGC` PNG chunk, or EXIF JSON) **+ C2PA** signed by ByteDance Volcano Engine (`volcengine`) | Reverse-alpha (captured α map) + thin residual inpaint, NCC-aligned across resolutions, + metadata strip |
+| **Jimeng / Dreamina** (即梦AI, ByteDance) | ✅ "★ 即梦AI" wordmark (bottom-right) | — | ✅ TC260 AIGC label + C2PA (Volcano Engine) | Reverse-alpha (captured α map) + residual inpaint over the glyph footprint, NCC-aligned across resolutions, + metadata strip |
+| **Samsung Galaxy AI** (Generative Edit, Sketch to Image, ...) | — | — | ✅ C2PA (signer "Samsung Galaxy") + `trainedAlgorithmicMedia` / proprietary `genAIType` marker | Detected (`identify`) + 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 watermarks (logo overlays) are currently used only by Google Gemini / Nano Banana. Other services rely on invisible watermarks and/or metadata. Our diffusion-based regeneration works against any invisible watermark in pixel or frequency domain.
+> Visible overlays are used by Google Gemini / Nano Banana (sparkle logo) and by ByteDance's Doubao ("豆包AI生成" corner text) and Jimeng / Dreamina ("★ 即梦AI" wordmark). All are removed on CPU by reverse-alpha against a captured alpha map (Jimeng adds a residual inpaint over the glyph footprint, since its mark re-rasterizes 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 (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" 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
 
@@ -57,24 +80,57 @@ A three-stage NCC (Normalized Cross-Correlation) detector finds the watermark po
 
 **Speed**: ~0.05s per image. No GPU needed.
 
+### Removing the Doubao "豆包AI生成" text watermark
+
+Doubao (ByteDance) stamps every output with a light, semi-transparent "豆包AI生成" text strip in the bottom-right corner — the visible AIGC label mandated by China's TC260 standard. It is a fixed semi-transparent white overlay, so it is removed by **reverse-alpha blending**: `original = (watermarked - α·logo) / (1 - α)`, recovering the true pixels instead of hallucinating them. The α map is solved from controlled black/gray captures (rebuildable with `scripts/visible_alpha_solve.py`). Like the Jimeng mark, Doubao re-rasterizes its text slightly per image, so reverse-alpha is followed by a thin residual inpaint over the glyph footprint to clear the leftover edges, and the α template is NCC-aligned to the actual mark (handling per-image scale/position jitter). Detection matches the same glyph silhouette against the corner (normalized correlation), so it keys on the "豆包AI生成" shape, not on textured corners.
+
+**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
+```
+
+### Universal region eraser
+
+For any visible mark the dedicated engines do not cover — a logo anywhere, any colour — `erase --region x,y,w,h` inpaints the box you specify. The default `cv2` backend is instant and dependency-free; the optional `lama` backend (big-LaMa via onnxruntime, `lama` extra, ~200 MB model downloaded on first use) gives much cleaner fills on textured regions at the cost of ~3-4 GB RAM per call.
+
 ### Removing SynthID and other invisible watermarks
 
 Google embeds **SynthID** into every image generated by Gemini / Nano Banana. Other AI services use StableSignature, TreeRing, and similar schemes. These imperceptible frequency-domain patterns survive cropping, resizing, and JPEG compression.
 
-The removal pipeline:
+The removal pipeline (default profile, SDXL):
 
 ```text
-image → downscale to 768px → encode to latent space (VAE)
+image → encode to latent space (VAE) at native resolution
       → add controlled noise (forward diffusion)
-      → denoise (reverse diffusion, ~2 steps at strength 0.02)
-      → decode back to pixels (VAE) → upscale to original resolution
+      → denoise (reverse diffusion, ~50 steps at strength 0.30)
+      → decode back to pixels (VAE)
 ```
 
-The key insight: even minimal noise injection (strength 0.02 = 2% perturbation) breaks the watermark signal while preserving visual quality. The diffusion model acts as a learned image prior — it reconstructs the image faithfully while destroying the watermark pattern.
+- Native resolution avoids shrinking the input to 1024 px first; that down-then-up round-trip was the main quality loss (issue #10). Use `--max-resolution N` only to cap GPU/MPS memory on very large inputs.
 
-**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.
+> **Default strength is `0.30`, tuned to remove the current Google SynthID.** An oracle-verified study (fresh Gemini images, "Verify with SynthID") found the current SynthID survives `0.10`/`0.15`/`0.20` and clears only at `0.30`. SynthID is a moving target (the threshold has climbed `0.05` → `0.10` → `~0.30` as Google hardens it), and there is no local SynthID detector, so the tool cannot self-check and auto-tune. If the oracle still reads SynthID, raise `--strength` further; if you care more about preserving fine text, lower it. `0.30` softens dense typography somewhat, so use the lowest value that comes back clean on the oracle.
+>
+> **Keep text protection on (the default) — it does not block SynthID removal.** SynthID is a global watermark, so strength `0.30` clears it whether or not text is protected, and text protection keeps headings and body text readable through the pass (only the very finest print still softens at `0.30`). You do not need to disable it for removal; `--no-protect-text` only trades text quality for a faster run.
+>
+> **OpenAI / ChatGPT images do not carry Google SynthID** (they use C2PA metadata, stripped by the metadata step), so `0.30` is overkill there; `--strength 0.10` preserves quality and the metadata strip is what matters.
+>
+> **`--pipeline ctrlregen` is experimental and not recommended.** On paper CtrlRegen ([ICLR 2025](https://github.com/yepengliu/CtrlRegen)) regenerates from near-clean Gaussian noise to defeat robust watermarks, but in testing on real images it **destroys content** — smooth and background regions fill with hallucinated micro-text — and it is heavy (several GB of extra models, minutes per image). It has no usable middle setting (too low removes nothing, high enough to remove wrecks the image), so the shippable path is the default SDXL pipeline at `~0.30`. CtrlRegen stays available for experimentation only.
 
-**Analog Humanizer**: optional film grain and chromatic aberration injection that makes the output indistinguishable from a photo of a screen, defeating AI-generated image classifiers.
+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.
+
+> **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.
+
+**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. Pass `--no-protect-faces` to skip the detector entirely (useful when the image has no people).
+
+**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.)
+
+**Text Protection** (automatic): SDXL img2img regenerates every pixel, so small text and glyphs get deformed at the strengths that defeat SynthID. The SDXL pipeline guards against this by default: a PP-OCRv3 text detector (a 2.4 MB ONNX model run on CPU via OpenCV's DNN module, downloaded and cached on first use) locates text regions, and if any are found the whole image is scrubbed normally and then each text block is **re-scrubbed at high resolution** and composited back. Because the text is regenerated (not copied), the watermark is still removed inside it, while running the text region at higher resolution keeps small strokes crisp through the regeneration. Detection is **language-agnostic** (it finds text regions, not characters), so Latin, Cyrillic, CJK, Hangul, Arabic, and digits are all protected, and it runs at the image's native resolution so small text on large images is not missed. Text-free images run the standard pass at no extra cost. Pass `--no-protect-text` to turn it off. SDXL default pipeline only.
 
 ### Stripping C2PA, EXIF, and "Made with AI" metadata
 
@@ -134,6 +190,21 @@ After installation the `remove-ai-watermarks` command is available system-wide.
 > ```bash
 > pip install -e ".[gpu]"   # or: uv pip install -e ".[gpu]"
 > ```
+>
+> To let `identify` decode the open Stable Diffusion / SDXL / FLUX invisible
+> watermarks, install the `detect` extra (adds the `invisible-watermark` decoder):
+>
+> ```bash
+> pip install -e ".[detect]"   # or: uv pip install -e ".[detect]"
+> ```
+>
+> To also decode the open **Adobe TrustMark** watermark (behind Adobe Durable
+> Content Credentials), install the `trustmark` extra (pulls torch and downloads
+> model weights on first use):
+>
+> ```bash
+> pip install -e ".[trustmark]"   # or: uv pip install -e ".[trustmark]"
+> ```
 
 #### Invisible watermark removal
 
@@ -179,13 +250,35 @@ remove-ai-watermarks batch ./images/ --mode all
 #### Individual commands
 
 ```bash
-# Visible watermark only (Gemini / Nano Banana sparkle) — fast, offline
+# Identify provenance: where an image was made + its watermark inventory.
+# Aggregates C2PA, IPTC "Made with AI", embedded SD/ComfyUI params, EXIF/XMP
+# generator tags (incl. inside AVIF/HEIF), the SynthID proxy, the visible Gemini
+# sparkle, and (with the [detect] extra) the open SD/SDXL/FLUX invisible
+# watermark into one verdict. Reports "unknown"
+# (never "clean") when no signal is found, since stripped metadata is not proof
+# of a clean origin. Add --json for machine-readable output.
+remove-ai-watermarks identify image.png
+
+# Visible watermark only — fast, offline, CPU. --mark auto (default) finds the
+# strongest known mark (Gemini sparkle / Doubao "豆包AI生成" / Jimeng "即梦AI"); force
+# one with --mark gemini / doubao / jimeng. 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.
+# Default cv2 inpainting (CPU). --backend lama uses big-LaMa (extra 'lama').
+remove-ai-watermarks erase image.png --region 1640,1930,400,100 -o clean.png
+
 # 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
+# GPU/MPS, cap the long side: --max-resolution 2048
+# Text / CJK glyphs are preserved automatically; disable with --no-protect-text
 
 # Check / strip AI metadata (C2PA, EXIF, "Made with AI" labels)
+# --check also flags SynthID-bearing sources: a C2PA manifest signed by
+# Google or OpenAI implies an invisible SynthID watermark in the pixels
+# (both vendors pair the two). Adobe Firefly / Microsoft sign C2PA without
+# SynthID, so they are reported as C2PA only.
 remove-ai-watermarks metadata image.png --check
 remove-ai-watermarks metadata image.png --remove
 
@@ -248,17 +341,67 @@ pip install certifi
 - [CtrlRegen](https://github.com/yepengliu/CtrlRegen) by Liu et al. (ICLR 2025) — controllable regeneration pipeline
 - NeuralBleach (MIT) — analog humanizer technique
 
-## ⚠️ Disclaimer
+## Roadmap
 
-This tool is provided for **educational and research purposes only**.
+Tracked but not yet implemented:
 
-Removing AI watermarks to misrepresent AI-generated content as human-created
-may violate applicable laws, including the U.S. Digital Millennium Copyright Act
-(DMCA) and the COPIED Act. Users are solely responsible for ensuring their use
-complies with all applicable laws and platform terms of service.
+- **SynthID-Image v2 automated regression test**. The default SDXL profile defeats v2 per manual checks against the [Gemini app](https://support.google.com/gemini/answer/16722517)'s "Verify with SynthID" feature on a Gemini 3 Pro output (May 2026). An automated end-to-end test would need either programmatic access to the [SynthID Detector portal](https://blog.google/innovation-and-ai/products/google-synthid-ai-content-detector/) (waitlist for media professionals and researchers) or an offline surrogate detector. The spectral phase-coherence surrogate from [reverse-SynthID](https://github.com/aloshdenny/reverse-SynthID) was evaluated and does not separate watermarked from cleaned real-content images (it only fires on controlled solid-color references at exact resolution), so it is not a usable oracle. Open.
+- **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**. 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.
 
-The authors do not condone the use of this tool for deception, fraud,
-or any activity that violates applicable laws or regulations.
+Won't fix:
+
+- **Nightshade / Glaze / PhotoGuard removal**. These are defensive perturbations used by artists to protect their work from being scraped into AI training sets. Removing them attacks artists, not AI provenance. Out of scope.
+
+## Legal
+
+Watermarking and provenance for AI-generated content is now regulated in several jurisdictions. The table below summarises the May 2026 status. None of this is legal advice.
+
+| 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 (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 **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. |
+
+## Threat model
+
+This tool defends already-distributed AI imagery against automatic detection systems (social-platform "Made with AI" labels, third-party classifiers, content-policy filters). It does **not** retroactively anonymise generation.
+
+In particular, **SynthID** (Google DeepMind) is embedded across Google's generative media stack — Imagen (images), Veo (video), Lyria (audio) — and Gemini app image outputs (Nano Banana / Gemini 3 Pro, which we verified positive via the Gemini app's SynthID oracle); Google reported over 10 billion items watermarked by December 2025. It carries a **multi-bit payload** — the research paper's SynthID-O variant encodes 136-bit payloads in 512x512 images ([arxiv 2510.09263](https://arxiv.org/abs/2510.09263)). The payload is believed to encode a user / session identifier. If the original watermarked file ever passed through a system controlled by the prompt originator (a saved Gemini account history, a screenshot uploaded to a Google product, a backup), Google retains the ability to link that original to the generating account. Stripping the watermark from a copy you possess does not erase Google's server-side record.
+
+Use cases where the threat model fits:
+- You generated the image yourself, want to publish it as your own work, and accept the consequences if Google ever publishes their detector logs.
+- You are running a security / robustness evaluation.
+- You are preserving art or historical record against false-positive "AI-generated" labels.
+
+Use cases where the threat model **does not** fit:
+- Generating an image, expecting that removing the watermark anonymises you to Google. It doesn't.
+- Distributing AI-generated content while claiming human authorship. The watermark is one of several traceability layers.
+
+This tool is intended for legitimate purposes such as:
+
+- Privacy protection (removing metadata that leaks user account identifiers).
+- Art preservation and fair-use research.
+- Removing false-positive "Made with AI" labels from human-edited photographs.
+- Security research and watermark robustness study.
+
+**Who bears the liability.** This is general-purpose software and is itself lawful to publish and run; legal responsibility attaches to the person who removes a marker and to how the result is then used, and the hinge is intent. Removing AI provenance to pass AI-generated content off as human-made, to commit fraud, to produce non-consensual deepfakes, or to conceal copyright infringement can expose the remover to liability. Two kinds of exposure are worth knowing:
+
+- **The downstream act.** Deception, fraud, defamation, IP infringement, or breaking a platform's terms — judged by intent and harm, not by the act of editing metadata itself. In the US, the **DMCA (17 U.S.C. § 1202)** specifically bars removing "copyright management information" *with intent to conceal or enable infringement*.
+- **The removal itself.** Some jurisdictions penalise tampering with the label/metadata as such, regardless of downstream use — notably **China** (Labeling Measures) and **India** (IT Amendment Rules 2026), which expressly prohibit removing or suppressing the AI label and provenance metadata. The US **COPIED Act** would do the same if enacted.
+
+Legitimate uses — publishing your own work, privacy (stripping metadata that leaks an account identifier), security / robustness research, or removing a false-positive "Made with AI" label from a human-edited photograph — are generally lawful. Users are solely responsible for ensuring their use complies with all applicable laws. The authors do not condone use of this tool for deception, fraud, or any activity that violates applicable laws or regulations. None of this is legal advice.
 
 ## License
 

data/doubao_capture/README.md

@@ -0,0 +1,87 @@
+# 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`).
+
+## What we already know (verified from prior art, 2026-05-26)
+
+- Blend model: **alpha compositing with a white logo** `watermarked = a*logo + (1-a)*original`,
+  `logo = (255,255,255)`. Inversion: `original = (watermarked - a*logo) / (1-a)`.
+  Confirmed by two independent sources (an open-source remover's algorithm doc + aiwatermarkremover.dev,
+  both say "alpha map"). One commercial blog (pixelcleanai) claims "screen blend" instead; the gray
+  capture below settles it empirically.
+- Position: **bottom-right corner**, small margins (right ~8-20px, bottom ~5px), scales with image size.
+  Confirmed by our sample `data/samples/doubao-1.png` (2048x2048) plus three sources.
+- 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.
+- 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
+
+The "豆包AI生成" mark is Doubao's. Jimeng / Dreamina use a different mark. Generate on doubao.com so
+the captured template matches our target.
+
+## How to capture (image-edit path, most reliable)
+
+For each seed in `seeds/`:
+
+1. Open Doubao image generation, use the image-edit / reference mode, upload the seed.
+2. Prompt (Chinese preferred):
+   `请完全按照原图重新生成这张图片，保持完全一致，不要添加或修改任何内容`
+   (English: `Recreate this image exactly as it is, keep it identical, do not add or change anything`)
+3. Download the ORIGINAL output file (not a screenshot). Do not crop / edit / re-save.
+
+Prior art confirms uploading a pure-black image and letting Doubao stamp it works.
+
+If edit mode is unavailable and text-to-image refuses a solid color, fall back to generating 10-12
+normal-content images at one fixed resolution; the mark is the only constant across them and can be
+extracted by per-pixel min/median.
+
+## What to capture (priority top to bottom)
+
+| Aspect | black | white | gray128 | why |
+|--------|-------|-------|---------|-----|
+| 1:1    | 3     | 1     | 1       | primary alpha map + confirm the stamp is pixel-identical across runs + settle blend mode |
+| 16:9   | 2     | 1     | 1       | anchor rule in landscape |
+| 9:16   | 2     | 1     | 1       | anchor rule in portrait |
+| 4:3, 3:4 | 1 each | -   | -       | optional, refines anchor rule |
+
+- 3 blacks on 1:1: if the first two are byte-identical in the watermark region, the third is optional.
+- gray128 is the blend-mode test: predict the gray result from the black capture under alpha vs screen;
+  whichever matches the real gray output is the true blend.
+- If the UI offers multiple output resolutions (1K / 2K / 4K), capture one black per resolution on 1:1 -
+  needed to learn how the watermark scales.
+- Also grab 3-5 normal-content images on 1:1 for end-to-end removal validation.
+
+## Hygiene
+
+- Original download, never a screenshot. PNG preferred; if Doubao only gives JPEG, note it.
+- No crop / edit / re-save. Default settings, watermark left ON.
+
+## Naming, drop into `captures/`
+
+```
+doubao_black_1x1_1.png
+doubao_white_1x1_1.png
+doubao_gray128_1x1_1.png
+doubao_black_16x9_1.png
+doubao_content_1x1_1.png
+```
+
+## Also report back
+
+1. Which resolutions and aspect ratios the Doubao UI actually offers.
+2. Whether there is a watermark on/off toggle in the UI.
+3. Download format (PNG or JPEG).

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/samples/openai-images-2/README.md

@@ -0,0 +1,41 @@
+# OpenAI ChatGPT Images 2.0 sample
+
+Reference image generated by OpenAI's ChatGPT Images 2.0 (`gpt-image-2`, launched 2026-04-21). Kept in the repo so the C2PA manifest parser and invisible-watermark pipeline can be re-verified against a real production output.
+
+## `amur-leopard.png`
+
+- Resolution: 1055 x 1491, PNG, 3.0 MB
+- Downloaded: 2026-04-22
+- Content: AI-generated infographic about the Amur leopard (*Panthera pardus orientalis*), chosen to exercise the model's new accurate-text-rendering feature
+
+### Embedded C2PA manifest (caBX chunk, 23607 bytes)
+
+Parsed by `remove-ai-watermarks metadata --check`:
+
+| Field | Value |
+| --- | --- |
+| `claim_generator` | GPT-4o |
+| `c2pa_spec` | 2.2.0 |
+| `digital_source_type` | http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia |
+| `c2pa_actions` | created, converted |
+| Signer | OpenAI OpCo, LLC / OpenAI Media Service API |
+| Claim signing CA | Trufo C2PA Claim Signing CA (2025) -> Trufo C2PA Root CA (ECC P384) |
+| Timestamp authority | OpenAI TSA Issuing CA -> OpenAI TSA Root CA |
+
+The `trainedAlgorithmicMedia` tag is what triggers "Made with AI" labels on Instagram, Facebook, and X.
+
+### Invisible pixel-level watermark
+
+OpenAI's system card for Images 2.0 states the model embeds an "imperceptible, robust, and content-specific" pixel-level watermark alongside C2PA. This sample was downloaded 2026-04-22, before OpenAI's 19 May 2026 rollout of Google's SynthID watermark across ChatGPT / Codex / the API, so it likely predates SynthID and carries only the original content-specific watermark. Since that rollout, the openai.com/verify tool (in preview) is the public oracle for both signals; there is still no local decoder, so bypass cannot be verified empirically here without the oracle.
+
+## Reproducing the removal
+
+```bash
+# C2PA strip only
+remove-ai-watermarks metadata amur-leopard.png --remove -o amur-leopard.clean.png
+
+# Full pipeline (visible + diffusion regeneration + metadata)
+remove-ai-watermarks all amur-leopard.png -o amur-leopard.all.png --device mps
+```
+
+Note: the diffusion step runs at native resolution by default (no pre-downscale), so fine text on a text-heavy infographic like this one is preserved. Pass `--max-resolution N` only if a very large image OOMs the GPU/MPS (that reintroduces a lossy downscale then upscale round-trip).

data/synthid_corpus/README.md

@@ -0,0 +1,152 @@
+# SynthID reference corpus
+
+A locally-collected, labeled image corpus for SynthID work. Two downstream uses:
+
+1. **Per-resolution spectral codebook** for an experimental SynthID detector
+   (carrier frequencies are resolution-dependent, so labels must record the
+   exact native resolution).
+2. **Removal regression set** — verify that our pipeline turns a SynthID-positive
+   image into a negative one.
+
+There is no reliable local detector of the SynthID pixel watermark (Google's
+decoder is proprietary). The ground-truth label therefore comes from an
+external oracle, recorded per image in `verified_via` (see below).
+
+## Layout
+
+```
+data/synthid_corpus/
+  README.md        # this protocol (committed)
+  manifest.csv     # labels + provenance (committed; one row per tracked image)
+  images/          # the labeled corpus (committed)
+    pos/           # SynthID present
+    neg/           # SynthID absent (incl. reviewed real photos)
+    cleaned/       # our pipeline output from a pos image
+  refs/            # synthetic black/white calibration fills (gitignored, regenerable)
+```
+
+The labeled images are committed so the corpus is reproducible and the removal
+regression set runs in CI. `manifest.csv` is kept in sync with the files on
+disk (one row per tracked image; dangling rows are pruned when files are
+removed). Before adding any image, confirm it carries no private or
+identifiable content you would not publish -- this is a public repo and git
+history is permanent. The synthetic `refs/` fills stay gitignored (regenerable,
+not part of the labeled set).
+
+## Verification levels (`verified_via`)
+
+Ground-truth quality, strongest first:
+
+- `gemini-app` — checked via the Gemini app "Verify with SynthID" feature. Gold standard for the pixel watermark (Google models).
+- `openai-verify` — checked via openai.com/verify (gold standard for OpenAI ChatGPT/Codex/API images).
+- `synthid-portal` — checked via Google's SynthID Detector portal.
+- `c2pa-metadata` — issuer-only proxy (Google/OpenAI C2PA manifest present). Weaker: the C2PA can be stripped while the pixel watermark remains.
+- `third-party` — label asserted by an external dataset, not independently verified.
+- `none` — unverified.
+
+Prefer `gemini-app` for any image that will train the codebook or gate a test.
+
+## What to collect
+
+For the **codebook** (per target resolution, e.g. 1024x1024, 1024x1536, 1536x2816):
+
+- 30-50+ SynthID-positive outputs per resolution (more is better; ~150-200 per
+  resolution materially improves carrier discovery).
+- At each target resolution, also a batch of **pure-black (#000000)** and
+  **pure-white (#FFFFFF)** fills generated by the SynthID model — these isolate
+  the content-independent carrier (the watermark is most of the signal there).
+
+For the **regression set**:
+
+- A handful of `pos` images, their `cleaned` counterparts (run through our
+  pipeline), and the cleaned re-verified via `gemini-app` (should read negative).
+- `neg` controls: non-AI photos and outputs from non-SynthID models (SD,
+  Midjourney, Firefly) verified negative.
+
+The corpus is committed to a public repo: review every image before adding it
+and keep out anything private or identifiable you would not publish.
+
+## Ingesting
+
+Use `scripts/synthid_corpus.py` — it copies a file in, records its sha256,
+resolution, format, and C2PA issuer (via our own detector), and appends a row
+to `manifest.csv`:
+
+```bash
+uv run python scripts/synthid_corpus.py ingest path/to/*.png \
+    --label pos --source "Gemini app" --model gemini-3-pro \
+    --verified-via gemini-app --notes "1024x1024 batch"
+
+uv run python scripts/synthid_corpus.py status   # counts by label / resolution / verification
+```
+
+## Autonomous collection via Chrome MCP
+
+Generation can be driven through the browser (the account must be logged in):
+
+- **Gemini** (`gemini.google.com`): type `Create an image: <prompt>`, wait, hover the
+  result, click the download icon (top-right). Single, reliable click. Outputs
+  carry Google C2PA + SynthID. Occasionally the composer stalls in a
+  "generating" state -> start a New chat to reset.
+- **ChatGPT** (`chatgpt.com`): the UI download is flaky (the fullscreen viewer
+  races and can grab the previous image; the share-modal path works but is
+  multi-step). Reliable path is an in-page fetch of the rendered image, which
+  preserves the original bytes (C2PA intact, unlike a canvas re-encode):
+
+  ```js
+  // run in the ChatGPT tab via the browser MCP javascript tool
+  (async () => {
+    const imgs = [...document.querySelectorAll('img')].filter(i => i.naturalWidth >= 400);
+    const img = imgs[imgs.length - 1];                 // newest large image
+    const b = await (await fetch(img.currentSrc || img.src)).blob();
+    const a = document.createElement('a');
+    a.href = URL.createObjectURL(b); a.download = 'dl.png';
+    document.body.appendChild(a); a.click(); a.remove();
+    return 'size=' + b.size;                            // do NOT return the src (privacy guard blocks query strings)
+  })()
+  ```
+
+  Gotcha: confirm the returned `size` differs from the previous image before
+  ingesting -- if the new image has not finished rendering, the script grabs the
+  prior one (the corpus dedups by sha256, but the notes would mislabel it).
+  ChatGPT also shows an A/B "which is better?" picker; click Skip first.
+
+**Originals, not previews.** Some platforms render a low-res preview in the chat
+(Grok serves a ~20KB 1024px JPEG/PNG; the in-page `<img>` fetch grabs *that*, not
+the original). Previews are re-encoded and **strip metadata**, so a "clean"
+preview is not proof the original is clean. Always pull the original via the
+platform's native Download / lightbox button and sanity-check the file size (a
+20KB "1024x1024" is a preview). ChatGPT's in-chat `<img>` *is* the full-res
+oaiusercontent original, so fetch+blob is fine there; Grok needs the lightbox
+Download; Leonardo serves the original JPEG in-chat (download button matches).
+
+## Per-platform watermark map (observed, May 2026)
+
+What each platform actually embeds, verified by byte-scan (and Gemini-app oracle
+where noted). The detector's coverage is complementary: metadata catches C2PA /
+IPTC; `exif_generator` catches EXIF `Make`/`Software` + XMP `CreatorTool`;
+`invisible_watermark.py` (imwatermark) catches the open SD/SDXL/FLUX DWT-DCT
+watermark on pristine files; the visible detector catches the Gemini-family
+sparkle; the SynthID *pixel* itself has no local detector (oracle only).
+
+| Platform | C2PA issuer | SynthID pixel | IPTC "Made with AI" | Visible sparkle | imwatermark | Corpus label |
+|---|---|---|---|---|---|---|
+| Gemini app | Google | yes | - | yes | - | pos |
+| ChatGPT / gpt-image | OpenAI | yes | - | - | - | pos |
+| Microsoft Designer | OpenAI + Microsoft | yes (via OpenAI) | - | - | - | pos |
+| Bing Image Creator | Microsoft (MAI-Image) | no | - | - | - | pos (C2PA "Microsoft", not OpenAI) |
+| Google AI Studio (Nano Banana) | **none** | yes (oracle-confirmed) | - | yes | - | pos (metadata blind spot) |
+| Stability AI (Brand Studio) | Stability AI Ltd | no | - | - | no | pos (C2PA only) |
+| Ideogram | none | no | - | - | no | pos (EXIF `Make="Ideogram AI"` only) |
+| Meta AI | none | no | **yes** | - | - | neg (for SynthID) |
+| Leonardo.ai | none | no | no | - | no | neg |
+| Recraft | none (export strips) | no | no | - | no | neg (re-encoded export, no signal) |
+| Krea (FLUX 2 host) | none | no | no | - | no | neg (host omits the imwatermark encoder) |
+| Grok (xAI) | none (non-adopter) | no | no | - | no | neg (captured: clean low-res preview) |
+
+Key takeaways:
+- The same model differs by *surface*: Gemini app wraps C2PA, AI Studio (API/playground) emits none -- only the pixel + sparkle survive.
+- Microsoft Designer's DALL-E backend inherits OpenAI's C2PA+SynthID (issuer "OpenAI, Microsoft"); Bing now runs Microsoft's own **MAI-Image** and signs C2PA as "Microsoft" (not OpenAI/DALL-E).
+- Meta uses the IPTC `digitalSourceType` marker, not C2PA or SynthID.
+- The open imwatermark fires only on *pristine* output from a pipeline that runs the encoder (diffusers default, official BFL) -- not from re-hosts (Krea, Stability hosted SDXL) or re-encoded design exports (Recraft, Canva). Ideogram's only signal is the EXIF `Make` tag.
+- Bing and Grok web UIs are uncooperative for autonomous capture (no document_idle for screenshots; blob downloads intermittently no-op; low-res in-chat previews). Use their native download button manually if a full-res sample is needed.

data/synthid_corpus/manifest.csv

@@ -0,0 +1,26 @@
+sha256,filename,label,source,model,width,height,format,c2pa_issuer,synthid_metadata,verified_via,added,notes
+4ef377bde1a1d4eff141972841938643b173f5052992a018b9a21b31ac31731e,"4ef377bd-ChatGPT Image May 23, 2026, 02_43_02 PM.png",pos,ChatGPT,gpt-image,1254,1254,png,OpenAI,yes,openai-verify,2026-05-23T21:48:12Z,fresh post-rollout 2026-05-23; openai.com/verify: SynthID+C2PA detected
+d09f84c0e4c6d8b336bf4a9a7277314e940dcb5052ae7051e785cbb3bb42d656,d09f84c0-Gemini_Generated_Image_vq7wkwvq7wkwvq7w.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,c2pa-metadata,2026-05-23T21:52:40Z,"user: latest Gemini, SynthID v2"
+7b650522d42db09568e249c04d683c469fb3e280a2c53fcd1031cb9df27c619a,"7b650522-ChatGPT Image May 24, 2026, 12_19_54 PM.png",pos,ChatGPT,gpt-image,1602,982,png,OpenAI,yes,c2pa-metadata,2026-05-24T19:20:25Z,content: misty pine forest at dawn
+fb28dba2a82cc101a92fdee5714867b32610d0564f37737fe4bb70782b8ecf32,fb28dba2-Gemini_Generated_Image_dsjlnsdsjlnsdsjl.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,c2pa-metadata,2026-05-24T19:30:25Z,content: elderly fisherman portrait
+d20d4cc936dbdfe909c52502039a9e84ba93d97b42b24a0acee5b7d6c71930ae,d20d4cc9-Gemini_Generated_Image_ug6kdpug6kdpug6k.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,c2pa-metadata,2026-05-24T19:33:15Z,content: red coffee mug product shot
+28f323345f6496d936c3f1a72f671ddf59d0f81565c24a63bf3286860f633afe,28f32334-chatgpt_fisherman.png,pos,ChatGPT,gpt-image,1023,1537,png,OpenAI,yes,c2pa-metadata,2026-05-24T19:39:20Z,content: elderly fisherman portrait (fetch+blob dl)
+88e61a384c2e0b12d97bc66046e4a10542b2987448ba89c4b49e66311e969c84,88e61a38-chatgpt_tokyo.png,pos,ChatGPT,gpt-image,1023,1537,png,OpenAI,yes,c2pa-metadata,2026-05-24T19:42:02Z,content: tokyo street night (fetch+blob dl)
+1fa5f77f710c11a4cc69fed60195450def734401ed57c2600a84ce191f985440,1fa5f77f-IMG_0786.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:47Z,post photo; no C2PA/SynthID (verified)
+2ea228ed270cd169e9d38bc3f1a162de7edbf54b6e5ad3c701a3c90010ec7067,2ea228ed-IMG_1791.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:47Z,post photo; no C2PA/SynthID (verified)
+0bb4c176d83fbcbf4e628de7587d6183b9134c4f3fa85f55b96e94185273c7f6,0bb4c176-IMG_1790.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:47Z,post photo; no C2PA/SynthID (verified)
+3fc0c4253f86427777904f41355eacbdcc1a29f6897ec694c7fc68b6e7f70846,3fc0c425-IMG_1450.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+2b148db2b1a314a87647a03828b3d235e7c4c939252f448b572b7658c7bb9723,2b148db2-IMG_1832.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+2d02fed0b6d60ce1142eadac9837a83896569dddbdad7cc5cfdec018f0506d36,2d02fed0-IMG_1520.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+8f170c06f843c2bcf4cf6e249dd76365287fdb3a322637ba93c570f50cb19772,8f170c06-IMG_1078.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+3fc4c8316012abc462df5534d4d995e5af84d35076a2927331107ff994293d9e,3fc4c831-IMG_2566.HEIC,neg,iPhone (me/post_photos),,5712,4284,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+5fe59521d579b536340253d2bcaa7c28ddd2485fa964fc27a9b9e5118ad0cdd1,5fe59521-IMG_1496.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+4ead7918a5aeea7fba78b36af44358fea7ed1db7f46f4bc675152b9d04e68c38,4ead7918-IMG_1300.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
+4c795238b89178cf52a3674e721ed7f4cd5068028385491d12171a3c62545c35,4c795238-IMG_3034.HEIC,neg,iPhone (me/post_photos),,5712,4284,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
+5abfaccb37c549de67c7f3a751a528a423e24a82c643fdb29094be8debbb206d,5abfaccb-IMG_3018.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
+5fed1923d513c1e9ffcba2f240e617fa9344fb39d35144169570ece8b0bd0f33,5fed1923-IMG_0272.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
+06b04d8fe8e1cd6bee9a973f93bfda37586924cbfec7d372f59d52aa9196160b,06b04d8f-IMG_1474.HEIC,neg,iPhone (me/post_photos),,5712,4284,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
+8fdb574a94e65e14ac29017cf2d5a2ede18a8c4e3f12e04c64292b0d38570062,8fdb574a-IMG_3557.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
+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."

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,38 +1,108 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.3.3"
+version = "0.8.4"
 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"}
+classifiers = [
+    "License :: OSI Approved :: MIT 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",
-    "diffusers>=0.25.0",
-    "transformers>=4.35.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",
+    # 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
+# pulls non-headless opencv AND torch (invisible-watermark declares torch a hard
+# dependency, and WatermarkDecoder eagerly imports rivaGan -> torch at import
+# time, so the dwtDct-only detect path still needs torch present even though it
+# never runs on GPU). So `detect` alone pulls torch -- no need to add `gpu` for
+# detection. identify() guards the import and skips the signal when absent.
+detect = [
+    "invisible-watermark>=0.2.0",
+]
+# Adobe TrustMark decoder -- the open, keyless watermark behind Adobe Durable
+# Content Credentials (soft-binding alg ``com.adobe.trustmark.P``). Optional
+# because it pulls torch and downloads model weights on first use. identify()
+# guards the import and skips the TrustMark signal when absent.
+trustmark = [
+    "trustmark>=0.8.0",
+]
+# Universal region eraser backend -- big-LaMa via onnxruntime (Carve/LaMa-ONNX,
+# Apache-2.0). CPU, no torch. Model (~200 MB) is downloaded on first use and
+# cached by huggingface_hub; it is never bundled in this repo. The default cv2
+# eraser backend needs none of this.
+lama = [
+    "onnxruntime>=1.16.0",
+    "huggingface-hub>=0.20.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-cov>=4.1.0",
     "ruff>=0.4.0",
     "pyright>=1.1.0",
+    "invisible-watermark>=0.2.0",
 ]
-all = ["remove-ai-watermarks[gpu,dev]"]
+all = ["remove-ai-watermarks[gpu,detect,trustmark,lama,dev]"]
+
+# diffusers 0.38.0 (security fix for GHSA-98h9-4798-4q5v) declares a dependency
+# on safetensors>=0.8.0rc0 — a pre-release. Allow pre-releases globally so the
+# resolver can satisfy that. Drop once diffusers publishes a release with a
+# stable safetensors pin (or once safetensors 0.8.0 stable is out).
+[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"
@@ -41,12 +111,24 @@ remove-ai-watermarks = "remove_ai_watermarks.cli:main"
 Repository = "https://github.com/wiltodelta/remove-ai-watermarks"
 
 [build-system]
-requires = ["hatchling"]
+# Pin hatchling < 1.28: 1.28+ emits Metadata-Version 2.5 (PEP 639), which the twine
+# bundled in pypa/gh-action-pypi-publish@release/v1 rejects ("'2.5' is not a valid
+# Metadata-Version"), failing the PyPI upload (v0.8.3, 2026-06-01). 1.27.x emits 2.4,
+# which uploads fine (0.8.2 shipped on it). Lift this pin once the publish action's
+# twine is upgraded to >= 6.1.0 (2.5-aware) or the workflow moves to `uv publish`.
+requires = ["hatchling<1.28"]
 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"]
@@ -90,3 +172,33 @@ reportUnknownMemberType = false
 reportUnknownArgumentType = false
 reportUnknownVariableType = false
 reportMissingTypeArgument = false
+
+# CtrlRegen is a torch/diffusers/controlnet-aux boundary: those libs ship no
+# usable types, so strict pyright cannot know the tensor element types. Relax the
+# unknown-type rules for this subpackage only (mirrors the per-file pragmas used
+# for the cv2 engines); the rest of the codebase stays strict.
+[[tool.pyright.executionEnvironments]]
+root = "src/remove_ai_watermarks/noai/ctrlregen"
+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

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/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/synthid_corpus.py

@@ -0,0 +1,239 @@
+"""Ingest and inspect the local SynthID reference corpus.
+
+Copies images into ``data/synthid_corpus/images/<label>/`` and records one row
+per image in ``manifest.csv`` (sha256, resolution, format, C2PA issuer, and the
+external verification level). Dogfoods the project's own C2PA detector so the
+recorded metadata matches what the library sees.
+
+See ``data/synthid_corpus/README.md`` for the collection protocol.
+
+Usage:
+    uv run python scripts/synthid_corpus.py ingest IMAGES... --label pos \\
+        --source "Gemini app" --model gemini-3-pro --verified-via gemini-app
+    uv run python scripts/synthid_corpus.py status
+"""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import logging
+import shutil
+import subprocess
+import sys
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+from _plain_console import Console, Table
+from PIL import Image
+
+from remove_ai_watermarks.noai.c2pa import extract_c2pa_info
+
+log = logging.getLogger(__name__)
+console = Console()
+
+DEFAULT_ROOT = Path(__file__).resolve().parent.parent / "data" / "synthid_corpus"
+LABELS = ("pos", "neg", "cleaned")
+VERIFIED_VIA = ("gemini-app", "openai-verify", "synthid-portal", "c2pa-metadata", "third-party", "none")
+FIELDNAMES = [
+    "sha256",
+    "filename",
+    "label",
+    "source",
+    "model",
+    "width",
+    "height",
+    "format",
+    "c2pa_issuer",
+    "synthid_metadata",
+    "verified_via",
+    "added",
+    "notes",
+]
+
+
+def _manifest_path(root: Path) -> Path:
+    return root / "manifest.csv"
+
+
+def _read_manifest(root: Path) -> list[dict[str, str]]:
+    path = _manifest_path(root)
+    if not path.exists():
+        return []
+    with open(path, newline="") as f:
+        return list(csv.DictReader(f))
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _dims_via_sips(path: Path) -> tuple[int, int]:
+    """Read pixel dimensions via macOS ``sips`` (handles HEIC, which PIL can't
+    open without pillow-heif). Returns (0, 0) off macOS or on failure."""
+    sips = shutil.which("sips")
+    if sys.platform != "darwin" or not sips:
+        return 0, 0
+    try:
+        # Fixed command; the only variable is a local file path passed to ingest.
+        out = subprocess.run(  # noqa: S603
+            [sips, "-g", "pixelWidth", "-g", "pixelHeight", str(path)],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        ).stdout
+        dims = {"pixelWidth": 0, "pixelHeight": 0}
+        for line in out.splitlines():
+            for key in dims:
+                if f"{key}:" in line:
+                    dims[key] = int(line.split(":")[1].strip())
+        return dims["pixelWidth"], dims["pixelHeight"]
+    except Exception:  # sips missing/odd output; dims stay unknown
+        return 0, 0
+
+
+def _probe(path: Path) -> tuple[int, int, str, str, bool]:
+    """Return (width, height, format, c2pa_issuer, synthid_metadata)."""
+    width = height = 0
+    fmt = path.suffix.lstrip(".").lower()
+    try:
+        with Image.open(path) as img:
+            width, height = img.size
+            fmt = (img.format or fmt).lower()
+    except Exception as exc:  # unknown/user formats can raise non-OSError; see CLAUDE.md
+        log.debug("PIL could not open %s: %s", path, exc)
+
+    if width == 0:  # e.g. HEIC from iPhone — fall back to macOS sips
+        width, height = _dims_via_sips(path)
+
+    info = extract_c2pa_info(path)
+    issuer = str(info.get("issuer", ""))
+    synthid = "synthid_watermark" in info
+    return width, height, fmt, issuer, synthid
+
+
+@click.group()
+def cli() -> None:
+    """Manage the local SynthID reference corpus."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+@cli.command()
+@click.argument("images", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path))
+@click.option("--label", required=True, type=click.Choice(LABELS), help="SynthID label.")
+@click.option("--source", default="", help="Where the image came from (free text).")
+@click.option("--model", default="", help="Generating model, e.g. gemini-3-pro.")
+@click.option(
+    "--verified-via", "verified_via", default="none", type=click.Choice(VERIFIED_VIA), help="Ground-truth oracle."
+)
+@click.option("--notes", default="", help="Free-text notes (e.g. resolution batch).")
+@click.option("--root", type=click.Path(path_type=Path), default=DEFAULT_ROOT, help="Corpus root.")
+def ingest(
+    images: tuple[Path, ...],
+    label: str,
+    source: str,
+    model: str,
+    verified_via: str,
+    notes: str,
+    root: Path,
+) -> None:
+    """Copy IMAGES into the corpus and append rows to the manifest."""
+    dest_dir = root / "images" / label
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    rows = _read_manifest(root)
+    seen = {r["sha256"] for r in rows}
+    added = 0
+    new_rows: list[dict[str, str]] = []
+
+    for src in images:
+        digest = _sha256(src)
+        if digest in seen:
+            console.print(f"  [dim]skip (duplicate sha256): {src.name}[/]")
+            continue
+        seen.add(digest)
+
+        width, height, fmt, issuer, synthid = _probe(src)
+        stored_name = f"{digest[:8]}-{src.name}"
+        shutil.copy2(src, dest_dir / stored_name)
+
+        new_rows.append(
+            {
+                "sha256": digest,
+                "filename": stored_name,
+                "label": label,
+                "source": source,
+                "model": model,
+                "width": str(width),
+                "height": str(height),
+                "format": fmt,
+                "c2pa_issuer": issuer,
+                "synthid_metadata": "yes" if synthid else "",
+                "verified_via": verified_via,
+                "added": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "notes": notes,
+            }
+        )
+        added += 1
+        flag = " [yellow](C2PA-SynthID)[/]" if synthid else ""
+        console.print(f"  [green]+[/] {label}/{stored_name}  {width}x{height} {fmt}{flag}")
+
+    if new_rows:
+        path = _manifest_path(root)
+        write_header = not path.exists()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "a", newline="") as f:
+            writer = csv.DictWriter(f, fieldnames=FIELDNAMES)
+            if write_header:
+                writer.writeheader()
+            writer.writerows(new_rows)
+
+    console.print(f"\n  Ingested [bold]{added}[/] image(s); skipped {len(images) - added} duplicate(s).")
+
+
+@cli.command()
+@click.option("--root", type=click.Path(path_type=Path), default=DEFAULT_ROOT, help="Corpus root.")
+def status(root: Path) -> None:
+    """Print corpus counts by label, resolution, and verification level."""
+    rows = _read_manifest(root)
+    if not rows:
+        console.print("  [dim]Corpus is empty.[/]")
+        return
+
+    by_label = Counter(r["label"] for r in rows)
+    by_verified = Counter(r["verified_via"] for r in rows)
+    by_res = Counter(f"{r['label']}  {r['width']}x{r['height']}" for r in rows)
+
+    console.print(f"\n  [bold]{len(rows)}[/] image(s) in {root}")
+
+    t = Table(title="By label", show_header=True, header_style="bold")
+    t.add_column("Label")
+    t.add_column("Count", justify="right")
+    for k in LABELS:
+        if by_label.get(k):
+            t.add_row(k, str(by_label[k]))
+    console.print(t)
+
+    t = Table(title="By label x resolution", show_header=True, header_style="bold")
+    t.add_column("Label / resolution")
+    t.add_column("Count", justify="right")
+    for k, v in sorted(by_res.items()):
+        t.add_row(k, str(v))
+    console.print(t)
+
+    t = Table(title="By verification", show_header=True, header_style="bold")
+    t.add_column("verified_via")
+    t.add_column("Count", justify="right")
+    for k, v in by_verified.most_common():
+        t.add_row(k, str(v))
+    console.print(t)
+
+
+if __name__ == "__main__":
+    cli()

scripts/synthid_pixel_probe.py

@@ -0,0 +1,149 @@
+"""SynthID pixel-carrier probe -- EXPERIMENTAL / DIAGNOSTIC ONLY.
+
+There is no local detector of the SynthID pixel watermark on real content: the
+carrier drowns in scene texture (see CLAUDE.md, confirmed repeatedly). This
+probe is meaningful ONLY on **solid-color fills**, where the per-pixel deviation
+from the image mean is essentially the watermark carrier (almost all the
+variance). It answers two controlled questions, neither of which is a
+real-content detector:
+
+  consistency IMAGES...
+      Mean pairwise normalized cross-correlation (NCC) of the carriers across
+      independent solid fills from one model, vs a random baseline. Genuine
+      SynthID positives share a fixed carrier, so they correlate well above
+      random (the pilot saw ~0.92 on gpt-image black fills); clean fills don't.
+
+  removal --pos P... --cleaned C...
+      Build a carrier template from the positive fills, then compare how the
+      positives and the pipeline-cleaned fills correlate to it. If removal
+      worked, the cleaned correlation collapses toward the random baseline --
+      pixel-domain evidence that the pipeline destroys the carrier, not just the
+      C2PA metadata.
+
+Do NOT run this on real-content images; the numbers are uninformative there.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import click
+import numpy as np
+from _plain_console import Console
+from PIL import Image
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+log = logging.getLogger(__name__)
+console = Console()
+
+
+def load_gray(path: str) -> NDArray[np.float64]:
+    """Load an image as a float64 grayscale array (mean of RGB channels)."""
+    with Image.open(path) as img:
+        return np.asarray(img.convert("RGB"), dtype=np.float64).mean(axis=2)
+
+
+def carrier(gray: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Zero-mean, unit-norm residual of a solid-fill image -- its carrier.
+
+    Returns a flattened unit-norm vector for NCC comparison. A perfectly flat
+    image (std 0, e.g. a synthetic #000000 reference) has no carrier and yields
+    an all-zero vector, which correlates to 0 with everything.
+    """
+    residual = gray - float(gray.mean())
+    norm = float(np.linalg.norm(residual))
+    if norm == 0.0:
+        return residual.ravel()
+    return (residual / norm).ravel()
+
+
+def ncc(a: NDArray[np.float64], b: NDArray[np.float64]) -> float:
+    """Normalized cross-correlation of two carriers (unit-norm zero-mean vectors)."""
+    if a.shape != b.shape or a.size == 0:
+        return 0.0
+    return float(np.dot(a, b))
+
+
+def mean_pairwise_ncc(carriers: list[NDArray[np.float64]]) -> float:
+    """Average NCC over all distinct carrier pairs; 0.0 if fewer than two."""
+    scores = [ncc(carriers[i], carriers[j]) for i in range(len(carriers)) for j in range(i + 1, len(carriers))]
+    return float(np.mean(scores)) if scores else 0.0
+
+
+def template(carriers: list[NDArray[np.float64]]) -> NDArray[np.float64]:
+    """Average carrier, renormalized to unit norm (the shared-pattern estimate)."""
+    avg = np.mean(carriers, axis=0)
+    norm = float(np.linalg.norm(avg))
+    return avg / norm if norm else avg
+
+
+def random_baseline(shape: tuple[int, ...], n: int, *, seed: int = 0) -> float:
+    """Mean pairwise NCC of ``n`` random-noise carriers of ``shape`` (~0)."""
+    rng = np.random.default_rng(seed)
+    noise = [carrier(rng.standard_normal(shape)) for _ in range(max(n, 2))]
+    return mean_pairwise_ncc(noise)
+
+
+def _load_carriers(paths: tuple[str, ...]) -> list[NDArray[np.float64]]:
+    """Load carriers for same-shaped images; warn and skip mismatched shapes."""
+    grays = [(p, load_gray(p)) for p in paths]
+    shape = grays[0][1].shape
+    carriers: list[NDArray[np.float64]] = []
+    for p, g in grays:
+        if g.shape != shape:
+            console.print(f"  [yellow]skip[/] {p}: shape {g.shape} != {shape}")
+            continue
+        carriers.append(carrier(g))
+    return carriers
+
+
+@click.group()
+def cli() -> None:
+    """SynthID pixel-carrier probe (solid-color fills only)."""
+
+
+@cli.command()
+@click.argument("images", nargs=-1, required=True, type=click.Path(exists=True))
+def consistency(images: tuple[str, ...]) -> None:
+    """Mean pairwise carrier NCC across solid fills, vs the random baseline."""
+    carriers = _load_carriers(images)
+    if len(carriers) < 2:
+        console.print("[red]Need at least two same-shaped images.[/]")
+        raise SystemExit(1)
+    observed = mean_pairwise_ncc(carriers)
+    baseline = random_baseline(carriers[0].shape, len(carriers))
+    console.print(f"  carriers:          {len(carriers)}")
+    console.print(f"  mean pairwise NCC: [bold]{observed:.3f}[/]")
+    console.print(f"  random baseline:   {baseline:.3f}")
+    verdict = "shared carrier present" if observed > 0.3 else "no shared carrier (within noise)"
+    console.print(f"  verdict: [bold]{verdict}[/]")
+
+
+@cli.command()
+@click.option("--pos", "pos", multiple=True, required=True, type=click.Path(exists=True), help="Positive solid fills.")
+@click.option(
+    "--cleaned", "cleaned", multiple=True, required=True, type=click.Path(exists=True), help="Pipeline-cleaned fills."
+)
+def removal(pos: tuple[str, ...], cleaned: tuple[str, ...]) -> None:
+    """Does the pipeline drop the carrier correlation toward the random baseline?"""
+    pos_carriers = _load_carriers(pos)
+    cleaned_carriers = _load_carriers(cleaned)
+    if not pos_carriers or not cleaned_carriers:
+        console.print("[red]Need at least one positive and one cleaned fill of matching shape.[/]")
+        raise SystemExit(1)
+    tmpl = template(pos_carriers)
+    pos_corr = float(np.mean([ncc(c, tmpl) for c in pos_carriers]))
+    cleaned_corr = float(np.mean([ncc(c, tmpl) for c in cleaned_carriers]))
+    baseline = random_baseline(tmpl.shape, max(len(cleaned_carriers), 2))
+    console.print(f"  positive->template NCC: [bold]{pos_corr:.3f}[/]")
+    console.print(f"  cleaned->template NCC:  [bold]{cleaned_corr:.3f}[/]")
+    console.print(f"  random baseline:        {baseline:.3f}")
+    effective = cleaned_corr < pos_corr / 2
+    console.print(f"  verdict: [bold]{'carrier attenuated' if effective else 'carrier survives'}[/]")
+
+
+if __name__ == "__main__":
+    cli()

scripts/text_detection_benchmark.py

@@ -0,0 +1,150 @@
+"""Multilingual recall benchmark for the text-protection detector.
+
+Measures the core lever of text protection (`text_protector.TextProtector`): if
+the PP-OCRv3 DB detector misses a text region, that text is NOT preserved during
+the SDXL watermark-removal pass and gets deformed (issue #14). This renders short
+text in several scripts at several font sizes on two canvas sizes, runs detection,
+and reports the fraction of each known text bbox the detector covers.
+
+Findings (2026-05-29):
+  - Detection is script-agnostic: DB segments text *regions*, not characters, so
+    Latin / Cyrillic / CJK / Hangul / Arabic / digits score identically. Language
+    was never the lever.
+  - The only lever is resolution. A fixed small detector input downscaled large
+    canvases so far that small text was missed. Detecting at the native long side
+    (capped, see ``text_protector._DET_MAX_LONG_SIDE``) lifts overall hit-rate
+    from 0.91 to 1.00 and the worst cell (~16 px text on a 2048 canvas) from
+    0.06 to 1.00.
+
+This needs the detector model (downloaded on first use) and a font that covers
+all the scripts (macOS "Arial Unicode"; on Linux install a Noto super-font).
+No GPU. Run:
+
+    uv run python scripts/text_detection_benchmark.py
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+from _plain_console import Console
+from PIL import Image, ImageDraw, ImageFont
+
+from remove_ai_watermarks import text_protector as tp
+
+log = logging.getLogger(__name__)
+console = Console()
+
+# A single font covering every tested script isolates "language" from "font".
+_FONT_CANDIDATES = [
+    "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
+    "/Library/Fonts/Arial Unicode.ttf",
+    "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+    "/usr/share/fonts/truetype/unifont/unifont.ttf",
+]
+SCRIPTS = {
+    "Latin": "Generated by AI",
+    "Cyrillic": "Сгенерировано ИИ",
+    "CJK": "豆包AI生成内容",
+    "Hangul": "AI로 생성됨",
+    "Arabic": "أنشئ بالذكاء",
+    "Digits": "0123456789",
+}
+FONT_SIZES = [16, 24, 32, 48, 64]
+CANVASES = [1024, 2048]
+PLACEMENTS = [(0.08, 0.15), (0.30, 0.55), (0.10, 0.82)]
+BG_COLORS = [(35, 40, 60), (210, 205, 200)]
+
+
+def _find_font() -> str:
+    for path in _FONT_CANDIDATES:
+        if Path(path).exists():
+            return path
+    raise SystemExit(
+        "No multi-script font found. Install one (macOS ships 'Arial Unicode'; "
+        "on Linux: a Noto CJK/super font) and add its path to _FONT_CANDIDATES."
+    )
+
+
+def _render(
+    font_path: str,
+    canvas: int,
+    text: str,
+    font_size: int,
+    place: tuple[float, float],
+    bg: tuple[int, int, int],
+) -> tuple[Image.Image, tuple[int, int, int, int]]:
+    img = Image.new("RGB", (canvas, canvas), bg)
+    draw = ImageDraw.Draw(img)
+    font = ImageFont.truetype(font_path, font_size)
+    x, y = int(place[0] * canvas), int(place[1] * canvas)
+    fg = (245, 245, 245) if sum(bg) < 360 else (20, 20, 20)
+    draw.text((x, y), text, font=font, fill=fg)
+    return img, draw.textbbox((x, y), text, font=font)
+
+
+def _coverage(boxes: list[Any], bbox: tuple[int, int, int, int], h: int, w: int) -> float | None:
+    gt = np.zeros((h, w), np.uint8)
+    cv2.rectangle(gt, (bbox[0], bbox[1]), (bbox[2], bbox[3]), 1, -1)
+    area = int(gt.sum())
+    if area == 0:
+        return None
+    det = np.zeros((h, w), np.uint8)
+    if boxes:
+        cv2.fillPoly(det, [np.asarray(b, np.int32) for b in boxes], 1)
+    return int((gt & det).sum()) / area
+
+
+def _hitrate(values: list[float], thr: float = 0.5) -> float:
+    return sum(c >= thr for c in values) / len(values) if values else float("nan")
+
+
+def main() -> int:
+    logging.basicConfig(level=logging.WARNING)
+    if not tp.is_available():
+        raise SystemExit("text detector unavailable (need opencv with cv2.dnn.TextDetectionModel_DB)")
+    font_path = _find_font()
+    detector = tp.TextProtector()
+
+    by_script_size: dict[tuple[str, int], list[float]] = defaultdict(list)
+    by_size_canvas: dict[tuple[int, int], list[float]] = defaultdict(list)
+    by_script: dict[str, list[float]] = defaultdict(list)
+
+    for canvas in CANVASES:
+        for script, text in SCRIPTS.items():
+            for font_size in FONT_SIZES:
+                for idx, place in enumerate(PLACEMENTS):
+                    img, bbox = _render(font_path, canvas, text, font_size, place, BG_COLORS[idx % len(BG_COLORS)])
+                    bgr = cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR)
+                    cov = _coverage(detector.detect_text_boxes(bgr), bbox, canvas, canvas)
+                    if cov is None:
+                        continue
+                    by_script_size[(script, font_size)].append(cov)
+                    by_size_canvas[(font_size, canvas)].append(cov)
+                    by_script[script].append(cov)
+
+    console.print("=== hit-rate (coverage>=0.5) by script x font-size ===")
+    console.print("script".ljust(10) + "".join(f"{fs:>7}" for fs in FONT_SIZES))
+    for script in SCRIPTS:
+        console.print(
+            script.ljust(10) + "".join(f"{_hitrate(by_script_size[(script, fs)]):>7.2f}" for fs in FONT_SIZES)
+        )
+
+    console.print("\n=== hit-rate by font-size x canvas (the downscale effect) ===")
+    console.print("size".ljust(8) + "".join(f"{c:>8}" for c in CANVASES))
+    for fs in FONT_SIZES:
+        console.print(str(fs).ljust(8) + "".join(f"{_hitrate(by_size_canvas[(fs, c)]):>8.2f}" for c in CANVASES))
+
+    overall = _hitrate([c for vals in by_script.values() for c in vals])
+    console.print(f"\nOVERALL hit-rate: {overall:.2f}  (detector max long side = {tp._DET_MAX_LONG_SIDE})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/visible_alpha_solve.py

@@ -0,0 +1,247 @@
+"""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
+
+
+_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",
+    ),
+}
+
+_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]) -> tuple[int, int, int, int]:
+    """Bounding box of the white mark on the black capture (bottom-right).
+
+    Thresholds well above the blotchy near-black background, then unions the
+    sufficiently-large bright components so the box spans the whole word.
+    """
+    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
+    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, "no mark found on the black capture (bottom-right 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)
+    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
+    log.info(
+        "%s: alpha %dx%d max %.3f | WIDTH_FRAC %.4f HEIGHT_FRAC %.4f "
+        "MARGIN_RIGHT_FRAC %.4f MARGIN_BOTTOM_FRAC %.4f (native_width %d)",
+        spec.name,
+        aw,
+        ah,
+        float(tight.max()),
+        aw / spec.native_width,
+        ah / spec.native_width,
+        (img_w - (abs_x0 + aw)) / 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 ("doubao", "jimeng", "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()

src/remove_ai_watermarks/__init__.py

@@ -1,3 +1,14 @@
 """Remove-AI-Watermarks: Unified tool for removing visible and invisible AI watermarks."""
 
-__version__ = "0.3.3"
+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.8.4"

src/remove_ai_watermarks/doubao_engine.py

@@ -0,0 +1,420 @@
+"""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 -- the explicit AIGC
+label mandated by China's TC260 standard, a near-white semi-transparent overlay.
+
+Like the Gemini sparkle and the Jimeng wordmark, it is a fixed overlay, so removal
+starts from **reverse-alpha blending** against a captured alpha map
+(``remove_watermark_reverse_alpha``): ``original = (wm - a*logo)/(1-a)``. The alpha
+map is rebuilt by ``scripts/visible_alpha_solve.py`` from black/gray Doubao captures
+(the careful gray-self solve; logo is pure white) and bundled as
+``assets/doubao_alpha.png``. The mark re-rasterizes a few px off per image, so
+removal ALWAYS NCC-aligns the template to the actual mark and then clears the
+residual edges with a deliberately THIN inpaint over the glyph footprint (an
+earlier under-estimated alpha + fixed-no-inpaint left a readable outline that the
+detector did not flag -- see the reverse-alpha section below).
+
+Detection (``detect``) is shape-consistent: it matches that same alpha glyph
+silhouette against the corner via normalized correlation, so it keys on the actual
+"豆包AI生成" shape rather than coverage/structure heuristics.
+
+``locate`` (geometry box, scales with image WIDTH) and ``extract_mask`` (the
+candidate glyph mask the detector correlates) mirror the Jimeng engine.
+Arbitrary-region inpainting still lives in ``region_eraser`` / the ``erase``
+command. Fast, offline, no GPU.
+"""
+
+# 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 typing import TYPE_CHECKING, Any
+
+import cv2
+import numpy as np
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+
+# Geometry as a fraction of image WIDTH. The Doubao mark scales with width and
+# is anchored bottom-right. The box must be GENEROUSLY wider than the mark and
+# reach close to the corner -- the mark is re-rasterized a few px off per image,
+# and the NCC alignment search only registers within this box, so a tight box
+# (the old 0.185 / margin 0.012) let a corner-ward shift fall partly outside it
+# and the alignment missed. The glyph mask tightens the actual removal.
+WM_WIDTH_FRAC = 0.22
+WM_HEIGHT_FRAC = 0.075
+MARGIN_RIGHT_FRAC = 0.004
+MARGIN_BOTTOM_FRAC = 0.004
+
+# 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).
+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 is reverse-alpha-consistent: the mark is recognized by matching the
+# bundled alpha-template glyph silhouette (assets/doubao_alpha.png -- the exact
+# shape we invert) against the extracted candidate mask via zero-mean normalized
+# correlation (cv2 TM_CCOEFF_NORMED). It keys on the actual "豆包AI生成" glyph
+# SHAPE, not on coverage/structure heuristics, so a merely-textured corner does
+# not fire (the old coverage detector false-positived on ~28% of images; #23).
+# Corpus-tuned: real marks score median ~0.61, arbitrary corners <=0.17 (p99);
+# threshold 0.4 -> false positives 7/1243 (0.6%). A small coverage floor skips
+# the template match on a near-empty candidate box.
+DETECT_MIN_COVERAGE = 0.04
+DETECT_NCC_THRESHOLD = 0.4
+
+# ── Reverse-alpha (recovery + thin residual inpaint) ─────────────────
+# The Doubao mark is a fixed semi-transparent white overlay, so given its alpha
+# map the original pixels are recovered by inverting the blend: (wm - a*logo)/(1-a).
+# The alpha map is rebuilt by scripts/visible_alpha_solve.py from the black/gray
+# Doubao captures (data/doubao_capture/): the CAREFUL solve -- a = (I - B)/(255 - B)
+# on the gray capture with B a per-channel cubic background fit, mean over channels,
+# full halo extent, unblurred. The earlier build (a coarser solve) under-estimated
+# the alpha and left a clearly READABLE "豆包AI生成" outline on real samples
+# (issue #13 follow-up: the detector was fooled by the outline -- conf 0.0 -- so the
+# test passed while the result was visibly bad; suspect the captured alpha map, not
+# the method). The mark is re-rasterized and a few px off per image, so removal
+# does NOT trust fixed geometry: it ALWAYS tries fixed AND `_aligned_alpha_map`'s
+# TM_CCOEFF_NORMED scale+position search and keeps the lower-residual placement,
+# then a deliberately THIN residual inpaint clears the leftover edges without
+# smearing the recovered texture. Geometry below is emitted by the solver -- keep in
+# sync when the asset is rebuilt.
+_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
+# Margins (of image WIDTH) of the captured mark -- the geometry record / where to
+# seed; alignment refines the actual position, so these are not load-bearing.
+_ALPHA_MARGIN_RIGHT_FRAC = 0.0132
+_ALPHA_MARGIN_BOTTOM_FRAC = 0.0166
+# Alignment scale search (np.linspace args) around the width-scaled glyph size.
+_ALPHA_ALIGN_SEARCH = (0.88, 1.12, 25)
+# Residual inpaint over the glyph footprint -- thin (NS, small radius) so it clears
+# the leftover edges without the smear a wide full-footprint pass caused.
+_RESIDUAL_ALPHA_FLOOR = 0.05
+_RESIDUAL_DILATE = 5
+_RESIDUAL_INPAINT_RADIUS = 2
+_alpha_template_cache: NDArray[Any] | None = None
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """Lazily load the bundled Doubao alpha template (float [0,1]), or None."""
+    global _alpha_template_cache
+    if _alpha_template_cache is None:
+        from pathlib import Path
+
+        from remove_ai_watermarks import image_io
+
+        path = Path(__file__).parent / "assets" / "doubao_alpha.png"
+        img = image_io.imread(str(path), cv2.IMREAD_GRAYSCALE)
+        if img is None:
+            return None
+        _alpha_template_cache = img.astype(np.float32) / 255.0
+    return _alpha_template_cache
+
+
+@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
+
+
+@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
+
+
+_silhouette_cache: NDArray[Any] | None = None
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "豆包AI生成" silhouette (255 = glyph) from the bundled alpha map,
+    used as the detection template. None if the alpha asset is missing."""
+    global _silhouette_cache
+    if _silhouette_cache is None:
+        at = _alpha_template()
+        if at is None:
+            return None
+        _silhouette_cache = (at > 0.15).astype(np.uint8) * 255
+    return _silhouette_cache
+
+
+def _template_match_score(box_mask: NDArray[Any], image_width: int) -> 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 "豆包AI生成" shape does.
+    """
+    sil = _glyph_silhouette()
+    if sil is None or box_mask.size == 0:
+        return 0.0
+    gw = min(box_mask.shape[1] - 1, max(8, int(_ALPHA_WIDTH_FRAC * image_width)))
+    gh = min(box_mask.shape[0] - 1, max(4, int(_ALPHA_HEIGHT_FRAC * image_width)))
+    if gw < 8 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 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[Any]) -> 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[Any], loc: DoubaoLocation) -> NDArray[Any]:
+        """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
+        # 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 the native code on some platforms (observed: a Windows
+        # access violation via the always-align removal's residual `detect`). Skip
+        # the cv2 pipeline and return an empty mask there.
+        if bh < 16 or bw < 16:
+            return np.zeros((h, w), np.uint8)
+        # Normalize the ROI to 3-channel BGR: a 2D grayscale or 4-channel BGRA
+        # input would otherwise break the axis=2 channel reductions below.
+        roi = image[y : y + bh, x : x + bw]
+        if roi.ndim == 2:
+            roi = cv2.cvtColor(roi, cv2.COLOR_GRAY2BGR)
+        elif roi.shape[2] == 4:
+            roi = cv2.cvtColor(roi, cv2.COLOR_BGRA2BGR)
+        roi = roi.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[Any]) -> DoubaoDetection:
+        """Detect the visible Doubao mark by matching the alpha-template glyph
+        silhouette against the corner candidate (TM_CCOEFF_NORMED).
+
+        Keys on the "豆包AI生成" SHAPE, not coverage, so a textured corner does
+        not fire. ``confidence`` is the correlation score; ``detected`` is it
+        clearing ``DETECT_NCC_THRESHOLD``.
+        """
+        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
+        if coverage >= DETECT_MIN_COVERAGE:
+            score = _template_match_score(box, image.shape[1])
+            det.confidence = score
+            det.detected = score >= DETECT_NCC_THRESHOLD
+            logger.debug("Doubao detect: coverage=%.3f ncc=%.2f detected=%s", coverage, score, det.detected)
+        return det
+
+    # ── Reverse-alpha (exact recovery) ────────────────────────────────
+
+    def reverse_alpha_available(self, image: NDArray[Any]) -> bool:
+        """True if the bundled alpha map is loadable. Sub-pixel NCC alignment
+        (see ``_aligned_alpha_map``) places it on the actual mark at ANY
+        resolution, so there is no width gate -- the caller still gates on
+        ``detect`` so a clean corner is never touched."""
+        return image is not None and image.size > 0 and _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 (used there instead of integer-pixel NCC alignment)."""
+        at = _alpha_template()
+        if at is None:
+            return None
+        h, w = image.shape[:2]
+        # Glyph box scales with WIDTH; on a wide/short image the height-from-width
+        # box can exceed the image height. Clamp both dims so the slice assignment
+        # below cannot overflow (a degenerate 2048x1 input otherwise raised
+        # ValueError on the broadcast). Normal images are unaffected.
+        gw = min(w, max(1, int(_ALPHA_WIDTH_FRAC * w)))
+        gh = min(h, max(1, int(_ALPHA_HEIGHT_FRAC * w)))
+        ax = max(0, w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw)
+        ay = max(0, 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), 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:
+        """Build a full-image alpha map with the captured template registered to
+        the actual mark via a TM_CCOEFF_NORMED scale + position search -- so the
+        single capture works off the captured width (a pure width-scale ghosts).
+        Returns ``(alpha_map, glyph_bbox)`` or None."""
+        at = _alpha_template()
+        sil = _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 = _ALPHA_WIDTH_FRAC * w
+        best: tuple[float, int, int, int, int] | None = None
+        for scale in np.linspace(*_ALPHA_ALIGN_SEARCH):
+            gw, gh = int(expected * scale), int(_ALPHA_HEIGHT_FRAC * w * scale)
+            if gw < 8 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(_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
+        ``original = (wm - a*logo)/(1-a)``, then clear the residual edges 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 is re-rasterized and a few px off per image, so fixed
+        geometry alone leaves a visible outline (it did on the doubao-1.png sample).
+        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 leftover edges instead of smearing the whole footprint.
+        Call only when :meth:`reverse_alpha_available` and the mark is detected.
+        """
+        # Normalize to 3-channel BGR so a 2D grayscale or 4-channel BGRA input
+        # does not break the reverse-alpha math (which assumes a 3-channel logo).
+        if image.ndim == 2:
+            image = cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+        elif image.shape[2] == 4:
+            image = cv2.cvtColor(image, cv2.COLOR_BGRA2BGR)
+        # An image too small to hold the mark would make the geometry boxes
+        # degenerate and feed cv2.resize a ~1-px-tall target / GaussianBlur a sliver
+        # ROI, which faults natively on Windows (access violation / "Unknown C++
+        # exception"). No real watermarked image is this small; skip cv2 entirely.
+        h, w = image.shape[:2]
+        if h < 32 or w < 64:
+            return image.copy()
+        maps = [c for c in (self._fixed_alpha_map(image), self._aligned_alpha_map(image)) if c 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((_RESIDUAL_DILATE, _RESIDUAL_DILATE), np.uint8)
+            rm = cv2.dilate((best_amap > _RESIDUAL_ALPHA_FLOOR).astype(np.uint8) * 255, kernel)
+            best_out = cv2.inpaint(best_out, rm, _RESIDUAL_INPAINT_RADIUS, cv2.INPAINT_NS)
+        return best_out
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path, cv2.IMREAD_COLOR)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/face_protector.py

@@ -1,5 +1,8 @@
 """YOLO-based face detection and soft-blend restoration for diffusion pipelines."""
 
+# cv2/numpy/ultralytics 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, reportOptionalMemberAccess=false, reportOptionalCall=false, reportOptionalSubscript=false, reportOptionalOperand=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false, reportPrivateUsage=false, reportInvalidTypeForm=false, reportConstantRedefinition=false, reportUnnecessaryComparison=false, reportPossiblyUnboundVariable=false
 import logging
 from pathlib import Path
 

src/remove_ai_watermarks/gemini_engine.py

@@ -13,13 +13,17 @@ 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
@@ -86,7 +90,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 +107,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():
@@ -151,13 +155,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]:
@@ -170,7 +174,7 @@ class GeminiEngine:
 
     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)."""
@@ -304,64 +308,69 @@ class GeminiEngine:
 
     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
+        copy. Reverse alpha blending applied where no sparkle exists creates a
+        visible inverse artifact, so we refuse to touch pixels without a positive
+        detection. To bypass detection (e.g. you know the exact region), use
+        ``remove_watermark_custom``.
+
         Args:
             image: BGR image as numpy array (will NOT be modified in-place).
             force_size: Force a specific watermark size (auto-detect if None).
 
         Returns:
-            Cleaned BGR image as numpy array.
+            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:
+        # 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.
+        if result.ndim == 2:
+            result = cv2.cvtColor(result, cv2.COLOR_GRAY2BGR)
+        elif result.shape[2] == 4:
             result = cv2.cvtColor(result, cv2.COLOR_BGRA2BGR)
         elif result.shape[2] == 1:
             result = cv2.cvtColor(result, cv2.COLOR_GRAY2BGR)
 
-        h, w = result.shape[:2]
-        size = force_size or get_watermark_size(w, h)
+        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 the confidence is really high (>0.15), use the dynamically detected position and size.
-        if detection.confidence > 0.15:
-            pos = (detection.region[0], detection.region[1])
-            alpha_map = self.get_interpolated_alpha(detection.region[2])
+        if not detection.detected:
             logger.debug(
-                "Using dynamic watermark position (%d, %d) at size %dx%d [conf=%.3f]",
-                pos[0],
-                pos[1],
-                detection.region[2],
-                detection.region[3],
+                "No watermark detected (conf=%.3f); returning image unchanged.",
                 detection.confidence,
             )
-        else:
-            config = get_watermark_config(w, h)
-            pos = config.get_position(w, h)
-            alpha_map = self.get_alpha_map(size)
-            logger.debug(
-                "Dynamic search failed. Using fallback default position (%d, %d) with %dx%d alpha map.",
-                pos[0],
-                pos[1],
-                alpha_map.shape[1],
-                alpha_map.shape[0],
-            )
+            return result
+
+        pos = (detection.region[0], detection.region[1])
+        alpha_map = self.get_interpolated_alpha(detection.region[2])
+        logger.debug(
+            "Removing watermark at (%d, %d) size %dx%d [conf=%.3f]",
+            pos[0],
+            pos[1],
+            detection.region[2],
+            detection.region[3],
+            detection.confidence,
+        )
 
         self._reverse_alpha_blend(result, alpha_map, pos)
         return result
 
     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:
@@ -390,8 +399,8 @@ class GeminiEngine:
 
     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.
@@ -442,13 +451,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
@@ -546,3 +555,19 @@ class GeminiEngine:
             result[py1:py2, px1:px2] = blended.astype(np.uint8)
 
         return result
+
+
+def detect_sparkle_confidence(image_path: Path) -> float | None:
+    """Visible-sparkle detection confidence for a file, for provenance use.
+
+    Loads the image with cv2 and runs :meth:`GeminiEngine.detect_watermark`.
+    Returns the NCC confidence in [0, 1], or None if the image cannot be read
+    (cv2 returns None for unsupported containers such as HEIC). Kept here so the
+    cv2 dependency stays in this module; callers apply their own threshold.
+    """
+    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

@@ -4,6 +4,9 @@ Simulates analog film imperfections to defeat digital AI perfection
 classifiers. Ported from NeuralBleach.
 """
 
+# 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 +36,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))
 

src/remove_ai_watermarks/identify.py

@@ -0,0 +1,666 @@
+"""Image provenance: identify where an image was made and what watermarks it carries.
+
+Aggregates every locally-readable signal into a single :class:`ProvenanceReport`:
+
+- **C2PA Content Credentials** (issuer, claim generator, digital source type) ->
+  the signing platform (OpenAI, Google, Adobe, Microsoft).
+- **IPTC ``digitalSourceType``** "Made with AI" marker (Meta, X, others).
+- **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 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
+(proprietary decoder). Absence of signals is therefore reported as ``Unknown``,
+never as "clean". See CLAUDE.md "SynthID detection is metadata-only".
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from remove_ai_watermarks.metadata import (
+    AI_METADATA_KEYS,
+    AIGC_MARKERS,
+    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
+
+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.
+_SCAN_BYTES = 1024 * 1024
+
+# Visible-sparkle confidence above which the signal is trusted as provenance.
+# Stricter than the removal default (0.25): on the corpus, Gemini-family
+# sparkles score >= 0.56 while non-sparkle images top out at 0.49, so 0.5
+# cleanly separates them and avoids false positives when sparkle is the only
+# 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)"),
+    ("Black Forest Labs", "Black Forest Labs (FLUX)"),
+    ("ByteDance", "ByteDance (Doubao / Jimeng / Volcano Engine)"),
+)
+
+# PNG-text / EXIF keys that indicate a local diffusion pipeline (vs. a hosted
+# platform's C2PA). Subset of AI_METADATA_KEYS; excludes the C2PA/Software keys.
+_LOCAL_GEN_KEYS = frozenset(
+    AI_METADATA_KEYS & {"parameters", "prompt", "negative_prompt", "workflow", "comfyui", "invokeai_metadata", "dream"}
+)
+
+_STRIP_CAVEAT = (
+    "Absence of metadata is not proof the image is clean: C2PA, EXIF, and PNG "
+    "text chunks are stripped by re-encoding, screenshots, or social-media upload."
+)
+_SYNTHID_CAVEAT = (
+    "SynthID is a metadata proxy here; the pixel watermark is not locally "
+    "verifiable (proprietary decoder). Confirm via the Gemini app or openai.com/verify."
+)
+_OPENAI_CAVEAT = (
+    "OpenAI began pairing SynthID with C2PA around 2026-05; OpenAI images from "
+    "before the rollout carry C2PA without SynthID, so the SynthID verdict is 'likely'."
+)
+_IPTC_ONLY_CAVEAT = "The IPTC 'Made with AI' tag flags AI provenance but does not identify the specific platform."
+_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
+class Signal:
+    """A single provenance signal that was found (or affirmatively absent)."""
+
+    name: str
+    detail: str
+    confidence: str  # "high" | "medium"
+
+
+@dataclass
+class ProvenanceReport:
+    """Aggregated provenance verdict for one image."""
+
+    path: Path
+    is_ai_generated: bool | None  # True / False is never asserted; None = unknown
+    platform: str | None
+    confidence: str  # "high" | "medium" | "none"
+    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]:
+    """C2PA issuer names whose signature byte appears in ``data`` (binary scan)."""
+    return sorted({name for sig, name in C2PA_ISSUERS.items() if sig in data})
+
+
+def _ai_tools_in(data: bytes) -> list[str]:
+    """Known C2PA AI-tool / generator names appearing in ``data`` (binary scan).
+
+    PNG has a structured claim_generator; for JPEG/WebP/AVIF/HEIF/JXL the
+    generator lives in a JUMBF/EXIF/XMP blob the PNG parser can't reach, so a
+    byte scan recovers the same attribution (e.g. "Imagen", "DALL-E").
+    """
+    return sorted({name for sig, name in C2PA_AI_TOOLS.items() if sig in data})
+
+
+# Distinctive C2PA device/camera tokens (cert CN, cert org, or claim-generator
+# substrings) scanned in the manifest bytes -> platform. This is more reliable
+# than mapping an issuer name (which also matches incidental mentions: a
+# timestamp authority like "Truepic" in a Leica chain, an XMP-toolkit "Adobe"
+# string in a Nikon file, or "Google" in a Pixel camera's cert -- all verified
+# on real samples), and more robust than parsing the claim generator (which
+# lives under varying CBOR keys, e.g. `claim_generator` vs `claim_generator_info`,
+# and is absent on the Pixel sample where only the cert CN "Pixel Camera"
+# identifies it). Camera C2PA marks CAPTURE authenticity, not AI, so these never
+# 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,
+# 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)"),
+    (b"NIKON", "Nikon (camera, C2PA capture)"),
+    (b"Pixel Camera", "Google Pixel (camera, C2PA capture)"),
+    # Sony uses its own ``sony.*`` C2PA assertion namespace (sony.sig / sony.cert);
+    # match that, NOT bare "Sony" (which is an EXIF Make on countless photos).
+    # Verified on a real Sony-signed file (Sony PXW-Z300, signer "Sony Corporation").
+    (b"sony.sig", "Sony (camera, C2PA capture)"),
+    (b"sony.cert", "Sony (camera, C2PA capture)"),
+    # "Truepic_Lens" (from the Lens SDK claim generator), NOT bare "Truepic" --
+    # Truepic is a C2PA signing authority whose name appears in the trust chain
+    # of unrelated manifests (e.g. OpenAI), so the bare token mis-attributes.
+    (b"Truepic_Lens", "Truepic Lens (verified capture)"),
+)
+
+
+def _device_platform(head: bytes) -> str | None:
+    """Map a distinctive C2PA device/camera token in the manifest bytes to a platform."""
+    for token, platform in _DEVICE_C2PA_PLATFORM:
+        if token in head:
+            return platform
+    return None
+
+
+# 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
+
+
+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] = []
+
+    by_vendor: dict[str, list[str]] = {}
+    for family, vendor in ai_vendors.items():
+        by_vendor.setdefault(vendor, []).append(family)
+    if len(by_vendor) >= 2:
+        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.
+
+    Optional: needs cv2/numpy (no GPU). The cv2 work lives in gemini_engine so
+    this module stays dependency-light; returns None if cv2 or the engine
+    assets are missing, or the image can't be read.
+    """
+    try:
+        from remove_ai_watermarks.gemini_engine import detect_sparkle_confidence
+    except Exception as exc:  # cv2/engine assets missing
+        log.debug("visible-sparkle detector unavailable: %s", exc)
+        return 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)",
+}
+
+
+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.
+
+    Optional: needs the imwatermark decoder (extra ``detect``). Returns None if
+    it is not installed or no known watermark decodes.
+    """
+    from remove_ai_watermarks.invisible_watermark import detect_invisible_watermark
+
+    return detect_invisible_watermark(image_path)
+
+
+def _trustmark(image_path: Path) -> str | None:
+    """Adobe TrustMark scheme name or None.
+
+    Optional: needs the ``trustmark`` decoder (extra ``trustmark``). Returns None
+    if it is not installed or no TrustMark watermark decodes.
+    """
+    from remove_ai_watermarks.trustmark_detector import detect_trustmark
+
+    return detect_trustmark(image_path)
+
+
+def identify(image_path: Path, *, check_visible: bool = True, check_invisible: bool = True) -> ProvenanceReport:
+    """Identify an image's origin platform and watermark inventory.
+
+    Args:
+        image_path: Path to the image (PNG, JPEG, WebP, or ISOBMFF container).
+        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.
+
+    Returns:
+        A :class:`ProvenanceReport`. ``is_ai_generated`` is True when any AI
+        signal is found and None (unknown) when none is -- it is never asserted
+        False, because stripped metadata leaves no local proof of a clean origin.
+    """
+    info = extract_c2pa_info(image_path)  # PNG-structured; {} for other formats
+    meta = get_ai_metadata(image_path)  # PNG text + EXIF + C2PA fields + synthid
+
+    # 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 {}.
+    # 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 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")
+    )
+    # Generator string (for the signal detail): structured for PNG, CBOR-scanned
+    # for other containers. Best-effort -- some manifests key it as
+    # `claim_generator_info` (Pixel), so this can be None even when a device is
+    # identified by `_device_platform`.
+    generator = (
+        info.get("claim_generator")
+        or cbor_text_after(head, b"claim_generator")
+        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), 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 watermark, inferred from C2PA metadata ({synthid})")
+        caveats.append(_SYNTHID_CAVEAT)
+        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
+    # the watermark itself can't be decoded; names whose watermark stamped the pixels.
+    soft_binding = meta.get("soft_binding") or (", ".join(v) if (v := soft_binding_vendors_in(head)) else None)
+    if soft_binding:
+        signals.append(Signal("soft_binding", f"C2PA soft binding: {soft_binding}", "high"))
+        watermarks.append(f"Forensic watermark soft binding ({soft_binding})")
+
+    # ── IPTC "Made with AI" (Meta etc.), only meaningful without C2PA ─
+    iptc = any(m in head for m in IPTC_AI_MARKERS)
+    if iptc and not has_c2pa:
+        signals.append(Signal("iptc", "digitalSourceType (Made with AI)", "high"))
+        watermarks.append("IPTC digitalSourceType (Made with AI)")
+        caveats.append(_IPTC_ONLY_CAVEAT)
+        if platform is None:
+            platform = "Made-with-AI tag (e.g. Meta AI); platform not specified"
+
+    # ── IPTC 2025.1 AI-disclosure fields (Iptc4xmpExt:AISystemUsed etc.) ─
+    iptc_ai = any(m in head for m in IPTC_AI_FIELD_MARKERS)
+    if iptc_ai:
+        system = iptc_ai_system(image_path)
+        named = bool(system) and system != "fields present"
+        signals.append(
+            Signal("iptc_ai_system", f"IPTC AI disclosure ({system})" if named else "IPTC AI disclosure fields", "high")
+        )
+        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) ──
+    # 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_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)
+    if local_keys:
+        signals.append(Signal("gen_params", f"embedded keys: {', '.join(local_keys)}", "high"))
+        watermarks.append("Embedded generation parameters (Stable Diffusion / ComfyUI)")
+        if platform is None:
+            platform = "Stable Diffusion / local pipeline (Automatic1111, ComfyUI, InvokeAI)"
+
+    # ── EXIF Software / XMP CreatorTool generator (cross-format) ─────
+    # Catches a generator tag (incl. inside AVIF/HEIF/JXL) when there is no C2PA.
+    if generator_tag := exif_generator(image_path):
+        signals.append(Signal("exif_generator", f"EXIF/XMP generator: {generator_tag}", "high"))
+        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>"
+    # + a UUID Artist. Distinct from exif_generator (which matches generator
+    # tokens); verified stable across 3 generations. See CLAUDE.md.
+    if xai_signature(image_path):
+        signals.append(Signal("xai_signature", "EXIF Signature blob + UUID Artist", "high"))
+        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.
+    if check_invisible and (scheme := _invisible_watermark(image_path)) is not None:
+        signals.append(Signal("invisible_watermark", scheme, "high"))
+        watermarks.append(f"Open invisible watermark: {scheme}")
+        caveats.append(_INVISIBLE_WM_CAVEAT)
+        if platform is None:
+            platform = f"{scheme} (open DWT-DCT watermark)"
+
+    # ── Adobe TrustMark invisible watermark (open decoder, no key) ───
+    # The watermark behind Adobe Durable Content Credentials. Decoded locally,
+    # but it binds provenance for human-authored content too, so it enriches the
+    # watermark inventory without by itself asserting AI origin.
+    if check_invisible and (tm_scheme := _trustmark(image_path)) is not None:
+        signals.append(Signal("trustmark", tm_scheme, "high"))
+        watermarks.append(f"Adobe TrustMark invisible watermark ({tm_scheme})")
+        if platform is None:
+            platform = "Adobe (TrustMark / Content Credentials)"
+
+    # ── Verdict so far (metadata + embedded watermark) ──────────────
+    invisible_wm = any(s.name == "invisible_watermark" for s in signals)
+    exif_gen = any(s.name == "exif_generator" for s in signals)
+    xai_sig = any(s.name == "xai_signature" for s in signals)
+    ai_from_metadata = bool(
+        (has_c2pa and (c2pa_is_ai or synthid))
+        or iptc
+        or iptc_ai
+        or aigc
+        or local_keys
+        or invisible_wm
+        or exif_gen
+        or xai_sig
+    )
+
+    # ── Visible Gemini sparkle (fallback for stripped-metadata case) ─
+    if check_visible and (conf := _visible_sparkle(image_path)) is not None and conf >= _SPARKLE_THRESHOLD:
+        signals.append(Signal("visible_sparkle", f"NCC confidence {conf:.2f}", "medium"))
+        watermarks.append(f"Visible Gemini sparkle (confidence {conf:.2f})")
+        if platform is None:
+            platform = "Google Gemini family (visible sparkle detected)"
+
+    # ── Visible Doubao / Jimeng text marks (registry; same stripped-metadata
+    #    fallback role as the Gemini sparkle above) ─
+    if check_visible:
+        for det in _visible_text_marks(image_path):
+            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 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))
+
+    return ProvenanceReport(
+        path=image_path,
+        is_ai_generated=is_ai,
+        platform=platform,
+        confidence=confidence,
+        watermarks=watermarks,
+        signals=signals,
+        caveats=caveats,
+        integrity_clashes=clashes,
+    )

src/remove_ai_watermarks/image_io.py

@@ -0,0 +1,70 @@
+"""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 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,6 +7,10 @@ This module requires the 'gpu' extra dependencies:
     uv pip install 'remove-ai-watermarks[gpu]'
 """
 
+# cv2/torch boundary: this engine wraps cv2 (resize/imwrite/cvtColor), the YOLO
+# face protector, 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
@@ -33,13 +37,27 @@ 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.
+
+    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.
+    """
+    if max_resolution > 0 and max(width, height) > max_resolution:
+        ratio = max_resolution / max(width, height)
+        # 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)))
+    return None
 
 
 class InvisibleEngine:
@@ -52,7 +70,11 @@ class InvisibleEngine:
     to break watermark patterns, and reconstructs via reverse diffusion.
     """
 
-    DEFAULT_MODEL_ID = "Lykon/dreamshaper-8"
+    # SDXL base is the default since May 2026; the current Google SynthID is
+    # removed at strength ~0.30 / steps=50 / native res (oracle-verified, n=3 fresh
+    # Gemini -- 0.10/0.15/0.2 still detected). See CLAUDE.md "Known limitations" for
+    # the strength study and the regression evidence ruling out SD-1.5 pipelines.
+    DEFAULT_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
     CTRLREGEN_MODEL_ID = "yepengliu/ctrlregen"
 
     def __init__(
@@ -67,8 +89,9 @@ class InvisibleEngine:
 
         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" or "ctrlregen").
+            device: Device for inference (auto/cpu/mps/cuda/xpu). None = auto.
+            pipeline: Pipeline profile. "default" (SDXL base, defeats SynthID
+                v2) or "ctrlregen" (CtrlRegen).
             hf_token: HuggingFace API token.
             progress_callback: Optional callback for progress messages.
         """
@@ -103,18 +126,29 @@ class InvisibleEngine:
         seed: int | None = None,
         humanize: float = 0.0,
         protect_faces: bool = True,
+        protect_text: bool = True,
+        max_resolution: int = 0,
     ) -> 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 -> profile default
+                (0.10 for SDXL, 1.0 clean-noise for ctrlregen).
             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.
+            protect_text: Detect text regions and preserve them via Differential
+                Diffusion when any are found, so glyphs (incl. CJK) survive the
+                removal pass. On by default; the detector decides per image.
+            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).
 
         Returns:
             Path to the cleaned image.
@@ -123,41 +157,35 @@ class InvisibleEngine:
 
         from PIL import Image, ImageOps
 
-        max_dimension = 768
+        # 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.
         image = Image.open(image_path)
         image = ImageOps.exif_transpose(image)
         orig_size = image.size  # (width, height)
-        _tmp_path = None
 
-        if max(image.width, image.height) > max_dimension:
-            ratio = max_dimension / max(image.width, image.height)
-            new_size = (int(image.width * ratio), int(image.height * ratio))
+        # Optional long-side downscale; native resolution by default (issue #10).
+        target = _target_size(image.width, image.height, max_resolution)
+        if target is not None:
             if self._progress_callback:
                 self._progress_callback(
                     f"Downscaling {image.width}x{image.height} "
-                    f"to {new_size[0]}x{new_size[1]} "
-                    f"(model trained at {max_dimension}px)..."
+                    f"to {target[0]}x{target[1]} "
+                    f"(max-resolution cap {max_resolution}px)..."
                 )
-            image = image.resize(new_size, Image.Resampling.LANCZOS)
+            image = image.resize(target, Image.Resampling.LANCZOS)
 
-            # Save to a temp file instead of overwriting the original
-            _tmp_fd, _tmp_str = tempfile.mkstemp(suffix=image_path.suffix)
-            _tmp_path = Path(_tmp_str)
-            image.save(_tmp_path)
-            import os as _os
-
-            _os.close(_tmp_fd)
-            image_path = _tmp_path
-        else:
-            # We must save the transposed image back to a tmp file if it was rotated
-            # otherwise WatermarkRemover will reload it without EXIF rotation!
-            _tmp_fd, _tmp_str = tempfile.mkstemp(suffix=image_path.suffix)
-            _tmp_path = Path(_tmp_str)
-            image.save(_tmp_path)
-            import os as _os
-
-            _os.close(_tmp_fd)
-            image_path = _tmp_path
+        # Always persist to a temp file, even without downscaling: WatermarkRemover
+        # reloads by path, so the EXIF-transposed pixels must be saved or rotation
+        # is lost. Cleaned up in the finally block via _tmp_path.
+        _tmp_fd, _tmp_str = tempfile.mkstemp(suffix=image_path.suffix)
+        _tmp_path = Path(_tmp_str)
+        image.save(_tmp_path)
+        os.close(_tmp_fd)
+        image_path = _tmp_path
 
         try:
             # Optional: Face protection (Phase 1 - Extraction)
@@ -188,6 +216,7 @@ class InvisibleEngine:
                 num_inference_steps=num_inference_steps,
                 guidance_scale=guidance_scale,
                 seed=seed,
+                protect_text=protect_text,
             )
 
             # Optional: Face restoration & Humanizer (Phase 2 - Post-processing)
@@ -195,7 +224,11 @@ class InvisibleEngine:
                 import cv2
                 import numpy as np
 
-                out_cv = cv2.imread(str(out_path), cv2.IMREAD_COLOR)
+                from remove_ai_watermarks import image_io
+
+                out_cv = image_io.imread(out_path, cv2.IMREAD_COLOR)
+                if out_cv is None:
+                    return out_path
 
                 if protect_faces and original_faces:
                     if self._progress_callback:
@@ -221,31 +254,34 @@ class InvisibleEngine:
                     # 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)
+                image_io.imwrite(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)
+                from remove_ai_watermarks import image_io
+
+                out_cv = image_io.imread(out_path, cv2.IMREAD_COLOR)
                 if out_cv is not None and (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]}..."
                         )
                     out_cv = cv2.resize(out_cv, orig_size, interpolation=cv2.INTER_LANCZOS4)
-                    cv2.imwrite(str(out_path), out_cv)
+                    image_io.imwrite(out_path, out_cv)
 
             return out_path
         finally:
-            if _tmp_path is not None and _tmp_path.exists():
+            # _tmp_path is always set above (we persist the image unconditionally).
+            if _tmp_path.exists():
                 _tmp_path.unlink()
 
     def remove_watermark_batch(
         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

@@ -0,0 +1,109 @@
+"""Detect open invisible watermarks embedded by the ``invisible-watermark``
+(imwatermark) library -- used by Stable Diffusion, SDXL, and FLUX.
+
+Unlike SynthID (proprietary, no local decoder), these are DWT-DCT watermarks
+with a PUBLIC decoder and no secret key, so a fresh, un-re-encoded output can be
+identified locally. The known fixed patterns were verified against upstream
+source:
+
+- **Stable Diffusion XL** -- diffusers ``StableDiffusionXLWatermarker``
+  ``WATERMARK_MESSAGE`` (48-bit).
+- **FLUX.2** -- ``black-forest-labs/flux2`` ``src/flux2/watermark.py`` (48-bit).
+- **Stable Diffusion 1.x / 2.x** -- the library's default ``"StableDiffusionV1"``
+  string (136-bit).
+
+The watermark is fragile: it does NOT survive JPEG re-encoding or resizing
+(verified -- gone after JPEG q90), so detection works only on pristine PNG
+originals. Absence is never proof. Requires the optional ``invisible-watermark``
+package (extra: ``detect``); ``detect_invisible_watermark`` returns None when it
+is not installed.
+"""
+
+# imwatermark ships no type stubs (like cv2); its decoder returns are Unknown.
+# Relax the untyped-library diagnostics for this thin wrapper module only.
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# Known 48-bit ``bits`` watermarks (dwtDct, no key), name -> message integer.
+_BITS_48: dict[str, int] = {
+    "Stable Diffusion XL": 0b101100111110110010010000011110111011000110011110,
+    "FLUX.2 (Black Forest Labs)": 0b001010101111111010000111100111001111010100101110,
+}
+# The invisible-watermark default string watermark (SD 1.x / 2.x).
+_SD1_STRING = b"StableDiffusionV1"
+
+# Decoded bits/bytes never match a 48-bit pattern by chance: random decode lands
+# near 24/48, an exact embed at 48/48 (measured). 44 (<=4 bit errors) is a safe
+# floor that tolerates light perturbation without risking a false positive.
+_MATCH_48 = 44
+_MATCH_SD1_FRAC = 0.92  # fraction of the 136 string bits that must match
+
+
+def is_available() -> bool:
+    """True if the optional imwatermark decoder is installed."""
+    import importlib.util
+
+    return importlib.util.find_spec("imwatermark") is not None
+
+
+def _bits_match(value: int, ref: int, width: int = 48) -> int:
+    """Number of matching bits between two ``width``-bit integers."""
+    return width - bin(value ^ ref).count("1")
+
+
+def _bytes_match_frac(a: bytes, b: bytes) -> float:
+    """Fraction of matching bits between two equal-length byte strings."""
+    if len(a) != len(b) or not a:
+        return 0.0
+    diff = sum(bin(x ^ y).count("1") for x, y in zip(a, b, strict=True))
+    return 1.0 - diff / (8 * len(b))
+
+
+def detect_invisible_watermark(image_path: Path) -> str | None:
+    """Return the embedding scheme name if a known open watermark is decoded.
+
+    Returns e.g. ``"Stable Diffusion XL"`` / ``"FLUX.2 (Black Forest Labs)"`` /
+    ``"Stable Diffusion 1.x / 2.x"``, or None if none matches, the decoder is
+    unavailable, or the image can't be read. Meaningful only on pristine
+    (un-re-encoded) images.
+    """
+    if not is_available():
+        return None
+    from imwatermark import WatermarkDecoder
+
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(image_path)
+    if img is None:
+        return None
+
+    # 48-bit fixed-message watermarks (SDXL, FLUX.2).
+    try:
+        bits = WatermarkDecoder("bits", 48).decode(img, "dwtDct")
+        value = 0
+        for bit in bits:
+            value = (value << 1) | (1 if bit else 0)
+        for name, ref in _BITS_48.items():
+            if _bits_match(value, ref) >= _MATCH_48:
+                return name
+    except Exception as exc:  # decode can fail on tiny images
+        log.debug("48-bit watermark decode failed for %s: %s", image_path, exc)
+
+    # 136-bit default string watermark (SD 1.x / 2.x).
+    try:
+        raw = cast("bytes", WatermarkDecoder("bytes", 8 * len(_SD1_STRING)).decode(img, "dwtDct"))
+        if _bytes_match_frac(raw, _SD1_STRING) >= _MATCH_SD1_FRAC:
+            return "Stable Diffusion 1.x / 2.x"
+    except Exception as exc:
+        log.debug("string watermark decode failed for %s: %s", image_path, exc)
+
+    return None

src/remove_ai_watermarks/jimeng_engine.py

@@ -0,0 +1,415 @@
+"""Jimeng (即梦AI) visible watermark removal engine.
+
+Jimeng / Dreamina (ByteDance's image generator, distinct from Doubao) stamps a
+visible "★ 即梦AI" wordmark -- a four-point sparkle icon followed by the 即梦AI
+characters -- in the bottom-right corner: a near-white semi-transparent overlay,
+the explicit AIGC label under China's TC260 standard.
+
+Like the Gemini sparkle and the Doubao strip, it is a fixed overlay, so removal
+starts from **reverse-alpha blending** against a captured alpha map
+(``remove_watermark_reverse_alpha``): ``original = (wm - a*logo)/(1-a)``. The logo
+is pure white (255,255,255); the alpha map was solved from the GRAY Jimeng capture
+(see data/jimeng_capture/), bundled as ``assets/jimeng_alpha.png`` -- a careful
+build (cubic-background fit, mean over channels, full halo extent, unblurred) that
+drops the self-residual to ~1.3. Gray is the chosen background because the mark
+sits on bright photo content in real use, not on black.
+
+Unlike the Doubao mark, Jimeng re-rasterizes its mark per generation AND jitters
+its position a few px (the alpha maps solved from independent captures correlate
+0.998 but not 1.0), so a single 2048 alpha map does not pixel-cancel the mark on
+every image/resolution 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 deliberately THIN inpaint over the
+glyph footprint. The reverse-alpha pre-step recovers the true background (including
+edges) under the semi-transparent mark, so the thin inpaint only finishes the
+residual edges rather than smearing the whole footprint -- a wide full-footprint
+pass blurred the texture/edges under the mark. Verified clean on the solid captures
+(native 2048) and on a real 1440-wide Jimeng download (off-native, table edge kept).
+
+Detection (``detect``) matches the bundled "即梦AI" glyph silhouette against the
+corner candidate via normalized correlation, so it keys on the actual mark shape
+(real marks score >=0.81, the Doubao strip 0.21, other AI output 0.0) rather than
+coverage heuristics, and does not hijack ``--mark auto`` on a Doubao image.
+
+``locate`` (geometry box, scales with image WIDTH) and ``extract_mask`` (the
+candidate glyph mask the detector correlates) mirror the Doubao engine. Fast,
+offline, no GPU. Arbitrary-region inpainting still lives in ``region_eraser`` /
+the ``erase`` command.
+"""
+
+# 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 typing import TYPE_CHECKING, Any
+
+import cv2
+import numpy as np
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+
+# Geometry as a fraction of image WIDTH. The Jimeng mark scales with width and is
+# anchored bottom-right. The box is intentionally generous (the glyph mask
+# tightens it); values cover the measured 2048 captures plus a real 1440 download.
+WM_WIDTH_FRAC = 0.27
+WM_HEIGHT_FRAC = 0.092
+MARGIN_RIGHT_FRAC = 0.008
+MARGIN_BOTTOM_FRAC = 0.010
+
+# Glyph appearance: a low-saturation light gray rendered brighter than the
+# surrounding content (white top-hat: brighter than a blurred local background)
+# intersected with the grayish + minimum-brightness tests. Same polarity logic as
+# the Doubao engine: leaves white-paper documents untouched (the mark is not
+# brighter than its surroundings there, so nothing is masked).
+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 matches the bundled alpha-template glyph silhouette
+# (assets/jimeng_alpha.png) against the candidate via zero-mean normalized
+# correlation (cv2 TM_CCOEFF_NORMED). Real Jimeng marks score >=0.83, the Doubao
+# strip 0.22, other AI output 0.0 -> threshold 0.45 separates cleanly while
+# keeping `--mark auto` from confusing Jimeng with Doubao. A small coverage floor
+# skips the template match on a near-empty candidate box.
+DETECT_MIN_COVERAGE = 0.02
+DETECT_NCC_THRESHOLD = 0.45
+
+# ── Reverse-alpha (recovery, Gemini/Doubao-style) ────────────────────
+# The Jimeng mark is a fixed semi-transparent white overlay; given its alpha map
+# the original pixels are recovered by inverting the blend. The logo is pure white
+# (the white capture confirms L=255 and a pair-solve of L lands at ~254.6). The
+# alpha map was solved from the GRAY capture: a = (I - B)/(255 - B) with B a
+# per-capture CUBIC background fit over the non-glyph pixels, averaged over the
+# three channels, kept at full halo extent (down to a~0.02) and UNBLURRED. Gray
+# (background ~132, mark contrast ~120) is chosen over black because it is the
+# best proxy for real content, where the mark sits on bright photo areas, not on
+# black; the careful build drops the gray self-residual to ~1.3 (the earlier
+# max-channel / quadratic-bg / blurred / halo-truncated build was visibly worse --
+# the mask, not the method, was the limit). The bundled asset
+# (assets/jimeng_alpha.png) is the alpha template (a*255) at the captured width.
+# The mark scales with image WIDTH; a pure width-scale is only sub-pixel-accurate
+# at the captured width, so removal also registers the template to the actual mark
+# via a TM_CCOEFF_NORMED scale+position search (`_aligned_alpha_map`) off it.
+_ALPHA_NATIVE_WIDTH = 2048
+_ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
+# Geometry below is emitted by scripts/visible_alpha_solve.py for the bundled
+# asset -- keep them in sync when the asset is rebuilt.
+_ALPHA_WIDTH_FRAC = 0.2021  # asset width / image width -- the alignment scale seed
+_ALPHA_HEIGHT_FRAC = 0.0576
+# Margins (of image WIDTH) of the captured mark -- the geometry record / where to
+# seed; alignment refines the actual position, so these are not load-bearing.
+_ALPHA_MARGIN_RIGHT_FRAC = 0.0288
+_ALPHA_MARGIN_BOTTOM_FRAC = 0.0288
+# Alignment scale search (np.linspace args) around the width-scaled glyph size --
+# fine enough that a per-image scale/position jitter does not leave a thick
+# edge-misalignment outline (a coarse step left ~4px slop at the mark ends).
+_ALPHA_ALIGN_SEARCH = (0.90, 1.12, 23)
+# Residual inpaint footprint: unlike Doubao, Jimeng's per-image render variation
+# leaves a faint outline even at native, so the glyph footprint (alpha above this)
+# is always inpainted after reverse-alpha (dilated by this kernel, INPAINT_NS).
+# Kept deliberately THIN -- the careful alpha map (cubic-background, mean-channel,
+# full-halo solve) knocks the mark down far enough that a tight footprint clears
+# it, so the inpaint does not smear the texture/edges under the mark the way a
+# wide full-footprint pass did.
+_RESIDUAL_ALPHA_FLOOR = 0.05
+_RESIDUAL_DILATE = 5
+_RESIDUAL_INPAINT_RADIUS = 2
+_alpha_template_cache: NDArray[Any] | None = None
+
+
+def _alpha_template() -> NDArray[Any] | None:
+    """Lazily load the bundled Jimeng alpha template (float [0,1]), or None."""
+    global _alpha_template_cache
+    if _alpha_template_cache is None:
+        from pathlib import Path
+
+        from remove_ai_watermarks import image_io
+
+        path = Path(__file__).parent / "assets" / "jimeng_alpha.png"
+        img = image_io.imread(str(path), cv2.IMREAD_GRAYSCALE)
+        if img is None:
+            return None
+        _alpha_template_cache = img.astype(np.float32) / 255.0
+    return _alpha_template_cache
+
+
+@dataclass(frozen=True)
+class JimengLocation:
+    """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
+
+
+@dataclass
+class JimengDetection:
+    """Result of visible Jimeng 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
+
+
+_silhouette_cache: NDArray[Any] | None = None
+
+
+def _glyph_silhouette() -> NDArray[Any] | None:
+    """Binary "即梦AI" silhouette (255 = glyph) from the bundled alpha map, used
+    as the detection template. None if the alpha asset is missing."""
+    global _silhouette_cache
+    if _silhouette_cache is None:
+        at = _alpha_template()
+        if at is None:
+            return None
+        _silhouette_cache = (at > 0.15).astype(np.uint8) * 255
+    return _silhouette_cache
+
+
+def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
+    """Zero-mean normalized correlation of the alpha-template glyph silhouette
+    (scaled to the mark's expected size) against the candidate ``box_mask``."""
+    sil = _glyph_silhouette()
+    if sil is None or box_mask.size == 0:
+        return 0.0
+    gw = min(box_mask.shape[1] - 1, max(8, int(_ALPHA_WIDTH_FRAC * image_width)))
+    gh = min(box_mask.shape[0] - 1, max(4, int(_ALPHA_HEIGHT_FRAC * image_width)))
+    if gw < 8 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 JimengEngine:
+    """Remove the visible Jimeng "即梦AI" watermark (locate -> mask -> reverse-alpha)."""
+
+    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[Any]) -> JimengLocation:
+        """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 JimengLocation(x=x, y=y, w=wm_w, h=wm_h, is_fallback=True)
+
+    # ── Mask ──────────────────────────────────────────────────────────
+
+    def extract_mask(self, image: NDArray[Any], loc: JimengLocation) -> 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).
+        """
+        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 the native code on some platforms (observed: a Windows
+        # access violation via the always-align removal's residual `detect`). Skip
+        # the cv2 pipeline and return an empty mask there.
+        if bh < 16 or bw < 16:
+            return np.zeros((h, w), np.uint8)
+        # Normalize the ROI to 3-channel BGR: a 2D grayscale or 4-channel BGRA
+        # input would otherwise break the axis=2 channel reductions below.
+        roi = image[y : y + bh, x : x + bw]
+        if roi.ndim == 2:
+            roi = cv2.cvtColor(roi, cv2.COLOR_GRAY2BGR)
+        elif roi.shape[2] == 4:
+            roi = cv2.cvtColor(roi, cv2.COLOR_BGRA2BGR)
+        roi = roi.astype(np.float32)
+
+        luma = roi.mean(axis=2)
+        sat = roi.max(axis=2) - roi.min(axis=2)
+        grayish = sat < MAX_SATURATION
+
+        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
+        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[Any]) -> JimengDetection:
+        """Detect the visible Jimeng mark by matching the alpha-template glyph
+        silhouette against the corner candidate (TM_CCOEFF_NORMED)."""
+        det = JimengDetection()
+        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 >= DETECT_MIN_COVERAGE:
+            score = _template_match_score(box, image.shape[1])
+            det.confidence = score
+            det.detected = score >= DETECT_NCC_THRESHOLD
+            logger.debug("Jimeng detect: coverage=%.3f ncc=%.2f detected=%s", coverage, score, det.detected)
+        return det
+
+    # ── Reverse-alpha (recovery + 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``)."""
+        return image is not None and image.size > 0 and _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."""
+        at = _alpha_template()
+        if at is None:
+            return None
+        h, w = image.shape[:2]
+        gw = min(w, max(1, int(_ALPHA_WIDTH_FRAC * w)))
+        gh = min(h, max(1, int(_ALPHA_HEIGHT_FRAC * w)))
+        ax = max(0, w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw)
+        ay = max(0, 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), 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 -- so the single capture works
+        off the captured width. Returns ``(alpha_map, glyph_bbox)`` or None."""
+        at = _alpha_template()
+        sil = _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 = _ALPHA_WIDTH_FRAC * w
+        best: tuple[float, int, int, int, int] | None = None
+        for scale in np.linspace(*_ALPHA_ALIGN_SEARCH):
+            gw, gh = int(expected * scale), int(_ALPHA_HEIGHT_FRAC * w * scale)
+            if gw < 8 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(_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 -- Jimeng jitters the mark a few px per image even at
+        the captured width, so fixed geometry alone is not reliable. A single 2048
+        alpha cannot pixel-cancel the mark re-rasterized at another resolution, so a
+        deliberately THIN residual inpaint (``_RESIDUAL_*``) follows: reverse-alpha
+        has already recovered the true background (edges included) 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.
+        """
+        # Normalize to 3-channel BGR so a 2D grayscale or 4-channel BGRA input
+        # does not break the reverse-alpha math (which assumes a 3-channel logo).
+        if image.ndim == 2:
+            image = cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+        elif image.shape[2] == 4:
+            image = cv2.cvtColor(image, cv2.COLOR_BGRA2BGR)
+        # An image too small to hold the mark would make the geometry boxes
+        # degenerate and feed cv2.resize a ~1-px-tall target / GaussianBlur a sliver
+        # ROI, which faults natively on Windows (access violation / "Unknown C++
+        # exception"). No real watermarked image is this small; skip cv2 entirely.
+        h, w = image.shape[:2]
+        if h < 32 or w < 64:
+            return image.copy()
+        # Always try fixed geometry AND the NCC-aligned placement and keep
+        # whichever leaves the least residual mark (re-detect confidence on the
+        # bare reverse-alpha). Unlike Doubao's deterministic overlay, Jimeng jitters
+        # the mark's position a few px PER IMAGE even at the captured width, so
+        # fixed geometry alone misses there too -- the NCC search registers the
+        # template to the actual mark; fixed stays as a fallback if the search has
+        # no saliency to lock onto (a flat/contrastless mark).
+        maps = [c for c in (self._fixed_alpha_map(image), self._aligned_alpha_map(image)) if c 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((_RESIDUAL_DILATE, _RESIDUAL_DILATE), np.uint8)
+            rm = cv2.dilate((best_amap > _RESIDUAL_ALPHA_FLOOR).astype(np.uint8) * 255, kernel)
+            best_out = cv2.inpaint(best_out, rm, _RESIDUAL_INPAINT_RADIUS, cv2.INPAINT_NS)
+        return best_out
+
+
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read an image as BGR ndarray (helper for scripts/tests)."""
+    from remove_ai_watermarks import image_io
+
+    img = image_io.imread(path, cv2.IMREAD_COLOR)
+    if img is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return img

src/remove_ai_watermarks/metadata.py

@@ -10,7 +10,9 @@ from __future__ import annotations
 
 import contextlib
 import logging
-from typing import TYPE_CHECKING
+import re
+import struct
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -60,6 +62,90 @@ AI_KEYWORDS: tuple[str, ...] = (
     "c2pa",
 )
 
+# C2PA UUID used in ISOBMFF (AVIF, HEIF, MP4) ``uuid`` boxes.
+# 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, ...] = (
+    b"trainedAlgorithmicMedia",
+    b"compositeSynthetic",
+    b"algorithmicMedia",
+    b"compositeWithTrainedAlgorithmicMedia",
+)
+
+# IPTC Photo Metadata 2025.1 (published 2025-11-27) added explicit AI-disclosure
+# XMP properties in the Iptc4xmpExt namespace. Their mere presence is an AI
+# signal; ``AISystemUsed`` additionally carries the generator name. Property
+# tokens verified against the IPTC 2025.1 specification.
+IPTC_AI_FIELD_MARKERS: tuple[bytes, ...] = (
+    b"AISystemUsed",
+    b"AISystemVersionUsed",
+    b"AIPromptInformation",
+    b"AIPromptWriterName",
+)
+
+# ISOBMFF containers whose AI-provenance boxes ``remove_ai_metadata`` strips at
+# the container level (image, video, audio -- all ISOBMFF). A content sniff
+# (``ftyp``) is also accepted, so this is a fast-path hint, not the sole gate.
+_ISOBMFF_EXTS: frozenset[str] = frozenset({".avif", ".heif", ".heic", ".jxl", ".mp4", ".mov", ".m4v", ".m4a"})
+
+# Non-ISOBMFF audio/video the ISOBMFF box walker can't reach (EBML / framed /
+# RIFF / Vorbis). remove_ai_metadata strips their container metadata losslessly
+# via ffmpeg (`-c copy`), so it needs ffmpeg on PATH for these.
+_FFMPEG_STRIP_EXTS: frozenset[str] = frozenset(
+    {".webm", ".mkv", ".mka", ".mp3", ".wav", ".flac", ".ogg", ".oga", ".opus", ".aac"}
+)
+
+# China's mandatory AI-content labeling (TC260, the national cybersecurity
+# standards committee). AI generators serving China embed an XMP block in the
+# TC260 namespace -- ``<TC260:AIGC>{"Label":"1",...}``. Doubao (ByteDance) uses
+# this; the same standard is mandatory for Jimeng, Kling, Qwen, Ernie, etc.,
+# so the marker covers the whole China-AIGC-labeled ecosystem. Container-
+# agnostic (XMP is text), so a raw-byte scan catches it in PNG/JPEG/etc.
+AIGC_MARKERS: tuple[bytes, ...] = (
+    b"tc260.org.cn/ns/AIGC",
+    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",
@@ -84,6 +170,80 @@ 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)
+                pos = data_start + 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.
+    """
+    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.
 
@@ -95,25 +255,389 @@ def has_ai_metadata(image_path: Path) -> bool:
     """
     from PIL import Image
 
-    with Image.open(image_path) as img:
-        for key in img.info:
-            if _is_ai_key(key):
-                return True
-
-    # Check C2PA
+    # 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.
     try:
-        from c2pa import has_c2pa_metadata
+        with Image.open(image_path) as img:
+            for key in img.info:
+                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)
+
+    # Check C2PA — via the official ``c2pa`` lib if available, otherwise via a
+    # binary scan that also catches AVIF/HEIF/JPEG-XL containers (PIL doesn't
+    # expose their metadata uniformly).
+    try:
+        # 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
     except ImportError:
-        # Try simple binary scan (read only first 512KB to avoid OOM on huge files)
-        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
+        pass
 
-    return False
+    # Binary scan covers C2PA (PNG caBX, JPEG APP11, AVIF/HEIF/JXL uuid boxes)
+    # 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
+    if any(marker in data for marker in IPTC_AI_MARKERS):
+        return True
+    # 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 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 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
+    from typing import cast
+
+    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:
+        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
+    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:
+    """Return an IPTC 2025.1 AI-disclosure note if the file carries those XMP
+    properties, else None.
+
+    IPTC Photo Metadata 2025.1 added ``Iptc4xmpExt`` AI-disclosure properties
+    (see ``IPTC_AI_FIELD_MARKERS``); their presence alone flags AI content, and
+    ``AISystemUsed`` names the generator. Returns the ``AISystemUsed`` value when
+    extractable, otherwise the literal ``"fields present"``. Container-agnostic
+    raw-byte scan; handles both XMP element and attribute serializations.
+    """
+    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)
+    if match and (value := match.group(1).decode("utf-8", "replace").strip()):
+        return value
+    return "fields present"
+
+
+def synthid_source(image_path: Path) -> str | None:
+    """Return the vendor name(s) if the image carries a SynthID pixel watermark.
+
+    This is a *metadata-based* proxy: Google (Imagen/Gemini) and OpenAI
+    (ChatGPT/DALL-E/gpt-image) embed an invisible SynthID watermark alongside
+    a C2PA manifest, so a C2PA manifest signed by one of them on AI-generated
+    content implies SynthID in the pixels. Adobe Firefly / Microsoft Designer
+    sign C2PA but do not use SynthID, so they return None.
+
+    The verdict is reliable only while the C2PA manifest is intact -- absence
+    is not proof, because C2PA can be stripped while the pixel watermark
+    survives, and the pixel watermark itself is not locally detectable
+    (proprietary decoder).
+
+    Args:
+        image_path: Path to the image (PNG, JPEG, WebP, or ISOBMFF container).
+
+    Returns:
+        Comma-joined vendor name(s) (e.g. ``"OpenAI"``) or None.
+    """
+    from remove_ai_watermarks.noai.c2pa import extract_c2pa_info, synthid_vendors_in
+
+    # PNG: the caBX chunk parser gives a clean, structured issuer.
+    vendors = extract_c2pa_info(image_path).get("synthid_vendors")
+    if vendors:
+        return ", ".join(vendors)
+
+    # 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.
+    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):
+        return None
+    matched = synthid_vendors_in(data)
+    return ", ".join(matched) if matched else None
+
+
+def exif_generator(image_path: Path) -> str | None:
+    """Return an AI-generator name from the EXIF ``Software`` / XMP ``CreatorTool``
+    field, if it matches a known generator (see ``AI_GENERATOR_TOKENS``), else None.
+
+    Cross-format: EXIF is read via PIL + piexif for any container PIL can open
+    (JPEG/WebP/AVIF/PNG); an XMP ``CreatorTool`` raw-byte scan additionally covers
+    HEIF/JPEG-XL that PIL can't open without plugins. Only AI tokens match, so
+    ordinary editors (plain "Adobe Photoshop", "GIMP") are not flagged.
+    """
+    import re
+
+    from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
+
+    candidates: list[str] = []
+
+    # EXIF Software / Artist / ImageDescription (0th IFD) via PIL exif bytes.
+    try:
+        import piexif
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            exif_bytes = img.info.get("exif")
+        if exif_bytes:
+            tags = piexif.load(exif_bytes).get("0th", {})
+            # Make catches camera-style tags AI tools reuse (Ideogram writes
+            # Make="Ideogram AI"); real cameras put "Apple"/"Canon" there, which
+            # carry no AI token, so this stays low-false-positive.
+            for tag in (
+                piexif.ImageIFD.Software,
+                piexif.ImageIFD.Make,
+                piexif.ImageIFD.Artist,
+                piexif.ImageIFD.ImageDescription,
+            ):
+                value = tags.get(tag)
+                if isinstance(value, bytes):
+                    candidates.append(value.decode("latin1", "replace"))
+    except Exception as exc:  # unopenable format / malformed EXIF
+        logger.debug("EXIF generator read failed for %s: %s", image_path, exc)
+
+    # XMP CreatorTool: text, container-agnostic (covers HEIF/JXL via raw scan).
+    try:
+        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:
+        logger.debug("XMP CreatorTool scan failed for %s: %s", image_path, exc)
+
+    for value in candidates:
+        if any(token in value.lower() for token in AI_GENERATOR_TOKENS):
+            return value.strip()
+    return None
+
+
+# xAI / Grok EXIF signature scheme. A 64+ char base64 blob after "Signature:"
+# is far beyond any incidental description text, and the UUID Artist makes the
+# pair xAI-specific -- both required keeps the false-positive rate near zero.
+_XAI_SIGNATURE_RE = re.compile(r"Signature:\s*[A-Za-z0-9+/=]{64,}")
+_UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.IGNORECASE)
+
+
+def _is_xai_signature_pair(description: str, artist: str) -> bool:
+    """True if an EXIF (ImageDescription, Artist) pair is xAI/Grok's scheme."""
+    return _XAI_SIGNATURE_RE.match(description) is not None and _UUID_RE.fullmatch(artist) is not None
+
+
+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 ""
+
+
+def xai_signature(image_path: Path) -> bool:
+    """Detect xAI / Grok's EXIF provenance signature scheme.
+
+    Grok image downloads (Aurora model) carry no C2PA, XMP, SynthID, or IPTC --
+    their only provenance signal is a private EXIF pair: ``ImageDescription`` =
+    ``"Signature: <base64>"`` together with ``Artist`` = the image UUID. Verified
+    stable across three independent generations (2026-05-26; see CLAUDE.md). The
+    signature is xAI's and is not locally verifiable (no public key); detection
+    keys on this distinctive, low-false-positive shape, not on the signature's
+    validity. It survives only on the *original* JPEG download -- the web-UI
+    image is a re-encoded WebP that drops EXIF.
+    """
+    try:
+        import piexif
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            exif_bytes = img.info.get("exif")
+        if not exif_bytes:
+            return False
+        tags = piexif.load(exif_bytes).get("0th", {})
+    except Exception as exc:  # unopenable format / malformed EXIF
+        logger.debug("xAI-signature EXIF read failed for %s: %s", image_path, exc)
+        return False
+
+    return _is_xai_signature_pair(
+        _exif_text(tags, piexif.ImageIFD.ImageDescription), _exif_text(tags, piexif.ImageIFD.Artist)
+    )
+
+
+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: ..."
+    + UUID ``Artist``) and (b) any ``Software`` / ``Make`` / ``Artist`` /
+    ``ImageDescription`` tag whose value carries an ``AI_GENERATOR_TOKENS`` token
+    (Ideogram's ``Make``, Firefly's ``Software``, etc.). Mirrors the detection in
+    ``xai_signature`` / ``exif_generator`` so removal scrubs exactly what
+    ``identify`` flags, while leaving genuine camera/editor EXIF intact. Returns
+    the names of the removed tags (for logging).
+    """
+    import piexif
+
+    from remove_ai_watermarks.noai.constants import AI_GENERATOR_TOKENS
+
+    ifd = exif_dict.get("0th")
+    if not ifd:
+        return []
+
+    drop: dict[int, str] = {}
+
+    # (a) xAI / Grok: the Signature blob and the UUID Artist go together.
+    if _is_xai_signature_pair(
+        _exif_text(ifd, piexif.ImageIFD.ImageDescription), _exif_text(ifd, piexif.ImageIFD.Artist)
+    ):
+        drop[piexif.ImageIFD.ImageDescription] = "ImageDescription"
+        drop[piexif.ImageIFD.Artist] = "Artist"
+
+    # (b) Known AI generator token in any of the text tags.
+    for tag, name in (
+        (piexif.ImageIFD.Software, "Software"),
+        (piexif.ImageIFD.Make, "Make"),
+        (piexif.ImageIFD.Artist, "Artist"),
+        (piexif.ImageIFD.ImageDescription, "ImageDescription"),
+    ):
+        if any(token in _exif_text(ifd, tag).lower() for token in AI_GENERATOR_TOKENS):
+            drop[tag] = name
+
+    for tag in drop:
+        ifd.pop(tag, None)
+    return list(drop.values())
 
 
 def get_ai_metadata(image_path: Path) -> dict[str, str]:
@@ -127,21 +651,114 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
     """
     from PIL import Image
 
+    from remove_ai_watermarks.noai.c2pa import extract_c2pa_info, soft_binding_vendors_in, synthid_verdict
+
     result: dict[str, str] = {}
 
-    with Image.open(image_path) as img:
-        for key, value in img.info.items():
-            if _is_ai_key(key):
-                if isinstance(value, bytes):
-                    result[key] = f"<binary {len(value)} bytes>"
-                elif isinstance(value, str) and len(value) > 200:
-                    result[key] = value[:200] + "…"
-                else:
-                    result[key] = str(value)
+    # 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.
+    try:
+        with Image.open(image_path) as img:
+            for key, value in img.info.items():
+                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:
+                        result[key] = value[:200] + "…"
+                    else:
+                        result[key] = str(value)
+    except Exception as exc:
+        logger.debug("PIL could not open %s for AI-metadata scan: %s", image_path, exc)
 
+    # C2PA manifest fields from the single canonical parser (noai/c2pa.py).
+    c2pa = extract_c2pa_info(image_path)
+    for key in (
+        "c2pa_manifest",
+        "claim_generator",
+        "c2pa_spec",
+        "issuer",
+        "source_type",
+        "actions",
+        "synthid_watermark",
+        "soft_binding",
+    ):
+        if key in c2pa:
+            result.setdefault(key, str(c2pa[key]))
+
+    # Non-PNG containers (JPEG/WebP/AVIF/MP4): extract_c2pa_info is PNG-only, so
+    # fall back to the format-agnostic source check for the SynthID verdict and
+    # the soft-binding (forensic-watermark vendor) scan.
+    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:
+        head = scan_head(image_path)
+        if vendors := soft_binding_vendors_in(head):
+            result["soft_binding"] = ", ".join(vendors)
+
+    # China TC260 AI-content label (Doubao and other China-served generators).
+    if aigc := aigc_label(image_path):
+        producer = aigc.get("ContentProducer", "")
+        result["aigc_label"] = f"China AIGC label (TC260){f'; producer {producer}' if producer else ''}"
+
+    # xAI / Grok EXIF signature scheme (its only provenance signal).
+    if xai_signature(image_path):
+        result.setdefault("xai_signature", "xAI/Grok EXIF signature (Artist UUID + Signature blob)")
+
+    # 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
 
 
+def _strip_with_ffmpeg(source_path: Path, output_path: Path) -> Path:
+    """Strip container metadata from a non-ISOBMFF audio/video file via ffmpeg.
+
+    Uses a lossless stream copy (``-c copy``), so codec data is untouched and only
+    container-level tags/chapters are dropped -- the metadata strip for WebM /
+    Matroska (EBML), MP3 (ID3), WAV / FLAC / OGG (RIFF / Vorbis comments) that the
+    ISOBMFF box walker cannot reach. Requires ffmpeg on PATH (raises if absent).
+    The output extension should match the source so ``-c copy`` can re-mux.
+    """
+    import shutil
+    import subprocess
+
+    ffmpeg = shutil.which("ffmpeg")
+    if ffmpeg is None:
+        raise RuntimeError(
+            f"ffmpeg is required to strip metadata from {source_path.suffix} files but was not found on "
+            "PATH; install ffmpeg (e.g. `brew install ffmpeg`) or re-encode the file with another tool"
+        )
+    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",
+        str(output_path),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)  # noqa: S603
+    if result.returncode != 0:
+        raise RuntimeError(f"ffmpeg failed to strip metadata from {source_path}: {result.stderr.strip()[:300]}")
+    logger.info("Stripped container metadata via ffmpeg -> %s", output_path)
+    return output_path
+
+
 def remove_ai_metadata(
     source_path: Path,
     output_path: Path | None = None,
@@ -167,16 +784,61 @@ def remove_ai_metadata(
     if output_path is None:
         output_path = source_path
 
+    # ISOBMFF containers (AVIF/HEIF/JPEG-XL images, MP4/MOV/M4V video, M4A audio):
+    # strip C2PA + AI-label boxes at the container level without re-encoding.
+    # Avoids needing PIL plugins (pillow-heif / pillow-jxl) and preserves the
+    # 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 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), 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
+    # box walker can't reach these, so strip container metadata losslessly via
+    # ffmpeg (-c copy -- codec data untouched, only tags/chapters dropped).
+    if source_path.suffix.lower() in _FFMPEG_STRIP_EXTS:
+        return _strip_with_ffmpeg(source_path, output_path)
+
     # Read image and filter metadata
     with Image.open(source_path) as img:
         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"
 
@@ -185,6 +847,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":
@@ -205,6 +869,10 @@ def remove_ai_metadata(
             save_kwargs["pnginfo"] = pnginfo
 
         if exif_data and save_kwargs["format"] == "JPEG":
+            # Scrub AI-provenance EXIF tags (xAI/Grok signature, generator tokens)
+            # while keeping genuine camera/editor EXIF; PNG output drops EXIF entirely.
+            if removed := _scrub_ai_exif(exif_data):
+                logger.info("Scrubbed AI EXIF tag(s): %s", ", ".join(removed))
             with contextlib.suppress(Exception):
                 save_kwargs["exif"] = piexif.dump(exif_data)
 

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

@@ -28,7 +28,9 @@ from remove_ai_watermarks.noai.constants import (
     C2PA_CHUNK_TYPE,
     C2PA_ISSUERS,
     C2PA_SIGNATURES,
+    C2PA_SOFT_BINDINGS,
     PNG_SIGNATURE,
+    SYNTHID_C2PA_ISSUERS,
 )
 
 
@@ -53,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:
@@ -60,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:
@@ -72,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
@@ -106,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:
@@ -113,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
@@ -129,10 +143,68 @@ def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
     return c2pa_info
 
 
+def cbor_text_after(payload: bytes, key: bytes) -> str | None:
+    """Return the CBOR text-string immediately following ``key`` in ``payload``.
+
+    Handles CBOR major-type 3 length prefixes: direct (0x60-0x77), 1-byte
+    (0x78 NN), and 2-byte (0x79 NN NN). This reads the actual encoded value, so
+    it avoids the byte-grabbing artifacts a loose regex produces (e.g. the
+    leading length byte showing up as ``fGPT-4o``).
+    """
+    idx = payload.find(key)
+    if idx < 0:
+        return None
+    p = idx + len(key)
+    if p >= len(payload):
+        return None
+    head = payload[p]
+    if 0x60 <= head <= 0x77:
+        length, start = head - 0x60, p + 1
+    elif head == 0x78 and p + 1 < len(payload):
+        length, start = payload[p + 1], p + 2
+    elif head == 0x79 and p + 2 < len(payload):
+        length, start = (payload[p + 1] << 8) | payload[p + 2], p + 3
+    else:
+        return None
+    raw_str = payload[start : start + length]
+    try:
+        return raw_str.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw_str.decode("latin1", errors="replace")
+
+
+def synthid_verdict(vendors: str) -> str:
+    """Human-readable SynthID-source verdict, shared by all callers."""
+    return f"likely present ({vendors} embeds SynthID with C2PA)"
+
+
+def synthid_vendors_in(buffer: bytes) -> list[str]:
+    """Return SynthID-using C2PA issuer names whose signature appears in ``buffer``.
+
+    Shared by the PNG caBX parser and the format-agnostic binary scan so both
+    apply the same SYNTHID_C2PA_ISSUERS rule against their respective bytes.
+    """
+    return sorted({name for sig, name in C2PA_ISSUERS.items() if sig in buffer and sig in SYNTHID_C2PA_ISSUERS})
+
+
+def soft_binding_vendors_in(buffer: bytes) -> list[str]:
+    """Return forensic-watermark vendor names whose C2PA soft-binding ``alg``
+    identifier appears in ``buffer``.
+
+    A ``c2pa.soft-binding`` assertion names the watermark scheme that stamped the
+    pixels (Adobe TrustMark, Digimarc, Imatag, Steg.AI, ...). Shared by the PNG
+    caBX parser and the format-agnostic binary scan so both apply the same
+    C2PA_SOFT_BINDINGS rule against their respective bytes.
+    """
+    return sorted({name for sig, name in C2PA_SOFT_BINDINGS.items() if sig in buffer})
+
+
 def _parse_c2pa_chunk(chunk_data: bytes, c2pa_info: dict[str, Any]) -> None:
     """Parse C2PA chunk data and populate info dictionary."""
+    c2pa_info["c2pa_manifest"] = f"C2PA manifest ({len(chunk_data)} bytes)"
+
     # Find issuers
-    issuers = []
+    issuers: list[str] = []
     for sig, name in C2PA_ISSUERS.items():
         if sig in chunk_data:
             issuers.append(name)
@@ -140,44 +212,25 @@ def _parse_c2pa_chunk(chunk_data: bytes, c2pa_info: dict[str, Any]) -> None:
         c2pa_info["issuer"] = ", ".join(set(issuers))
 
     # Find AI tools
-    ai_tools = []
+    ai_tools: list[str] = []
     for sig, name in C2PA_AI_TOOLS.items():
         if sig in chunk_data:
             ai_tools.append(name)
     if ai_tools:
         c2pa_info["ai_tool"] = ", ".join(set(ai_tools))
 
-    # Extract software agent (multiple patterns)
-    patterns = [
-        rb"softwareAgent.*?dname([^\x00]+?)(?:q|l|m|n)",
-        rb"software_agent[^\x00]*?([A-Za-z0-9_\-\.]+)",
-        rb"Software[^\x00]*?([A-Za-z0-9_\-\. ]+)",
-    ]
-    for pattern in patterns:
-        match = re.search(pattern, chunk_data, re.DOTALL | re.IGNORECASE)
-        if match:
-            agent = match.group(1).decode("utf-8", errors="ignore").strip()
-            if agent and len(agent) < 100:
-                c2pa_info["software_agent"] = agent
-                break
-
-    # Extract claim generator (multiple patterns)
-    claim_patterns = [
-        rb"claim_generator[^\x00]*?([A-Za-z0-9_\-\.\/\:]+)",
-        rb"claimGenerator[^\x00]*?([A-Za-z0-9_\-\.\/\:]+)",
-        rb"dname([^\x00]{3,50})(?:q|l|m|n|i)",
-    ]
-    for pattern in claim_patterns:
-        match = re.search(pattern, chunk_data, re.DOTALL | re.IGNORECASE)
-        if match:
-            gen_name = match.group(1).decode("utf-8", errors="ignore").strip()
-            # Filter out common false positives
-            if gen_name and len(gen_name) < 100 and not gen_name.startswith(("\\x", "\\\\x")):
-                c2pa_info["claim_generator"] = gen_name
-                break
+    # Claim generator and spec version: read the CBOR text-string values
+    # directly (regex byte-grabbing produced artifacts like ``fGPT-4o``).
+    # Guard with isprintable(): on some manifests (e.g. Microsoft Designer) the
+    # first ``name`` key precedes a binary field (a hash), not the generator
+    # string, which would otherwise surface as control-char garbage.
+    if (generator := cbor_text_after(chunk_data, b"name")) and generator.isprintable():
+        c2pa_info["claim_generator"] = generator
+    if (spec := cbor_text_after(chunk_data, b"specVersion")) and spec.isprintable():
+        c2pa_info["c2pa_spec"] = spec
 
     # Find actions
-    actions = []
+    actions: list[str] = []
     for sig, name in C2PA_ACTIONS.items():
         if sig in chunk_data:
             actions.append(name)
@@ -192,12 +245,30 @@ def _parse_c2pa_chunk(chunk_data: bytes, c2pa_info: dict[str, Any]) -> None:
             c2pa_info["timestamps"] = [t.decode("utf-8") for t in timestamp_matches[:3]]
 
     # Find digital source type
+    ai_source = False
     if b"trainedAlgorithmicMedia" in chunk_data:
         c2pa_info["source_type"] = "trainedAlgorithmicMedia (AI-generated)"
+        ai_source = True
     elif b"algorithmicMedia" in chunk_data:
         c2pa_info["source_type"] = "algorithmicMedia"
     elif b"compositeWithTrainedAlgorithmicMedia" in chunk_data:
         c2pa_info["source_type"] = "compositeWithTrainedAlgorithmicMedia (AI-enhanced)"
+        ai_source = True
+
+    # SynthID pixel-watermark proxy: a C2PA manifest from a SynthID-using
+    # vendor (Google/OpenAI) on AI-generated content implies an invisible
+    # SynthID watermark in the pixels (see SYNTHID_C2PA_ISSUERS).
+    synthid_vendors = synthid_vendors_in(chunk_data)
+    if synthid_vendors and ai_source:
+        c2pa_info["synthid_vendors"] = synthid_vendors
+        c2pa_info["synthid_watermark"] = synthid_verdict(", ".join(synthid_vendors))
+
+    # Soft-binding: a forensic/third-party watermark vendor named in the
+    # manifest (Adobe TrustMark, Digimarc, ...), independent of the issuer.
+    soft_binding_vendors = soft_binding_vendors_in(chunk_data)
+    if soft_binding_vendors:
+        c2pa_info["soft_binding_vendors"] = soft_binding_vendors
+        c2pa_info["soft_binding"] = ", ".join(soft_binding_vendors)
 
 
 def extract_c2pa_chunk(image_path: Path) -> bytes | None:
@@ -219,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:
@@ -226,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
@@ -240,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

@@ -85,8 +85,40 @@ C2PA_ISSUERS = {
     b"Microsoft": "Microsoft",
     b"OpenAI": "OpenAI",
     b"Truepic": "Truepic",
+    # 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",
+    # 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.
+    b"Black Forest Labs": "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.
+    b"volcengine": "ByteDance (Volcano Engine)",
 }
 
+# C2PA issuers whose signed outputs also carry an invisible SynthID pixel
+# watermark -- a metadata proxy for "SynthID is in the pixels":
+#   - Google (Imagen/Gemini): embeds SynthID, long-standing (DeepMind docs).
+#   - OpenAI (ChatGPT/Codex/API): pairs SynthID with C2PA since ~2026-05-20.
+#     Confirmed by OpenAI's Help Center ("C2PA and SynthID in OpenAI-generated
+#     images", updated 2026-05-21): "Images generated with ChatGPT, Codex, and
+#     our API include both C2PA metadata and SynthID watermarks." OpenAI also
+#     notes a signal may be absent if "the image was created before these
+#     signals were available" -- so OpenAI images from BEFORE the rollout carry
+#     C2PA WITHOUT SynthID (e.g. data/samples/openai-images-2/amur-leopard.png,
+#     C2PA timestamp 2026-04-22). For OpenAI the proxy is therefore "likely",
+#     not certain; the verdict string is hedged accordingly. OpenAI's own oracle
+#     is openai.com/verify (Google's is the Gemini app "Verify with SynthID").
+# The issuer byte ("OpenAI"/"Google") is verified locally against data/samples;
+# the SynthID pairing is documented behavior (Google: DeepMind; OpenAI: above).
+# Adobe Firefly and Microsoft Designer sign C2PA but do NOT use SynthID, so a
+# 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"})
+
 # C2PA known AI tools
 C2PA_AI_TOOLS = {
     b"GPT-4o": "GPT-4o",
@@ -98,6 +130,61 @@ C2PA_AI_TOOLS = {
     b"Firefly": "Firefly",
 }
 
+# C2PA ``c2pa.soft-binding`` algorithm identifiers -> the forensic-watermark
+# vendor that stamped the pixels. The manifest's ``alg`` field names the
+# watermark scheme even when the watermark itself cannot be decoded locally, so
+# a byte-scan for these (keyed on a distinctive prefix to catch all variants)
+# tells us a third-party forensic watermark is present and whose. Verified
+# against the official C2PA registry (github.com/c2pa-org/softbinding-algorithm-list).
+# Adobe TrustMark is additionally decodable locally (see ``trustmark_detector``);
+# the rest (Digimarc, Imatag, Steg.AI, etc.) are proprietary oracle-only decoders.
+C2PA_SOFT_BINDINGS = {
+    b"com.adobe.trustmark": "Adobe TrustMark",
+    b"com.adobe.icn": "Adobe (content fingerprint)",
+    b"com.digimarc": "Digimarc",
+    b"com.imatag.lamark": "Imatag (Lamark)",
+    b"ai.steg": "Steg.AI",
+    b"com.microsoft.invismark": "Microsoft InvisMark",
+    b"com.microsoft.wavmark": "Microsoft WavMark",
+    b"com.verimatrix": "Verimatrix",
+    b"com.nagra.nexguard": "NAGRA NexGuard",
+    b"com.aiwatermark": "AIWatermark (Meta PixelSeal)",
+    b"ai.trufo": "Trufo",
+    b"app.overlai": "Overlai",
+    b"com.markany": "MarkAny",
+    b"com.mentaport": "Mentaport",
+    b"es.lumatrace": "LumaTrace",
+    b"ai.verda": "VerdaAI",
+    b"ai.contentlens": "ContentLens",
+    b"io.iscc": "ISCC (content code)",
+}
+
+# Lowercased substrings that mark an AI generator when found in an EXIF
+# ``Software`` / XMP ``CreatorTool`` value. Conservative on purpose: plain
+# editors like "Adobe Photoshop" or "GIMP" must NOT match (no AI token), so only
+# generator names land here. Add new generators here, not inline.
+AI_GENERATOR_TOKENS: frozenset[str] = frozenset(
+    {
+        "firefly",
+        "dall-e",
+        "dalle",
+        "midjourney",
+        "stable diffusion",
+        "stable-diffusion",
+        "stablediffusion",
+        "comfyui",
+        "automatic1111",
+        "invokeai",
+        "imagen",
+        "gpt-image",
+        "nightcafe",
+        "ideogram",
+        "leonardo",
+        "flux",
+        "dreamstudio",
+    }
+)
+
 # C2PA action types
 C2PA_ACTIONS = {
     b"c2pa.created": "created",
@@ -106,6 +193,8 @@ C2PA_ACTIONS = {
     b"c2pa.filtered": "filtered",
     b"c2pa.cropped": "cropped",
     b"c2pa.resized": "resized",
+    b"c2pa.opened": "opened",
+    b"c2pa.placed": "placed",
 }
 
 # PNG signature

src/remove_ai_watermarks/noai/ctrlregen/engine.py

@@ -36,9 +36,10 @@ _HAS_COLOR_MATCHER = False
 _HAS_DIFFUSERS = False
 
 try:
-    from ctrlregen.pipeline import CustomCtrlRegenPipeline
     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]
@@ -54,7 +55,7 @@ except ImportError:
     CannyDetector = None  # type: ignore[assignment,misc]
 
 try:
-    from ctrlregen.color import color_match
+    from remove_ai_watermarks.noai.ctrlregen.color import color_match
 
     _HAS_COLOR_MATCHER = True
 except ImportError:
@@ -239,7 +240,7 @@ class CtrlRegenEngine:
         needs_tiling = orig_w > TILE_SIZE or orig_h > TILE_SIZE
 
         if needs_tiling:
-            from ctrlregen.tiling import resize_center_crop, run_tiled
+            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
@@ -264,7 +265,7 @@ class CtrlRegenEngine:
                 ip_adapter_image=orig_image,
             )
         else:
-            from ctrlregen.tiling import resize_center_crop
+            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")

src/remove_ai_watermarks/noai/ctrlregen/tiling.py

@@ -20,6 +20,8 @@ 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 not (0 <= overlap < tile):
+        raise ValueError(f"overlap must satisfy 0 <= overlap < tile (got overlap={overlap}, tile={tile})")
     if total <= tile:
         return [0]
     n = max(2, math.ceil((total - overlap) / (tile - overlap)))

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

@@ -121,6 +121,96 @@ def run_img2img_with_mps_fallback(
         raise
 
 
+def run_differential(
+    pipeline: Any,
+    image: Image.Image,
+    change_map: Any,
+    strength: float,
+    num_inference_steps: int,
+    guidance_scale: float,
+    generator: Any,
+    device: str,
+    set_progress: Callable[[str], None],
+) -> Image.Image:
+    """Run the SDXL Differential-Diffusion pipeline and return the image.
+
+    Unlike standard img2img, the differential pipeline needs pre-processed image
+    tensors plus a per-pixel change map (HxW float32 in [0, 1]); white preserves
+    the original pixels, black regenerates them. Runs without a step callback --
+    the community pipeline's callback signature differs across diffusers
+    versions, and a protect-text pass is short.
+    """
+    import torch
+
+    image_tensor = pipeline.image_processor.preprocess(image).to(device)
+    map_tensor = torch.from_numpy(change_map)[None].to(device)  # pyright: ignore[reportPrivateImportUsage, reportUnknownMemberType]
+    set_progress(f"Running protected regeneration ({device}, strength={strength})...")
+    result = pipeline(
+        prompt="",
+        image=image_tensor,
+        original_image=image_tensor,
+        map=map_tensor,
+        strength=strength,
+        num_inference_steps=num_inference_steps,
+        guidance_scale=guidance_scale,
+        generator=generator,
+    )
+    return result.images[0]
+
+
+def run_differential_with_mps_fallback(
+    load_pipeline: Callable[[], Any],
+    image: Image.Image,
+    change_map: Any,
+    strength: float,
+    num_inference_steps: int,
+    guidance_scale: float,
+    generator: Any,
+    device: str,
+    set_progress: Callable[[str], None],
+    *,
+    reload_on_cpu: Callable[[], Any],
+) -> tuple[Image.Image, str]:
+    """Run differential img2img; on MPS error, fall back to CPU.
+
+    Returns:
+        (result_image, final_device) -- device may change to ``"cpu"`` on fallback.
+    """
+    pipeline = load_pipeline()
+    try:
+        img = run_differential(
+            pipeline,
+            image,
+            change_map,
+            strength,
+            num_inference_steps,
+            guidance_scale,
+            generator,
+            device,
+            set_progress,
+        )
+        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()
+            pipeline = reload_on_cpu()
+            img = run_differential(
+                pipeline,
+                image,
+                change_map,
+                strength,
+                num_inference_steps,
+                guidance_scale,
+                None,
+                "cpu",
+                set_progress,
+            )
+            return img, "cpu"
+        raise
+
+
 def _call_pipeline(
     pipeline: Any,
     image: Image.Image,

src/remove_ai_watermarks/noai/isobmff.py

@@ -0,0 +1,225 @@
+"""Minimal ISOBMFF box walker for stripping C2PA from AVIF / HEIF / MP4 / JPEG-XL.
+
+The ISO Base Media File Format wraps content in nested ``[size:4][type:4][...]``
+boxes. C2PA stores its manifest in a top-level ``uuid`` box keyed by the
+C2PA UUID; JPEG-XL uses a ``jumb`` box (JUMBF) instead. To strip provenance
+without re-encoding the image, we walk the top-level box list, drop boxes that
+carry C2PA, and emit the rest verbatim. The codestream (``mdat`` for ISOBMFF,
+``jxlc`` / ``jxlp`` for JPEG-XL) is untouched, so pixel data is preserved
+bit-for-bit.
+
+This file intentionally avoids dependencies on format-specific libraries
+(pillow-heif, pillow-jxl, pymp4) so it works on systems where they aren't
+installed.
+
+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,
+    C2PA_UUID,
+    IPTC_AI_FIELD_MARKERS,
+    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).
+C2PA_BOX_TYPES: frozenset[bytes] = frozenset({b"uuid", b"jumb"})
+
+# AI-label byte markers (TC260 AIGC, IPTC "Made with AI", IPTC 2025.1 AI fields)
+# whose presence inside an XMP ``uuid`` box means the box carries an AI label.
+# Matching the payload rather than a fixed XMP UUID avoids the XMP-box UUID
+# byte-order ambiguity and stays surgical: only AI-bearing XMP is dropped, plain
+# 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.
+
+    Handles all three ISOBMFF box-size encodings:
+    - ``size > 1``: 32-bit size field is the total box length.
+    - ``size == 1``: 64-bit ``largesize`` follows after the type field.
+    - ``size == 0``: box runs to end of file.
+    """
+    pos = 0
+    n = len(data)
+    while pos + 8 <= n:
+        size32 = struct.unpack_from(">I", data, pos)[0]
+        box_type = data[pos + 4 : pos + 8]
+        if size32 == 1:
+            if pos + 16 > n:
+                return
+            size = struct.unpack_from(">Q", data, pos + 8)[0]
+            payload_off = pos + 16
+        elif size32 == 0:
+            size = n - pos
+            payload_off = pos + 8
+        else:
+            size = size32
+            payload_off = pos + 8
+        if size < (payload_off - pos) or pos + size > n:
+            return
+        yield pos, pos + size, box_type, payload_off
+        pos += size
+
+
+def is_isobmff(data: bytes) -> bool:
+    """Cheap sniff: ISOBMFF files start with an ``ftyp`` box."""
+    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.
+
+    Walks top-level boxes and drops:
+    - any ``uuid`` box whose UUID equals ``C2PA_UUID`` (a C2PA manifest);
+    - any ``uuid`` box whose payload carries an AI-label marker (an XMP packet
+      with a TC260 / IPTC / IPTC-2025.1 AI field -- caught by content, not by the
+      XMP UUID, so it works regardless of the UUID's byte order, and leaves plain
+      non-AI XMP intact);
+    - any ``jumb`` box (JPEG-XL JUMBF container).
+
+    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: 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
+            has_ai_label = any(marker in data[payload_off:end] for marker in _AI_LABEL_MARKERS)
+            if is_c2pa or has_ai_label:
+                stripped += 1
+                continue
+        elif box_type == b"jumb":
+            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,19 +1,69 @@
-"""Watermark removal model profiles, strength presets, and profile detection.
+"""Watermark removal model profiles, the default strength, and profile detection.
 
 Pure configuration and lookup functions with no ML dependencies.
 """
 
 from __future__ import annotations
 
-DEFAULT_MODEL_ID = "Lykon/dreamshaper-8"
+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
+# Single default denoising strength for the SDXL img2img scrub, overridable from
+# the CLI (`--strength`). Raised 0.10 -> 0.30 after an oracle-verified GPU strength
+# study (2026-05-31, Modal A100, native res, Gemini-app "Verify with SynthID", n=3
+# FRESH Gemini images + protect_text/faces OFF): the CURRENT Google SynthID survives
+# 0.10/0.15/0.2 and is only REMOVED at 0.3 (0.3 is the threshold; 0.2 still present).
+# This supersedes the earlier n=1 "0.10 removes it" note, which is now stale -- Google
+# has hardened SynthID and the threshold has climbed 0.05 -> 0.10 -> ~0.3 over time, so
+# treat this as a moving target and re-test against fresh Gemini output periodically.
+# Cost of 0.3: SSIM ~0.97 vs original (modest), but fine/dense typography softens, and
+# it is OVERKILL for non-SynthID sources (OpenAI/ChatGPT carry C2PA, not Google SynthID
+# -- 0.10 is plenty there). protect_text is RECOMMENDED ON for SynthID removal (A/B
+# verified 2026-05-31): SynthID is GLOBAL, so 0.3 clears it whether protection is on or
+# off, and protection salvages medium-text fidelity (~3x runtime); only the very finest
+# text still softens at 0.3. (An earlier comment claimed protect_text shields the
+# watermark -- that was wrong, it mistook the 0.10 strength failure for a protection
+# effect.) The only true tension is the finest typography softening at this aggressive
+# strength. (Fixed LOW/MEDIUM/HIGH presets were removed -- the one knob is this default
+# plus the per-call override.)
+DEFAULT_STRENGTH = 0.30
 
-_HIGH_PERTURBATION = ("stegasamp", "stegastamp", "treering", "ringid")
-_LOW_PERTURBATION = ("stablesignature", "dwtectsvd", "rivagan", "ssl", "hidden")
+# CtrlRegen removes watermarks by regenerating from (near) clean Gaussian noise,
+# NOT by the light-touch partial-noise img2img the SDXL default uses. The research
+# is explicit (CtrlRegen, ICLR 2025, arXiv:2410.05470): partial-noise regeneration
+# "struggles with high-perturbation watermarks" because a small noise step "retains"
+# watermark information that diffuses back into the output; the fix is to start from
+# clean noise. With the StableDiffusionControlNetImg2ImgPipeline that maps to a high
+# strength (~1.0 = full noise at the first timestep, structure held by the canny
+# ControlNet + DINOv2 IP-Adapter, not by the watermarked latent). So the ctrlregen
+# profile must NOT inherit the SDXL default (`DEFAULT_STRENGTH`, a partial-noise
+# value) -- at that low strength it loads ControlNet + DINOv2-giant and then barely
+# changes the image (a no-op for removal). Tunable via
+# `--strength`; lower it to trade removal strength for fidelity (the CtrlRegen+ regime).
+#
+# EXPERIMENTAL -- NOT recommended for production. The same GPU study that set the 0.3
+# SDXL threshold tested ctrlregen at its clean-noise strength and found it DESTROYS
+# images: smooth/background regions fill with hallucinated micro-text garbage, and it
+# is heavy (~8.5 min / ~$0.30 vs ~25 s / ~$0.02 for SDXL on a large image). The pipeline
+# is effectively binary -- low strength = no-op, high strength = destroys -- with no
+# usable middle, so the literature's "clean-noise is the lever" (arXiv:2410.05470) did
+# NOT survive empirical testing on real content. SDXL img2img at ~0.3 is the shippable
+# path; ctrlregen stays opt-in and flagged experimental.
+CTRLREGEN_DEFAULT_STRENGTH = 1.0
+
+
+def resolve_strength(strength: float | None, profile: str) -> float:
+    """Resolve the denoising strength, applying the profile-specific default when unset.
+
+    ``None`` means "the user did not pass ``--strength``": the SDXL default profile
+    resolves to ``DEFAULT_STRENGTH`` (the SynthID-removal default, ~0.3), while
+    ``ctrlregen`` resolves to ``CTRLREGEN_DEFAULT_STRENGTH`` (clean-noise regeneration).
+    An explicit value always wins. Shared by the CLI (for display) and the engine (for
+    execution) so the two never disagree.
+    """
+    if strength is not None:
+        return strength
+    return CTRLREGEN_DEFAULT_STRENGTH if profile == "ctrlregen" else DEFAULT_STRENGTH
 
 
 def get_model_id_for_profile(profile: str) -> str:
@@ -31,21 +81,3 @@ def detect_model_profile(model_id: str) -> str:
     if "ctrlregen" in model_id.lower():
         return "ctrlregen"
     return "default"
-
-
-def get_recommended_strength(watermark_type: str) -> float:
-    """Get recommended strength for different watermark types.
-
-    Args:
-        watermark_type: Type of watermark. One of: 'low', 'medium', 'high',
-                        or specific names like 'stegastamp', 'treering', etc.
-
-    Returns:
-        Recommended strength value.
-    """
-    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

src/remove_ai_watermarks/noai/watermark_remover.py

@@ -10,6 +10,9 @@ This module implements a simple regeneration attack that:
 4. Decodes back to pixel space
 """
 
+# 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
@@ -28,10 +31,9 @@ from PIL import Image
 from remove_ai_watermarks.noai.watermark_profiles import (
     CTRLREGEN_MODEL_ID,
     DEFAULT_MODEL_ID,
-    HIGH_STRENGTH,
-    LOW_STRENGTH,
-    MEDIUM_STRENGTH,
+    DEFAULT_STRENGTH,
     detect_model_profile,
+    resolve_strength,
 )
 
 logger = logging.getLogger(__name__)
@@ -60,6 +62,24 @@ 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
+
+
 _CUDA_FIX_ENV_KEY = "NOAI_CUDA_FIXED"
 
 
@@ -176,8 +196,11 @@ def _reinstall_torch_cuda_and_restart() -> None:
         return
 
     os.environ[_CUDA_FIX_ENV_KEY] = "1"
-    restart_code = f"import sys; sys.argv = {sys.argv!r}; from remove_ai_watermarks.cli import main; sys.exit(main())"
-    os.execl(sys.executable, sys.executable, "-c", restart_code)
+    # Re-exec via ``-m`` rather than building a ``-c`` string from repr(sys.argv).
+    # ``-m`` makes Python set argv[0] to the module path, so forward only the
+    # actual args (sys.argv[1:]); passing the full argv would re-inject the
+    # program name as a spurious first argument to Click.
+    os.execv(sys.executable, [sys.executable, "-m", "remove_ai_watermarks.cli", *sys.argv[1:]])
 
 
 def _ensure_watermark_deps() -> None:
@@ -216,6 +239,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():
@@ -223,23 +259,48 @@ def get_device() -> str:
     return "cpu"
 
 
+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
+
+
+def _generator_device(generator: Any) -> str:
+    """Best-effort device type of a ``torch.Generator`` (e.g. ``"cpu"``, ``"mps"``)."""
+    device = getattr(generator, "device", None)
+    return getattr(device, "type", str(device)) if device is not None else "cpu"
+
+
 # Keep legacy name available for backwards compatibility
 _detect_model_profile_from_id = detect_model_profile
 
+# SDXL Differential-Diffusion community pipeline, pinned to the installed
+# diffusers version so the fetched pipeline code matches the library (see #21).
+# Diffusers' dynamic-module loader resolves ``custom_revision`` against the
+# package version string (``0.38.0``), NOT the GitHub git tag (``v0.38.0``).
+_DIFF_PIPELINE_NAME = "pipeline_stable_diffusion_xl_differential_img2img"
+_DIFF_PIPELINE_REVISION = "0.38.0"
+
 
 class WatermarkRemover:
     """Remove watermarks from images using diffusion model regeneration.
 
     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
 
     def __init__(
         self,
@@ -257,8 +318,8 @@ class WatermarkRemover:
         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
@@ -268,6 +329,7 @@ class WatermarkRemover:
             self.torch_dtype = torch_dtype
 
         self._pipeline: AutoImg2ImgPipeline | None = None
+        self._diff_pipeline: Any = None
         self._ctrlregen_engine: Any = None
         self._progress_callback = progress_callback
         self.hf_token: str | None = hf_token or os.environ.get("HF_TOKEN")
@@ -333,6 +395,14 @@ class WatermarkRemover:
             if self.hf_token:
                 load_kwargs["token"] = self.hf_token
 
+            # Avoid the SDXL fp16 NaN/all-black decode (issue #29) by loading the
+            # fp16-fixed VAE for the default SDXL checkpoint on a fp16 GPU.
+            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)
+
             self._pipeline = AutoImg2ImgPipeline.from_pretrained(  # type: ignore
                 self.model_id,
                 **load_kwargs,
@@ -376,6 +446,7 @@ class WatermarkRemover:
         num_inference_steps: int = 50,
         guidance_scale: float | None = None,
         seed: int | None = None,
+        protect_text: bool = True,
     ) -> Path:
         """Remove watermark from an image using regeneration attack.
 
@@ -386,6 +457,10 @@ class WatermarkRemover:
             num_inference_steps: Number of denoising steps.
             guidance_scale: Classifier-free guidance scale.
             seed: Random seed for reproducibility.
+            protect_text: Detect text regions and preserve them via Differential
+                Diffusion when any are found (SDXL default profile only). On by
+                default; the detector decides per image, and text-free inputs run
+                the standard pass at no extra cost.
 
         Returns:
             Path to the cleaned image.
@@ -400,7 +475,7 @@ class WatermarkRemover:
         if output_path is None:
             output_path = image_path
 
-        strength = strength or self.LOW_STRENGTH
+        strength = resolve_strength(strength, self.model_profile)
 
         if not 0.0 <= strength <= 1.0:
             raise ValueError(f"Strength must be between 0.0 and 1.0, got {strength}")
@@ -416,7 +491,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(
@@ -434,7 +509,21 @@ class WatermarkRemover:
                 guidance_scale,
                 generator,
             )
+        elif protect_text and self._can_protect_text():
+            cleaned_image = self._run_region_hires(
+                init_image,
+                strength,
+                num_inference_steps,
+                guidance_scale,
+                generator,
+            )
         else:
+            if protect_text:
+                logger.debug(
+                    "Text protection unavailable "
+                    "(needs the SDXL default model and the cv2 text detector); "
+                    "running standard img2img."
+                )
             cleaned_image = self._run_img2img(
                 init_image,
                 strength,
@@ -517,6 +606,196 @@ class WatermarkRemover:
         self._pipeline = None
         return self._load_pipeline()
 
+    # ── Text-protected differential runner ───────────────────────────
+
+    def _can_protect_text(self) -> bool:
+        """True when text protection can run: SDXL default model + cv2 detector."""
+        from remove_ai_watermarks import text_protector
+
+        return self.model_id == self.DEFAULT_MODEL_ID and text_protector.is_available()
+
+    def _load_differential_pipeline(self) -> Any:
+        """Load the SDXL Differential-Diffusion community pipeline lazily."""
+        if self._diff_pipeline is None:
+            from diffusers import DiffusionPipeline
+
+            self._set_progress("Loading Differential-Diffusion pipeline (protect-text)...")
+            use_fp16 = self.device in {"mps", "cuda", "xpu"}
+            load_kwargs: dict[str, Any] = {
+                "custom_pipeline": _DIFF_PIPELINE_NAME,
+                "custom_revision": _DIFF_PIPELINE_REVISION,
+                "torch_dtype": torch.float16 if use_fp16 else torch.float32,  # type: ignore[attr-defined]
+                "use_safetensors": True,
+            }
+            if use_fp16:
+                load_kwargs["variant"] = "fp16"
+            if self.hf_token:
+                load_kwargs["token"] = self.hf_token
+
+            pipeline = DiffusionPipeline.from_pretrained(self.model_id, **load_kwargs).to(self.device)
+            # The differential pipeline upcasts the SDXL VAE to fp32 internally
+            # (the fp16 VAE decodes to NaN/black otherwise), so we add no extra
+            # VAE handling here. Attention slicing is also left off on MPS: it
+            # produced NaN latents with this pipeline, and the protect-text pass
+            # is short enough not to need it.
+            with contextlib.suppress(Exception):
+                pipeline.set_progress_bar_config(disable=True)
+            self._diff_pipeline = pipeline
+        return self._diff_pipeline
+
+    def _reload_differential_on_cpu(self) -> Any:
+        """Reload the differential pipeline on CPU after an MPS failure."""
+        self.device = "cpu"
+        self.torch_dtype = torch.float32  # type: ignore[assignment]
+        self._diff_pipeline = None
+        return self._load_differential_pipeline()
+
+    # Region high-res text scrub: defaults tuned so each text block is upscaled
+    # enough that strokes exceed the VAE's ~8px latent cell, capped so a single
+    # region never blows past the GPU/MPS memory budget.
+    _REGION_HIRES_SCALE = 3.0
+    _REGION_MAX_MEGAPIXELS = 1.3
+
+    def _run_region_hires(
+        self,
+        init_image: Image.Image,
+        strength: float,
+        num_inference_steps: int,
+        guidance_scale: float,
+        generator: Any,
+    ) -> Image.Image:
+        """Scrub the whole image, then RE-scrub each detected text block at high
+        resolution and composite it back.
+
+        Unlike the Differential-Diffusion path (which freezes text in latent space
+        and so leaves the watermark intact there), every pixel here is regenerated
+        -- the watermark is removed everywhere. Small text survives because each
+        text block is upscaled before its img2img pass, so strokes span more than
+        one VAE latent cell (the ~8px floor that softens text at native scale);
+        the scrubbed crop is downscaled and feather-composited back. Falls back to
+        the plain global scrub when no text is detected.
+        """
+        import math
+
+        import cv2
+        import numpy as np
+
+        from remove_ai_watermarks import text_protector
+
+        base = self._run_img2img(init_image, strength, num_inference_steps, guidance_scale, generator)
+
+        # The base pass may have fallen back from MPS to CPU (it flips
+        # self.device). The generator was built for the original device, and
+        # diffusers rejects a device-mismatched generator ("Expected a 'cpu'
+        # device generator but found 'mps'"), so drop it for the per-region
+        # passes -- they then seed from the global RNG, which is fine here.
+        if generator is not None and self.device == "cpu" and _generator_device(generator) != "cpu":
+            generator = None
+
+        bgr = cv2.cvtColor(np.array(init_image), cv2.COLOR_RGB2BGR)
+        try:
+            boxes = text_protector.TextProtector().detect_text_boxes(bgr)
+        except Exception as exc:
+            logger.warning("Text detection failed (%s); keeping the global scrub.", exc)
+            return base
+        if not boxes:
+            self._set_progress("No text detected; global scrub only.")
+            return base
+
+        width, height = init_image.size
+        regions = text_protector.merge_text_regions(boxes, height, width)
+        orig_bgr = cv2.cvtColor(np.array(init_image), cv2.COLOR_RGB2BGR)
+        out_bgr = cv2.cvtColor(np.array(base), cv2.COLOR_RGB2BGR)
+        budget = self._REGION_MAX_MEGAPIXELS * 1_000_000
+
+        done = 0
+        for x, y, w, h in regions:
+            area = max(1, w * h)
+            # INTEGER scale so the upscale -> scrub -> downscale round-trip is an
+            # exact dimensional inverse (a fractional factor truncates and shifts
+            # the composited text ~1-2px, which is invisible but tanks alignment).
+            scale = int(min(self._REGION_HIRES_SCALE, math.sqrt(budget / area)))
+            if scale < 2:
+                # Region too large to even double within the budget: upscaling
+                # buys nothing here; the global scrub covers it (documented limit
+                # for very large text areas -- tiling is the future fix).
+                continue
+            crop = orig_bgr[y : y + h, x : x + w]
+            up = cv2.resize(crop, (w * scale, h * scale), interpolation=cv2.INTER_LANCZOS4)
+            up_pil = Image.fromarray(cv2.cvtColor(up, cv2.COLOR_BGR2RGB))
+            scrubbed = self._run_img2img(up_pil, strength, num_inference_steps, guidance_scale, generator)
+            down = cv2.resize(cv2.cvtColor(np.array(scrubbed), cv2.COLOR_RGB2BGR), (w, h), interpolation=cv2.INTER_AREA)
+            # The up -> scrub -> down round-trip can offset the re-rendered text by
+            # a pixel or two (the diffusion pipeline rounds dims to a multiple of
+            # 8, so the inverse resize is not perfectly centered). Phase-correlate
+            # the patch back to the original crop and translate it so the glyphs
+            # land exactly where they were -- otherwise a sub-pixel shift garbles
+            # the composite even though the text is crisp.
+            cg = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY).astype(np.float32)
+            dg = cv2.cvtColor(down, cv2.COLOR_BGR2GRAY).astype(np.float32)
+            (sx, sy), resp = cv2.phaseCorrelate(cg, dg)
+            # Only correct for the real 1-2px round-trip shift. On a near-flat /
+            # low-contrast crop phaseCorrelate returns a spurious large offset at
+            # a tiny response (e.g. (19,19) at resp ~0.005); warping by that
+            # garbles the composite -- the exact failure this was meant to
+            # prevent. Gate on both a confident response and a plausible offset.
+            if resp > 0.3 and abs(sx) < 4 and abs(sy) < 4 and (abs(sx) > 0.1 or abs(sy) > 0.1):
+                m = np.float32([[1, 0, -sx], [0, 1, -sy]])
+                down = cv2.warpAffine(down, m, (w, h), flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
+            out_bgr = text_protector.feather_paste(out_bgr, down, x, y)
+            done += 1
+        self._set_progress(f"Re-scrubbed {done}/{len(regions)} text region(s) at high resolution.")
+        return Image.fromarray(cv2.cvtColor(out_bgr, cv2.COLOR_BGR2RGB))
+
+    def _run_differential(
+        self,
+        init_image: Image.Image,
+        strength: float,
+        num_inference_steps: int,
+        guidance_scale: float,
+        generator: Any,
+    ) -> Image.Image:
+        """Run differential img2img that preserves detected text regions."""
+        import cv2
+        import numpy as np
+
+        from remove_ai_watermarks import text_protector
+
+        self._set_progress("Detecting text regions to protect (protect-text)...")
+        bgr = cv2.cvtColor(np.array(init_image), cv2.COLOR_RGB2BGR)
+        try:
+            boxes = text_protector.TextProtector().detect_text_boxes(bgr)
+        except Exception as exc:
+            logger.warning("Text detection failed (%s); running standard img2img.", exc)
+            return self._run_img2img(init_image, strength, num_inference_steps, guidance_scale, generator)
+
+        if not boxes:
+            self._set_progress("No text detected; running standard img2img.")
+            return self._run_img2img(init_image, strength, num_inference_steps, guidance_scale, generator)
+
+        width, height = init_image.size
+        change_map = text_protector.build_change_map(boxes, height, width)
+        self._set_progress(f"Protecting {len(boxes)} text region(s) via Differential Diffusion...")
+
+        from remove_ai_watermarks.noai.img2img_runner import run_differential_with_mps_fallback
+
+        result_image, final_device = run_differential_with_mps_fallback(
+            load_pipeline=self._load_differential_pipeline,
+            image=init_image,
+            change_map=change_map,
+            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_differential_on_cpu,
+        )
+        if final_device != self.device:
+            self.device = final_device
+            self.torch_dtype = torch.float32  # type: ignore[assignment]
+        return result_image
+
     # ── CtrlRegen runner ─────────────────────────────────────────────
 
     def _run_ctrlregen(
@@ -616,12 +895,16 @@ 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 default (0.10 for SDXL, clean-noise
+    1.0 for ctrlregen); pass a value to override.
+    """
     remover = WatermarkRemover(model_id=model_id, device=device, hf_token=hf_token)
     return remover.remove_watermark(
         image_path=image_path,

src/remove_ai_watermarks/region_eraser.py

@@ -0,0 +1,188 @@
+"""Universal region eraser: remove anything inside user-given boxes via inpainting.
+
+Position- and content-agnostic. You supply the rectangle(s); the eraser inpaints
+whatever is inside, so it removes any visible logo / watermark / object regardless
+of colour, style, or location. Localisation is the user's responsibility (pass the
+box); restoration runs on CPU. This is the universal fallback for marks the
+deterministic per-generator engines (Gemini sparkle, Doubao) do not cover.
+
+Backends:
+  - ``cv2`` (default): ``cv2.inpaint`` (Telea / Navier-Stokes). Instant, no extra
+    dependencies, lower quality on large or textured regions.
+  - ``lama`` (optional, extra ``lama``): big-LaMa via onnxruntime
+    (``Carve/LaMa-ONNX``, Apache-2.0). CPU, resolution-robust, much better on
+    texture. The model (~200 MB) is downloaded on first use and cached by
+    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, Any, Literal
+
+import cv2
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+Backend = Literal["cv2", "lama"]
+
+_LAMA_REPO = "Carve/LaMa-ONNX"
+_LAMA_FILE = "lama_fp32.onnx"
+
+# Cached onnxruntime session (loading is expensive; reuse across calls).
+_lama_session: object | None = None
+
+
+def boxes_to_mask(
+    shape: tuple[int, int],
+    boxes: list[tuple[int, int, int, int]],
+    dilate: int = 3,
+) -> 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)
+    for x, y, bw, bh in boxes:
+        x0, y0 = max(0, x), max(0, y)
+        x1, y1 = min(w, x + bw), min(h, y + bh)
+        if x1 > x0 and y1 > y0:
+            mask[y0:y1, x0:x1] = 255
+    if dilate > 0 and mask.any():
+        k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * dilate + 1, 2 * dilate + 1))
+        mask = cv2.dilate(mask, k)
+    return mask
+
+
+def erase_cv2(
+    image_bgr: NDArray[Any],
+    mask: NDArray[Any],
+    *,
+    method: Literal["telea", "ns"] = "telea",
+    radius: int = 6,
+) -> 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)."""
+    import importlib.util
+
+    return importlib.util.find_spec("onnxruntime") is not None
+
+
+def _get_lama_session() -> object:
+    """Load (once) the big-LaMa ONNX session, downloading the model on first use."""
+    global _lama_session
+    if _lama_session is not None:
+        return _lama_session
+
+    import onnxruntime as ort
+    from huggingface_hub import hf_hub_download
+
+    model_path = hf_hub_download(repo_id=_LAMA_REPO, filename=_LAMA_FILE)
+    logger.info("Loading LaMa-ONNX model: %s", model_path)
+    _lama_session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
+    return _lama_session
+
+
+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.
+    """
+    session = _get_lama_session()
+    inp = session.get_inputs()  # type: ignore[attr-defined]
+    img_name = inp[0].name
+    mask_name = inp[1].name
+    # Model declares a fixed square spatial size (e.g. 512); fall back to 512.
+    dims = inp[0].shape
+    size = next((d for d in reversed(dims) if isinstance(d, int) and d > 1), 512)
+
+    h, w = image_bgr.shape[:2]
+    ys, xs = np.where(mask > 0)
+    if len(xs) == 0:
+        return image_bgr.copy()
+
+    # Padded crop around the mask (context for the inpainter).
+    pad = max(16, int(0.4 * max(xs.max() - xs.min() + 1, ys.max() - ys.min() + 1)))
+    cx0, cy0 = max(0, int(xs.min()) - pad), max(0, int(ys.min()) - pad)
+    cx1, cy1 = min(w, int(xs.max()) + 1 + pad), min(h, int(ys.max()) + 1 + pad)
+    crop = image_bgr[cy0:cy1, cx0:cx1]
+    crop_mask = mask[cy0:cy1, cx0:cx1]
+    ch, cw = crop.shape[:2]
+
+    # Resize crop + mask to the model size, normalise to [0,1] RGB CHW.
+    crop_rs = cv2.resize(crop, (size, size), interpolation=cv2.INTER_AREA)
+    mask_rs = cv2.resize(crop_mask, (size, size), interpolation=cv2.INTER_NEAREST)
+    img_in = cv2.cvtColor(crop_rs, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    img_in = np.transpose(img_in, (2, 0, 1))[None]  # (1,3,size,size)
+    mask_in = (mask_rs > 127).astype(np.float32)[None, None]  # (1,1,size,size), 1=hole
+
+    out = session.run(None, {img_name: img_in, mask_name: mask_in})[0]  # type: ignore[attr-defined]
+    out = np.asarray(out)[0]  # (3,size,size)
+    out = np.transpose(out, (1, 2, 0))
+    if float(out.max()) <= 1.5:  # model emits [0,1]; otherwise already [0,255]
+        out = out * 255.0
+    out = np.clip(out, 0, 255).astype(np.uint8)
+    out_bgr = cv2.cvtColor(out, cv2.COLOR_RGB2BGR)
+
+    # Resize back to crop size and paste only the masked pixels.
+    out_crop = cv2.resize(out_bgr, (cw, ch), interpolation=cv2.INTER_LINEAR)
+    result = image_bgr.copy()
+    region = result[cy0:cy1, cx0:cx1]
+    paste = crop_mask > 127
+    region[paste] = out_crop[paste]
+    result[cy0:cy1, cx0:cx1] = region
+    return result
+
+
+def erase(
+    image_bgr: NDArray[Any],
+    *,
+    boxes: list[tuple[int, int, int, int]] | None = None,
+    mask: NDArray[Any] | None = None,
+    backend: Backend = "cv2",
+    dilate: int = 3,
+    cv2_method: Literal["telea", "ns"] = "telea",
+    cv2_radius: int = 6,
+) -> 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``
+    (uint8, 255 = erase). Returns an unmodified copy when nothing is selected.
+    """
+    if image_bgr is None or image_bgr.size == 0:
+        return image_bgr
+    if mask is None:
+        if not boxes:
+            return image_bgr.copy()
+        mask = boxes_to_mask(image_bgr.shape[:2], boxes, dilate=dilate)
+    if not mask.any():
+        return image_bgr.copy()
+
+    if backend == "lama":
+        if not lama_available():
+            raise RuntimeError(
+                "LaMa backend requires onnxruntime. Install the extra: pip install 'remove-ai-watermarks[lama]'"
+            )
+        return erase_lama(image_bgr, mask)
+    return erase_cv2(image_bgr, mask, method=cv2_method, radius=cv2_radius)

src/remove_ai_watermarks/text_protector.py

@@ -0,0 +1,271 @@
+"""Text-region protection for diffusion-based watermark removal.
+
+SDXL img2img (the ``invisible`` pipeline) regenerates every pixel, so small text
+and CJK glyphs get deformed at the strengths that defeat SynthID (issue #21).
+This module detects text regions and builds a per-pixel "change map" for
+Differential Diffusion: the background is regenerated normally while text
+regions are largely preserved, so glyphs survive the watermark-removal pass.
+
+Detection uses only OpenCV's DNN module (no torch): the PP-OCRv3 text detector
+is a ~2.4 MB ONNX model (Apache-2.0, from opencv_zoo) that is CJK-native and
+returns rotated quadrilaterals. The model is downloaded and cached on first use;
+it is never bundled in this repo.
+
+Change-map polarity (verified empirically against the differential pipeline):
+white (1.0) = PRESERVE the original pixels, black (0.0) = MAXIMUM change. So the
+map is black everywhere except the text polygons, which are painted toward
+white. ``preserve`` stays below a hard 1.0 freeze by default: SynthID is
+designed to survive cropping, so totally freezing text pixels would leave the
+watermark intact there. A high-but-partial preserve still scrubs lightly.
+"""
+
+# cv2 ships no type stubs; mirror the pragma used by the other cv2-using modules.
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false, reportCallIssue=false, reportArgumentType=false, reportReturnType=false
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+import urllib.request
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+# PP-OCRv3 Chinese text detector (DB head), opencv_zoo, Apache-2.0.
+_MODEL_URL = (
+    "https://github.com/opencv/opencv_zoo/raw/main/models/text_detection_ppocr/text_detection_cn_ppocrv3_2023may.onnx"
+)
+_MODEL_FILENAME = "text_detection_cn_ppocrv3_2023may.onnx"
+
+# DB detector input: the image is detected at its NATIVE long side, capped at
+# this value (rounded to a multiple of 32), never upscaled. A fixed small input
+# (the old 736) downscaled large images so far that small text fell below the
+# detector's resolution and was missed -- the cause of the "small text still
+# distorts" reports (issue #14). Detection is script-agnostic (DB segments text
+# *regions*, not characters), so this recall fix applies to every language; the
+# only lever that mattered was resolution. 1536 recovers full recall down to
+# ~12 px text on a 2048 canvas at ~100 ms on CPU (a fixed 736 missed it); going
+# higher buys no measured recall at 2x+ the cost. Benchmarked in
+# scripts/text_detection_benchmark.py. Very large canvases with tiny text may
+# still need tiling -- a documented limit, not yet built.
+_DET_MAX_LONG_SIDE = 1536
+# ImageNet mean (x255) and 1/255 scale -- the normalization PP-OCRv3 expects.
+_DET_MEAN = (0.485 * 255, 0.456 * 255, 0.406 * 255)
+_DET_SCALE = 1 / 255.0
+
+
+def is_available() -> bool:
+    """True when OpenCV's DNN text-detection model is importable."""
+    try:
+        import cv2
+
+        return hasattr(cv2.dnn, "TextDetectionModel_DB")
+    except ImportError:
+        return False
+
+
+def _cache_dir() -> Path:
+    """Local cache directory for the detector model (created on demand)."""
+    cache = Path.home() / ".cache" / "remove-ai-watermarks"
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache
+
+
+def _model_path() -> Path:
+    """Return the cached detector path, downloading it on first use."""
+    target = _cache_dir() / _MODEL_FILENAME
+    if target.exists() and target.stat().st_size > 0:
+        return target
+    logger.info("Downloading PP-OCRv3 text detector (~2.4 MB) to %s", target)
+    # Download to a temp file in the same dir, then atomically rename so a
+    # partial download never leaves a corrupt model cached.
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), suffix=".onnx.part")
+    tmp_path = Path(tmp_name)
+    try:
+        os.close(fd)
+        with urllib.request.urlopen(_MODEL_URL) as resp:  # noqa: S310 (trusted GitHub URL)
+            tmp_path.write_bytes(resp.read())
+        tmp_path.replace(target)
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink()
+    return target
+
+
+def _detection_input_size(height: int, width: int) -> tuple[int, int]:
+    """DB-detector input ``(in_w, in_h)`` for an image of the given size.
+
+    Detect at the native long side, capped at ``_DET_MAX_LONG_SIDE`` and never
+    upscaled, each side rounded down to a multiple of 32 (the DB head requires
+    /32 dims), floored at 32. Pure function so the resolution contract (the
+    issue #14 small-text recall fix) is unit-testable without the model.
+    """
+    long_side = max(height, width)
+    scale = min(_DET_MAX_LONG_SIDE, long_side) / long_side
+    in_w = max((round(width * scale) // 32) * 32, 32)
+    in_h = max((round(height * scale) // 32) * 32, 32)
+    return in_w, in_h
+
+
+def build_change_map(
+    boxes: list[NDArray[Any]],
+    height: int,
+    width: int,
+    preserve: float = 0.9,
+    feather: int = 15,
+) -> NDArray[Any]:
+    """Build a Differential-Diffusion change map from text polygons.
+
+    Args:
+        boxes: Text-region polygons as arrays of (x, y) vertices.
+        height: Output map height in pixels.
+        width: Output map width in pixels.
+        preserve: Map value painted inside text polygons (0..1). White (1.0)
+            fully preserves the original pixels; the default 0.9 preserves
+            strongly while still letting a light scrub through.
+        feather: Gaussian-blur kernel size for soft polygon edges (forced odd).
+
+    Returns:
+        Float32 HxW array in [0, 1]: ~0 in the background (full change),
+        ``preserve`` inside text regions, blended at the edges.
+    """
+    import cv2
+    import numpy as np
+
+    change_map = np.zeros((height, width), np.float32)
+    if boxes:
+        polys = [np.asarray(b, np.int32) for b in boxes]
+        cv2.fillPoly(change_map, polys, float(preserve))
+    if feather > 0:
+        if feather % 2 == 0:
+            feather += 1
+        change_map = cv2.GaussianBlur(change_map, (feather, feather), 0)
+        # GaussianBlur can overshoot the painted value by a float epsilon; keep
+        # the contract that the map stays a valid [0, 1] change map.
+        np.clip(change_map, 0.0, 1.0, out=change_map)
+    return change_map
+
+
+def merge_text_regions(
+    boxes: list[NDArray[Any]],
+    height: int,
+    width: int,
+    dilate_frac: float = 0.012,
+    pad_frac: float = 0.02,
+    max_regions: int = 8,
+) -> list[tuple[int, int, int, int]]:
+    """Group detected text polygons into a few padded axis-aligned rectangles.
+
+    The DB detector returns one box per word/line; the region-high-res text scrub
+    runs a separate diffusion pass per region, so we coalesce nearby boxes into a
+    handful of *local* blocks (a light dilation merges within a paragraph but not
+    across the whole image, so each block stays small enough to upscale within a
+    memory budget). Returns ``(x, y, w, h)`` rects, largest-area first, clipped to
+    the image and capped at ``max_regions``.
+    """
+    import cv2
+    import numpy as np
+
+    mask = np.zeros((height, width), np.uint8)
+    if not boxes:
+        return []
+    cv2.fillPoly(mask, [np.asarray(b, np.int32) for b in boxes], 1)
+    k = max(1, int(min(height, width) * dilate_frac))
+    mask = cv2.dilate(mask, cv2.getStructuringElement(cv2.MORPH_RECT, (k, k)))
+    n, _labels, stats, _c = cv2.connectedComponentsWithStats(mask, 8)
+    pad = int(min(height, width) * pad_frac)
+    rects: list[tuple[int, int, int, int]] = []
+    for i in range(1, n):
+        x, y, w, h = (
+            int(stats[i, cv2.CC_STAT_LEFT]),
+            int(stats[i, cv2.CC_STAT_TOP]),
+            int(stats[i, cv2.CC_STAT_WIDTH]),
+            int(stats[i, cv2.CC_STAT_HEIGHT]),
+        )
+        x0, y0 = max(0, x - pad), max(0, y - pad)
+        x1, y1 = min(width, x + w + pad), min(height, y + h + pad)
+        rects.append((x0, y0, x1 - x0, y1 - y0))
+    rects.sort(key=lambda r: -(r[2] * r[3]))
+    return rects[:max_regions]
+
+
+def feather_paste(
+    base: NDArray[Any],
+    patch: NDArray[Any],
+    x: int,
+    y: int,
+    feather: int = 8,
+) -> NDArray[Any]:
+    """Alpha-composite ``patch`` into ``base`` at ``(x, y)`` with a feathered edge.
+
+    Used to drop a separately re-scrubbed (high-resolution) text region back into
+    the globally-scrubbed image without a visible seam. Returns a new array;
+    ``base`` is not modified. ``patch`` is clipped to ``base`` bounds.
+    """
+    import numpy as np
+
+    out = base.copy()
+    bh, bw = base.shape[:2]
+    ph, pw = patch.shape[:2]
+    x0, y0 = max(0, x), max(0, y)
+    x1, y1 = min(bw, x + pw), min(bh, y + ph)
+    if x1 <= x0 or y1 <= y0:
+        return out
+    patch_roi = patch[y0 - y : y1 - y, x0 - x : x1 - x].astype(np.float32)
+    base_roi = out[y0:y1, x0:x1].astype(np.float32)
+    rh, rw = base_roi.shape[:2]
+    alpha = np.ones((rh, rw), np.float32)
+    f = max(0, min(feather, rh // 2, rw // 2))
+    if f > 0:
+        ramp = np.linspace(0.0, 1.0, f, dtype=np.float32)
+        alpha[:f, :] *= ramp[:, None]
+        alpha[rh - f :, :] *= ramp[::-1, None]
+        alpha[:, :f] *= ramp[None, :]
+        alpha[:, rw - f :] *= ramp[None, ::-1]
+    a3 = alpha[:, :, None]
+    out[y0:y1, x0:x1] = (patch_roi * a3 + base_roi * (1.0 - a3)).astype(base.dtype)
+    return out
+
+
+class TextProtector:
+    """Detect text regions with PP-OCRv3 for diffusion change-map protection."""
+
+    def __init__(
+        self,
+        binary_threshold: float = 0.3,
+        polygon_threshold: float = 0.5,
+        max_candidates: int = 200,
+        unclip_ratio: float = 2.0,
+    ) -> None:
+        import cv2
+
+        self._detector = cv2.dnn.TextDetectionModel_DB(str(_model_path()))
+        self._detector.setBinaryThreshold(binary_threshold)
+        self._detector.setPolygonThreshold(polygon_threshold)
+        self._detector.setMaxCandidates(max_candidates)
+        self._detector.setUnclipRatio(unclip_ratio)
+
+    def detect_text_boxes(self, bgr_image: NDArray[Any]) -> list[NDArray[Any]]:
+        """Detect text regions, returning a list of rotated quad polygons.
+
+        Args:
+            bgr_image: Image as an HxWx3 BGR uint8 array (OpenCV convention).
+
+        Returns:
+            One array of four (x, y) vertices per detected text region.
+        """
+        height, width = bgr_image.shape[:2]
+        in_w, in_h = _detection_input_size(height, width)
+        self._detector.setInputParams(
+            scale=_DET_SCALE,
+            size=(in_w, in_h),
+            mean=_DET_MEAN,
+            swapRB=True,
+        )
+        boxes, _confidences = self._detector.detect(bgr_image)
+        return list(boxes)

src/remove_ai_watermarks/trustmark_detector.py

@@ -0,0 +1,118 @@
+"""Detect Adobe TrustMark invisible watermarks.
+
+TrustMark (github.com/adobe/trustmark, MIT) is the open, keyless image watermark
+behind Adobe "Durable Content Credentials": when a C2PA manifest is stripped, a
+TrustMark soft binding can still re-link the asset to its manifest in a
+repository. Unlike SynthID it has a PUBLIC decoder with no secret key, so a
+TrustMark-stamped image can be identified locally. Adobe's shipping products use
+Variant P (the ``com.adobe.trustmark.P`` soft-binding ``alg``); this wrapper
+loads that model.
+
+Optional dependency (extra: ``trustmark``); the model weights download on first
+use. ``detect_trustmark`` returns None when the package is absent. This detects
+provenance (Adobe Content Credentials), NOT AI generation as such -- TrustMark
+also marks human-authored content -- so callers should treat it as a watermark
+signal, not proof of AI origin.
+"""
+
+# trustmark ships no type stubs; relax untyped-library diagnostics for this thin
+# wrapper module only.
+# pyright: reportMissingTypeStubs=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false, reportMissingImports=false
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+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:
+    """True if the optional ``trustmark`` package is installed."""
+    import importlib.util
+
+    return importlib.util.find_spec("trustmark") is not None
+
+
+def _decoder() -> Any:
+    global _tm
+    if _tm is None:
+        with _tm_lock:
+            if _tm is None:
+                from trustmark import TrustMark
+
+                _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 *durable* TrustMark watermark is
+    decoded, else None.
+
+    Returns e.g. ``"Adobe TrustMark (variant P, schema 0)"`` when the decoder
+    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
+    try:
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            cover = img.convert("RGB")
+        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})"
+
+
+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/watermark_registry.py

@@ -0,0 +1,233 @@
+"""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;
+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.
+"""
+
+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()
+        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
+
+
+def _doubao_detect(image: NDArray[Any]) -> MarkDetection:
+    d = _engine("doubao").detect(image)
+    return MarkDetection("doubao", "Doubao 豆包AI生成 text", "bottom-right", d.detected, d.confidence, d.region)
+
+
+def _doubao_remove(
+    image: NDArray[Any], _inpaint_method: InpaintMethod, _inpaint: bool, _strength: float, force: bool
+) -> tuple[NDArray[Any], Region | None]:
+    # Reverse-alpha only: apply when the mark is present AND the resolution is in
+    # the alpha map's calibrated band. Outside it we do NOT inpaint (no
+    # hallucination) -- removal is skipped until a capture for that resolution.
+    engine = _engine("doubao")
+    det = engine.detect(image)
+    if (det.detected or force) and engine.reverse_alpha_available(image):
+        return engine.remove_watermark_reverse_alpha(image), (det.region if det.detected else None)
+    return image.copy(), None
+
+
+def _jimeng_detect(image: NDArray[Any]) -> MarkDetection:
+    d = _engine("jimeng").detect(image)
+    return MarkDetection("jimeng", "Jimeng 即梦AI wordmark", "bottom-right", d.detected, d.confidence, d.region)
+
+
+def _jimeng_remove(
+    image: NDArray[Any], _inpaint_method: InpaintMethod, _inpaint: bool, _strength: float, force: bool
+) -> tuple[NDArray[Any], Region | None]:
+    # Reverse-alpha (with an always-on residual inpaint over the glyph footprint,
+    # see the engine): apply when the mark is present and the alpha asset loads.
+    # Skipped otherwise (no hallucination on a clean corner).
+    engine = _engine("jimeng")
+    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
+
+
+_REGISTRY: tuple[KnownMark, ...] = (
+    KnownMark("gemini", "Google Gemini sparkle", "bottom-right", True, "reverse-alpha", _gemini_detect, _gemini_remove),
+    KnownMark(
+        "doubao", "Doubao 豆包AI生成 text", "bottom-right", True, "reverse-alpha", _doubao_detect, _doubao_remove
+    ),
+    KnownMark(
+        "jimeng", "Jimeng 即梦AI wordmark", "bottom-right", True, "reverse-alpha", _jimeng_detect, _jimeng_remove
+    ),
+)
+
+
+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/conftest.py

@@ -2,10 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from pathlib import Path
+from pathlib import Path
 
 import cv2
 import numpy as np
@@ -13,6 +10,22 @@ import pytest
 from PIL import Image
 from PIL.PngImagePlugin import PngInfo
 
+CORPUS_NEG_DIR = Path(__file__).resolve().parent.parent / "data" / "synthid_corpus" / "images" / "neg"
+
+
+@pytest.fixture
+def clean_photo() -> Path:
+    """A verified-negative real photo from the corpus neg/ set.
+
+    Used by the "non-AI image" assertions (no SynthID, verdict unknown). These
+    are real photos with no AI provenance, the ground truth for "must not false-
+    positive". Skips if the corpus is not checked out.
+    """
+    files = sorted(CORPUS_NEG_DIR.glob("*")) if CORPUS_NEG_DIR.exists() else []
+    if not files:
+        pytest.skip("no corpus neg/ images present")
+    return files[0]
+
 
 @pytest.fixture
 def tmp_image_path(tmp_path: Path) -> Path:

tests/test_cli.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from typing import TYPE_CHECKING
 from unittest.mock import MagicMock, patch
 
@@ -26,7 +27,9 @@ def runner():
 @pytest.fixture
 def sample_png(tmp_path: Path) -> Path:
     """Create a sample PNG for CLI testing."""
-    img = np.random.randint(0, 255, (200, 200, 3), dtype=np.uint8)
+    # Seeded: an unseeded random corner can occasionally trip the Doubao
+    # visible-mark detector, making `visible --mark auto` flaky.
+    img = np.random.default_rng(0).integers(0, 255, (200, 200, 3), dtype=np.uint8)
     path = tmp_path / "input.png"
     cv2.imwrite(str(path), img)
     return path
@@ -36,8 +39,9 @@ def _make_batch_dir(tmp_path: Path, count: int = 3) -> Path:
     """Create a directory with test images for batch testing."""
     input_dir = tmp_path / "input"
     input_dir.mkdir()
+    rng = np.random.default_rng(0)
     for i in range(count):
-        img = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)
+        img = rng.integers(0, 255, (100, 100, 3), dtype=np.uint8)
         cv2.imwrite(str(input_dir / f"img_{i}.png"), img)
     return input_dir
 
@@ -71,6 +75,27 @@ def _mock_invisible_engine():
     return mock_cls, mock_engine
 
 
+def _mock_invisible_engine_drops_alpha():
+    """Mock InvisibleEngine that mimics the real engine's BGR-only output path.
+
+    The real diffusion-based engine reads with cv2.IMREAD_COLOR and writes a
+    3-channel result. This mock simulates that so we can regression-test alpha
+    preservation across the ``all`` pipeline.
+    """
+
+    def _mock_remove_watermark(image_path, output_path=None, **kwargs):
+        out = output_path or image_path.with_stem(image_path.stem + "_clean")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        bgr = cv2.imread(str(image_path), cv2.IMREAD_COLOR)
+        cv2.imwrite(str(out), bgr)
+        return out
+
+    mock_engine = MagicMock()
+    mock_engine.remove_watermark.side_effect = _mock_remove_watermark
+    mock_cls = MagicMock(return_value=mock_engine)
+    return mock_cls, mock_engine
+
+
 class TestMainGroup:
     """Tests for the top-level CLI group."""
 
@@ -97,7 +122,8 @@ class TestVisibleCommand:
     def test_visible_help(self, runner):
         result = runner.invoke(main, ["visible", "--help"])
         assert result.exit_code == 0
-        assert "Gemini watermark" in result.output
+        assert "visible AI watermark" in result.output
+        assert "--mark" in result.output
 
     def test_visible_basic(self, runner, sample_png, tmp_path):
         output = tmp_path / "clean.png"
@@ -143,6 +169,77 @@ class TestVisibleCommand:
         result = runner.invoke(main, ["visible", "/nonexistent/file.png"])
         assert result.exit_code != 0
 
+    def test_visible_preserves_rgba_transparency(self, runner, tmp_path):
+        """Visible removal on an RGBA PNG must keep the alpha channel,
+        not silently flatten the image onto an opaque background.
+        """
+        rgba = np.zeros((200, 200, 4), dtype=np.uint8)
+        rgba[:, :, :3] = 200  # light grey foreground
+        rgba[50:150, 50:150, 3] = 255  # opaque square in the middle, rest transparent
+        src = tmp_path / "rgba_in.png"
+        cv2.imwrite(str(src), rgba)
+
+        output = tmp_path / "rgba_out.png"
+        result = runner.invoke(
+            main,
+            ["visible", str(src), "-o", str(output), "--no-detect"],
+        )
+
+        assert result.exit_code == 0, result.output
+        assert output.exists()
+
+        out = cv2.imread(str(output), cv2.IMREAD_UNCHANGED)
+        assert out.ndim == 3, f"output is not 3D: shape={out.shape}"
+        assert out.shape[2] == 4, f"output is not RGBA: shape={out.shape}"
+        # The transparent corners must remain transparent.
+        assert out[0, 0, 3] == 0
+        assert out[199, 199, 3] == 0
+        # The opaque centre remains opaque (the watermark region default is bottom-right,
+        # which doesn't overlap the centre square at 200x200).
+        assert out[100, 100, 3] == 255
+
+    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_kept.png"
+        result = runner.invoke(
+            main,
+            ["visible", str(src), "-o", str(output), "--no-detect"],
+        )
+
+        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 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] == 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."""
+        output = tmp_path / "rgb_out.png"
+        result = runner.invoke(
+            main,
+            ["visible", str(sample_png), "-o", str(output), "--no-detect"],
+        )
+
+        assert result.exit_code == 0, result.output
+        out = cv2.imread(str(output), cv2.IMREAD_UNCHANGED)
+        assert out.ndim == 3, f"output is not 3D: shape={out.shape}"
+        assert out.shape[2] == 3, f"RGB input produced non-RGB output: shape={out.shape}"
+
 
 class TestInvisibleCommand:
     """Tests for the 'invisible' subcommand."""
@@ -156,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),
         ):
@@ -170,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),
         ):
@@ -209,6 +308,33 @@ class TestAllCommand:
         result = runner.invoke(main, ["all", "/nonexistent/file.png"])
         assert result.exit_code != 0
 
+    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).
+        """
+        rgba = np.zeros((200, 200, 4), dtype=np.uint8)
+        rgba[:, :, :3] = 200
+        rgba[50:150, 50:150, 3] = 255  # opaque square; corners transparent
+        src = tmp_path / "rgba_in.png"
+        cv2.imwrite(str(src), rgba)
+
+        output = tmp_path / "rgba_out.png"
+        mock_cls, _engine = _mock_invisible_engine_drops_alpha()
+        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, ["all", str(src), "-o", str(output)])
+
+        assert result.exit_code == 0, result.output
+        out = cv2.imread(str(output), cv2.IMREAD_UNCHANGED)
+        assert out.ndim == 3, f"output not 3D: shape={out.shape}"
+        assert out.shape[2] == 4, f"output is not RGBA: shape={out.shape}"
+        assert out[0, 0, 3] == 0
+        assert out[100, 100, 3] == 255
+
 
 class TestMetadataCommand:
     """Tests for the 'metadata' subcommand."""
@@ -243,6 +369,44 @@ class TestMetadataCommand:
         assert "stripped" in result.output
 
 
+class TestIdentifyCommand:
+    """Tests for the 'identify' subcommand."""
+
+    def test_identify_help(self, runner):
+        result = runner.invoke(main, ["identify", "--help"])
+        assert result.exit_code == 0
+
+    def test_identify_clean_png(self, runner, tmp_clean_png):
+        result = runner.invoke(main, ["identify", str(tmp_clean_png), "--no-visible"])
+        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
+        assert "AI-generated" in result.output
+        assert "Stable Diffusion" in result.output
+
+    def test_identify_json_is_valid(self, runner, tmp_png_with_ai_metadata):
+        result = runner.invoke(main, ["identify", str(tmp_png_with_ai_metadata), "--no-visible", "--json"])
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["is_ai_generated"] is True
+        assert payload["confidence"] == "high"
+
+    def test_identify_nonexistent_file(self, runner):
+        result = runner.invoke(main, ["identify", "/nonexistent/file.png"])
+        assert result.exit_code != 0
+
+
 class TestBatchCommand:
     """Tests for the 'batch' subcommand."""
 
@@ -319,6 +483,37 @@ class TestBatchCommand:
         assert result.exit_code == 0, result.output
         assert "3 processed" in result.output
 
+    def test_batch_all_mode_preserves_rgba(self, runner, tmp_path):
+        """Regression: batch ``all`` must keep transparency across the
+        alpha-dropping invisible step (mirrors test_all_preserves_rgba_...).
+        """
+        input_dir = tmp_path / "input"
+        input_dir.mkdir()
+        rgba = np.zeros((200, 200, 4), dtype=np.uint8)
+        rgba[:, :, :3] = 200
+        rgba[50:150, 50:150, 3] = 255
+        cv2.imwrite(str(input_dir / "rgba.png"), rgba)
+
+        output_dir = tmp_path / "output"
+        mock_cls, _engine = _mock_invisible_engine_drops_alpha()
+        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", "all"],
+            )
+        assert result.exit_code == 0, result.output
+
+        out = cv2.imread(str(output_dir / "rgba.png"), cv2.IMREAD_UNCHANGED)
+        assert out.ndim == 3, f"output not 3D: shape={out.shape}"
+        assert out.shape[2] == 4, f"output is not RGBA: shape={out.shape}"
+        assert out[0, 0, 3] == 0
+        assert out[100, 100, 3] == 255
+
     def test_batch_default_output_dir(self, runner, tmp_path):
         input_dir = _make_batch_dir(tmp_path)
         result = runner.invoke(
@@ -328,3 +523,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

@@ -0,0 +1,213 @@
+"""Tests for the Doubao visible-watermark engine (reverse-alpha only)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pytest
+
+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"
+
+
+class TestLocate:
+    def test_box_anchored_bottom_right(self):
+        eng = DoubaoEngine()
+        img = np.zeros((2048, 2048, 3), np.uint8)
+        loc = eng.locate(img)
+        assert 2048 - (loc.x + loc.w) < int(2048 * 0.03)
+        assert 2048 - (loc.y + loc.h) < int(2048 * 0.03)
+
+    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))
+        assert large.w == pytest.approx(small.w * 2, rel=0.1)
+
+
+# ── 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):
+        det = DoubaoEngine().detect(load_image_bgr(SAMPLE))
+        assert det.detected
+        assert det.confidence >= DETECT_NCC_THRESHOLD
+
+    def test_reverse_alpha_removes_mark(self):
+        eng = DoubaoEngine()
+        img = load_image_bgr(SAMPLE)
+        assert eng.reverse_alpha_available(img)  # sample is at the captured width
+        out = eng.remove_watermark_reverse_alpha(img)
+        assert not eng.detect(out).detected  # mark gone after recovery
+
+    def test_far_region_untouched(self):
+        eng = DoubaoEngine()
+        img = load_image_bgr(SAMPLE)
+        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])
+
+
+# ── Reverse-alpha (exact recovery) ──────────────────────────────────
+
+
+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()
+        assert eng.reverse_alpha_available(np.zeros((1024, 1024, 3), np.uint8))
+        assert eng.reverse_alpha_available(np.zeros((1773, 1535, 3), np.uint8))
+        assert not eng.reverse_alpha_available(np.zeros((0, 0, 3), np.uint8))
+
+    @staticmethod
+    def _compose(w: int, h: int, bg: float = 100.0):
+        """Composite the real alpha (scaled to width ``w``) onto a flat bg.
+        Returns ``(watermarked_uint8, mark_bool_mask)``."""
+        img = np.full((h, w, 3), bg, np.float32)
+        at = _alpha_template()
+        gw, gh = int(_ALPHA_WIDTH_FRAC * w), int(_ALPHA_HEIGHT_FRAC * w)
+        ax = w - int(_ALPHA_MARGIN_RIGHT_FRAC * w) - gw
+        ay = h - int(_ALPHA_MARGIN_BOTTOM_FRAC * w) - gh
+        amap = np.zeros((h, w), np.float32)
+        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh))
+        a3 = amap[:, :, None]
+        wm = (a3 * np.array(_ALPHA_LOGO_BGR, np.float32) + (1 - a3) * img).clip(0, 255).astype(np.uint8)
+        return wm, amap > 0.2
+
+    def test_removes_synthetic_mark(self):
+        """Reverse-alpha + thin residual inpaint clears a mark composed from the
+        real alpha (re-detect no longer fires)."""
+        eng = DoubaoEngine()
+        wm, _mark = self._compose(_ALPHA_NATIVE_WIDTH, _ALPHA_NATIVE_WIDTH)
+        assert eng.detect(wm).detected
+        out = eng.remove_watermark_reverse_alpha(wm)
+        assert not eng.detect(out).detected
+
+    @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_gemini_engine.py

@@ -12,6 +12,7 @@ from remove_ai_watermarks.gemini_engine import (
     WatermarkPosition,
     WatermarkSize,
     _calculate_alpha_map,
+    detect_sparkle_confidence,
     get_watermark_config,
     get_watermark_size,
 )
@@ -174,6 +175,21 @@ class TestDetection:
         assert isinstance(result.gradient_score, float)
 
 
+class TestDetectSparkleConfidence:
+    """File-level entry point used by identify.py."""
+
+    def test_returns_float_in_range_for_real_image(self, tmp_image_path):
+        conf = detect_sparkle_confidence(tmp_image_path)
+        assert conf is not None
+        assert 0.0 <= conf <= 1.0
+
+    def test_returns_none_for_unreadable_file(self, tmp_path):
+        # cv2.imread returns None for a non-image; the helper must not raise.
+        bogus = tmp_path / "not_an_image.png"
+        bogus.write_bytes(b"this is not a PNG")
+        assert detect_sparkle_confidence(bogus) is None
+
+
 # ── Inpainting ──────────────────────────────────────────────────────
 
 

tests/test_humanizer.py

@@ -50,3 +50,23 @@ 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