chore(release): v0.11.2

When `visible --mark auto` (or an explicit `--mark` with detection on) found
no registered mark, it exited 0 without writing output -- which a wrapping
service reads as success and re-serves the unchanged input. ~74% of real
uploads carry no registered visible mark, so this was the dominant "it didn't
work" / NPS score-0 failure mode.

Now it runs a cheap metadata-only identify, prints actionable guidance (route
to `all` for an invisible/metadata mark, or `erase` for an arbitrary logo),
writes no output file, and exits EXIT_NO_VISIBLE_MARK (2) -- distinct from
success (0) and a hard error (1) so the caller can surface the message.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/settings.json

@@ -1,14 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebSearch",
-      "WebFetch"
-    ]
-  },
-  "enabledPlugins": {
-    "pyright-lsp@claude-plugins-official": true,
-    "context7@claude-plugins-official": true,
-    "code-simplifier@claude-plugins-official": true,
-    "claude-md-management@claude-plugins-official": true
-  }
-}

.github/workflows/distribute.yml

@@ -0,0 +1,106 @@
+name: Distribute on release
+
+# Fans a published GitHub Release out to the channels that need a nudge.
+# PyPI is handled by publish.yml; conda-forge is handled by its autotick bot.
+# This workflow event-drives the two channels that would otherwise be manual:
+#   - Homebrew tap: rewrite the formula's url + sha256 to the new sdist.
+#   - HF Space: factory-rebuild so it reinstalls the latest sdist from PyPI.
+# Both wait for the freshly published sdist to appear on PyPI first, since the
+# Release event fires in parallel with publish.yml's upload.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to distribute (no leading v), e.g. 0.10.3. Blank = latest on PyPI."
+        required: false
+
+jobs:
+  resolve:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.v.outputs.version }}
+      url: ${{ steps.sdist.outputs.url }}
+      sha: ${{ steps.sdist.outputs.sha }}
+    steps:
+      - name: Resolve target version
+        id: v
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "release" ]; then
+            v="${GITHUB_REF_NAME#v}"
+          elif [ -n "${{ github.event.inputs.version }}" ]; then
+            v="${{ github.event.inputs.version }}"
+          else
+            v=$(curl -fsSL https://pypi.org/pypi/remove-ai-watermarks/json \
+              | python3 -c "import sys,json;print(json.load(sys.stdin)['info']['version'])")
+          fi
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          echo "Target version: $v"
+
+      - name: Wait for the sdist on PyPI, capture url + sha256
+        id: sdist
+        run: |
+          set -euo pipefail
+          v="${{ steps.v.outputs.version }}"
+          for i in $(seq 1 30); do
+            if rel=$(curl -fsSL "https://pypi.org/pypi/remove-ai-watermarks/$v/json" 2>/dev/null); then
+              url=$(echo "$rel" | python3 -c "import sys,json;d=json.load(sys.stdin);print(next((u['url'] for u in d['urls'] if u['packagetype']=='sdist'),''))")
+              sha=$(echo "$rel" | python3 -c "import sys,json;d=json.load(sys.stdin);print(next((u['digests']['sha256'] for u in d['urls'] if u['packagetype']=='sdist'),''))")
+              if [ -n "$url" ] && [ -n "$sha" ]; then
+                echo "url=$url" >> "$GITHUB_OUTPUT"
+                echo "sha=$sha" >> "$GITHUB_OUTPUT"
+                echo "Found sdist for $v"
+                exit 0
+              fi
+            fi
+            echo "sdist for $v not on PyPI yet (attempt $i), waiting..."
+            sleep 20
+          done
+          echo "::error::sdist for $v did not appear on PyPI in time"
+          exit 1
+
+  homebrew:
+    needs: resolve
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the tap
+        uses: actions/checkout@v6
+        with:
+          repository: wiltodelta/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+      - name: Bump the formula
+        env:
+          URL: ${{ needs.resolve.outputs.url }}
+          SHA: ${{ needs.resolve.outputs.sha }}
+          VERSION: ${{ needs.resolve.outputs.version }}
+        run: |
+          set -euo pipefail
+          F=Formula/remove-ai-watermarks.rb
+          sed -i -E "s|url \"[^\"]*\"|url \"$URL\"|" "$F"
+          sed -i -E "s|sha256 \"[^\"]*\"|sha256 \"$SHA\"|" "$F"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add "$F"
+          git commit -m "remove-ai-watermarks $VERSION" || { echo "Formula already current"; exit 0; }
+          git push
+
+  hf-space:
+    needs: resolve
+    runs-on: ubuntu-latest
+    steps:
+      - name: Factory-rebuild the HuggingFace Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          python3 -m pip install --quiet huggingface_hub
+          python3 - <<'PY'
+          import os
+          from huggingface_hub import HfApi
+          HfApi(token=os.environ["HF_TOKEN"]).restart_space(
+              "wiltodelta/remove-ai-watermarks", factory_reboot=True
+          )
+          print("HF Space factory rebuild triggered")
+          PY

.gitignore

@@ -18,9 +18,6 @@ Thumbs.db
 *.swp
 *.swo
 
-# 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/
@@ -49,6 +46,7 @@ data/gemini_capture/captures/gemini_content_*.png
 data/samsung_capture/seeds/
 data/samsung_capture/captures/samsung_content_*
 
-# GFPGAN downloads its RetinaFace/parsing weights to a CWD ./gfpgan/weights/
-# working dir on first use (the restore extra). Runtime artifact, never committed.
+# Leftover GFPGAN weights dir from the retired face-restore experiments
+# (GFPGAN wrote RetinaFace/parsing weights to a CWD ./gfpgan/weights/ working
+# dir on first use). Runtime artifact, never committed.
 gfpgan/

CLAUDE.md

@@ -4,21 +4,24 @@ 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, the Jimeng "★ 即梦AI" wordmark, and the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-LEFT, locale-specific — Italian variant calibrated); `--mark gemini` / `--mark doubao` / `--mark jimeng` / `--mark samsung` force one (choices come from the registry). Gemini/Doubao recover pixels exactly with no inpaint at native; **Jimeng and Samsung add an always-on thin residual inpaint over the glyph footprint** (their marks re-rasterize per image, so reverse-alpha alone leaves a faint outline). For arbitrary logos/objects use `erase`.
+- `uv run remove-ai-watermarks all <image.png> -o <output.png>` — full pipeline (visible + invisible + metadata). Same diffusion knobs as `invisible` below, plus the visible-pass `--inpaint/--no-inpaint`/`--inpaint-method`. **When the `[gpu]` extra is absent, step 2 (invisible/SynthID) is skipped** — `all` still writes an output (visible mark + metadata stripped) but prints a prominent end-of-run banner ("the invisible (SynthID) watermark was NOT removed") AND exits **non-zero** (1), so a skipped SynthID pass is not mistaken for a clean result (the recurring #14/#47 trap, where the old quiet inline warning was missed). `invisible` already hard-errors without the extra; only `all` continued, hence the loud end-banner. Regression-guarded by `tests/test_cli.py::TestAllCommand::test_all_loud_warning_and_nonzero_exit_when_gpu_missing`. **Test trap:** any `all` test that exercises the full pipeline MUST `patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True)` — CI installs core+dev only (no `[gpu]`), so an unpatched `all` test takes the skip branch and now hits the non-zero exit. This passed locally (gpu present → `is_available()` True) but red-failed every matrix cell on the v0.11.0 commit (`test_all_basic`/`test_all_visible_step_uses_registry` asserted exit 0); both now patch `is_available` True.
+- `uv run remove-ai-watermarks invisible <image.png> -o <out.png>` — diffusion SynthID removal. **Full knob set** (kept identical across `invisible`/`all`/`batch`): `--strength` (vendor-adaptive default), `--steps`, `--guidance-scale` (CFG, default 7.5), `--pipeline sdxl|controlnet` (default `controlnet`), `--controlnet-scale`, `--model` (HF model id, default SDXL base), `--device`, `--seed`, `--hf-token`, `--max-resolution`/`--min-resolution`, `--upscaler lanczos|esrgan`, `--humanize` (Analog Humanizer grain), `--unsharp` (final sharpen), and `--adaptive-polish/--no-adaptive-polish` (**ON by default**; detail-targeted polish that self-gates to a no-op where there is no deficit). `--auto` is deprecated and now a no-op that only warns (the polish it used to enable is ON by default).
+- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — known-visible-mark removal, CPU, no GPU. Reverse-alpha based: each mark is removed by inverting its captured alpha map. `--mark auto` (default) picks the strongest detected of the Gemini sparkle, the Doubao "豆包AI生成" text strip, the Jimeng "★ 即梦AI" wordmark, and the Samsung Galaxy AI "✦ Contenuti generati dall'AI" strip (bottom-LEFT, locale-specific — Italian variant calibrated); `--mark gemini` / `--mark doubao` / `--mark jimeng` / `--mark samsung` force one (choices come from the registry). Gemini/Doubao recover pixels exactly with no inpaint at native; **Jimeng and Samsung add an always-on thin residual inpaint over the glyph footprint** (their marks re-rasterize per image, so reverse-alpha alone leaves a faint outline). For arbitrary logos/objects use `erase`. **When `--mark auto` finds no known mark (the common case — ~74% of real uploads carry no registered visible mark), the command does NOT silently re-serve the input as a finished result.** It runs a cheap metadata-only `identify`, prints actionable guidance (if the image carries an invisible/metadata mark, e.g. an OpenAI/Gemini C2PA image, it points to `all`; otherwise to `erase --region`), writes NO output file, and exits **`EXIT_NO_VISIBLE_MARK` (2)** — distinct from success (0) and a hard error (1) so a wrapping service (raiw.cc) can surface the message instead of treating the unchanged image as done (the production "it didn't work" / score-0 trap). Same handling for an explicit `--mark <name>` that is not detected. Helper `cli._no_visible_mark_exit`; regression-guarded by `tests/test_cli.py::TestVisibleCommand::test_visible_auto_no_mark_exits_two_with_eraser_hint` and `test_visible_auto_no_mark_routes_to_all_when_metadata`. `--no-detect` still forces the gemini fallback and proceeds (exit 0).
 - `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`/`--controlnet-scale`/`--device`/`--max-resolution`/`--min-resolution`/`--upscaler`/`--seed`/`--hf-token` knobs as `invisible`, `--inpaint/--no-inpaint` for the visible pass, `--humanize` for the Analog Humanizer + `--unsharp` for the final sharpening post-filter, and `--auto` (+ `--adaptive-polish/--no-adaptive-polish`) for the content-adaptive quality mode (re-planned per image; one engine cached per resolved pipeline)
+- `uv run remove-ai-watermarks batch <directory>` — process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the **full `invisible` knob set above** (`--strength`/`--steps`/`--guidance-scale`/`--pipeline`/`--controlnet-scale`/`--model`/`--device`/`--max-resolution`/`--min-resolution`/`--upscaler`/`--seed`/`--hf-token`/`--humanize`/`--unsharp`/`--adaptive-polish`), plus `--inpaint/--no-inpaint` for the visible pass. `--adaptive-polish` is ON by default; `--auto` is deprecated and a no-op that only warns. One engine cached per pipeline; the polish is resolved once before the loop.
 
 ## Test and lint
 
-- **CI** (`.github/workflows/test.yml`): runs on push to `main` + every PR. A `lint` job (ubuntu: `ruff check` + `ruff format --check`) plus a `test` matrix (ubuntu/macos/windows x py3.10/3.12) that does `uv sync --frozen --extra dev` then `pytest`. The matrix installs only core + dev (no `gpu` extra), so the GPU/model-running tests skip there and it exercises the metadata/identify/visible/cv2-eraser surface on all three OSes. Keep `uv.lock` valid (don't break `--frozen`) when editing `pyproject.toml`. `publish.yml` stays release-only and now verifies the release tag matches the `pyproject.toml` version (fails the build on a mismatch) before building, then uploads via `uv publish` (PyPI trusted publishing over OIDC, no token — replaced the `pypa/gh-action-pypi-publish` action so the upload no longer depends on that action's bundled twine accepting the Metadata-Version; the `id-token: write` permission + `pypi` environment + workflow filename are unchanged, so PyPI's trusted-publisher entry still matches). **Release flow:** bump the version in `pyproject.toml` + `src/remove_ai_watermarks/__init__.py` + `uv.lock` (the project's own `[[package]]` entry, ~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 (the multi-hundred-MB synthid_corpus images + the visible-mark captures) pushed the **0.8.0** sdist past PyPI's per-project file-size limit (400 "File too large") — the wheel uploaded but the sdist was rejected, so 0.8.0 shipped wheel-only and 0.8.1 carried the fix. The wheel only ships `src/` (via `[tool.hatch.build.targets.wheel] packages`), so it was never affected. **A failed PyPI upload of one artifact still leaves the other live and you cannot re-upload the same version** — fix the build and cut the next patch. **Build backend is pinned `hatchling<1.31`** (`[build-system] requires`): hatchling **1.30.0** made **Metadata-Version 2.5** (PEP 794) the default, which the twine bundled in `pypa/gh-action-pypi-publish@release/v1` rejects (`"'2.5' is not a valid Metadata-Version"`) — this **failed the v0.8.3 PyPI upload on 2026-06-01** (tag-match + build passed, the upload step failed; nothing was uploaded, so the version stayed empty on PyPI), when unpinned `requires = ["hatchling"]` pulled 1.30.0. **hatchling 1.30.1 reverted the default back to 2.4** ("kept at 2.4 until more tools support 2.5"), and 1.27-1.29 always emitted 2.4 — so `<1.31` keeps `uv build` on a 2.4-emitting hatchling (it resolves to the latest allowed, **1.30.1**, which uploads fine). (The earlier "1.28+ emits 2.5" note was imprecise: the 2.5 default landed only in 1.30.0, verified against hatch's changelog.) The publish workflow **now uses `uv publish`** (its uploader handles 2.5), so this pin is no longer load-bearing — it stays as belt-and-suspenders so the first uv-publish release ships 2.4 metadata (isolating the uploader swap from the metadata-version bump); drop it to `requires = ["hatchling"]` once that release confirms the path.
-- `bash maintain.sh` — uv-outdated, uv-secure, ruff check/fix, ruff format, pyright, pytest -n auto
-- **Strict pyright is clean across `src/` (0 errors).** The cv2/torch/diffusers boundary files (`gemini_engine`, `region_eraser`, `doubao_engine`, `humanizer`, `invisible_engine`, `noai/watermark_remover`) carry a documented per-file `# pyright:` relax pragma that turns off only the unknown-type / untyped-third-party rules — those libs ship no usable types, so strict typing there fights the ecosystem. Pure-logic files stay fully strict; `typings/piexif/__init__.pyi` is a local stub so `metadata.py`/`extractor.py` resolve piexif. Public ndarray-returning signatures on the relaxed engines are still annotated `NDArray[Any]` so strict consumers (`cli.py`) stay clean. When touching a relaxed file, prefer fixing real issues over widening the pragma; keep the pragma scoped to genuinely-untyped boundaries. (`uv-secure` is clean since idna was bumped 3.11 -> 3.16, fixing GHSA-65pc-fj4g-8rjx, and aiohttp 3.13.5 -> 3.14.0 via `uv lock --upgrade-package aiohttp`, fixing GHSA-hg6j-4rv6-33pg + GHSA-jg22-mg44-37j8. (The basicsr Dependabot alert (GHSA-86w8-vhw6-q9qq, command injection, no patch, <= 1.4.2): accepted, not fixable -- basicsr is the optional `restore` extra pinned to 1.4.2 as the only buildable version, experimental and off by default.)
+- **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`.
+- **Release flow + distribution channels** (PyPI publish via `publish.yml`/`uv publish`, the automated Homebrew-tap + HF-Space bumps in `distribute.yml`, conda-forge, ComfyUI Registry, the sdist `data/` exclusion, hatchling pin history): see `docs/release-and-distribution.md` before cutting a release.
+- `bash maintain.sh` — uv-outdated, uv-secure, ruff check/fix, ruff format, pyright (scoped `src/`, see the OOM note below), pytest -n auto. The helper tools live in the `dev` extra (`pytest-xdist`, plus `uv-outdated`/`uv-secure` marker-gated to py3.12+ so the py3.10 resolution stays solvable) — a bare env without `--extra dev` does not have them.
+- **Strict pyright is clean across `src/` (0 errors).** The cv2/torch/diffusers boundary files (`gemini_engine`, `region_eraser`, `doubao_engine`, `humanizer`, `invisible_engine`, `noai/watermark_remover`) carry a documented per-file `# pyright:` relax pragma that turns off only the unknown-type / untyped-third-party rules — those libs ship no usable types, so strict typing there fights the ecosystem. Pure-logic files stay fully strict; `typings/piexif/__init__.pyi` is a local stub so `metadata.py`/`extractor.py` resolve piexif. Public ndarray-returning signatures on the relaxed engines are still annotated `NDArray[Any]` so strict consumers (`cli.py`) stay clean. When touching a relaxed file, prefer fixing real issues over widening the pragma; keep the pragma scoped to genuinely-untyped boundaries. (`uv-secure` is clean since idna was bumped 3.11 -> 3.16, fixing GHSA-65pc-fj4g-8rjx, and aiohttp 3.13.5 -> 3.14.0 via `uv lock --upgrade-package aiohttp`, fixing GHSA-hg6j-4rv6-33pg + GHSA-jg22-mg44-37j8. (The old basicsr Dependabot alert (GHSA-86w8-vhw6-q9qq) is resolved by removal: the experimental `restore` extra was retired and basicsr is no longer anywhere in the dependency tree.) The torch Dependabot alert **GHSA-rrmf-rvhw-rf47** (`torch.jit.script` memory corruption, vulnerable `<= 2.12.0`) is **dismissed as `not_used`** (2026-06-10): torch is a transitive dep of the optional `gpu` extra only, the codebase never calls `torch.jit` (grep-verified), and **no patched torch version exists** (`first_patched_version` is null), so it cannot be closed by an upgrade — do not re-triage it.
 - **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.
+- **Stale `trustmark` remnant in site-packages after an extras change:** the `trustmark` package downloads model weights INTO its own package dir, so when a narrower `uv sync` prunes the package, a `trustmark/models/` directory survives as an empty namespace package. Symptom: pyright `"TrustMark" is unknown import symbol` on `trustmark_detector.py` and `find_spec("trustmark")` returning a loader-less spec (so `is_available()` lies True). Fix: `rm -rf .venv/lib/python3.12/site-packages/trustmark` (regenerable weights cache).
 - 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. **`cleaned/` examples must be produced by a CURRENT shipped removal method** -- the default SDXL img2img pass (optionally `--max-resolution`). Do NOT archive cleaned outputs from methods that are no longer in the pipeline (ctrlregen, the old text/face-protection, IP-Adapter FaceID, CodeFormer) or from the experimental opt-in paths (controlnet, face restore) as corpus examples; a cleaned reference should represent the canonical removal, and a removed method's output is not a reproducible example. Keep those experiment outputs in a local working dir, never in the committed corpus.
@@ -28,66 +31,46 @@ You are a **principal Python engineer** maintaining a CLI tool and library for r
 - GPU/ML modules (invisible_engine, watermark_remover) are optional — guard imports with `is_available()` checks
 - Optional detection extras: `detect` (imwatermark — open SD/SDXL/FLUX watermark) and `trustmark` (Adobe TrustMark decoder; pulls torch + downloads weights). Both are guarded by `is_available()` and skipped by `identify` when absent.
 - Optional `esrgan` extra (spandrel only): Real-ESRGAN pre-diffusion super-resolution for small inputs (`upscaler.py`, CLI `--upscaler esrgan` on `invisible`/`all`/`batch`). Guarded by `upscaler.is_available()`; the default upscaler stays Lanczos (cv2, no deps) and the engine falls back to Lanczos when the extra is absent or the model errors. spandrel is MIT and pulls NO basicsr (only torch/torchvision/safetensors/numpy/einops); Real-ESRGAN weights are BSD-3-Clause and download on first use via `torch.hub` (never bundled). Kept OUT of `all` (heavy + model download).
-- Tests for the *model-running* paths are limited to availability checks (multi-GB downloads). But the **pure helpers inside ML-adjacent modules are unit-tested without any download** and must stay that way: `_target_size` (native-vs-downscale-cap-vs-upscale-floor, `test_invisible_engine.py`), `humanizer.unsharp_mask`/`adaptive_polish` (`test_humanizer.py`), `auto_config.plan`/detectors (`test_auto_config.py`), and the MPS->CPU fallback control flow via mocked pipelines (`test_img2img_runner.py`, 100% cover). Don't skip these as "ML, needs a model" — only `remove_watermark`/the diffusion bodies do.
+- Tests for the *model-running* paths are limited to availability checks (multi-GB downloads). But the **pure helpers inside ML-adjacent modules are unit-tested without any download** and must stay that way: `_target_size` (native-vs-downscale-cap-vs-upscale-floor, `test_invisible_engine.py`), `humanizer.unsharp_mask`/`adaptive_polish` (`test_humanizer.py`), and the MPS->CPU fallback control flow via mocked pipelines (`test_img2img_runner.py`, 100% cover). Don't skip these as "ML, needs a model" — only `remove_watermark`/the diffusion bodies do.
 
 ## Key modules
 
-- `noai/c2pa.py` — PNG chunk parser; use `extract_c2pa_chunk(path)` to get raw caBX payload, `has_c2pa_metadata(path)` to detect. Do not reimplement chunk parsing. `extract_c2pa_info(path)` sets `synthid_watermark`/`synthid_vendors` when the manifest is signed by a SynthID-using vendor, and `soft_binding`/`soft_binding_vendors` when a `c2pa.soft-binding` `alg` names a forensic-watermark vendor (`soft_binding_vendors_in(buffer)` is the shared byte-scan, used by both the PNG parser and the non-PNG binary path). PNG/caBX chunk reads are clamped to the remaining file size (`safe_length = min(length, remaining)`; skipped chunks use seek) so a malformed huge `length` cannot drive a multi-GB allocation (shared safety discipline matching `isobmff.scan_c2pa_region`).
-- `noai/constants.py` — PNG_SIGNATURE, C2PA_CHUNK_TYPE, C2PA_SIGNATURES, and `C2PA_AI_VENDORS` — the single `C2paAiVendor` registry of C2PA-signing vendors (issuer byte, resolved org name, the `identify` platform label, and a `synthid` flag), from which `C2PA_ISSUERS`, `SYNTHID_C2PA_ISSUERS` (issuers that pair SynthID with C2PA: Google, OpenAI), and `identify._ISSUER_PLATFORM` are all **derived** — plus `C2PA_SOFT_BINDINGS` (soft-binding `alg` prefix → forensic-watermark vendor: Adobe TrustMark, Digimarc, Imatag, Steg.AI, Microsoft, ...). Add a new C2PA vendor as one `C2PA_AI_VENDORS` entry (never edit the derived dicts), a new soft-binding to `C2PA_SOFT_BINDINGS`; not inline.
-- `metadata.py` — `scan_head(path, size=1MB)` is the shared input for every C2PA/AIGC/IPTC byte scan: first `size` bytes plus the payloads of any provenance metadata found beyond that window — for ISOBMFF, the late provenance boxes from `isobmff.scan_c2pa_region` (catches a manifest after a large `mdat`); for **PNG**, the late `tEXt`/`iTXt`/`zTXt`/`eXIf`/`iCCP` chunks from `_png_late_metadata` (catches an XMP/EXIF packet appended after a large `IDAT`, e.g. a TC260 AIGC label at ~2.7 MB). Behavior-neutral (`f.read(size)`) for non-ISOBMFF inputs and for any file that fits within `size`. Use it instead of `open().read(1MB)` for any new marker scan. `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 / Samsung Galaxy AI "Contenuti generati dall'AI" text marks via the `watermark_registry` — open invisible watermark, Adobe TrustMark via `trustmark_detector`) into one `ProvenanceReport`. `is_ai_generated` is True or None (never asserted False — stripped metadata is not proof of clean origin). The `hf_job`, visible-mark, and Samsung `samsung_genai` signals are **medium** confidence: each lifts an otherwise-Unknown verdict to a tentative AI (`hf_only` / `visible_only` / `samsung_only`, parallel branches; `visible_only` fires on any `visible_*` signal) but is excluded from the high-confidence `ai_from_metadata` set, so none overrides a hard metadata signal. **Visible-mark detection** (`check_visible`, signals `visible_sparkle` / `visible_doubao` / `visible_jimeng` / `visible_samsung`): the Gemini sparkle keeps its own file-level path (`_visible_sparkle` → `gemini_engine.detect_sparkle_confidence`, promoted only at confidence ≥ `_SPARKLE_THRESHOLD` 0.5; corpus-tuned to separate Gemini sparkles ≥0.56 from non-sparkle ≤0.49), while Doubao/Jimeng/Samsung reuse the registry detectors (`_visible_text_marks` → `watermark_registry`, iterating `_VISIBLE_MARK_PLATFORM`), each gated by its own engine NCC threshold via `MarkDetection.detected` (Doubao 0.4, Jimeng 0.45, Samsung 0.4). Doubao/Jimeng are normally also caught by the TC260 AIGC metadata label and Samsung by its C2PA + `genAIType` marker, so the visible path is their stripped-metadata fallback. Visible marks set `platform` only when no harder signal already did, and (like the sparkle) are excluded from integrity-clash vendor claims. The cv2 dependency lives in the engines, not here. **`import identify` is deliberately light** (~21 MB; ~36 MB with cv2 loaded by a visible-mark run, ~106 MB for a full `check_visible` run): it imports only the pure `noai.c2pa`/`noai.constants` submodules, and `noai/__init__` is lazy (see "Test and lint"), so torch/diffusers are NOT pulled at import even in a full `gpu`/`detect` install — fits a 512 MB host. The heavy paths are opt-in: `check_invisible=True` needs the `detect`/`trustmark` extras (each pulls **torch**; TrustMark also **downloads weights**), so on a core-only deploy leave `check_invisible` off (it is a no-op there anyway). Before the lazy `__init__`, the mere presence of torch in the env inflated `import identify` to ~420 MB. **C2PA platform attribution is device-token-first, issuer-scan fallback** (`_device_platform` scans manifest bytes for `_DEVICE_C2PA_PLATFORM` tokens, then `_attribute_platform`/`_ISSUER_PLATFORM`). **Why, verified on real signed files 2026-05-26:** the old issuer-only byte-scan matched ANY issuer substring anywhere, so multi-entity manifests mis-attributed -- Leica→"Truepic" (a signing authority in the trust chain), Nikon→"Adobe Firefly" (XMP-toolkit "Adobe" + the sample's "Adobe_MAX" name), Pixel→"Google (Gemini)" ("Google LLC" cert org), Truepic→"Google". A distinctive device token wins instead. **Token distinctiveness is load-bearing:** bare `b"Truepic"` mis-fires (it appears in unrelated trust chains -- it mis-attributed the OpenAI `chatgpt-1.png` fixture), so the token is the specific `b"Truepic_Lens"` from the Lens SDK claim generator; likewise `b"Pixel Camera"` (cert CN) not bare `b"Pixel"`. `_DEVICE_C2PA_PLATFORM` lists ONLY tokens **verified against a real C2PA file**: Leica (`lc_c2pa`/`Leica Camera`), Nikon (`NIKON`), Pixel (`Pixel Camera` -- from a real Pixel 10 Pro file attached to c2pa-rs issue #1609/#1554), Sony (`sony.sig`/`sony.cert` -- Sony's own C2PA assertion namespace, verified on a real Sony PXW-Z300 file; NOT bare "Sony" which is a common EXIF Make), Truepic (`Truepic_Lens`). Canon/Bria have **no public direct-download C2PA sample** (checked exhaustively: GitHub issue/PR attachments, contentcredentials gallery, HF datasets -- all upload-to-verify or token-gated; Canon's only public file was a self-signed hobbyist CR3, not factory), so they stay unmapped until a real file is captured (same fixture discipline as Grok/Doubao). The Sony sample is video (MP4) -- our ISOBMFF C2PA path detects it; Sony Alpha stills likely share the `sony.*` namespace but are not separately verified. **Samsung Galaxy + ASUS Gallery live in a separate `_SIGNER_C2PA_PLATFORM` (scaLine truncated
-- `watermark_registry.py` — **single catalog of known visible watermarks**, the unified "find known marks in their usual places, recognize, remove" entry. **Reverse-alpha based by policy**: a mark is listed only once a real alpha map has been captured for it, and removal inverts that map (`original = (wm - a*logo)/(1-a)`) — Gemini recovers cleanly with no inpaint (its sparkle alpha comes from a pure-black capture, so it is near-exact), while **Doubao, Jimeng, and Samsung all add an always-on THIN residual inpaint** over the glyph footprint (their text marks re-rasterize + jitter a few px per image, so a single capture cannot pixel-cancel them; the inpaint blends into the reverse-alpha-recovered pixels). Arbitrary-region inpainting still lives in `region_eraser`/`erase`. Each `KnownMark` ties a key to {usual `location`, `in_auto` flag, `recovery` (="reverse-alpha"), a `detect` adapter → uniform `MarkDetection`, a `remove` adapter}. Entries today: `gemini` (bottom-right sparkle), `doubao` (bottom-right "豆包AI生成"), `jimeng` (bottom-right "★ 即梦AI"), and `samsung` (bottom-**LEFT** "✦ Contenuti generati dall'AI", Samsung Galaxy AI, Italian locale). `detect_marks` scans all; `best_auto_mark` picks the highest-confidence detection. **Cross-engine confidences aren't directly comparable**, so the gemini adapter applies the corpus-validated 0.5 sparkle threshold (`_GEMINI_AUTO_MIN_CONF`) for its `detected` flag — otherwise the gemini engine's loose internal threshold weakly fires (~0.36) on the Doubao text and hijacks `auto`. The shape-keyed Doubao/Jimeng/Samsung NCC detectors don't cross-fire (jimeng scores ~0.22 on the Doubao strip, well under its 0.45 threshold; Samsung is bottom-left so it shares no corner with the others, and scored 0.0 on Doubao/Jimeng captures and they 0.0 on a real Samsung photo), so `auto` picks the right one. `cli.cmd_visible` is registry-driven: `--mark auto` → `best_auto_mark`, `--mark <key>` → that mark; `--mark` choices come from `mark_keys()`. `_doubao_remove`/`_jimeng_remove`/`_samsung_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. **Detection localization (issue #36):** `detect_watermark`'s global multi-scale NCC search applies a size weight (`(scale/96)**0.5`) that suppresses tiny-patch false positives but can let a larger, mediocre match (e.g. a bright collar in a portrait) outrank a small, near-perfect sparkle in the corner — so a faint sparkle on a busy background scored below threshold and read as clean (the regression osachub reported from widening the search window 256px->512px between v0.7.2 and v0.8.8). `_corner_promote` adds a bottom-right-corner raw-NCC pass on top of the global search: a match with raw NCC >= `_CORNER_PROMOTE_NCC` 0.85 that beats the global pick overrides it (it only ever replaces a lower-fidelity pick, so it cannot weaken an existing detection), rescuing the buried sparkle without reverting the wider window. The corner side is **relative-clamped** (`_CORNER_PROMOTE_FRAC` 0.20 of the short side, clamped to `[_CORNER_PROMOTE_MIN` 96, `_CORNER_PROMOTE_MAX` 384`]`): a fixed 256px is a true corner on a large image but covers ~70% of a small portrait, where a real photo raw-matches the star at ~0.81 (relative tightening drops that worst case to ~0.69, while the upper clamp stops the corner ballooning on huge images where a real photo reached ~0.83 at 512px). The 0.85 gate sits midway between the worst real-photo corner match (~0.78 across native + downscaled negatives) and a genuine faint sparkle (~0.93), so promotion adds true detections with zero corpus false positives (Gemini's sparkle sits ~60-160px from the corner at fixed margins, covered by the [96, 384] band at every measured size). Regression-guarded by `test_gemini_engine.py::TestCornerPromotion`. **Removal is reverse-alpha with an over-subtraction guard** (`remove_watermark` → `_reverse_alpha_blend`, else `_inpaint_footprint`): the sparkle alpha is computed (`alpha = max(R,G,B)/255`) from the bundled sparkle-on-black captures `assets/gemini_bg_{96,48}.png` (the capture max is ~130, NOT 255 — the sparkle is a ~51%-opaque white overlay, so `alpha` maxes at ~0.51, which is CORRECT for the capture, not under-exposed). The alpha is near-exact only when the real mark's effective opacity matches the capture, which holds on bright/flat backgrounds — re-verified clean on `demo_banana_before.png` 2026-05-31. **Issue #30 (dark-background black pit):** on a dark/textured background (e.g. grass, ~73) the real sparkle's effective opacity is LOWER than the captured 0.51, so the fixed-alpha reverse blend OVER-subtracts (`watermarked - a*logo` goes negative) and drives the footprint to black — the white sparkle becomes a black diamond. `remove_watermark` now detects this via `_reverse_alpha_oversubtracts` (fraction of footprint pixels with `alpha >= _FOOTPRINT_ALPHA` 0.1 whose numerator < 0 exceeds `_OVERSUB_FOOTPRINT_FRAC` 0.05) and **inpaints the footprint** (`_inpaint_footprint`, cv2 NS over the dilated alpha mask) from the surrounding pixels instead. **Behavior-neutral on the working case:** a bright background over-subtracts at ~0% so reverse-alpha is used and the output is byte-identical to before (verified: demo_banana 0.0 frac vs issue-#30 grass 0.61 frac; regression-guarded by `test_gemini_engine.py::TestOverSubtractionGuard`, which composites the sparkle at a reduced effective alpha to reproduce the mismatch). **Under-subtraction (the symmetric case, fixed 2026-06-03):** some real Gemini sparkles are rendered MORE opaque than the captured ~0.51, so the fixed-alpha reverse blend UNDER-subtracts and leaves a bright sparkle residual the detector still fires on (measured on the spaces corpus: a visible-removal audit through the registry path left a detectable sparkle on a meaningful fraction of marks, all under-removals, NOT a background-brightness class — failures and successes had the same input confidence and the same background-luma distribution; the discriminator was the removal delta itself). `remove_watermark` now estimates a per-image alpha gain (`_estimate_alpha_gain`: effective sparkle opacity at the bright core vs the local background ring, `a_eff/a_cap`, clamped `[1.0, _ALPHA_GAIN_MAX` 1.94`]`) and scales the alpha to match before the over-sub/blend branch. The gain cleanly separates on the corpus (under-removed marks ~1.47, cleanly-removed ~1.00), and a deadband (`_ALPHA_GAIN_DEADBAND` 1.05) keeps a matching sparkle **byte-identical** to the pre-fix output, so the fix is purely additive (0 regressions on the audit set; the over-sub guard still runs on the scaled alpha as the safety net for an over-shooting estimate). Regression-guarded by `test_gemini_engine.py::TestUnderSubtractionGain` (composites a more-opaque-than-captLine truncated
-- `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.
-- `samsung_engine.py` — visible Samsung Galaxy AI "✦ Contenuti generati dall'AI" remover/detector (cv2/numpy, no GPU), built 2026-06-05 from issue #37's flat captures (@f-liva). Mirrors `jimeng_engine` but anchored **bottom-LEFT** (Doubao/Jimeng are bottom-right): `locate` anchors a bottom-left box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma — `LOGO_MIN_LUMA` is lowered to **110** because the mark is faint, peak alpha ~0.38, so on a mid/dark background its glyph luma is lower than Jimeng's), `detect` matches the bundled glyph silhouette (`assets/samsung_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.40** (real marks ~0.79 on a real photo, ~0.57/0.71 on the black/gray captures; 0.0 on Doubao/Jimeng captures, and Doubao/Jimeng score 0.0 on a real Samsung photo — no cross-fire, also because the corner differs). **Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; white capture confirms). **Alpha solved by `scripts/visible_alpha_solve.py samsung` from the GRAY capture** (`data/samsung_capture/captures/`, the flat black/gray/white captures committed; the solver gained a `corner="bl"` mode + left-margin logging for this), same careful recipe as Jimeng (cubic background, mean-channel, full halo, unblurred). Geometry emitted at `_ALPHA_NATIVE_WIDTH` **1086** (the flat-edit capture width): `_ALPHA_WIDTH_FRAC` 0.3195, `_ALPHA_HEIGHT_FRAC` 0.0378, `_ALPHA_MARGIN_LEFT_FRAC` 0.0110, `_ALPHA_MARGIN_BOTTOM_FRAC` 0.0064. **Removal = reverse-alpha + a deliberately THIN residual inpaint** (`remove_watermark_reverse_alpha`, same `_RESIDUAL_*` recipe as Jimeng) with **always-try fixed AND `_aligned_alpha_map` NCC scale+position search, keep the lower-residual** (`_ALPHA_ALIGN_SEARCH` widened to (0.85, 1.18, 23) because the flat captures are far off the real-photo width). **Resolution caveat:** the flat captures arrived at 1086 wide while real photos are ~2958 wide (the mark scales with width, so the captured glyph ~334px is ~2.7x smaller than the ~903px real-photo glyph); width-scale + NCC-align still removes it cleanly (verified on a real 2958-wide @f-liva photo: re-detect 0.79→0.00, no readable text or outline on the recovered wooden table — checked **visually**, not just by the detector, per the Gemini self-verify lesson), but a flat capture at the real photo resolution would make the alpha pixel-sharp instead of upscaled (open quality upgrade, noted in `data/samsung_capture/README.md`). **The mark is locale-specific** (text differs per language); this build is the Italian "Contenuti generati dall'AI" variant — other locales need their own captured template. `reverse_alpha_available` is just "asset present"; the registry gates on `detect`. **No committed real sample** (the real photo stays gitignored; only the flat calibration captures are committed) — `tests/test_samsung_engine.py` synthesizes a mark from the bundled alpha asset (bottom-left geometry), with `test_recovers_shifted_mark_on_texture` guarding the align-on-shift path. Samsung Galaxy AI edits are independently caught by C2PA + the `genAIType` marker in `metadata`/`identify`, so this engine is the visible-mark *removal* path; it also feeds `identify` as the medium-confidence `visible_samsung` signal via the registry (the stripped-metadata fallback).
-- `region_eraser.py` — universal region eraser (`erase` CLI). `erase(image, boxes=|mask=, backend=)` accepts grayscale (2D) and RGBA (4-channel) inputs on **both** backends (`erase_cv2` and `erase_lama` each split off any alpha plane and re-attach it unchanged, and promote grayscale to BGR for processing — LaMa would otherwise crash on grayscale and drop alpha on BGRA): `boxes_to_mask` → `cv2.inpaint` (`cv2` backend, default, no deps) or big-LaMa via onnxruntime (`lama` backend, extra `lama`, `Carve/LaMa-ONNX` Apache-2.0 model downloaded on first use, never bundled). `erase_lama` crops a padded region around the mask, runs LaMa at its fixed 512² input, pastes only masked pixels back (untouched areas stay pixel-exact). Lazy `_get_lama_session` singleton; `lama_available()` guards the optional import. **LaMa-ONNX costs ~3.5-4 GB peak RAM and ~5-6 s/call on CPU** (FFC working set, not arena — `enable_cpu_mem_arena=False` does not help), so it does NOT fit a minimal droplet; the cv2 backend (tens of MB, ~30 ms) does. LaMa quality at low RAM = serverless/GPU, mirroring how raiw.cc offloads SDXL to fal.
-- `invisible_watermark.py` — `detect_invisible_watermark(path)` decodes the OPEN DWT-DCT watermarks (public decoder, no key) embedded by Stable Diffusion / SDXL / FLUX via the `imwatermark` library. Known fixed patterns (verified against upstream source) live in `_BITS_48` (SDXL 48-bit, FLUX.2 48-bit) and `_SD1_STRING` ("StableDiffusionV1", SD 1.x/2.x). Optional dep (extra `detect`); returns None when absent. The `detect` extra pulls **torch** transitively (invisible-watermark declares torch a hard dep, and `WatermarkDecoder` eagerly imports `rivaGan` -> `torch` at import time), so detection needs torch present even though dwtDct runs CPU-only on cv2/numpy/pywavelets — no GPU and no separate `gpu` extra required. **Unlike SynthID this is locally detectable**, but the watermark is fragile (does not survive JPEG re-encode/resize — verified gone after JPEG q90), so it confirms origin only on pristine files. Add new known patterns here. The file carries a top-of-module pyright pragma because imwatermark/cv2 ship no type stubs.
-- `trustmark_detector.py` — `detect_trustmark(path)` decodes the OPEN, keyless **Adobe TrustMark** watermark (the soft binding behind Adobe Durable Content Credentials, `alg` `com.adobe.trustmark.P`) via the optional `trustmark` package (extra `trustmark`; pulls torch, downloads model weights on first use). Mirrors `invisible_watermark.py` (lazy singleton guarded by a double-checked `threading.Lock` so concurrent callers do not double-download the weights, top-of-module pyright pragma, returns None when absent). It detects *provenance*, not AI origin as such (TrustMark also marks human-authored content), so `identify` lists it as a watermark without setting `is_ai_generated`. Other soft-binding vendors (Digimarc/Imatag/Steg.AI/...) have no public decoder — they are only *named* via the `C2PA_SOFT_BINDINGS` scan, not decoded. **False-positive gate (added 2026-05-29):** TrustMark's `wm_present` is a BCH error-correction validity flag that spuriously validates on a content-correlated fraction of un-watermarked images — AI-generated textures trip it far more than camera photos (verified 2026-05-29 on real files: it fires on Gemini/OpenAI/Doubao output that *cannot* carry Adobe's watermark, with a random-bytes decoded secret, while signal-free camera photos did not trip it). A genuine TrustMark is a *durable* soft binding engineered to survive re-encoding, so `detect_trustmark` re-decodes after a mild JPEG round-trip (`_survives_reencode`, `_REENCODE_QUALITY` 95) and requires the same schema both times; every observed false positive collapsed (none survived even q95), so the gate is the durability property the watermark guarantees. The second decode runs only on the rare initial hit, so the cost is negligible. Do NOT remove the gate to "catch more" — a lone TrustMark hit without it is almost always content noise.
-- `noai/watermark_remover.py` — the `WatermarkRemover` class has two diffusion pipelines, selected by the explicit `pipeline` ctor arg (NOT inferred from `model_id` -- both use the same SDXL base, `DEFAULT_MODEL_ID`). **`default`** runs plain SDXL img2img (`_run_img2img`). **`controlnet`** (**EXPERIMENTAL, opt-in**; `_run_controlnet`, `_load_controlnet_pipeline`) runs `StableDiffusionXLControlNetImg2ImgPipeline` with the SDXL-native canny ControlNet `xinsir/controlnet-canny-sdxl-1.0` (`watermark_profiles.CONTROLNET_CANNY_MODEL`): the control image is `cv2.Canny(gray, 100, 200)` stacked to 3 channels (`_CANNY_LOW`/`_CANNY_HIGH`, prompt `_CONTROLNET_PROMPT` / `_CONTROLNET_NEGATIVE`). **Removal comes from the img2img regeneration (`strength`); the ControlNet only PRESERVES text and face STRUCTURE via the edge map.** No original pixels are copied or frozen, BUT **validation 2026-06-04 disproved the old "so SynthID does not survive" claim: SynthID CAN survive controlnet on photoreal/high-detail content.** At the shared low removal strength the canny edge-conditioning keeps the regeneration so close to the original that the pixel perturbation that destroys SynthID does not happen (oracle-confirmed: an OpenAI bracelet photo + a 9-face grid read **SynthID-detected** after controlnet at strength 0.10/0.15, but **SynthID-not-detected** after the `default` pipeline at the SAME strength + resolution -- only the pipeline differed). **But the reverse also holds: a flat-graphic logo/poster SURVIVED `default` while clearing controlnet** -- removal at the low strength is content×pipeline dependent and neither pipeline is universally safe; the real lever is a higher strength. See the controlnet Known-limitations bullet for the full table + root cause. Canny holds face STRUCTURE but NOT identity (the regenerated face drifts in likeness -- canny carries edges, not identity). The drifted cleaned face is the LEAST-AI state we can reach without re-introducing SynthID; the library does NOT ship a face-restore extra. Every restore approach we evaluated (GFPGAN-on-cleaned, PhotoMaker-V2 txt2img, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps, 2026-06-04 - 2026-06-08 Modal cert sweeps) regenerated the face from an ArcFace embedding via SDXL diffusion -- which makes the output face look MORE AI-generated, not less. Empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up". For production face preservation, ship the cleaned image as-is. `controlnet_conditioning_scale` (ctor arg, default 1.0) is the structure-preservation knob. Same dtype rule as `default` (fp32 on cpu/mps, fp16 only on cuda/xpu; the fp16-fixed SDXL VAE `_SDXL_FP16_VAE_ID` is swapped in on fp16 GPUs -- issue #29) and the same MPS->CPU fallback (reload on cpu/fp32, drop a non-cpu generator, retry once).
-- `auto_config.py` — the `--auto` quality-mode planner (EXPERIMENTAL). `plan(image_path) -> AutoConfig | None` inspects the INPUT image (before the diffusion model loads) and picks the pipeline modes, so the run adapts to content. **Designed to run as the FIRST step of the invisible/all pipeline, wherever that runs** — locally or the raiw.cc Modal GPU worker — **never on the 512 MB web host** (image work there OOM-crashes the container; the planner is `_apply_auto` in `cli.py` for the CLI, and raiw-app would call `plan()` inside `RaiwProtect.remove`). **Quality-priority routing:** ControlNet (text/face-structure preservation) is the default; it is skipped for `default` (plain SDXL) only on a clearly structure-less image (`not has_face and not has_text and edge_density < _STRUCTURELESS_EDGE_MAX` 0.008). **CAVEAT (oracle-validated 2026-06-04, see the controlnet Known-limitations bullet): at the low vendor-adaptive strength NEITHER pipeline removes SynthID on all content -- it is content×pipeline dependent (photoreal SURVIVES controlnet / clears default; flat graphics SURVIVE default / clear controlnet; flat text clears both). So `--auto` picking controlnet for faces/photos leaves SynthID on exactly those, and plain `default` would leave it on flat graphics -- pipeline choice alone does NOT guarantee removal. The real lever is a HIGHER strength, oracle-validated per content type. Removal-priority callers (raiw.cc) must oracle-validate strength across content types BEFORE adopting auto; the "must keep SynthID removed" gate in the adoption note below is the blocker this caught.** When the controlnet smoothing pipeline ran, the **adaptive polish** (`humanizer.adaptive_polish`) is applied: it targets the input's Laplacian variance (detail level) with a capped unsharp + edge-masked grain, restoring photo/face texture while **sparing text** (text is already high-frequency, so the deficit is tiny and almost no polish lands -- the old fixed unsharp/grain speckled small text; validated 2026-06-03 on gemini_3 lap-var 84->334 toward the 592 original, openai_1 text near-untouched). **Detection is cv2-only and torch-free** (~100 MB peak RSS, a few ms — measured): OpenCV **YuNet** (`cv2.FaceDetectorYN`, MIT, 232 KB model bundled at `assets/face_detection_yunet_2023mar.onnx`) for faces, **DBNet** (PP-OCRv3 differentiable-binarization via `cv2.dnn.TextDetectionModel_DB`, a 2.4 MB Apache-2.0 model bundled at `assets/text_detection_ppocrv3_2023may.onnx`) for text, with the old Canny+MSER region heuristic kept as a fallback if the DBNet model can't load (`_detect_text_dbnet` returns None → `_detect_text_mser`). The en/cn opencv_zoo PP-OCRv3 detection models are byte-identical, so it is bundled language-neutral. Text only ever ADDS controlnet, so a miss is backstopped by edge-density and a false positive only costs a controlnet run. Plus `edge_density`. `min_resolution` stays 1024. **Every auto decision is independently overridable** (interface principle): `_apply_auto` (cli.py) overrides only the content-adaptive modes the user left at their click default (`ctx.get_parameter_source(...) == DEFAULT`) — `--pipeline` and **`--adaptive-polish`/`--no-adaptive-polish`** always win; `--min-resolution`/`--strength`/`--unsharp`/`--humanize` are independent knobs. `--adaptive-polish` also works WITHOUT `--auto` (manual detail-targeted polish; the engine's `adaptive_polish` param uses the full-res original as the detail reference). Prints the chosen plan (`AutoConfig.reason`). Wired into `cmd_all`/`cmd_invisible`/`cmd_batch` — in `batch` the plan is recomputed per image and the invisible engine is cached **per resolved pipeline** (`ctx.obj["_inv_engines"]`, keyed `default`/`controlnet`) instead of a single shared instance, so a mixed directory builds at most one engine of each kind. **Adds ZERO new pip deps** (all cv2 core + the bundled MIT YuNet + Apache-2.0 DBNet models + the cv2-only adaptive polish). The auto plan does NOT select the `esrgan` upscaler (that needs the optional extra and would make auto's behavior install-dependent); `--upscaler esrgan` stays a separate manual knob. Unit-tested without a heavy download (`tests/test_auto_config.py`): flat/text synthetic images for routing (the bundled DBNet fires on a real text card), monkeypatched `detect_face`/`_detect_text_dbnet`/`_detect_text_mser` for the face/text/fallback branches (a real detectable-face fixture is private, never committed). Production adoption path for raiw.cc: validate (must keep SynthID removed, not hallucinate micro-text, beat plain SDXL on the real upload distribution), then bump the library SHA in `modal_app.py` and pass `auto=True`.
-- `upscaler.py` — optional Real-ESRGAN pre-diffusion super-resolution for small inputs (spandrel boundary, top-of-file pyright pragma). `is_available()` gates on spandrel+torch (via `importlib.util.find_spec`); `upscale(bgr, device=None)` loads a lazily-built spandrel `ImageModelDescriptor` singleton (double-checked lock) and upscales by the model's native factor (x2), with a non-CPU→CPU device fallback mirroring the diffusion engine's MPS→CPU retry. Weights (`RealESRGAN_x2plus.pth`, BSD-3-Clause) download on first use to the `torch.hub` checkpoints cache; never bundled. Used only when UPscaling to the `min_resolution` floor (a `max_resolution` downscale always uses Lanczos). The wiring is `InvisibleEngine._esrgan_upscale(pil, target)` — Real-ESRGAN at native factor, then a Lanczos resize to the exact target, falling back to a plain Lanczos resize if the extra is absent or the model errors (so an optional upscaler can never break removal). The default `--upscaler` is `lanczos` (cv2, no deps). **ESRGAN is a generic photo/texture GAN with no face/glyph prior**, so it best fits photo/texture content and can degrade faces (glassy/asymmetric eyes -- the diffusion pass regenerates faces so the full-pipeline final recovers) and thin/small text (the GAN invents wrong strokes, and low-strength diffusion will not fix it). Verified 2026-06-04: isolated upscale lap-var ~5x Lanczos on faces+textures but glassy eyes; end-to-end `invisible` final lap-var 1634 vs Lanczos 663 with natural faces (diffusion cleaned the artifact). Kept a **manual opt-in knob** (the auto plan never selects it) with `lanczos` the default; not content-gated by design (use Lanczos for text-heavy inputs). spandrel is MIT and pulls no basicsr. Unit-tested without the model: `tests/test_upscaler.py` (availability guard + the not-installed RuntimeError) and `tests/test_invisible_engine.py::TestEsrganUpscale` (the three `_esrgan_upscale` branches via a monkeypatched `upscaler`).
-- `image_io.py` — Unicode-safe cv2 IO (issue #17). `imread(path, flags=None)` / `imwrite(path, img)` wrap `np.fromfile`+`cv2.imdecode` / `cv2.imencode`+`tofile` so non-ASCII paths work on Windows -- bare `cv2.imread`/`cv2.imwrite` use the platform ANSI code-page API there and fail (empty decode + `can't open/read file`) on Chinese/Cyrillic/accented filenames. `imread` keeps `cv2.imread` semantics (defaults to `IMREAD_COLOR`, returns `None` on missing/empty/undecodable). **Every cv2 file read/write in the package routes through here; do not call `cv2.imread`/`cv2.imwrite` directly.** `imwrite` returns `False` on an unwritable path (`OSError` caught) instead of raising, matching `cv2.imwrite` semantics. macOS/Linux already accept UTF-8 paths, so it is behavior-neutral there (the bug only reproduces on Windows). cv2/numpy are imported lazily inside the functions, so the module is cheap to import in a bare env.
+Compact map. The full per-module detail (design decisions, tuned thresholds, calibration history, incident records, and the regression-guard map) lives in `docs/module-internals.md` — **read the relevant section there before changing any module below.**
 
-### Doubao clean-reverse-alpha distillation (re-investigated 2026-05-29)
+- `noai/c2pa.py` — PNG caBX chunk parser (`extract_c2pa_chunk` / `has_c2pa_metadata` / `extract_c2pa_info`). Do not reimplement chunk parsing; chunk reads are clamped to the remaining file size by design.
+- `noai/constants.py` — the single `C2PA_AI_VENDORS` registry (+ `C2PA_SOFT_BINDINGS`) from which `C2PA_ISSUERS` / `SYNTHID_C2PA_ISSUERS` / `identify._ISSUER_PLATFORM` are all derived. Add a new vendor as one registry entry; never edit the derived dicts and never add inline.
+- `metadata.py` — `scan_head(path)` is the shared (memoized) input for every C2PA/AIGC/IPTC byte scan; use it instead of `open().read(1MB)` for any new marker scan. Also home to `synthid_source`, `xai_signature`, `iptc_ai_system`, `aigc_label`, `huggingface_job`, `samsung_genai`, and `remove_ai_metadata` (fail-safe `strip_c2pa_boxes`).
+- `identify.py` — aggregates every locally-readable signal into one `ProvenanceReport`; `is_ai_generated` is True or None, never asserted False. `import identify` is deliberately light (lazy `noai/__init__`, fits a 512 MB host) — keep heavy imports out. Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM` only when verified against a real C2PA file; editing-app/AI-device signer tokens go to `_SIGNER_C2PA_PLATFORM`; generator/issuer platforms to `C2PA_AI_VENDORS` in `constants.py`. Integrity-clash detection is high-precision by design (only hard generator stamps feed it, source-grouped independence).
+- `watermark_registry.py` — the single catalog of known visible watermarks (gemini / doubao / jimeng / samsung), reverse-alpha based by policy. Add a new visible text mark = one `_text_mark(...)` row + a `TextMarkConfig` with a captured alpha map; do not re-add per-mark `if` branches. `cli._write_bgr_with_alpha` must NOT zero alpha in the watermark bbox (issue #30 white-box regression).
+- `gemini_engine.py` — visible Gemini-sparkle remover/detector (cv2/numpy, no GPU): top-K size-weighted fusion candidate selection (`_SELECT_TOPK`), corner-promote, over/under-subtraction guards, false-positive gate, self-verify repair. Detection scores the top-K size-weighted matches by full fusion (spatial+gradient+variance) and keeps the highest — NOT the raw-NCC argmax, which re-admits the tiny-patch FPs the size weight suppresses (the osachub 2026-06-12 sub-0.85 corner-sparkle regression; see `docs/module-internals.md`). Keep the 0.85 corner-promote NCC gate; a margin/chroma-gated lower promote was measured and REJECTED 2026-06-11 (~33% FP on non-Google content). Gate any removal candidate on a physical brightness check, not the detector alone.
+- `_text_mark_engine.py` — shared base for the three reverse-alpha text-mark engines (extracted 2026-06-09); the per-engine modules are config-only subclasses. New text mark = a `TextMarkConfig` + a thin subclass + one registry row. Gemini stays a separate engine (different model).
+- `doubao_engine.py` / `jimeng_engine.py` / `samsung_engine.py` — thin `TextMarkEngine` subclasses: Doubao "豆包AI生成" (bottom-right), Jimeng "★ 即梦AI" (bottom-right), Samsung Galaxy AI "✦ Contenuti generati dall'AI" (bottom-LEFT, locale-specific — Italian variant calibrated). Removal = reverse-alpha (always-align) + thin residual inpaint. A detector-only removal test is insufficient — assert visual residual (the textured-shift tests).
+- `region_eraser.py` — universal region eraser (`erase` CLI): cv2 backend default (no deps), optional big-LaMa via onnxruntime (~3.5-4 GB peak RAM, ~5-6 s/call CPU — does not fit a minimal droplet).
+- `invisible_watermark.py` — decodes the OPEN DWT-DCT watermarks (SD / SDXL / FLUX) via `imwatermark` (extra `detect`, pulls torch). Fragile: does not survive JPEG re-encode/resize, so it confirms origin only on pristine files.
+- `trustmark_detector.py` — Adobe TrustMark open decoder (extra `trustmark`). Do NOT remove the JPEG re-encode false-positive gate — a lone TrustMark hit without it is almost always content noise.
+- `noai/watermark_remover.py` — `WatermarkRemover` with two diffusion pipelines selected by the explicit `pipeline` ctor arg, never inferred from `model_id`: `sdxl` (plain SDXL img2img) and `controlnet` (SDXL + canny ControlNet, **the DEFAULT since 2026-06-09**). Removal comes from the img2img `strength`; ControlNet only preserves text/face STRUCTURE — SynthID CAN survive controlnet on photoreal content at low strength. No face-restore extra ships, by validated decision (every restore approach looked MORE AI-generated).
+- `auto_config.py` + the content-detection layer were REMOVED 2026-06-09; `--auto` is a deprecated no-op (controlnet is the default pipeline and the adaptive polish is ON by default and self-gates to a no-op where there is no detail deficit).
+- `upscaler.py` — optional Real-ESRGAN pre-diffusion super-resolution for small inputs (extra `esrgan`, spandrel only). Manual opt-in; the default `--upscaler` stays `lanczos` and the engine always falls back to Lanczos on absence/error. ESRGAN can degrade faces and thin text.
+- `image_io.py` — Unicode-safe cv2 IO (issue #17). Every cv2 file read/write in the package routes through `imread`/`imwrite`; do not call `cv2.imread`/`cv2.imwrite` directly. `to_bgr(image)` is the shared channel normalizer — use it instead of inlining `cvtColor` branches.
 
-**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.
+For the Doubao alpha-distillation history (why content-image reverse-alpha distillation fails by physics and controlled captures were required), see `docs/research-doubao-distillation.md`.
 
-**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.**
+## Watermarking landscape
 
-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). It ALSO burns a **visible** localized wordmark into the pixels — a sparkle + "generated with AI" string in the bottom-LEFT corner (issue #37; the Italian "✦ Contenuti generati dall'AI" variant is calibrated) — removed by `samsung_engine.py` / `visible --mark samsung` (reverse-alpha, see the engine bullet); detection feeds `identify` as the medium `visible_samsung` signal. The string is locale-specific, so each locale needs its own captured alpha template. **ASUS Gallery** also signs edited photos as C2PA (`com.asus.gallery`) but with no AI source type — a signer, not an AI marker. **Black Forest Labs (FLUX)** API output signs C2PA: `claim_generator_info "Black Forest Labs API"` + a `c2pa.ai_generated_content` assertion + `trainedAlgorithmicMedia` (issuer `b"Black Forest Labs"` added to `C2PA_ISSUERS`, platform "Black Forest Labs (FLUX)"). **ByteDance Volcano Engine (Volcengine)** — the cloud behind Doubao / Jimeng — signs its AI image output with a cert from `certificate_center@volcengine.com` + `trainedAlgorithmicMedia` (issuer `b"volcengine"` → "ByteDance (Volcano Engine)", platform "ByteDance (Doubao / Jimeng / Volcano Engine)"); note this is the C2PA-signed surface, distinct from the XMP/PNG TC260 `AIGC` label Doubao also uses. All three verified on real signed files 2026-05-29.
-- **EXIF/XMP generator tag (caught by `exif_generator`):** **Ideogram** writes EXIF `Make="Ideogram AI"` (collected 2026-05-24 — no C2PA, no SynthID, no imwatermark; the Make tag is the only signal).
-- **xAI / Grok — its own EXIF signature scheme, NOT C2PA (DETECTED by `metadata.xai_signature`, built 2026-05-26).** Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC** — only EXIF `Artist` = a UUID and EXIF `ImageDescription` = `Signature: <base64>` (a crypto signature, unverifiable locally without xAI's public key). This empirically kills the earlier unverified "xAI signs C2PA as xAI" lead — xAI is not even a C2PA member. `exif_generator` misses it (neither field holds an `AI_GENERATOR_TOKENS` token), so a dedicated detector `xai_signature(path)` matches the pair (`ImageDescription ~ ^Signature: [A-Za-z0-9+/=]{64,}` AND UUID `Artist`); wired into `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify` (signal `xai_signature`, platform "xAI (Grok / Aurora)"). **Format confirmed stable across n=3 genuine generations:** exactly three EXIF tags (`Artist`, `ExifOffset`, `ImageDescription`), `Signature:` prefix constant, base64 payload 300-1004 chars. Two capture facts: (a) the `Artist` UUID **equals the public image id** in the asset URL (`https://imagine-public.x.ai/imagine-public/images/<uuid>.jpg`), so it is NOT a private per-user secret — only the `Signature` blob is; (b) the Grok web-UI image is a re-encoded **WebP with no signature** — the EXIF survives only in the *original* JPEG (download button or that public tokenless URL), which is why screenshots / re-encodes are metadata-stripped. A real fixture `data/samples/grok-1.jpg` plus **synthetic** JPEG fixtures (fake UUID + fake `Signature:` blob) cover the detector; never add a real Grok image carrying private content (the repo is public). **Stripped on removal too:** `remove_ai_metadata` now calls `_scrub_ai_exif` on the JPEG EXIF, which deletes the xAI Signature+UUID-Artist pair **and** any `Software`/`Make`/`Artist`/`ImageDescription` tag holding an `AI_GENERATOR_TOKENS` token (so Ideogram's `Make="Ideogram AI"` is scrubbed too), while keeping genuine camera/editor EXIF. The shared `_is_xai_signature_pair` helper (module-level compiled regexes) is the single source of truth for the pattern, used by both `xai_signature` and `_scrub_ai_exif`. (AVIF/HEIF/JXL still strip only C2PA boxes via `isobmff`, not EXIF — unchanged.)
-- **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`). **Doubao** (ByteDance) uses it (verified on the real #13 sample 2026-05-25; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` 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.
+Who embeds what (C2PA / IPTC / EXIF / TC260 AIGC / xAI signature / open and proprietary invisible watermarks), whether each is locally detectable, the C2PA 2.4 durable-credentials implications, and the regulatory driver table live in `docs/watermarking-landscape.md` (research 2026-05-24, updated through 2026-06-10). Read it before adding a new `identify` signal, vendor token, or metadata marker. See `identify.py` for what we read today.
 
 ## Known limitations
 
-- `invisible` pipeline processes at **native resolution for inputs whose long side is >= 1024px**, and **auto-upscales smaller inputs UP to a 1024px floor** (`min_resolution=1024`, the default; `--min-resolution 0` disables) before diffusion -- SDXL img2img distorts badly on a tiny latent (a 381x512 portrait wrecks at native, the #36 follow-up), and the output is restored to the original input size so the floor is a transparent quality boost (it adds time/memory on small inputs). The floor upscale uses Lanczos by default; **`--upscaler esrgan`** (opt-in, the `esrgan` extra) runs Real-ESRGAN first for better detail before the Lanczos resize to the exact target (`upscaler.py` / `InvisibleEngine._esrgan_upscale`, falls back to Lanczos if the extra is absent). `max_resolution=0` (default) means no downscale cap, matching the hosted raiw.cc backend (fal fast-sdxl, no pre-downscale). The old forced downscale-to-1024 -> upscale-back round-trip for LARGE images was the main quality loss (issue #10) and is gone; at strength ~0.05 SDXL img2img does not need a downscale. **Final `--unsharp` post-filter (`humanizer.unsharp_mask`, opt-in, default 0):** applied LAST (after the face-restore pass, else it would be smoothed over) to counter the soft/over-smoothed look diffusion + restoration leave (an AI tell); ~0.5-0.8 safe, higher risks halos. Pairs with `--humanize` (grain adds sensor-noise texture, unsharp adds crispness). `--max-resolution N` re-introduces an opt-in long-side cap purely to bound GPU/MPS memory on very large inputs (it reintroduces the lossy round-trip). For huge images that OOM at native, tile-based diffusion is still the proper long-term fix. **Concrete MPS data points (the OOM is memory-tier-dependent, NOT a hard MPS limit):** on a ~24 GB unified-memory machine (verified 2026-05-25, 1254x1254 gpt-image SDXL, fp32) native res OOMs at the *UNet* step (peak ~17 GiB), not only the VAE decode, and the auto-fallback in `img2img_runner` reloads on CPU and finishes (slow, ~13 min) -- the output is still weight-identical and defeats SynthID, so "looks hung/crashed" on Mac is usually this CPU fallback, not a pipeline error. On a **32 GB** unified-memory machine the same default SDXL pass runs entirely on MPS with **no CPU fallback** (verified 2026-05-31, 1122x1402 gpt-image, `all`/default, ~155 s end-to-end), so 32 GB clears the native-res UNet peak that 24 GB could not. Adding `enable_vae_tiling()` alone does NOT prevent the 24 GB OOM (the peak is the UNet, not the VAE). The fast Mac workarounds for memory-constrained machines are fp16 on MPS (roughly halves memory) or `--max-resolution` to cap the long side; neither is wired as the default. The `controlnet` pipeline adds the canny ControlNet weights on top of SDXL, so its peak is a bit higher than the plain `default` pass; the same MPS->CPU fallback covers an OOM. The native-vs-cap-vs-floor decision lives in the pure helper `invisible_engine._target_size(w, h, max_resolution, min_resolution)` (returns `None` for native, a target tuple for a downscale cap OR an upscale floor; cap takes precedence, the floor is skipped on a min>max misconfig) so it is unit-tested (`tests/test_invisible_engine.py::TestTargetSize`, the #10/#15/#36 regression guard) without loading the model -- keep that logic in the helper, don't re-inline it.
-- **fp16 VAE black-output fix (issue #29, 2026-05-30):** on a **CUDA/XPU fp16** backend the stock SDXL VAE overflows to NaN and the *plain* img2img path decodes to an **all-black** image (reproduced on the raiw.cc result: a 1086x1448 input -> a uniformly black 4.6 KB PNG, mean 0). `watermark_remover._load_pipeline` / `_load_controlnet_pipeline` swap in the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix` = `_SDXL_FP16_VAE_ID`) when `_needs_fp16_vae_fix(model_id, DEFAULT_MODEL_ID, is_fp16)` is true -- only the default SDXL checkpoint on fp16. **cpu/mps run fp32** (the stock VAE is fine there, which is why the bug never reproduces on Mac). A custom non-SDXL `model_id` keeps its own VAE (the fp16-fix VAE is SDXL-architecture-specific). The decision is a pure helper, unit-tested without a download (`tests/test_platform.py::TestFp16VaeFix`); the actual black->clean recovery needs a CUDA GPU. **Confirmed on real CUDA hardware 2026-06-03:** running `all` on a 1086x1448 OpenAI gpt-image (the #29 repro size) at fp16 produced a normal (non-black) output, so the fp16-fix VAE swap resolves the all-black decode. (It was not reproducible on this MPS machine, which runs fp32, so the verification had to happen on an NVIDIA box.) **Follow-up safety net (issue #41, 2026-06-04):** the swap is gated to `model_id == DEFAULT_MODEL_ID`, so a custom model, a stale pre-fix install, or a fal/custom loader can still hit the black decode -- a new reporter did (gpt-image 1448x1086, the #29 size, with the exact `image_processor.py:142 invalid value encountered in cast` warning the NaN->0 cast emits). `remove_watermark` now adds a model-agnostic backstop: after generation, if the run was fp16 AND the output is degenerate (`_is_degenerate_image`: mean and std both below `_DEGENERATE_THRESHOLD` 1.0 -- a uniform all-black/NaN frame; the variance guard spares a legitimately dark-but-textured photo), it rebuilds the pipeline in fp32 on the SAME device and re-runs once. fp32 is the verified-clean path, so the user never gets a black image regardless of model_id/version. Mirrors the existing MPS->CPU fallback's self-mutation pattern (reset `torch_dtype` + clear `_pipeline`/`_controlnet_pipeline`); `batch` inherits it through `remove_watermark`, and once one image trips it the rest of the batch stays on the safe fp32. The detector is a pure helper, unit-tested without a model (`tests/test_platform.py::TestDegenerateOutputGuard`); the full fp16->detect->fp32-retry chain was verified e2e on this MPS machine by forcing fp16 with the swap disabled (first pass black, guard fired, retry produced a normal image). CAVEAT: the fp32 retry uses ~2x memory, so on a VRAM-constrained GPU it can OOM (a visible error, still better than a silent black frame; the MPS->CPU fallback covers that path). The reporter's "CPU also black" symptom is NOT reproducible here -- fp32 (cpu/mps) decodes clean -- so it points at an old version or a non-fp32 run, pending their version + command.
+Compact list. Full measurements, incident history, and oracle-validation runs live in `docs/known-limitations.md` — **read the relevant section there before changing the diffusion pipelines, strength defaults, resolution handling, or metadata coverage.**
+
+- `invisible` processes at native resolution for inputs >= 1024px long side and auto-upscales smaller inputs to a 1024px floor (`--min-resolution 0` disables; `--max-resolution N` is an opt-in cap to bound GPU/MPS memory). MPS OOM is memory-tier dependent, not a hard limit: ~24 GB unified memory falls back to CPU (slow but weight-identical output), 32 GB runs native on MPS. The native-vs-cap-vs-floor decision lives in the pure helper `invisible_engine._target_size` — keep the logic there, unit-tested without the model.
+- fp16 VAE black-output (issues #29/#41): the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix`) is swapped in for the default SDXL checkpoint on cuda/xpu fp16, plus a model-agnostic backstop that detects a degenerate (all-black) fp16 output and re-runs once in fp32. cpu/mps run fp32 and never reproduce the bug.
 - Pyright first run is slow (2-3 min) due to ML deps (torch/diffusers/transformers stubs); full-project `uv run pyright` can stall for many minutes — scope it to changed files.
 - A third-party PIL plugin autoload (e.g. an HEIF/AVIF plugin) can raise a non-OSError (`ModuleNotFoundError`), not `UnidentifiedImageError`, when opening a file. Code that opens user-supplied or unknown-format files should `except Exception`, not just `OSError`/`UnidentifiedImageError`.
-- **rich was dropped (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.)
+- rich was dropped: the CLI + analysis scripts print plain text (`click.echo` / the `scripts/_plain_console.py` shim). `rich` is NOT a dependency — importing it breaks the core+dev CI sync; new scripts must use the shim. No Unicode glyphs / colors / progress bars in CLI output by design.
+- AVIF/HEIF/JPEG-XL metadata detection is a binary scan; C2PA removal in those containers (and MP4/MOV/M4V) is `noai/isobmff.py`; non-ISOBMFF audio/video (WebM/MP3/WAV/FLAC/OGG) strips losslessly via ffmpeg on PATH. Still NOT built: an `Exif` meta-box *item* (needs `iinf`/`iloc` surgery) and Resemble PerTh audio detection (no presence/confidence flag exists).
 - **SynthID technical reference: `docs/synthid.md`** — primary-source-cited doc covering mechanism (post-hoc encoder/decoder pair, 136-bit payload at 512x512, pixel-space, model weights NOT modified), robustness numbers (arXiv:2510.09263: ~99.98% TPR@0.1%FPR across 30 transforms including JPEG/crop/resize/color/noise), removal attacks and forensic detectability (arXiv:2605.09203: all 6 attacks detectable at >98% TPR@1%FPR), detectability limits (no public decoder, metadata-proxy only), oracle scope, and adoption landscape. Read that doc first before adding notes here.
-
-- **SynthID detection is metadata-only.** There is no reliable *local* detector of the SynthID *pixel* watermark — Google's decoder is proprietary, no public spec or API (only a waitlisted portal). Authoritative confirmation: Google DeepMind's own paper "SynthID-Image: Image watermarking at internet scale" (Gowal et al., arXiv:2510.09263) states the verification service is restricted to "trusted testers" and does not release detector weights or a reproducible algorithm — so a local pixel detector is infeasible by design, not just unbuilt. https://arxiv.org/abs/2510.09263 We detect SynthID by its C2PA companion (`synthid_source` / `SYNTHID_C2PA_ISSUERS`), which is reliable while the manifest is intact but says nothing once C2PA is stripped. **Surface-dependent blind spot (verified 2026-05-24):** the same Google model emits different metadata per surface -- the Gemini *app* wraps outputs in Google C2PA, but the *API/playground* (AI Studio, Nano Banana / gemini-2.5-flash-image) emits the SynthID *pixel* watermark (confirmed via the Gemini-app oracle) + the visible sparkle but **no C2PA/IPTC at all**, so `synthid_source` returns None despite SynthID being present. Only the pixel oracle or the visible-sparkle detector catches those. (Meta AI is another surface mismatch: it writes the IPTC `digitalSourceType=trainedAlgorithmicMedia` marker, not C2PA and not SynthID.) Google→SynthID is long-standing; OpenAI→SynthID is confirmed by OpenAI's Help Center (ChatGPT/Codex/API "include both C2PA metadata and SynthID watermarks", updated 2026-05-21) but time-gated (pre-rollout OpenAI images carry C2PA without SynthID), so the OpenAI verdict is hedged "likely". Oracles: Gemini app "Verify with SynthID" (Google), openai.com/verify (OpenAI). **Each vendor's oracle detects only its OWN content (verified on the page 2026-05-31):** `openai.com/research/verify` states verbatim "OpenAI generation signals will only be detected if the image was generated with our tools" and "Content could also still be AI-generated by another company's model, which the tool currently does not detect" -- SynthID is shared tech but the verifier is keyed to its own vendor's payload, so a Google-SynthID image reads clean on OpenAI's verifier and vice-versa. **This explains the recurring "oracle says clean but `identify` still flags SynthID" report (#14):** the oracle reads the *pixel* watermark (gone after our SDXL pass), while `identify` reads the *C2PA-metadata proxy* (still present if the manifest survived). Different signals, not a contradiction -- strip the metadata too (`metadata --remove` / `all`) and the proxy goes quiet, but a quiet proxy is not proof the pixel watermark is gone. **SynthID is durable to JPEG re-encode by design, so a GitHub-recompressed issue attachment is still a valid SynthID test subject** (verified 2026-06-01 on issue #14's pic3: the GitHub-served JPEG survived re-encoding and openai.com/verify still detected SynthID). Do NOT dismiss issue-attachment JPEGs as "not faithful originals" when reproducing a SynthID-survival report: the recompression strips the **C2PA metadata** (so `identify` reads Unknown on the attachment) but NOT the **pixel watermark** that openai.com/verify reads. A true byte-original only matters for the metadata/C2PA path, not for the pixel-SynthID-removal test. (Contrast the open imwatermark above, which IS fragile to JPEG.) The spectral phase-coherence approach from `github.com/aloshdenny/reverse-SynthID` was evaluated (May 2026) and **does not work for real-content detection**: on its own shipped codebook + validation set, watermarked and cleaned images were indistinguishable (conf within noise, cleaned often higher); it only fires on pure-black 1024x1024 reference images at exact resolution (the controlled case it was calibrated on). The README's "90% / conf=0.91" reproduces only in that lab condition. Do not build a production detector on it; if revisited, it is experimental/diagnostic only and needs a per-resolution, per-model reference corpus. A from-scratch gpt-image pilot (2026-05-24) confirmed this independently: 5 independent solid-black gpt-image outputs share a near-identical fixed signature (pairwise residual correlation **0.92**, avg-template retains 97% energy), so the watermark/carrier IS strongly present and consistent on flat content — but the carrier frequencies extracted from it do NOT discriminate real content (carrier-to-random ratio: cleaned 1.86 > watermarked 1.53; a non-gpt-image image scored highest at 3.67). The signature drowns in content texture. Net: a perfectly consistent solid-color signature still yields no real-content pixel detector with magnitude/carrier methods. A corpus discrimination test (2026-05-24, `scripts/synthid_pixel_probe.py`, raw zero-mean residual NCC) independently re-confirms this: at matched resolution, SynthID positives do NOT cluster apart from negatives (within-Gemini 0.07; at 1024 px pos-vs-neg >= pos-vs-pos). The only high correlations Line truncated
-- **External AI-vs-real classifier models are out of scope (decided 2026-05-24).** Generic HuggingFace detectors (`Organika/sdxl-detector` Swin Transformer, `umm-maybe/AI-image-detector`, and fine-tunes) exist and report ~0.98 on their *own* SDXL-vs-real validation sets, but they are per-generator and the model cards themselves note degraded accuracy off-distribution; they are untested on gpt-image / Gemini Nano Banana (the metadata-stripped surfaces we care about), and our own light SDXL pass would likely defeat them the same way it defeats SynthID. Detection here stays local + signal-based (metadata + visible sparkle); do not add a bundled classifier dependency.
-- **DEFAULT STRENGTH IS NOW VENDOR-ADAPTIVE (2026-06-01, SUPERSEDES every fixed-default claim in this bullet and the next).** `resolve_strength(strength, profile, vendor)` + `vendor_for_strength(path)` (`watermark_profiles.py`) read the C2PA issuer (`metadata.synthid_source`) on the ORIGINAL input and pick `OPENAI_STRENGTH` **0.10** / `GEMINI_STRENGTH` **0.15** / `UNKNOWN_STRENGTH` **0.15** when `--strength` is unset; explicit `--strength` always wins. The CLI detects the vendor from the pristine source (before the visible pass / metadata-strip removes C2PA from the temp file) and passes it to the engine, so display and execution agree; `cmd_invisible`/`cmd_all`/`batch` + the module-level `remove_watermark` all thread `vendor`. **This replaces the single 0.30 default AND the prior "do NOT build a vendor-adaptive default" policy** -- both came from the now-debunked region-rescrub-contaminated study (the per-region re-scrub that contaminated those numbers was removed in the controlnet refactor). Basis: the oracle-verified June 2026 controlled study (clean v0.8.6, protect OFF): OpenAI clears at 0.05 across 1024-1600 (n=4, resolution-independent); Google needs 0.15 on the capped-1536 path (n=4). `docs/synthid.md` §2.2 (data) + §5.2 (the adaptive default) are authoritative. **CAVEAT (oracle pass 2026-06-04): the OpenAI 0.10 default is content-dependent, NOT universal -- a flat-graphic OpenAI logo/poster still read SynthID-detected after `default` at 0.10, and photoreal images after controlnet at 0.10/0.15 (low-change regions under-perturbed). Removal at 0.10/0.15 is content×pipeline dependent (see the controlnet Known-limitations bullet); the lever is a higher strength, oracle-revalidated per content type. Do NOT assume the vendor-adaptive default clears every image.** CAVEAT: Google's 0.15 was validated only on `--max-resolution 1536`; native large Gemini (2816) was not locally measurable (OOM on M-series) and is pending GPU validation on raiw.cc -- if it survives 0.15 native, raise `--strength`. **Everything below in this bullet about a fixed 0.10/0.30 default is HISTORICAL; trust the vendor-adaptive constants + docs/synthid.md.**
-- **SynthID removal: strength + oracle scope.** Default strength is vendor-adaptive (see the bullet above); `docs/synthid.md` §2.2 is authoritative for the numbers. **Oracle scope (load-bearing):** the Gemini app "Verify with SynthID" is the ONLY valid SynthID oracle (detects Google's mark on any image); `openai.com/verify` is scoped to OpenAI provenance (its own C2PA), NOT a SynthID oracle -- a negative there is meaningless for SynthID. There is no local SynthID detector, so the tool cannot self-check; if the oracle still reads SynthID, raise `--strength` to the lowest value that verifies clean. Only the `default` (plain SDXL img2img) and `controlnet` (SDXL + canny ControlNet) profiles exist; the local `invisible` default is weight-for-weight identical to raiw.cc prod (`fal-ai/fast-sdxl` = `stabilityai/stable-diffusion-xl-base-1.0`, runtime-downloaded, not bundled). **Forensic-stealth caveat** (arXiv:2605.09203): defeating the SynthID verifier is NOT forensic invisibility -- independent detectors flag *removal-processed* images vs genuinely-clean ones at >98% TPR@1%FPR, so do not over-claim "indistinguishable from a real photo".
-- **`controlnet` pipeline (text/face STRUCTURE preservation, EXPERIMENTAL, opt-in `--pipeline controlnet`).** SDXL + the canny ControlNet `xinsir/controlnet-canny-sdxl-1.0` via `StableDiffusionXLControlNetImg2ImgPipeline` (`watermark_remover._run_controlnet` / `_load_controlnet_pipeline`). **Removal still comes from the img2img regeneration (`strength`); the ControlNet only PRESERVES text and face STRUCTURE by conditioning on the canny edge map** (`cv2.Canny(gray, 100, 200)`, 3-channel). Canny preserves edges, NOT face identity (a regenerated face drifts in likeness). The drifted cleaned face is the LEAST-AI state we can reach without re-introducing SynthID; **the library does NOT ship a face-restore extra** (every approach evaluated 2026-06-04 - 2026-06-08 -- GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps -- regenerated the face via SDXL and made it look MORE AI-generated). Full empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up". For production face preservation, ship the cleaned image as-is. No original pixels are copied or frozen, **BUT removal at the low vendor-adaptive strength is CONTENT × PIPELINE dependent and NEITHER pipeline clears all content -- oracle-validated against the OpenAI verifier 2026-06-04 (8 images, strength 0.10/0.15, `--max-resolution 1536`).** The survivors FLIP by content type: **photoreal** (a 9-face grid, a bracelet product photo) SURVIVES controlnet but CLEARS `default` (controlnet's dense edge map keeps the regen too close to the original, so the SynthID-destroying perturbation never happens; plain img2img perturbs photoreal texture enough); **flat graphic** (a logo/poster with large flat color fills) SURVIVES `default` but CLEARS controlnet (at low strength img2img barely changes flat fills so SynthID persists there, while controlnet repaints them more freely); a flat **text** card cleared under both. **Root cause is insufficient STRENGTH, not the pipeline: at 0.10 the low-change regions -- dense-edge photoreal under controlnet, large flat fills under `default` -- are not perturbed enough to destroy SynthID. The vendor-adaptive 0.10 from the June study is NOT universally sufficient (that study's content happened to clear at 0.10).** The robust fix is a HIGHER strength, oracle-revalidated per content type (controlnet can be cranked harder without losing structure; a lower `controlnet_conditioning_scale` also frees the regen on photoreal). So at today's default strength **both pipelines AND `--auto` can LEAVE SynthID on some content** -- a removal-priority caller (raiw.cc) MUST oracle-validate strength across content types before adopting, not pick a pipeline and assume removal. **Follow-up same day: re-running the two photoreal survivors through controlnet at an explicit `--strength 0.15` cleared BOTH on the oracle -- BUT one of them (the bracelet) had SURVIVED the SAME 0.15 controlnet config in the first pass (only the random, unset seed differed). So removal near the threshold is SEED-NON-DETERMINISTIC: the same image+pipeline+strength+resolution can pass or fail run-to-run (img2img uses `seed=None`/random unless `--seed` is passed, and there is no local SynthID detector to self-verify). 0.15 is the borderline, NOT a robust floor -- pick a strength with MARGIN (controlnet ~>= 0.20) rather than exactly on it; the content×pipeline table's 0.15 data point is near-threshold noise. A confirming run at `--strength 0.20` controlnet cleared BOTH photoreal survivors on the oracle (ladder: 0.10 grid detected → 0.15 borderline/non-deterministic → 0.20 both clean), so **0.20 is the recommended robust controlnet floor for OpenAI photoreal** (one margin run, not an N-run repeatability proof -- a service should add margin or verify repeatability since there is no local SynthID detector to self-check). **Engineering follow-up for raiw.cc: the controlnet pipeline should use a HIGHER vendor strength than `default` -- it currently shares `resolve_strength` (0.10/0.15, tuned for plain img2img), but controlnet's edge map preserves structure so it needs ~0.20+; calibrate per vendor/content on the GPU worker, do NOT just reuse the `default` ladder.** **CERTIFIED 2026-06-04 via the isolated `raiw-controlnet-cert` Modal app (`raiw-app/modal_cert.py`), restore OFF, ≤1536, each vendor on its own oracle: controlnet floors are OpenAI 0.20 (2 photoreal × 3 seeds = 6/6 clean; the 0.15-flipper is seed-robust at 0.20) and Gemini 0.30 (0.20 detected → 0.30 clean on 2/2 seeds). OpenAI 0.20 transfers to prod (resolution-independent); Gemini 0.30 holds only ≤1536 — Gemini is resolution-sensitive and raiw.cc runs NATIVE (`max_resolution=0`), so cap Gemini ≤1536 + use 0.30, or native-calibrate (~0.35+). Prod recipe: controlnet + per-vendor floor in `resolve_strength` (not the default ladder) + FIXED seed (kills the non-determinism). **No face-restore in the library:** every approach evalLine truncated
+- **SynthID detection is metadata-only.** No local pixel detector is possible by design (Google's decoder is proprietary, trusted-testers only); we read the C2PA companion proxy, which goes quiet once metadata is stripped — a quiet proxy is not proof the pixel watermark is gone. The Gemini app "Verify with SynthID" is the ONLY valid SynthID oracle; `openai.com/verify` is scoped to OpenAI provenance and each vendor's oracle detects only its own content. SynthID survives JPEG re-encode, so GitHub issue attachments remain valid pixel-watermark test subjects. Every spectral/phase detection approach evaluated (reverse-SynthID, our own probes) works only on controlled solid fills, never on real content.
+- **External AI-vs-real classifier models are out of scope** (decided 2026-05-24): per-generator, degrade off-distribution, and our own light SDXL pass would likely defeat them. Detection stays local + signal-based.
+- **Default strength is VENDOR-ADAPTIVE, one ladder for BOTH pipelines** (since 2026-06-09): `resolve_strength(strength, vendor)` picks OpenAI **0.20** / Gemini **0.30** / unknown **0.30** when `--strength` is unset; explicit `--strength` always wins. Removal at low strength is content x pipeline dependent, and near-threshold removal is SEED-NON-DETERMINISTIC — pick a strength with margin and oracle-revalidate per content type. Certified controlnet floors (Modal cert 2026-06-04): OpenAI 0.20 (resolution-independent), Gemini 0.30 (only <= 1536px; native large Gemini needs ~0.35+ or a cap).
+- **`controlnet` is the default pipeline**; `--pipeline sdxl` is the lighter opt-down. Neither pipeline clears all content at low strength (photoreal survives controlnet, flat graphics survive sdxl — the lever is higher strength). A removal-priority caller MUST oracle-validate strength across content types; prod recipe: controlnet + per-vendor floor + FIXED seed. Forensic-stealth caveat (arXiv:2605.09203): defeating the SynthID verifier is NOT forensic invisibility — removal-processed images are flaggable at >98% TPR@1%FPR.

README.md

@@ -8,6 +8,10 @@ Strips SynthID, C2PA Content Credentials, EXIF/XMP "Made with AI" labels, and vi
 >
 > No Python, no GPU, no setup. Visible-watermark and metadata removal are **free**. Invisible-watermark removal (SynthID / SDXL regeneration) normally needs a local GPU and ~2 GB of models. On **[raiw.cc](https://raiw.cc)** it runs on cloud GPUs in one click for a small per-image fee.
 
+[![PyPI](https://img.shields.io/pypi/v/remove-ai-watermarks?logo=pypi&logoColor=white)](https://pypi.org/project/remove-ai-watermarks/)
+[![Python](https://img.shields.io/pypi/pyversions/remove-ai-watermarks?logo=python&logoColor=white)](https://pypi.org/project/remove-ai-watermarks/)
+[![Downloads](https://static.pepy.tech/badge/remove-ai-watermarks/month)](https://pepy.tech/project/remove-ai-watermarks)
+[![License](https://img.shields.io/pypi/l/remove-ai-watermarks?color=blue)](LICENSE)
 [![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)
 
@@ -23,10 +27,10 @@ If this tool saves you time, consider [sponsoring its development](https://githu
 - **AI metadata stripping** — EXIF, PNG text chunks, C2PA provenance manifests (PNG / JPEG / AVIF / HEIF / JPEG-XL, **MP4 / MOV / M4V / M4A** at the container level, and **WebM / MP3 / WAV / FLAC / OGG** losslessly via ffmpeg), XMP DigitalSourceType
 - **"Made with AI" label removal** — removes the AI-disclosure metadata that platforms read to apply automatic labels (useful for clearing a false-positive label from a human-edited photograph)
 - **Analog Humanizer** — optional film grain and chromatic aberration post-processing
-- **Text and face preservation (experimental)** — optional `--pipeline controlnet` adds a canny ControlNet that keeps text and face structure sharp through the removal pass (without copying original pixels, so SynthID is still removed). Canny preserves face *structure*, not *identity* (the regenerated face drifts in likeness). The library does not ship a face-restore extra: every approach evaluated (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned) regenerated the face via SDXL and made the output look more AI-generated than the cleaned image. The cleaned controlnet output is the least-AI face state achievable without re-introducing SynthID.
+- **Text and face preservation (default)** — the default pipeline is a canny ControlNet that keeps text and face structure sharp through the removal pass (without copying original pixels, so SynthID is still removed). Use `--pipeline sdxl` for plain SDXL img2img (lighter, no extra model download) on inputs without text or faces. Canny preserves face *structure*, not *identity* (the regenerated face drifts in likeness). The library does not ship a face-restore extra: every approach evaluated (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned) regenerated the face via SDXL and made the output look more AI-generated than the cleaned image. The cleaned controlnet output is the least-AI face state achievable without re-introducing SynthID.
 - **Batch processing** — process entire directories
 - **Detection** — three-stage NCC watermark detection with confidence scoring
-- **Provenance detection (`identify`)** — aggregate C2PA issuer, the C2PA soft-binding forensic-watermark vendor (Adobe TrustMark, Digimarc, Imatag, ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, embedded SD/ComfyUI params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the China TC260 AIGC label (XMP, PNG chunk, or EXIF), the HuggingFace `hf-job-id` job marker, the SynthID metadata proxy, the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), the open SD/SDXL/FLUX invisible watermark, and (with the `trustmark` extra) the open Adobe TrustMark watermark into one origin-platform + watermark-inventory verdict (`--json` for machine output)
+- **Provenance detection (`identify`)** — aggregate C2PA issuer, the C2PA soft-binding forensic-watermark vendor (Adobe TrustMark, Digimarc, Imatag, ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, embedded SD/ComfyUI params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the China TC260 AIGC label (XMP, PNG chunk, EXIF, or JPEG segment), the HuggingFace `hf-job-id` job marker, the SynthID metadata proxy, the C2PA cloud-manifest reference (Adobe Durable Content Credentials, when the embedded manifest is stripped), the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), the open SD/SDXL/FLUX invisible watermark, and (with the `trustmark` extra) the open Adobe TrustMark watermark into one origin-platform + watermark-inventory verdict (`--json` for machine output)
 
 ## Examples
 
@@ -58,7 +62,7 @@ If this tool saves you time, consider [sponsoring its development](https://githu
 
 > Visible overlays are used by Google Gemini / Nano Banana (sparkle logo), by ByteDance's Doubao ("豆包AI生成" corner text) and Jimeng / Dreamina ("★ 即梦AI" wordmark), and by Samsung Galaxy AI ("✦ Contenuti generati dall'AI" strip, bottom-left, locale-specific). All are removed on CPU by reverse-alpha against a captured alpha map (Jimeng and Samsung add a thin residual inpaint over the glyph footprint, since their marks re-rasterize per image). Other services rely on invisible watermarks and/or metadata; our diffusion-based regeneration works against any invisible watermark in pixel or frequency domain. For a visible mark from any other source (any position, any colour), use the universal `erase --region` command.
 
-> **Detection:** `remove-ai-watermarks identify <image>` reports the origin platform and watermark inventory for all the signals above — C2PA issuer, the C2PA soft-binding forensic-watermark vendor (TrustMark / Digimarc / Imatag / ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, the China TC260 AIGC label (XMP, PNG chunk, or EXIF), the HuggingFace `hf-job-id` job marker, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), and (with the `[detect]` / `[trustmark]` extras) the open SD/SDXL/FLUX and Adobe TrustMark invisible watermarks. SynthID and the proprietary soft-binding watermarks (Digimarc etc.) have no local decoder, so they are reported by metadata proxy / vendor name only.
+> **Detection:** `remove-ai-watermarks identify <image>` reports the origin platform and watermark inventory for all the signals above — C2PA issuer, the C2PA soft-binding forensic-watermark vendor (TrustMark / Digimarc / Imatag / ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, the China TC260 AIGC label (XMP, PNG chunk, EXIF, or JPEG segment), the HuggingFace `hf-job-id` job marker, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, the C2PA cloud-manifest reference (Adobe Durable Content Credentials, when the embedded manifest is stripped), the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" / Samsung Galaxy AI "Contenuti generati dall'AI" text marks), and (with the `[detect]` / `[trustmark]` extras) the open SD/SDXL/FLUX and Adobe TrustMark invisible watermarks. SynthID and the proprietary soft-binding watermarks (Digimarc etc.) have no local decoder, so they are reported by metadata proxy / vendor name only.
 
 ## How it works
 
@@ -118,15 +122,16 @@ The removal pipeline (default profile, SDXL):
 image → encode to latent space (VAE) at native resolution
       → add controlled noise (forward diffusion)
       → denoise (reverse diffusion, ~50 steps; strength is vendor-adaptive:
-        0.10 OpenAI / 0.15 Google / 0.15 unknown, override with --strength)
+        0.20 OpenAI / 0.30 Google / 0.30 unknown, same for both pipelines;
+        override with --strength)
       → decode back to pixels (VAE)
 ```
 
 - Large inputs run at native resolution (no down-then-up round-trip, which was the main quality loss in issue #10); use `--max-resolution N` only to cap GPU/MPS memory on very large inputs. Small inputs (long side under 1024 px) are auto-upscaled to a 1024 px floor before diffusion, because SDXL distorts on a tiny latent, and the result is restored to the original size (a transparent quality boost). Disable the floor with `--min-resolution 0`. The floor upscale uses Lanczos by default; `--upscaler esrgan` (the `esrgan` extra) runs Real-ESRGAN first for sharper detail and falls back to Lanczos if the extra is absent. ESRGAN is a generic photo/texture GAN with no face/glyph prior, so it is best for photo/texture content -- it can degrade faces (the diffusion pass regenerates them, so the final recovers) and thin text; keep Lanczos for text-heavy inputs.
 
-> **Default strength is vendor-adaptive (no flag needed).** The tool reads the C2PA issuer to detect which vendor's SynthID is present and picks the strength that clears it with the least quality loss: **OpenAI gpt-image → `0.10`**, **Google Gemini → `0.15`**, **unknown source → `0.15`**. An oracle-verified June 2026 study (clean pipeline, per-image openai.com/verify or Gemini app) found OpenAI's watermark clears at `0.05` across `1024`-`1600` px (resolution-independent) while Google's is ~3x more robust and needs `0.15`. The dominant factor is the vendor, not resolution. There is no local SynthID detector, so if the oracle still reads SynthID, raise `--strength`; if you care more about preserving fine text, lower it. (Caveat: Google's `0.15` was validated on the capped `--max-resolution 1536` path; a very large native Gemini image may need more.)
+> **Default strength is vendor-adaptive (no flag needed).** The tool reads the C2PA issuer to detect which vendor's SynthID is present and picks the strength accordingly: **OpenAI gpt-image → `0.20`**, **Google Gemini → `0.30`**, **unknown source → `0.30`**. The **same ladder applies to both pipelines** — these are the oracle-certified `controlnet` floors (June 2026 Modal cert, multi-seed). They also cover plain `sdxl`: the two pipelines have opposite hard cases (controlnet leaves SynthID on photoreal, sdxl on flat graphics), but on its own hard case sdxl is the weaker remover, so it needs at least controlnet's strength — using one certified ladder is the safe choice (margin-based for sdxl, not separately certified). The dominant factor is the vendor (Google's SynthID is ~3x more robust). There is no local SynthID detector, so if the oracle still reads SynthID, raise `--strength`; if you care more about preserving fine detail, lower it. (Caveat: Google's `0.30` was validated only at `--max-resolution 1536`; a very large native Gemini image may need ~`0.35`+.)
 >
-> **`--pipeline controlnet` preserves text and face structure (experimental, opt-in).** It runs the same SDXL img2img scrub but adds a canny ControlNet that conditions the regeneration on the image's edge map, so text and structure stay sharp at the strengths that remove SynthID. The watermark removal still comes from the img2img regeneration (`--strength`); the ControlNet only preserves structure — no original pixels are copied or frozen, so SynthID does not survive. `--controlnet-scale` tunes the preservation strength (higher = closer to the original structure). Runs fp32 on mps/cpu (fp16 only on cuda/xpu, where the fp16-fixed SDXL VAE is loaded automatically).
+> **The default pipeline is `controlnet` — it preserves text and face structure.** It runs the same SDXL img2img scrub but adds a canny ControlNet that conditions the regeneration on the image's edge map, so text and structure stay sharp at the strengths that remove SynthID. The watermark removal still comes from the img2img regeneration (`--strength`); the ControlNet only preserves structure — no original pixels are copied or frozen. The default strength ladder (OpenAI `0.20` / Google `0.30`) is the oracle-certified controlnet floor. `--controlnet-scale` tunes the preservation strength (higher = closer to the original structure). Runs fp32 on mps/cpu (fp16 only on cuda/xpu, where the fp16-fixed SDXL VAE is loaded automatically). Pass `--pipeline sdxl` for plain SDXL img2img (lighter, no extra model download) on inputs without text or faces.
 >
 > **No face-restore extra in the library.** Every ArcFace-based regeneration approach we evaluated (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps, 2026-06-04 - 2026-06-08 Modal cert sweeps) regenerated the face via SDXL diffusion — the output face pixels were diffusion-fresh (SynthID not re-introduced), but the face inherently looked more AI-generated than the cleaned image (SDXL "clean skin" gloss, lost original identity precision). The cleaned image from the main controlnet 0.20 pass is the least-AI face state we can reach without re-introducing SynthID. Empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md`.
 
@@ -136,7 +141,7 @@ SDXL is the default since May 2026: empirically defeats SynthID v2 on Gemini 3 P
 
 > **Technical deep-dive:** see [`docs/synthid.md`](docs/synthid.md) for a primary-source-cited breakdown of how SynthID works mechanically (post-hoc encoder/decoder, 136-bit payload, pixel-space embedding), what it empirically survives (JPEG, crop, resize: ~99.98% TPR at 0.1% FPR from arXiv:2510.09263), what removes it, and the forensic-stealth tradeoff (all known removal attacks are detectable at >98% TPR@1%FPR per arXiv:2605.09203).
 
-**Text and face preservation** (experimental, opt-in `--pipeline controlnet`): adds a canny ControlNet so text and face *structure* stay sharp through the removal pass, without copying or freezing any original pixels (so SynthID is still removed). Tune the preservation strength with `--controlnet-scale`. Canny preserves structure but not face *identity*: the regenerated face drifts in likeness. The library does not ship a face-restore extra (see the callout above).
+**Text and face preservation** (the default pipeline; `--pipeline sdxl` opts down to plain SDXL): a canny ControlNet keeps text and face *structure* sharp through the removal pass, without copying or freezing any original pixels (so SynthID is still removed). Tune the preservation strength with `--controlnet-scale`. Canny preserves structure but not face *identity*: the regenerated face drifts in likeness. The library does not ship a face-restore extra (see the callout above).
 
 **Analog Humanizer**: optional film grain and chromatic aberration injection that mimics a photo of a screen, raising the bar for AI-generated image classifiers. (It frustrates generic classifiers but does not guarantee forensic invisibility — see the [arXiv:2605.09203](https://arxiv.org/abs/2605.09203) note above.)
 
@@ -153,6 +158,34 @@ The cleaner parses each layer, removes AI-related fields, and preserves standard
 
 ## Installation
 
+### Homebrew (macOS / Linux)
+
+```bash
+brew install wiltodelta/tap/remove-ai-watermarks
+```
+
+This installs the core command surface (`identify`, `metadata`, `visible`,
+`erase`) as a self-contained CLI. The diffusion-based `invisible` / `all`
+pipeline needs heavy ML dependencies (torch, diffusers, multi-GB) and is kept
+out of the Homebrew build; add it with the `gpu` extra via pip if you need it:
+
+```bash
+pip install "remove-ai-watermarks[gpu]"
+```
+
+### conda
+
+A conda-forge recipe is under review
+([staged-recipes PR](https://github.com/conda-forge/staged-recipes/pull/33674)).
+Once it merges, the core package installs with:
+
+```bash
+conda install -c conda-forge remove-ai-watermarks
+```
+
+Like the Homebrew build, this is the core command surface; add the diffusion
+`invisible` / `all` pipeline with the pip `gpu` extra.
+
 ### Recommended
 
 Install as an isolated CLI tool — no need to manage virtual environments:
@@ -199,6 +232,10 @@ After installation the `remove-ai-watermarks` command is available system-wide.
 > pip install -e ".[gpu]"   # or: uv pip install -e ".[gpu]"
 > ```
 >
+> Without the `[gpu]` extra, `all` still runs the visible and metadata steps, but
+> it skips the invisible (SynthID) step, prints a clear warning, and exits with a
+> non-zero status so a skipped step is not mistaken for a clean result.
+>
 > To let `identify` decode the open Stable Diffusion / SDXL / FLUX invisible
 > watermarks, install the `detect` extra (adds the `invisible-watermark` decoder):
 >
@@ -251,6 +288,23 @@ pytest
 ./maintain.sh
 ```
 
+## ComfyUI
+
+Custom nodes are available so the watermark tools run inside a ComfyUI graph:
+[ComfyUI-remove-ai-watermarks](https://github.com/wiltodelta/ComfyUI-remove-ai-watermarks)
+([registry](https://registry.comfy.org/nodes/remove-ai-watermarks)).
+
+Install via ComfyUI Manager (search "Remove AI Watermarks") or manually:
+
+```bash
+cd ComfyUI/custom_nodes
+git clone https://github.com/wiltodelta/ComfyUI-remove-ai-watermarks
+pip install -r ComfyUI-remove-ai-watermarks/requirements.txt
+```
+
+Nodes: Remove Visible Watermark, Detect Visible Watermark, Erase Region (by
+mask), and Remove Invisible Watermark / SynthID (needs the `gpu` extra).
+
 ## Usage
 
 ### CLI
@@ -279,6 +333,9 @@ remove-ai-watermarks identify image.png
 # strongest known mark (Gemini sparkle / Doubao "豆包AI生成" / Jimeng "即梦AI" /
 # Samsung Galaxy AI "Contenuti generati dall'AI"); force one with
 # --mark gemini / doubao / jimeng / samsung. Removed by reverse-alpha (true-pixel recovery).
+# If no known visible mark is found, it writes no output and exits 2 (not 0),
+# pointing you to `all` (for an invisible/metadata mark) or `erase` (for an
+# arbitrary logo) instead of handing back the unchanged image.
 remove-ai-watermarks visible image.png -o clean.png
 
 # Erase arbitrary region(s) — universal, any logo/watermark/object, any position.
@@ -292,14 +349,15 @@ remove-ai-watermarks invisible image.png -o clean.png --humanize 4.0 --unsharp 0
 # first (disable with --min-resolution 0); --upscaler esrgan uses Real-ESRGAN for
 # that floor upscale (needs the 'esrgan' extra). On a very large image that OOMs the
 # GPU/MPS, cap the long side: --max-resolution 2048
-# Strength is vendor-adaptive by default (OpenAI 0.10 / Google 0.15); override
-# with --strength. To preserve text/face structure, use --pipeline controlnet
-# Or let it choose: --auto picks the pipeline, face restore, and an adaptive polish
-# from the image content (controlnet when there is text/structure, polish that
-# restores the input's detail level while sparing text). Every choice is
-# overridable: --pipeline and --no-adaptive-polish win over the auto pick.
-# Experimental.
-# (SDXL + canny ControlNet); tune preservation with --controlnet-scale. Add
+# Strength is vendor-adaptive by default (OpenAI 0.20 / Google 0.30, same
+# for both pipelines); override with --strength. controlnet (text/face
+# structure preservation) is the default pipeline; --pipeline sdxl opts down
+# to plain SDXL for non-structure inputs. Tune structure preservation with
+# --controlnet-scale, the CFG with --guidance-scale (default 7.5), and the
+# diffusion model with --model (default: SDXL base).
+# --adaptive-polish (ON by default) restores the input's detail level (sparing
+# text) to counter the over-smoothed look; it self-limits to a no-op where
+# there is no detail deficit. Disable with --no-adaptive-polish.
 
 # Check / strip AI metadata (C2PA, EXIF, "Made with AI" labels)
 # --check also flags SynthID-bearing sources: a C2PA manifest signed by
@@ -312,9 +370,9 @@ remove-ai-watermarks metadata image.png --remove
 # Batch with a specific mode
 remove-ai-watermarks batch ./images/ --mode visible
 
-# Batch also accepts --auto (and --adaptive-polish): the plan is recomputed per
-# image, so a mixed directory routes each file to the right pipeline
-remove-ai-watermarks batch ./images/ --mode all --auto
+# Batch accepts the full invisible knob set (--strength/--guidance-scale/--model/
+# --pipeline/...); --adaptive-polish is on by default (--no-adaptive-polish to disable)
+remove-ai-watermarks batch ./images/ --mode all
 ```
 
 ### Python API
@@ -335,6 +393,30 @@ clean = engine.remove_watermark(image)
 cv2.imwrite("clean.png", clean)
 ```
 
+#### Invisible removal (diffusion)
+
+```python
+from pathlib import Path
+from remove_ai_watermarks.invisible_engine import InvisibleEngine
+
+# pipeline: "controlnet" (default, preserves text/face structure) or "sdxl" (plain).
+# model_id=None uses the SDXL base; controlnet_conditioning_scale tunes preservation.
+engine = InvisibleEngine(pipeline="controlnet")
+
+engine.remove_watermark(
+    Path("watermarked.png"),
+    Path("clean.png"),
+    strength=None,          # None = vendor-adaptive default (OpenAI 0.20 / Google 0.30)
+    num_inference_steps=50,
+    guidance_scale=None,    # None = the library default (7.5)
+    seed=None,              # set for reproducible output
+    adaptive_polish=True,   # detail-targeted polish, self-gating (default on in the CLI)
+    min_resolution=1024,    # upscale tiny inputs to this floor before diffusion
+    max_resolution=0,       # 0 = native; set only to cap GPU/MPS memory
+    upscaler="lanczos",     # or "esrgan" for the floor upscale (needs the 'esrgan' extra)
+)
+```
+
 ### Metadata stripping
 
 ```python
@@ -377,7 +459,7 @@ pip install certifi
 Tracked but not yet implemented:
 
 - **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.
+- **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 docs/known-limitations.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.)
@@ -390,6 +472,13 @@ 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.
 
+## Limitations
+
+- **Visible-mark and metadata removal is lossless.** Reverse-alpha recovers the original pixels under the mark; metadata stripping never touches image data.
+- **The invisible (SynthID) path is lossy and not guaranteed.** It runs a low-strength SDXL img2img regeneration, so it softens fine detail and is content-dependent. There is no public SynthID decoder, so the tool cannot verify removal locally; confirm with the Gemini app's "Verify with SynthID" oracle and raise `--strength` if it still detects. A vendor can change the scheme at any time, so treat this as an arms race, not a permanent fix.
+- **Large images are not tiled yet.** The SynthID path runs at the diffusion model's native resolution and caps or upscales larger inputs instead of tiling them, so very large images lose detail. (Nano Banana 2 is natively 1024px; GPT Image 2 supports 4K experimentally.) Tiled diffusion is the planned fix.
+- **Out of scope:** defeating trained AI-vs-real classifiers like Hive (see [Threat model](#threat-model)), visible-logo removal from video, and any guarantee that a stripped copy is untraceable server-side.
+
 ## 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.
@@ -407,14 +496,14 @@ Watermarking and provenance for AI-generated content is now regulated in several
 
 ## 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.
+This tool removes specific, known signals: the embedded SynthID pixel watermark, the visible vendor marks, and the C2PA / EXIF / IPTC provenance metadata that platforms read to apply automatic "Made with AI" labels. It is **not** a general detector-evasion tool. It does **not** defeat trained statistical AI-vs-real classifiers (for example Hive Moderation), and a light diffusion pass will not reliably fool those, so a clean classifier hit after removal is expected, not a bug. It also does **not** retroactively anonymise generation. And watermarking is a weak trust signal in the first place: a marker that is almost always present yet trivially removable can make a cleaned forgery look more trustworthy, not less, which is why durable provenance more likely comes from signing genuine content than from watermarking synthetic content.
 
 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.
+- A real photo of yours was lightly AI-edited (a retouch in Gemini or ChatGPT, say) and now carries a SynthID or C2PA label that overstates how AI-generated it is, and you want to clear that label from your own copy.
 
 Use cases where the threat model **does not** fit:
 - Generating an image, expecting that removing the watermark anonymises you to Google. It doesn't.

docs/known-limitations.md

@@ -0,0 +1,124 @@
+# Known limitations: full detail
+
+> Relocated verbatim from `CLAUDE.md` on 2026-06-11 to keep the always-loaded
+> context small. Long single-line entries were reformatted into paragraphs;
+> no content was changed or summarized.
+
+Full detail behind the compact Known-limitations list in `CLAUDE.md`:
+measurements, incident history, oracle runs, and the reasoning behind each
+decision. Read the relevant section here before changing the diffusion
+pipelines, strength defaults, or metadata coverage.
+
+## Invisible-pipeline resolution handling (native / 1024 floor / `--max-resolution`; MPS memory tiers)
+
+`invisible` pipeline processes at **native resolution for inputs whose long side is >= 1024px**, and **auto-upscales smaller inputs UP to a 1024px floor** (`min_resolution=1024`, the default; `--min-resolution 0` disables) before diffusion -- SDXL img2img distorts badly on a tiny latent (a 381x512 portrait wrecks at native, the #36 follow-up), and the output is restored to the original input size so the floor is a transparent quality boost (it adds time/memory on small inputs). The floor upscale uses Lanczos by default; **`--upscaler esrgan`** (opt-in, the `esrgan` extra) runs Real-ESRGAN first for better detail before the Lanczos resize to the exact target (`upscaler.py` / `InvisibleEngine._esrgan_upscale`, falls back to Lanczos if the extra is absent). `max_resolution=0` (default) means no downscale cap, matching the hosted raiw.cc backend (fal fast-sdxl, no pre-downscale). The old forced downscale-to-1024 -> upscale-back round-trip for LARGE images was the main quality loss (issue #10) and is gone; at strength ~0.05 SDXL img2img does not need a downscale.
+
+**Final `--unsharp` post-filter (`humanizer.unsharp_mask`, opt-in, default 0):** applied LAST (after the face-restore pass, else it would be smoothed over) to counter the soft/over-smoothed look diffusion + restoration leave (an AI tell); ~0.5-0.8 safe, higher risks halos. Pairs with `--humanize` (grain adds sensor-noise texture, unsharp adds crispness). `--max-resolution N` re-introduces an opt-in long-side cap purely to bound GPU/MPS memory on very large inputs (it reintroduces the lossy round-trip). For huge images that OOM at native, tile-based diffusion is still the proper long-term fix.
+
+**Concrete MPS data points (the OOM is memory-tier-dependent, NOT a hard MPS limit):** on a ~24 GB unified-memory machine (verified 2026-05-25, 1254x1254 gpt-image SDXL, fp32) native res OOMs at the *UNet* step (peak ~17 GiB), not only the VAE decode, and the auto-fallback in `img2img_runner` reloads on CPU and finishes (slow, ~13 min) -- the output is still weight-identical and defeats SynthID, so "looks hung/crashed" on Mac is usually this CPU fallback, not a pipeline error. On a **32 GB** unified-memory machine the same default SDXL pass runs entirely on MPS with **no CPU fallback** (verified 2026-05-31, 1122x1402 gpt-image, `all`/default, ~155 s end-to-end), so 32 GB clears the native-res UNet peak that 24 GB could not. Adding `enable_vae_tiling()` alone does NOT prevent the 24 GB OOM (the peak is the UNet, not the VAE). The fast Mac workarounds for memory-constrained machines are fp16 on MPS (roughly halves memory) or `--max-resolution` to cap the long side; neither is wired as the default. The `controlnet` pipeline adds the canny ControlNet weights on top of SDXL, so its peak is a bit higher than the plain `default` pass; the same MPS->CPU fallback covers an OOM. The native-vs-cap-vs-floor decision lives in the pure helper `invisible_engine._target_size(w, h, max_resolution, min_resolution)` (returns `None` for native, a target tuple for a downscale cap OR an upscale floor; cap takes precedence, the floor is skipped on a min>max misconfig) so it is unit-tested (`tests/test_invisible_engine.py::TestTargetSize`, the #10/#15/#36 regression guard) without loading the model -- keep that logic in the helper, don't re-inline it.
+
+## fp16 VAE black-output fix (issue #29) + degenerate-output fp32 backstop (issue #41)
+
+**fp16 VAE black-output fix (issue #29, 2026-05-30):** on a **CUDA/XPU fp16** backend the stock SDXL VAE overflows to NaN and the *plain* img2img path decodes to an **all-black** image (reproduced on the raiw.cc result: a 1086x1448 input -> a uniformly black 4.6 KB PNG, mean 0). `watermark_remover._load_pipeline` / `_load_controlnet_pipeline` swap in the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix` = `_SDXL_FP16_VAE_ID`) when `_needs_fp16_vae_fix(model_id, DEFAULT_MODEL_ID, is_fp16)` is true -- only the default SDXL checkpoint on fp16.
+
+**cpu/mps run fp32** (the stock VAE is fine there, which is why the bug never reproduces on Mac). A custom non-SDXL `model_id` keeps its own VAE (the fp16-fix VAE is SDXL-architecture-specific). The decision is a pure helper, unit-tested without a download (`tests/test_platform.py::TestFp16VaeFix`); the actual black->clean recovery needs a CUDA GPU.
+
+**Confirmed on real CUDA hardware 2026-06-03:** running `all` on a 1086x1448 OpenAI gpt-image (the #29 repro size) at fp16 produced a normal (non-black) output, so the fp16-fix VAE swap resolves the all-black decode. (It was not reproducible on this MPS machine, which runs fp32, so the verification had to happen on an NVIDIA box.)
+
+**Follow-up safety net (issue #41, 2026-06-04):** the swap is gated to `model_id == DEFAULT_MODEL_ID`, so a custom model, a stale pre-fix install, or a fal/custom loader can still hit the black decode -- a new reporter did (gpt-image 1448x1086, the #29 size, with the exact `image_processor.py:142 invalid value encountered in cast` warning the NaN->0 cast emits). `remove_watermark` now adds a model-agnostic backstop: after generation, if the run was fp16 AND the output is degenerate (`_is_degenerate_image`: mean and std both below `_DEGENERATE_THRESHOLD` 1.0 -- a uniform all-black/NaN frame; the variance guard spares a legitimately dark-but-textured photo), it rebuilds the pipeline in fp32 on the SAME device and re-runs once. fp32 is the verified-clean path, so the user never gets a black image regardless of model_id/version. Mirrors the existing MPS->CPU fallback's self-mutation pattern (reset `torch_dtype` + clear `_pipeline`/`_controlnet_pipeline`); `batch` inherits it through `remove_watermark`, and once one image trips it the rest of the batch stays on the safe fp32. The detector is a pure helper, unit-tested without a model (`tests/test_platform.py::TestDegenerateOutputGuard`); the full fp16->detect->fp32-retry chain was verified e2e on this MPS machine by forcing fp16 with the swap disabled (first pass black, guard fired, retry produced a normal image). CAVEAT: the fp32 retry uses ~2x memory, so on a VRAM-constrained GPU it can OOM (a visible error, still better than a silent black frame; the MPS->CPU fallback covers that path). The reporter's "CPU also black" symptom is NOT reproducible here -- fp32 (cpu/mps) decodes clean -- so it points at an old version or a non-fp32 run, pending their version + command.
+
+## rich was dropped (plain-text CLI and scripts)
+
+**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.
+
+## AVIF/HEIF/JPEG-XL metadata, ISOBMFF/ffmpeg removal, audio watermark detection
+
+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 (no local pixel detector)
+
+**SynthID detection is metadata-only.**
+
+There is no reliable *local* detector of the SynthID *pixel* watermark — Google's decoder is proprietary, no public spec or API (only a waitlisted portal). Authoritative confirmation: Google DeepMind's own paper "SynthID-Image: Image watermarking at internet scale" (Gowal et al., arXiv:2510.09263) states the verification service is restricted to "trusted testers" and does not release detector weights or a reproducible algorithm — so a local pixel detector is infeasible by design, not just unbuilt. https://arxiv.org/abs/2510.09263 We detect SynthID by its C2PA companion (`synthid_source` / `SYNTHID_C2PA_ISSUERS`), which is reliable while the manifest is intact but says nothing once C2PA is stripped.
+
+**Surface-dependent blind spot (verified 2026-05-24):** the same Google model emits different metadata per surface -- the Gemini *app* wraps outputs in Google C2PA, but the *API/playground* (AI Studio, Nano Banana / gemini-2.5-flash-image) emits the SynthID *pixel* watermark (confirmed via the Gemini-app oracle) + the visible sparkle but **no C2PA/IPTC at all**, so `synthid_source` returns None despite SynthID being present. Only the pixel oracle or the visible-sparkle detector catches those. (Meta AI is another surface mismatch: it writes the IPTC `digitalSourceType=trainedAlgorithmicMedia` marker, not C2PA and not SynthID.) Google→SynthID is long-standing; OpenAI→SynthID is confirmed by OpenAI's Help Center (ChatGPT/Codex/API "include both C2PA metadata and SynthID watermarks", updated 2026-05-21) but time-gated (pre-rollout OpenAI images carry C2PA without SynthID), so the OpenAI verdict is hedged "likely". Oracles: Gemini app "Verify with SynthID" (Google), openai.com/verify (OpenAI).
+
+**Each vendor's oracle detects only its OWN content (verified on the page 2026-05-31):** `openai.com/research/verify` states verbatim "OpenAI generation signals will only be detected if the image was generated with our tools" and "Content could also still be AI-generated by another company's model, which the tool currently does not detect" -- SynthID is shared tech but the verifier is keyed to its own vendor's payload, so a Google-SynthID image reads clean on OpenAI's verifier and vice-versa.
+
+**This explains the recurring "oracle says clean but `identify` still flags SynthID" report (#14):** the oracle reads the *pixel* watermark (gone after our SDXL pass), while `identify` reads the *C2PA-metadata proxy* (still present if the manifest survived). Different signals, not a contradiction -- strip the metadata too (`metadata --remove` / `all`) and the proxy goes quiet, but a quiet proxy is not proof the pixel watermark is gone.
+
+**SynthID is durable to JPEG re-encode by design, so a GitHub-recompressed issue attachment is still a valid SynthID test subject** (verified 2026-06-01 on issue #14's pic3: the GitHub-served JPEG survived re-encoding and openai.com/verify still detected SynthID). Do NOT dismiss issue-attachment JPEGs as "not faithful originals" when reproducing a SynthID-survival report: the recompression strips the **C2PA metadata** (so `identify` reads Unknown on the attachment) but NOT the **pixel watermark** that openai.com/verify reads. A true byte-original only matters for the metadata/C2PA path, not for the pixel-SynthID-removal test. (Contrast the open imwatermark above, which IS fragile to JPEG.) The spectral phase-coherence approach from `github.com/aloshdenny/reverse-SynthID` was evaluated (May 2026) and **does not work for real-content detection**: on its own shipped codebook + validation set, watermarked and cleaned images were indistinguishable (conf within noise, cleaned often higher); it only fires on pure-black 1024x1024 reference images at exact resolution (the controlled case it was calibrated on). The README's "90% / conf=0.91" reproduces only in that lab condition. Do not build a production detector on it; if revisited, it is experimental/diagnostic only and needs a per-resolution, per-model reference corpus. A from-scratch gpt-image pilot (2026-05-24) confirmed this independently: 5 independent solid-black gpt-image outputs share a near-identical fixed signature (pairwise residual correlation **0.92**, avg-template retains 97% energy), so the watermark/carrier IS strongly present and consistent on flat content — but the carrier frequencies extracted from it do NOT discriminate real content (carrier-to-random ratio: cleaned 1.86 > watermarked 1.53; a non-gpt-image image scored highest at 3.67). The signature drowns in content texture. Net: a perfectly consistent solid-color signature still yields no real-content pixel detector with magnitude/carrier methods. A corpus discrimination test (2026-05-24, `scripts/synthid_pixel_probe.py`, raw zero-mean residual NCC) independently re-confirms this: at matched resolution, SynthID positives do NOT cluster apart from negatives (within-Gemini 0.07; at 1024 px pos-vs-neg >= pos-vs-pos). The only high correlations were near-duplicate *content* (5 ChatGPT renders of one prompt at ~0.92, while a distinct ChatGPT image scored ~0 against them) — content, not a carrier. The probe is solid-fills-only and EXPERIMENTAL/DIAGNOSTIC; do not use it on real content.
+
+**Correction (deeper re-examination 2026-05-25):** the carrier IS real on solid fills — the earlier "no carrier" was a *method* artifact of using spatial / FFT-magnitude NCC, which can't see it. The carrier is a fixed *phase* at specific low frequencies, so the right metric is **per-bin phase coherence**. On 8 white `gemini-2.5-flash-image` fills (generated via the reverse-SynthID trick: identity-edit prompt "Recreate this image exactly as it is" on a synthetic pure-white PNG — this bypasses the recitation block that rejects text prompts for pure colors), phase coherence at the white carriers `(0,±7..±12,±20..±23)` = **0.86** vs **0.31** random; single-image leave-one-out phase-match **+0.83** vs real photos **-0.24**. (Black `2.5-flash` fills clip to std≈0 — SynthID can't push values below 0, so no carrier in black; the repo's dark carriers come from nano-banana-pro.)
+
+**But it does not generalize:** (a) carriers are model-version + resolution + color specific — the repo's v4 codebook (built for `gemini-3.1-flash-image-preview` + `nano-banana-pro-preview`) scores ~0.527 on my 2.5-flash white fills, indistinguishable from negatives (~0.50), i.e. carriers shift across model versions and need a per-model codebook; (b) on real content (30 `2.5-flash` images) the carrier collapses — set phase coherence at carriers 0.37 ≈ random 0.42, and the repo's v4 detector gives content 0.518 ≈ negatives 0.504 (no separation; a faint +0.24 single-image lean is likely a brightness confound). Net: the spectral/phase approach is a real *controlled-fill* characterizer, NOT an arbitrary-real-content detector, and is brittle to model version. Metadata proxy + visible sparkle + online oracles remain the ceiling for real content.
+
+## External AI-vs-real classifier models are out of scope
+
+**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.
+
+## Default strength is vendor-adaptive, one ladder for both pipelines
+
+**DEFAULT STRENGTH IS VENDOR-ADAPTIVE, ONE LADDER FOR BOTH PIPELINES (raised + unified 2026-06-09; vendor-adaptive since 2026-06-01, SUPERSEDES every fixed-default claim in this bullet and the next).**
+
+`resolve_strength(strength, vendor)` + `vendor_for_strength(path)` (`watermark_profiles.py`) read the C2PA issuer (`metadata.synthid_source`) on the ORIGINAL input and pick `OPENAI_STRENGTH` **0.20** / `GEMINI_STRENGTH` **0.30** / `UNKNOWN_STRENGTH` **0.30** when `--strength` is unset; explicit `--strength` always wins.
+
+**The SAME ladder applies to BOTH pipelines** (`sdxl` and `controlnet`) -- these are the 2026-06-04 Modal-cert controlnet floors.
+
+**Why one ladder (NOT a per-pipeline split):** the cert was run on controlnet and does NOT transfer to `sdxl` by symmetry (opposite hard cases -- controlnet leaves SynthID on photoreal, `sdxl` on flat graphics), BUT on its OWN hard case (flat fills) `sdxl` is the WEAKER remover (plain img2img barely perturbs a flat region at low strength), so it needs AT LEAST controlnet's strength -- hence the certified floor is the right floor for `sdxl` too. It is a MARGIN argument for `sdxl`, not a fresh certification (no local SynthID detector to self-verify); raise `--strength` if an oracle still reads a flat `sdxl` output. The higher strength costs little quality because `controlnet` is now the default pipeline AND the only `--auto` pick, so `sdxl` is reached only via an explicit `--pipeline sdxl` (a deliberate opt-down for inputs without faces/text), where over-regeneration has nothing to damage. (A short-lived per-pipeline split ladder -- `sdxl` 0.15/0.20 vs controlnet 0.20/0.30 -- existed on 2026-06-09 before being unified the same day; the `resolve_strength` `pipeline` param and the `CONTROLNET_*_STRENGTH` constants were removed.) The CLI detects the vendor from the pristine source (before the visible pass / metadata-strip removes C2PA from the temp file) and passes it to display calls so display and execution agree; `cmd_invisible`/`cmd_all`/`batch` thread `vendor`.
+
+**This replaces the single 0.30 default AND the prior "do NOT build a vendor-adaptive default" policy** -- both came from the now-debunked region-rescrub-contaminated study (the per-region re-scrub that contaminated those numbers was removed in the controlnet refactor). Basis: the oracle-verified June 2026 controlled study (clean v0.8.6, protect OFF): OpenAI clears at 0.05 across 1024-1600 (n=4, resolution-independent); Google needs 0.15 on the capped-1536 path (n=4). `docs/synthid.md` §2.2 (data) + §5.2 (the adaptive default) are authoritative.
+
+**CAVEAT (oracle pass 2026-06-04): the OpenAI 0.10 default is content-dependent, NOT universal -- a flat-graphic OpenAI logo/poster still read SynthID-detected after `default` at 0.10, and photoreal images after controlnet at 0.10/0.15 (low-change regions under-perturbed). Removal at 0.10/0.15 is content×pipeline dependent (see the controlnet Known-limitations bullet); the lever is a higher strength, oracle-revalidated per content type. Do NOT assume the vendor-adaptive default clears every image.**
+
+CAVEAT: Google's 0.15 was validated only on `--max-resolution 1536`; native large Gemini (2816) was not locally measurable (OOM on M-series) and is pending GPU validation on raiw.cc -- if it survives 0.15 native, raise `--strength`.
+
+**Everything below in this bullet about a fixed 0.10/0.30 default is HISTORICAL; trust the vendor-adaptive constants + docs/synthid.md.**
+
+## SynthID removal: strength + oracle scope
+
+**SynthID removal: strength + oracle scope.**
+
+Default strength is vendor-adaptive (see the bullet above); `docs/synthid.md` §2.2 is authoritative for the numbers.
+
+**Oracle scope (load-bearing):** the Gemini app "Verify with SynthID" is the ONLY valid SynthID oracle (detects Google's mark on any image); `openai.com/verify` is scoped to OpenAI provenance (its own C2PA), NOT a SynthID oracle -- a negative there is meaningless for SynthID. There is no local SynthID detector, so the tool cannot self-check; if the oracle still reads SynthID, raise `--strength` to the lowest value that verifies clean. Only the `sdxl` (plain SDXL img2img; `default` is a back-compat alias) and `controlnet` (SDXL + canny ControlNet) profiles exist; the local `invisible` default is weight-for-weight identical to raiw.cc prod (`fal-ai/fast-sdxl` = `stabilityai/stable-diffusion-xl-base-1.0`, runtime-downloaded, not bundled).
+
+**Forensic-stealth caveat** (arXiv:2605.09203): defeating the SynthID verifier is NOT forensic invisibility -- independent detectors flag *removal-processed* images vs genuinely-clean ones at >98% TPR@1%FPR, so do not over-claim "indistinguishable from a real photo".
+
+## `controlnet` pipeline: content x pipeline removal, certified floors, no face-restore
+
+**`controlnet` pipeline (text/face STRUCTURE preservation, THE DEFAULT since 2026-06-09; `--pipeline default` opts down to plain SDXL).**
+
+SDXL + the canny ControlNet `xinsir/controlnet-canny-sdxl-1.0` via `StableDiffusionXLControlNetImg2ImgPipeline` (`watermark_remover._run_controlnet` / `_load_controlnet_pipeline`).
+
+**Removal still comes from the img2img regeneration (`strength`); the ControlNet only PRESERVES text and face STRUCTURE by conditioning on the canny edge map** (`cv2.Canny(gray, 100, 200)`, 3-channel). Canny preserves edges, NOT face identity (a regenerated face drifts in likeness). The drifted cleaned face is the LEAST-AI state we can reach without re-introducing SynthID; **the library does NOT ship a face-restore extra** (every approach evaluated 2026-06-04 - 2026-06-08 -- GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps -- regenerated the face via SDXL and made it look MORE AI-generated). Full empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up". For production face preservation, ship the cleaned image as-is. No original pixels are copied or frozen, **BUT removal at the low vendor-adaptive strength is CONTENT × PIPELINE dependent and NEITHER pipeline clears all content -- oracle-validated against the OpenAI verifier 2026-06-04 (8 images, strength 0.10/0.15, `--max-resolution 1536`).**
+
+The survivors FLIP by content type: **photoreal** (a 9-face grid, a bracelet product photo) SURVIVES controlnet but CLEARS `default` (controlnet's dense edge map keeps the regen too close to the original, so the SynthID-destroying perturbation never happens; plain img2img perturbs photoreal texture enough); **flat graphic** (a logo/poster with large flat color fills) SURVIVES `default` but CLEARS controlnet (at low strength img2img barely changes flat fills so SynthID persists there, while controlnet repaints them more freely); a flat **text** card cleared under both.
+
+**Root cause is insufficient STRENGTH, not the pipeline: at 0.10 the low-change regions -- dense-edge photoreal under controlnet, large flat fills under `default` -- are not perturbed enough to destroy SynthID. The vendor-adaptive 0.10 from the June study is NOT universally sufficient (that study's content happened to clear at 0.10).**
+
+The robust fix is a HIGHER strength, oracle-revalidated per content type (controlnet can be cranked harder without losing structure; a lower `controlnet_conditioning_scale` also frees the regen on photoreal). So at today's default strength **both pipelines AND `--auto` can LEAVE SynthID on some content** -- a removal-priority caller (raiw.cc) MUST oracle-validate strength across content types before adopting, not pick a pipeline and assume removal.
+
+**Follow-up same day: re-running the two photoreal survivors through controlnet at an explicit `--strength 0.15` cleared BOTH on the oracle -- BUT one of them (the bracelet) had SURVIVED the SAME 0.15 controlnet config in the first pass (only the random, unset seed differed). So removal near the threshold is SEED-NON-DETERMINISTIC: the same image+pipeline+strength+resolution can pass or fail run-to-run (img2img uses `seed=None`/random unless `--seed` is passed, and there is no local SynthID detector to self-verify). 0.15 is the borderline, NOT a robust floor -- pick a strength with MARGIN (controlnet ~>= 0.20) rather than exactly on it; the content×pipeline table's 0.15 data point is near-threshold noise. A confirming run at `--strength 0.20` controlnet cleared BOTH photoreal survivors on the oracle (ladder: 0.10 grid detected → 0.15 borderline/non-deterministic → 0.20 both clean), so **0.20 is the recommended robust controlnet floor for OpenAI photoreal** (one margin run, not an N-run repeatability proof -- a service should add margin or verify repeatability since there is no local SynthID detector to self-check).
+
+**Engineering follow-up DONE 2026-06-09 (three coupled changes):** (1) **strength raised + unified** -- `resolve_strength(strength, vendor)` now applies ONE vendor-adaptive ladder (the certified controlnet floors 0.20/0.30/0.30) to BOTH pipelines; see the DEFAULT STRENGTH bullet above for why one ladder covers `sdxl`. (2) **`controlnet` is now the DEFAULT pipeline** (CLI `--pipeline` default = `controlnet` + both engine ctors). Rationale: with the certified higher ladder it clears BOTH content classes that flipped in the content-x-pipeline table (photoreal AND flat graphic), whereas plain SDXL left SynthID on flat graphics -- so controlnet is the more removal-robust default. Cost: every non-`--auto` run now downloads the canny ControlNet weights + a higher memory peak (MPS->CPU fallback covers OOM). (3) **the plain-SDXL profile was renamed `default` -> `sdxl`** (`watermark_profiles.SDXL_PROFILE`/`normalize_profile`); `default` stays as a back-compat CLI/ctor alias (the `--pipeline` Choice accepts `sdxl`/`controlnet`/`default`, a click callback `_normalize_pipeline` maps `default`->`sdxl` AND warns that `default` is deprecated). (4) **the content-detection layer + `--auto` planner were removed and `--auto` was retired to a deprecated alias for `--adaptive-polish`** -- see the dedicated `auto_config.py`-removal bullet above (controlnet is the default pipeline and the polish self-gates, so detection changed nothing). raiw.cc still needs its own per-vendor/content calibration on the GPU worker for native resolution. The Gemini-native resolution caveat stands: controlnet 0.30 is certified only <=1536.** **CERTIFIED 2026-06-04 via the isolated `raiw-controlnet-cert` Modal app (`raiw-app/modal_cert.py`), restore OFF, ≤1536, each vendor on its own oracle: controlnet floors are OpenAI 0.20 (2 photoreal × 3 seeds = 6/6 clean; the 0.15-flipper is seed-robust at 0.20) and Gemini 0.30 (0.20 detected → 0.30 clean on 2/2 seeds). OpenAI 0.20 transfers to prod (resolution-independent); Gemini 0.30 holds only ≤1536 — Gemini is resolution-sensitive and raiw.cc runs NATIVE (`max_resolution=0`), so cap Gemini ≤1536 + use 0.30, or native-calibrate (~0.35+). Prod recipe: controlnet + per-vendor floor in `resolve_strength` (not the default ladder) + FIXED seed (kills the non-determinism).
+
+**No face-restore in the library:** every approach evaluated (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img, InstantID img2img-on-cleaned, 2026-06-04 - 2026-06-08 cert sweeps) regenerated the face via SDXL diffusion -- the output face inherited SDXL "clean skin" gloss and lost original identity precision, looking MORE AI-generated than the cleaned image, not less. The drifted face from controlnet 0.20 is the least-AI state we can reach; for a paid service that's the prod output. See `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up".**
+
+See `docs/synthid.md` §5.5 + `docs/controlnet-removal-pipeline-research.md` (certified floors table).** **Lesson: visual-quality + face-recovery validation does NOT prove watermark removal -- only the SynthID oracle does, across MULTIPLE content types; never infer removal from sharpness/identity, and never conclude from a partial result (the photoreal-only data first read as "controlnet shields, default removes" -- the flat-graphic result reversed it).**
+
+`controlnet_conditioning_scale` (CLI `--controlnet-scale`, default 1.0) is the structure-preservation knob (higher = closer to the original structure); fp32 on cpu/mps, fp16-fixed VAE on cuda/xpu. The `controlnet` profile is threaded explicitly (`WatermarkRemover(pipeline=...)` / `InvisibleEngine(pipeline=...)`), NOT inferred from `model_id`. This productionizes the `scripts/controlnet_sweep.py` prototype; see `docs/controlnet-removal-pipeline-research.md`.
+
+**Forensic-stealth caveat still applies** (arXiv:2605.09203): defeating the SynthID verifier is not forensic invisibility -- a "this image went through a removal pipeline" classifier can still flag the output.

docs/module-internals.md

@@ -0,0 +1,212 @@
+# Module internals
+
+> Relocated verbatim from `CLAUDE.md` on 2026-06-11 to keep the always-loaded
+> context small. Long single-line entries were reformatted into paragraphs;
+> no content was changed or summarized.
+
+Full per-module detail: design decisions, tuned thresholds, calibration
+history, incident records, and the regression-guard map. The compact module
+list lives in `CLAUDE.md`; read the relevant section here before changing a
+module.
+
+## `noai/c2pa.py`
+
+`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`
+
+`noai/constants.py` — PNG_SIGNATURE, C2PA_CHUNK_TYPE, C2PA_SIGNATURES, and `C2PA_AI_VENDORS` — the single `C2paAiVendor` registry of C2PA-signing vendors (issuer byte, resolved org name, the `identify` platform label, and a `synthid` flag), from which `C2PA_ISSUERS`, `SYNTHID_C2PA_ISSUERS` (issuers that pair SynthID with C2PA: Google, OpenAI), and `identify._ISSUER_PLATFORM` are all **derived** — plus `C2PA_SOFT_BINDINGS` (soft-binding `alg` prefix → forensic-watermark vendor: Adobe TrustMark, Digimarc, Imatag, Steg.AI, Microsoft, ...). Add a new C2PA vendor as one `C2PA_AI_VENDORS` entry (never edit the derived dicts), a new soft-binding to `C2PA_SOFT_BINDINGS`; not inline.
+
+## `metadata.py`
+
+`metadata.py` — `scan_head(path, size=1MB)` is the shared input for every C2PA/AIGC/IPTC byte scan: first `size` bytes plus the payloads of any provenance metadata found beyond that window — for ISOBMFF, the late provenance boxes from `isobmff.scan_c2pa_region` (catches a manifest after a large `mdat`); for **PNG**, the late `tEXt`/`iTXt`/`zTXt`/`eXIf`/`iCCP` chunks from `_png_late_metadata` (catches an XMP/EXIF packet appended after a large `IDAT`, e.g. a TC260 AIGC label at ~2.7 MB). Behavior-neutral (`f.read(size)`) for non-ISOBMFF inputs and for any file that fits within `size`. Use it instead of `open().read(1MB)` for any new marker scan.
+
+**Memoized per (path, size, mtime)** (added 2026-06-09, `_scan_head_cached` lru_cache, `maxsize=8`): one `identify`/`get_ai_metadata` call fans out to ~8 byte-scan detectors that each re-read the same file head, so the cache turns those into a single read; the mtime key invalidates on change, a stat failure falls back to an uncached read. `synthid_source(path)` returns the vendor name(s) if the C2PA manifest implies a SynthID pixel watermark, else None. Format-agnostic: PNG via the caBX parser, JPEG/WebP/AVIF/HEIF/JXL via a binary scan (C2PA marker + SynthID issuer + AI-source marker). `get_ai_metadata` surfaces the verdict, and `metadata --check` prints it as a callout. Both `get_ai_metadata` and `has_ai_metadata` guard the PIL open with `except Exception` (HEIC/unknown formats raise non-OSError) and fall through to the binary scan. `xai_signature(path)` detects xAI/Grok's EXIF-only scheme (`ImageDescription` = `Signature: <base64>` + UUID `Artist`); it feeds `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify`. `iptc_ai_system(path)` detects the IPTC Photo Metadata 2025.1 AI-disclosure XMP properties (`IPTC_AI_FIELD_MARKERS` = `AISystemUsed`/`AISystemVersionUsed`/`AIPromptInformation`/`AIPromptWriterName`) and returns the `AISystemUsed` generator name (or `"fields present"`). `remove_ai_metadata` routes **ISOBMFF video** (`.mp4`/`.mov`/`.m4v`) through the same `isobmff.strip_c2pa_boxes` as AVIF/HEIF (MP4 is ISOBMFF), and `_scrub_ai_exif` removes the xAI signature + AI-generator EXIF tags on JPEG output. `strip_c2pa_boxes` is **fail-safe** on a malformed box: it returns the original bytes unchanged with a logged warning instead of truncating the tail to EOF (detection-only `scan_c2pa_region` still stops at a malformed box). `_png_late_metadata` clamps each late-chunk read to the remaining file size (`safe_length = min(length, remaining)`) so a malformed `length` cannot drive a multi-GB allocation, AND advances the cursor by `safe_length` (not the raw `length`) so an inflated length cannot jump past EOF and abort the scan, silently skipping a genuine AI-label chunk after it.
+
+## `identify.py`
+
+`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, **C2PA cloud-manifest reference** via `metadata.c2pa_cloud_manifest` — signal `c2pa_cloud`, **medium**, provenance-only (does NOT set `is_ai`, excluded from `ai_from_metadata` + clash vendors): a C2PA 2.4 Durable-Content-Credentials case where the embedded manifest is stripped but an XMP `dcterms:provenance` pointer to the vendor's cloud manifest store (`_C2PA_MANIFEST_REPOSITORIES`, today `cai-manifests.adobe.com` → "Adobe Content Authenticity") survives, so the credentials stay recoverable server-side; only emitted when no embedded manifest already attributed the file — surfaced on 2 corpus PNGs 2026-06-10 that read fully `unknown` before, IPTC "Made with AI" + IPTC 2025.1 `AISystemUsed`, embedded SD/ComfyUI params, SynthID proxy, xAI/Grok EXIF signature via `metadata.xai_signature`, the China TC260 AIGC label via `metadata.aigc_label`, the HuggingFace `hf-job-id` job marker via `metadata.huggingface_job`, the Samsung Galaxy AI editing marker via `metadata.samsung_genai`, the visible marks — Gemini sparkle plus the ByteDance Doubao 豆包AI生成 / Jimeng 即梦AI / Samsung Galaxy AI "Contenuti generati dall'AI" text marks via the `watermark_registry` — open invisible watermark, Adobe TrustMark via `trustmark_detector`) into one `ProvenanceReport`. `is_ai_generated` is True or None (never asserted False — stripped metadata is not proof of clean origin). The `hf_job`, visible-mark, and Samsung `samsung_genai` signals are **medium** confidence: each lifts an otherwise-Unknown verdict to a tentative AI (`hf_only` / `visible_only` / `samsung_only`, parallel branches; `visible_only` fires on any `visible_*` signal) but is excluded from the high-confidence `ai_from_metadata` set, so none overrides a hard metadata signal.
+
+**Visible-mark detection** (`check_visible`, signals `visible_sparkle` / `visible_doubao` / `visible_jimeng` / `visible_samsung`): the Gemini sparkle keeps its own file-level path (`_visible_sparkle` → `gemini_engine.detect_sparkle_confidence`, promoted only at confidence ≥ `_SPARKLE_THRESHOLD` 0.5; corpus-tuned to separate Gemini sparkles ≥0.56 from non-sparkle ≤0.49), while Doubao/Jimeng/Samsung reuse the registry detectors (`_visible_text_marks` → `watermark_registry`, iterating `_VISIBLE_MARK_PLATFORM`), each gated by its own engine NCC threshold via `MarkDetection.detected` (Doubao 0.4, Jimeng 0.45, Samsung 0.4). Doubao/Jimeng are normally also caught by the TC260 AIGC metadata label and Samsung by its C2PA + `genAIType` marker, so the visible path is their stripped-metadata fallback. Visible marks set `platform` only when no harder signal already did, and (like the sparkle) are excluded from integrity-clash vendor claims. The cv2 dependency lives in the engines, not here.
+
+**`import identify` is deliberately light** (~21 MB; ~36 MB with cv2 loaded by a visible-mark run, ~106 MB for a full `check_visible` run): it imports only the pure `noai.c2pa`/`noai.constants` submodules, and `noai/__init__` is lazy (see "Test and lint"), so torch/diffusers are NOT pulled at import even in a full `gpu`/`detect` install — fits a 512 MB host. The heavy paths are opt-in: `check_invisible=True` needs the `detect`/`trustmark` extras (each pulls **torch**; TrustMark also **downloads weights**), so on a core-only deploy leave `check_invisible` off (it is a no-op there anyway). Before the lazy `__init__`, the mere presence of torch in the env inflated `import identify` to ~420 MB.
+
+**C2PA platform attribution is device-token-first, issuer-scan fallback** (`_device_platform` scans manifest bytes for `_DEVICE_C2PA_PLATFORM` tokens, then `_attribute_platform`/`_ISSUER_PLATFORM`).
+
+**Why, verified on real signed files 2026-05-26:** the old issuer-only byte-scan matched ANY issuer substring anywhere, so multi-entity manifests mis-attributed -- Leica→"Truepic" (a signing authority in the trust chain), Nikon→"Adobe Firefly" (XMP-toolkit "Adobe" + the sample's "Adobe_MAX" name), Pixel→"Google (Gemini)" ("Google LLC" cert org), Truepic→"Google". A distinctive device token wins instead.
+
+**Token distinctiveness is load-bearing:** bare `b"Truepic"` mis-fires (it appears in unrelated trust chains -- it mis-attributed the OpenAI `chatgpt-1.png` fixture), so the token is the specific `b"Truepic_Lens"` from the Lens SDK claim generator; likewise `b"Pixel Camera"` (cert CN) not bare `b"Pixel"`. `_DEVICE_C2PA_PLATFORM` lists ONLY tokens **verified against a real C2PA file**: Leica (`lc_c2pa`/`Leica Camera`), Nikon (`NIKON`), Pixel (`Pixel Camera` -- from a real Pixel 10 Pro file attached to c2pa-rs issue #1609/#1554), Sony (`sony.sig`/`sony.cert` -- Sony's own C2PA assertion namespace, verified on a real Sony PXW-Z300 file; NOT bare "Sony" which is a common EXIF Make), Truepic (`Truepic_Lens`). Canon/Bria have **no public direct-download C2PA sample** (checked exhaustively: GitHub issue/PR attachments, contentcredentials gallery, HF datasets -- all upload-to-verify or token-gated; Canon's only public file was a self-signed hobbyist CR3, not factory), so they stay unmapped until a real file is captured (same fixture discipline as Grok/Doubao). The Sony sample is video (MP4) -- our ISOBMFF C2PA path detects it; Sony Alpha stills likely share the `sony.*` namespace but are not separately verified.
+
+**Samsung Galaxy + ASUS Gallery live in a separate `_SIGNER_C2PA_PLATFORM` (scanned after `_device_platform`, before the issuer fallback), NOT in `_DEVICE_C2PA_PLATFORM`** — verified on real signed files 2026-05-29. Reason: a Galaxy phone stamps BOTH its device cert AND a `trainedAlgorithmicMedia`/genAIType AI marker on a Generative-Edit image, so treating it as a "genuine camera capture" would false-fire integrity-clash rule 2 on every Galaxy AI edit. The signer tokens (`b"Samsung Galaxy"` cert org — distinct from the EXIF `SM-xxxx` model string on ordinary Samsung photos; `b"com.asus.gallery"` claim generator) only resolve the platform label; the AI verdict still comes from the source-type / genAIType. ASUS Gallery is a C2PA-signed edit with no AI marker, so it attributes the platform without asserting `is_ai`.
+
+**Samsung's `genAIType` (in the proprietary `PhotoEditor_Re_Edit_Data` JSON) is an undocumented Galaxy-AI editing marker** (`metadata.samsung_genai`, gated on the `PhotoEditor_Re_Edit_Data` container; non-zero value = AI tool used, values {1,5} observed): medium-confidence because the field has no public spec (verified 2026-05-29: absent from C2PA spec + Samsung docs), but it co-occurred with `trainedAlgorithmicMedia` in 3/3 verified files that record a source-type and was the SOLE AI marker on a Galaxy S24 file that omits the source type. Camera C2PA marks capture authenticity, not AI (Pixel carries `computationalCapture`, not `trainedAlgorithmicMedia`), so these never set `is_ai` -- that stays driven by digital-source-type. `c2pa.cbor_text_after` (now public) is best-effort for the `generator` detail string only and can be None when the manifest keys it `claim_generator_info` (Pixel).
+
+**Issuer→generator mapping is `is_ai`-gated** (`_attribute_platform(issuers, is_ai=c2pa_is_ai)`): a specific AI-generator platform is named only when the digital-source-type is `trainedAlgorithmicMedia`; on a non-AI source an issuer substring is treated as incidental (an "Adobe XMP" toolkit string in an *unmapped* Canon/Sony capture would otherwise mislabel it "Adobe Firefly"), so it degrades to the neutral "C2PA signer: X" label. Real Firefly/OpenAI/Google output carries the AI source-type, so it is unaffected (verified: chatgpt-1.png→OpenAI, firefly-1.png→Adobe Firefly still attribute). `_attribute_platform` defaults `is_ai=True` so the mapping stays unit-testable in isolation. Add capture-camera tokens to `_DEVICE_C2PA_PLATFORM`, editing-app/AI-device signer tokens to `_SIGNER_C2PA_PLATFORM`, generator/issuer platforms to the `C2PA_AI_VENDORS` registry in `constants.py` (which derives `_ISSUER_PLATFORM`), not inline. For non-PNG containers (JPEG/WebP/AVIF/HEIF/JXL) the caBX parser returns nothing, so issuer (`_issuers_in`) and generator (`_ai_tools_in`, reusing `C2PA_AI_TOOLS`) are recovered by binary-scanning the first MB. EXIF `Software` / `Make` / `Artist` / `ImageDescription` and XMP `CreatorTool` generator tags are read by `metadata.exif_generator` (PIL+piexif for any format PIL opens incl. AVIF, plus a container-agnostic XMP raw-byte scan that also covers HEIF/JXL), matched against `AI_GENERATOR_TOKENS` so ordinary editors (plain "Adobe Photoshop") and real-camera `Make` ("Apple"/"Canon") are not flagged.
+
+**Ideogram tags its output with EXIF `Make="Ideogram AI"`** (verified on a real download 2026-05-24) — that's why `Make` is read.
+
+**Integrity-clash detection** (`_integrity_clashes`, surfaced as `ProvenanceReport.integrity_clashes`, printed in red by `identify` and serialized to `--json`): contradictions between independent generator stamps are a laundering/spoofing tell. Two rules: (1) two or more distinct AI-origin vendors named by **independent** signals (e.g. C2PA OpenAI + EXIF `Make="Ideogram AI"`), and (2) a camera-capture C2PA device (`_DEVICE_C2PA_PLATFORM`) coexisting with an AI-generation marker **from a source INDEPENDENT of the camera's own manifest**.
+
+**Rule 2's independence gate (added 2026-06-11):** a device that both captures and runs on-device generative AI (Google Pixel Magic Editor / Pixel Studio) records the capture AND the AI edit in ONE C2PA manifest — so the AI vendor is named only from that same manifest (`c2pa` issuer + `synthid` proxy, both `c2pa_manifest` source) — a legitimate edit chain, NOT a clash. Rule 2 therefore fires only when some `ai_vendor_claims` family has a source `!= "c2pa_manifest"` (EXIF/XMP generator, IPTC, TC260 AIGC, a second manifest naming AI on a camera capture — the real laundering tell). This killed a false-positive class on the corpus: 2 real Pixel generative-edit PNGs (`computationalCapture` + `trainedAlgorithmicMedia` + "Applied imperceptible SynthID watermark" in one Google manifest) read as camera-vs-AI clashes before the gate. Pure cameras (Leica/Sony/Nikon/Truepic) that do NOT generate AI still clash on any within-manifest AI marker only if it is independent — they never legitimately carry one, so the gate is behavior-neutral for them while fixing Pixel (regression-guarded by `test_identify.py::TestIntegrityClashesHelper::{test_pixel_generative_edit_same_manifest_no_clash,test_camera_plus_independent_ai_marker_still_clashes}` + `TestIntegrityClashEndToEnd::test_pixel_generative_edit_no_clash`).
+
+**Independence is source-grouped (`_CLASH_SOURCE`, added 2026-06-02):** the C2PA issuer attribution (`c2pa`) and the SynthID proxy (`synthid`) are NOT independent — the proxy is inferred from the *same* manifest — so they share one source and two vendors named within a single manifest do not clash. This killed a false-positive class found on the spaces corpus: legitimate multi-actor manifests where a product wraps another vendor's engine (Microsoft Designer on OpenAI → `OpenAI, Microsoft`; Microsoft on Google → `Microsoft, Google LLC, Google C2PA Core Generator Library`) or an edit chain re-signs (Adobe over a Gemini original → Adobe c2pa + Google synthid) — 19 such files across the 2026-06-01/02 batches read as clashes before the fix. Rule 1 still fires when a manifest vendor disagrees with a genuinely independent stamp (EXIF/XMP generator, IPTC `AISystemUsed`, AIGC, xAI); each non-`c2pa`/`synthid` family is its own source (`test_identify.py::TestIntegrityClashes::{test_multi_actor_manifest_no_clash,test_manifest_vendor_vs_independent_signal_clashes}`). Vendor normalization is `_vendor_of` over `_AI_VENDOR_TOKENS` (so a C2PA "Google (Gemini)" issuer and a SynthID-Google proxy agree, while different vendors clash).
+
+**High-precision by design:** only hard generator stamps feed it (C2PA-issuer when source is AI, SynthID, EXIF/XMP generator, IPTC `AISystemUsed`, xAI, AIGC); the fuzzy visible sparkle and the open invisible watermark are **excluded** (the latter can be a by-product of our own SDXL removal pass). The c2pa vendor is classified from the issuer attribution / generator, NOT the resolved `platform` (a camera label like "Google Pixel" would mis-normalize to "Google"). All real single-origin fixtures (chatgpt/firefly/doubao/grok/mj) verified to produce **zero** clashes (false-positive guard in `test_identify.py::TestRealSamplesHaveNoClash`).
+
+## `watermark_registry.py`
+
+`watermark_registry.py` — **single catalog of known visible watermarks**, the unified "find known marks in their usual places, recognize, remove" entry.
+
+**Reverse-alpha based by policy**: a mark is listed only once a real alpha map has been captured for it, and removal inverts that map (`original = (wm - a*logo)/(1-a)`) — Gemini recovers cleanly with no inpaint (its sparkle alpha comes from a pure-black capture, so it is near-exact), while **Doubao, Jimeng, and Samsung all add an always-on THIN residual inpaint** over the glyph footprint (their text marks re-rasterize + jitter a few px per image, so a single capture cannot pixel-cancel them; the inpaint blends into the reverse-alpha-recovered pixels). Arbitrary-region inpainting still lives in `region_eraser`/`erase`. Each `KnownMark` ties a key to {usual `location`, `in_auto` flag, `recovery` (="reverse-alpha"), a `detect` adapter → uniform `MarkDetection`, a `remove` adapter}. Entries today: `gemini` (bottom-right sparkle), `doubao` (bottom-right "豆包AI生成"), `jimeng` (bottom-right "★ 即梦AI"), and `samsung` (bottom-**LEFT** "✦ Contenuti generati dall'AI", Samsung Galaxy AI, Italian locale). `detect_marks` scans all; `best_auto_mark` picks the highest-confidence detection.
+
+**Cross-engine confidences aren't directly comparable**, so the gemini adapter applies the corpus-validated 0.5 sparkle threshold (`_GEMINI_AUTO_MIN_CONF`) for its `detected` flag — otherwise the gemini engine's loose internal threshold weakly fires (~0.36) on the Doubao text and hijacks `auto`. The shape-keyed Doubao/Jimeng/Samsung NCC detectors don't cross-fire (jimeng scores ~0.22 on the Doubao strip, well under its 0.45 threshold; Samsung is bottom-left so it shares no corner with the others, and scored 0.0 on Doubao/Jimeng captures and they 0.0 on a real Samsung photo), so `auto` picks the right one. `cli.cmd_visible` is registry-driven: `--mark auto` → `best_auto_mark`, `--mark <key>` → that mark; `--mark` choices come from `mark_keys()`.
+
+**`cli._remove_visible_auto` is the shared visible-removal helper used by `cmd_all`/`cmd_batch` too** (they no longer hardcode `GeminiEngine`), so `all`/`batch` remove Doubao/Jimeng/Samsung text marks, not just the Gemini sparkle (regression-guarded by `test_all_visible_step_uses_registry`). The three text-mark adapters were consolidated 2026-06-09: a single `_text_mark(key, label, location)` builds the registry row from one parameterized `_text_mark_detect`/`_text_mark_remove` pair (reverse-alpha only when detected/forced AND `reverse_alpha_available`, else skipped — no inpaint); the gemini adapters stay bespoke. Add a new visible mark = one `_text_mark(...)` row + its `TextMarkConfig` (with a captured alpha map); do not re-add per-mark `if` branches or copy-paste adapters.
+
+**Alpha-on-save policy (issue #30):** `cli._write_bgr_with_alpha` rejoins the input's alpha plane **unchanged** — it must NOT zero alpha in the watermark bbox. Reverse-alpha (and `erase` inpaint) recover real pixels there, so zeroing alpha punched a transparent hole that renders as a solid **white box** on any non-transparent viewer (Gemini app exports are opaque RGBA, so every user hit it; regression-guarded by `test_visible_keeps_alpha_opaque_in_watermark_region`). The registry `remove()` still returns its region (used for `inpaint_residual` positioning), but the CLI no longer uses it to clear alpha.
+
+## `gemini_engine.py`
+
+`gemini_engine.py` — visible Gemini-sparkle remover/detector (cv2/numpy, no GPU). `detect_sparkle_confidence(path)` is the file-level entry point used by `identify.py`. The public entry points normalize a grayscale (2D) or RGBA (4-channel) input to BGR up front so a non-BGR image does not crash the cv2 pipeline.
+
+**Detection localization (issue #36):** `detect_watermark`'s global multi-scale NCC search applies a size weight (`(scale/96)**0.5`) that suppresses tiny-patch false positives but can let a larger, mediocre match (e.g. a bright collar in a portrait) outrank a small, near-perfect sparkle in the corner — so a faint sparkle on a busy background scored below threshold and read as clean (the regression osachub reported from widening the search window 256px->512px between v0.7.2 and v0.8.8). `_corner_promote` adds a bottom-right-corner raw-NCC pass on top of the global search: a match with raw NCC >= `_CORNER_PROMOTE_NCC` 0.85 that beats the global pick overrides it (it only ever replaces a lower-fidelity pick, so it cannot weaken an existing detection), rescuing the buried sparkle without reverting the wider window. The corner side is **relative-clamped** (`_CORNER_PROMOTE_FRAC` 0.20 of the short side, clamped to `[_CORNER_PROMOTE_MIN` 96, `_CORNER_PROMOTE_MAX` 384`]`): a fixed 256px is a true corner on a large image but covers ~70% of a small portrait, where a real photo raw-matches the star at ~0.81 (relative tightening drops that worst case to ~0.69, while the upper clamp stops the corner ballooning on huge images where a real photo reached ~0.83 at 512px). The 0.85 gate sits midway between the worst real-photo corner match (~0.78 across native + downscaled negatives) and a genuine faint sparkle (~0.93), so promotion adds true detections with zero corpus false positives (Gemini's sparkle sits ~60-160px from the corner at fixed margins, covered by the [96, 384] band at every measured size). Regression-guarded by `test_gemini_engine.py::TestCornerPromotion`.
+
+**Top-K fusion selection (osachub follow-up 2026-06-12):** `_corner_promote`'s 0.85 raw-NCC gate still missed a class the 256->512 widening exposed — a genuine MID-scale sparkle whose raw NCC sits *below* 0.85 but is buried by a LARGER, low-fidelity decoy that wins the size weight. The reporter's image (a scale-48 sparkle on light bedding) measured spatial 0.775 / grad 0.960 / fusion 0.676 at the true sparkle, but the size-weighted argmax instead locked onto a decoy at spatial 0.628 / grad 0.036 (fusion 0.325) — so `identify` read `unknown` on v0.8-0.11 where v0.7.2 (256px window) had caught it at 0.676. Fix: `detect_watermark` now keeps the **top-`_SELECT_TOPK` (3)** size-weighted candidates (NMS-deduped by location) plus the corner-promote candidate, scores EACH by the full fusion (spatial+gradient+variance) via the extracted `_grad_var_scores` helper, and selects the highest — the gradient term (the discriminator a contrast-invariant spatial NCC lacks) lifts the true sparkle over the decoy. Critically, selection ranks by the SIZE-WEIGHTED score, NOT raw NCC: a raw-NCC argmax (tried first) re-admitted the exact tiny-patch (scale 16-18) false positives the size weight exists to suppress — it flagged 14/65 doubao + 4/11 jimeng visible-corpus images (non-Gemini content) as Gemini sparkles. Top-K keeps tiny-patch suppression intact: a coincidental 16px match never ranks in the size-weighted top-K, so widening selection added **zero** flips on the doubao/jimeng corpora and left the 495-image Gemini set unchanged (479 detected, both before and after) while recovering the reporter's image. Regression-guarded by `test_gemini_engine.py::TestCornerPromotion::test_low_gradient_decoy_loses_to_high_gradient_corner_sparkle` (mirrors the real spatial/grad signature via a monkeypatched scan) and `test_size_weighted_search_alone_traps_on_the_decoy`.
+
+**Square-image residual misses are NOT fixable by lowering the detector threshold (measured + REJECTED 2026-06-11):** osachub (#36 follow-up) reported the corner-promote still misses Gemini sparkles on Google **square (1:1)** outputs. Reproduced on the spaces corpus: of 330 square Google-C2PA images, 140 score below the identify 0.5 threshold, and visual review confirmed a real class -- faint white sparkles on dark/textured/colored backgrounds (raw NCC 0.46-0.73, below the 0.85 promote gate) landing at fusion conf 0.41-0.47. A margin-gated promote (promote when raw NCC >= 0.50 AND `_core_ring_margin` >= 40) rescued 32/33 confirmed misses at an apparent 0 FP, but that 0 was a **measurement artifact** -- the negative set was the margin<40 misses, which a margin>=40 gate excludes by construction. On an honest 518-image non-Google pool the same gate fired on **~174 (≈33%)**, visually content (screenshots, Chinese "AI生成" Doubao/Jimeng text marks, logos, bright textures), not sparkles. Adding an achromatic-core constraint (`chroma <= 15`) did not separate them either (kept 15/33 POS, 41 NEG still firing). Root cause is the documented contrast-invariant-NCC wall: a faint sparkle on a busy background is indistinguishable from a bright/ornate content corner at the (shape-NCC, brightness-margin, core-chroma) feature level.
+
+**Conclusion: keep the 0.85 corner gate; do NOT add a margin/chroma-gated lower promote.**
+
+The cost (mislabel ~8-33% of non-Gemini content as Gemini) outweighs the benefit -- the visible sparkle is a medium-confidence stripped-metadata fallback, and intact Gemini is caught by C2PA in `identify` regardless. Remaining square misses are an accepted known limitation; a real fix would need a sparkle-specific discriminator (template match on a background-subtracted image, or a hard fixed-margin position prior), which is open research, not a threshold tweak.
+
+**Removal is reverse-alpha with an over-subtraction guard** (`remove_watermark` → `_reverse_alpha_blend`, else `_inpaint_footprint`): the sparkle alpha is computed (`alpha = max(R,G,B)/255`) from the bundled sparkle-on-black captures `assets/gemini_bg_{96,48}.png` (the capture max is ~130, NOT 255 — the sparkle is a ~51%-opaque white overlay, so `alpha` maxes at ~0.51, which is CORRECT for the capture, not under-exposed). The alpha is near-exact only when the real mark's effective opacity matches the capture, which holds on bright/flat backgrounds — re-verified clean on `demo_banana_before.png` 2026-05-31.
+
+**Issue #30 (dark-background black pit):** on a dark/textured background (e.g. grass, ~73) the real sparkle's effective opacity is LOWER than the captured 0.51, so the fixed-alpha reverse blend OVER-subtracts (`watermarked - a*logo` goes negative) and drives the footprint to black — the white sparkle becomes a black diamond. `remove_watermark` now detects this via `_reverse_alpha_oversubtracts` (fraction of footprint pixels with `alpha >= _FOOTPRINT_ALPHA` 0.1 whose numerator < 0 exceeds `_OVERSUB_FOOTPRINT_FRAC` 0.05) and **inpaints the footprint** (`_inpaint_footprint`, cv2 NS over the dilated alpha mask) from the surrounding pixels instead.
+
+**Behavior-neutral on the working case:** a bright background over-subtracts at ~0% so reverse-alpha is used and the output is byte-identical to before (verified: demo_banana 0.0 frac vs issue-#30 grass 0.61 frac; regression-guarded by `test_gemini_engine.py::TestOverSubtractionGuard`, which composites the sparkle at a reduced effective alpha to reproduce the mismatch).
+
+**Under-subtraction (the symmetric case, fixed 2026-06-03):** some real Gemini sparkles are rendered MORE opaque than the captured ~0.51, so the fixed-alpha reverse blend UNDER-subtracts and leaves a bright sparkle residual the detector still fires on (measured on the spaces corpus: a visible-removal audit through the registry path left a detectable sparkle on a meaningful fraction of marks, all under-removals, NOT a background-brightness class — failures and successes had the same input confidence and the same background-luma distribution; the discriminator was the removal delta itself). `remove_watermark` now estimates a per-image alpha gain (`_estimate_alpha_gain`: effective sparkle opacity at the bright core vs the local background ring, `a_eff/a_cap`, clamped `[1.0, _ALPHA_GAIN_MAX` 1.94`]`) and scales the alpha to match before the over-sub/blend branch. The gain cleanly separates on the corpus (under-removed marks ~1.47, cleanly-removed ~1.00), and a deadband (`_ALPHA_GAIN_DEADBAND` 1.05) keeps a matching sparkle **byte-identical** to the pre-fix output, so the fix is purely additive (0 regressions on the audit set; the over-sub guard still runs on the scaled alpha as the safety net for an over-shooting estimate). Regression-guarded by `test_gemini_engine.py::TestUnderSubtractionGain` (composites a more-opaque-than-capture sparkle; **asserts on footprint pixels, NOT the detector** — the detector's NCC is degenerate on a flat synthetic background, so a re-detect conf is meaningless there; the real corpus removal drops the detector from ~0.80 to ~0.27).
+
+**False-positive gate (added 2026-06-03):** `detect_watermark`'s shape-only NCC (`spatial*0.5 + gradient*0.3 + var*0.2`) fires on ornate/flat content (text strips, banners, hatching) that coincidentally matches the diamond shape — a real Gemini sparkle is a bright WHITE overlay, so its core sits above the local background, but the NCC is contrast-invariant and cannot see that. The fusion now **demotes** (caps confidence to 0.30) any match that is BOTH low-confidence (`< _SPARKLE_FP_CONF` 0.65) AND has a low core-ring brightness margin (`_core_ring_margin < _SPARKLE_FP_MARGIN` 5). Real sparkles escape via EITHER high confidence (white-bg sparkles score ≥0.79 despite a low margin — the NCC shape match is strong) OR high margin (dark/mid backgrounds, incl. the #36 faint-corner case, lift well clear), so BOTH must fail to demote. The gate is **monotonic** (only ever removes detections, never adds), so it cannot regress the verified-negative corpus (already 0 FPs). On the spaces corpus it demoted 16/495 flagged sparkles (13 carried no AI metadata = content FPs; the 3 AI-meta were visually FPs / a near-invisible white-on-white sparkle whose AI verdict is held by metadata anyway), and dropped the removal-audit failures 20→15 (post-removal flat footprints the NCC re-fired on). `_core_ring_margin` and `_estimate_alpha_gain` share the `_core_and_bg` helper (core 75th-pct brightness vs background-ring median). Regression-guarded by `test_gemini_engine.py::TestSparkleFalsePositiveGate`.
+
+**Self-verify repair (added 2026-06-04):** the gain estimate corrects most under-subtractions, but a tail of strong sparkles still survived reverse-alpha (position jitter, or a gain the `[1.0, 1.94]` clamp could not fully reach). After the reverse blend, `remove_watermark` re-detects via `_verify_and_repair`; when a sparkle at or above `_VERIFY_FALLBACK_CONF` 0.5 (the registry's real fail line) remains, it inpaints the footprint and **keeps that only when it lowers the re-detect confidence** — purely additive (the common clean removal re-detects below 0.5 and is returned untouched, so it can never regress). On the spaces corpus this rescued **4 of the 15 remaining gemini removal-audit failures** (15→11, doubao/jimeng still 0), verified through the registry/CLI path. Costs one extra `detect_watermark` per removal (two when the fallback fires). Regression-guarded by `test_gemini_engine.py::TestVerifyAndRepair` (stubs `detect_watermark` to drive the keep-best control flow, since the NCC is degenerate on flat synthetics).
+
+**An offset+scale alignment search was prototyped on the remaining 11 fails and REJECTED (2026-06-04):** an audit "ceiling" test suggested it could rescue 4 more (e.g. a5a9 0.577→0.417), but direct inspection showed those were NCC-gaming, not removal — the lower-scoring placement left the sparkle as bright or BRIGHTER (a5a9: first-pass slot 99.5th-pct ~76 at background level, the "aligned win" slot ~164), it just reshaped the residual so the contrast-invariant shape-NCC scored lower. A slot-brightness sanity gate rejected every one, so alignment contributed 0 genuine rescues and was removed (the footprint inpaint stays because it physically reconstructs the slot from its darker surroundings, so its rescues are real).
+
+**Lesson: the visible-audit pass/fail metric (re-detect conf < 0.5) is gameable by reshaping the residual — optimizing it directly finds NCC-gaming placements, not clean removals; gate any removal candidate on a physical brightness check, not the detector alone.**
+
+The 11 survivors are near-white ill-conditioning (reverse-alpha divides by `1-a`≈0.02) or detector false positives (before≈after≈0.51) that no reverse-alpha placement fixes. The registry's optional `inpaint_residual` (edge cleanup) is a no-op on a clean reverse-alpha removal (and on the same corpus it lowered the re-detect conf on 3 marks, raised it on 10, no-op on 466 — net-neutral on pass/fail, so the self-verify repair, not it, drives the removal tail); an earlier "Gemini smears" read was a misjudged soft-fur original, not an artifact.
+
+**The bg assets are now rebuilt from OUR OWN controlled captures** (`data/gemini_capture/captures/`, committed) by `scripts/visible_alpha_solve.py gemini`, which locates the 96px sparkle on the black capture and crops it to the two logo sizes; our capture matched the previously third-party-sourced `gemini_bg_96.png` to **NCC 0.9998**, validating the asset and making it reproducible. Gemini's multi-size fixed-slot model is genuinely different from the Doubao/Jimeng text-strip engines (so it stays a separate engine, not part of the shared-base refactor).
+
+## `_text_mark_engine.py`
+
+`_text_mark_engine.py` — **shared base for the three reverse-alpha text-mark engines (Doubao/Jimeng/Samsung), extracted 2026-06-09** (they were ~90% byte-identical clones). `TextMarkEngine(config: TextMarkConfig)` owns the whole `locate → extract_mask → detect → _fixed/_aligned_alpha_map → _apply_reverse_alpha → remove_watermark_reverse_alpha` pipeline (+ the asset-keyed `load_alpha_template`/`glyph_silhouette`/`template_match_score` caches). Each engine module is now a thin subclass: it supplies only its `TextMarkConfig` (the tuned constants, the bundled asset, and the bounded structural deltas — `corner` br/bl, `margin_floor` 4/2, `morph_open_size` 5/3, `min_gw` 8/16) plus the test-facing module shims (`_alpha_template`/`_glyph_silhouette`/`_template_match_score` + the constants). Behavior is byte-exact vs the old per-engine code (the three engine test suites pass unchanged). Gemini stays a SEPARATE engine (its multi-size fixed-slot sparkle model is genuinely different). Add a new text mark = a new `TextMarkConfig` + a thin subclass + one registry `_text_mark(...)` row. The engine bullets below describe each mark's calibration history; the LOGIC lives here.
+
+## `doubao_engine.py`
+
+`doubao_engine.py` — **a thin `_text_mark_engine.TextMarkEngine` subclass (config only) since 2026-06-09.** visible Doubao "豆包AI生成" remover/detector (cv2/numpy, no GPU). `DoubaoEngine.locate` anchors a bottom-right box by **geometry** (mark scales with image WIDTH), `extract_mask` pulls the light, low-chroma glyphs (the detection candidate) using a per-pixel channel-spread proxy `sat = roi.max(axis=2) - roi.min(axis=2)` (no HSV conversion). `detect` is **shape-consistent**: it matches the bundled alpha glyph silhouette (`assets/doubao_alpha.png`) against the candidate via zero-mean normalized correlation (`_template_match_score`, cv2 `TM_CCOEFF_NORMED`), gated at `DETECT_NCC_THRESHOLD` 0.4 over a small `DETECT_MIN_COVERAGE` floor. Keying on glyph SHAPE (not coverage heuristics) fixed #23 (corpus FP 7/1243).
+
+**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`
+
+`jimeng_engine.py` — **a thin `TextMarkEngine` subclass (config only) since 2026-06-09.** visible Jimeng / Dreamina "★ 即梦AI" remover/detector (cv2/numpy, no GPU), built 2026-05-30 from issue #13's solid captures (@powersee). Shares the base with `doubao_engine`: `locate` anchors a bottom-right box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma), `detect` matches the bundled "即梦AI" glyph silhouette (`assets/jimeng_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.45** cleanly separates real Jimeng marks (>=0.81) from the Doubao strip (0.21) and other AI output (0.0), so the two ByteDance marks don't cross-fire in `--mark auto`.
+
+**Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; the white capture + an L-pair-solve confirm ~254.6); compositing is **sRGB, not linear** (a linear-light solve tripled the cross-residual).
+
+**Alpha rebuilt by `scripts/visible_alpha_solve.py` from the GRAY capture** (`data/jimeng_capture/captures/`, the solid captures now committed): `a = (I - B)/(255 - B)`, B a per-capture **cubic** background fit over the non-glyph pixels, **averaged over channels, full halo extent (down to a~0.02), unblurred**. Gray (bg ~132) is the deliberate choice over black: it is the best proxy for real content (the mark sits on bright photo areas, not on black), and the careful build drops the gray self-residual to ~1.3.
+
+**The mask quality, not the method, was the earlier limit** — a max-channel / quadratic-bg / blurred / halo-truncated build (and a black-dominated LS) left a visible outline (lesson from issue #13: when reverse-alpha leaves a ghost, suspect the captured alpha map before adding heuristics or switching method). Geometry emitted by the solver at `_ALPHA_NATIVE_WIDTH` 2048: `_ALPHA_WIDTH_FRAC` 0.202, `_ALPHA_HEIGHT_FRAC` 0.058, margins ~0.029.
+
+**Removal = reverse-alpha + a deliberately THIN residual inpaint** (`remove_watermark_reverse_alpha`, `_RESIDUAL_DILATE` 5 over the `_RESIDUAL_ALPHA_FLOOR` 0.05 footprint, `_RESIDUAL_INPAINT_RADIUS` 2, `INPAINT_NS`): a single 2048 alpha cannot pixel-cancel the mark re-rasterized at another resolution (alpha maps from independent captures correlate 0.998, not 1.0; off-native reverse-alpha alone only halves the mark), so a tight inpaint clears the residual edges WITHOUT the texture/edge smear a wide full-footprint pass caused.
+
+**Placement ALWAYS tries fixed geometry AND `_aligned_alpha_map`'s NCC scale+position search, keeping the lower-residual** — the mark re-rasterizes + jitters a few px per image even at the captured width, so fixed geometry alone misses (there is no `_ALPHA_NATIVE_BAND` fast-path; the scale search `_ALPHA_ALIGN_SEARCH` is fine-stepped, and the `WM_*` locate box is generous so a corner-ward shift stays inside the search — the same widen that fixed Doubao). Verified clean on the solid captures (native 2048; faint self-residual ~1.3 visible only on a dead-flat field, hidden by real texture) and a real 1440-wide Jimeng download (off-native, table edge preserved). `reverse_alpha_available` is just "asset present"; the registry gates on `detect`.
+
+**No committed real sample** (the real content download stays gitignored; only the solid calibration captures are committed) — `tests/test_jimeng_engine.py` synthesizes a mark from the bundled alpha asset, and `test_recovers_shifted_mark_on_texture` guards the align-on-shift path that the Doubao defect exposed. Jimeng images are independently caught by the China TC260 AIGC label in `metadata`/`identify`, so this engine is the visible-mark *removal* path, not a new `identify` signal.
+
+## `samsung_engine.py`
+
+`samsung_engine.py` — **a thin `TextMarkEngine` subclass (config only) since 2026-06-09.** visible Samsung Galaxy AI "✦ Contenuti generati dall'AI" remover/detector (cv2/numpy, no GPU), built 2026-06-05 from issue #37's flat captures (@f-liva). Shares the base but anchored **bottom-LEFT** (Doubao/Jimeng are bottom-right): `locate` anchors a bottom-left box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma — `LOGO_MIN_LUMA` is lowered to **110** because the mark is faint, peak alpha ~0.38, so on a mid/dark background its glyph luma is lower than Jimeng's), `detect` matches the bundled glyph silhouette (`assets/samsung_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.40** (real marks ~0.79 on a real photo, ~0.57/0.71 on the black/gray captures; 0.0 on Doubao/Jimeng captures, and Doubao/Jimeng score 0.0 on a real Samsung photo — no cross-fire, also because the corner differs).
+
+**Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; white capture confirms).
+
+**Alpha solved by `scripts/visible_alpha_solve.py samsung` from the GRAY capture** (`data/samsung_capture/captures/`, the flat black/gray/white captures committed; the solver gained a `corner="bl"` mode + left-margin logging for this), same careful recipe as Jimeng (cubic background, mean-channel, full halo, unblurred). Geometry emitted at `_ALPHA_NATIVE_WIDTH` **1086** (the flat-edit capture width): `_ALPHA_WIDTH_FRAC` 0.3195, `_ALPHA_HEIGHT_FRAC` 0.0378, `_ALPHA_MARGIN_LEFT_FRAC` 0.0110, `_ALPHA_MARGIN_BOTTOM_FRAC` 0.0064.
+
+**Removal = reverse-alpha + a deliberately THIN residual inpaint** (`remove_watermark_reverse_alpha`, same `_RESIDUAL_*` recipe as Jimeng) with **always-try fixed AND `_aligned_alpha_map` NCC scale+position search, keep the lower-residual** (`_ALPHA_ALIGN_SEARCH` widened to (0.85, 1.18, 23) because the flat captures are far off the real-photo width).
+
+**Resolution caveat:** the flat captures arrived at 1086 wide while real photos are ~2958 wide (the mark scales with width, so the captured glyph ~334px is ~2.7x smaller than the ~903px real-photo glyph); width-scale + NCC-align still removes it cleanly (verified on a real 2958-wide @f-liva photo: re-detect 0.79→0.00, no readable text or outline on the recovered wooden table — checked **visually**, not just by the detector, per the Gemini self-verify lesson), but a flat capture at the real photo resolution would make the alpha pixel-sharp instead of upscaled (open quality upgrade, noted in `data/samsung_capture/README.md`).
+
+**The mark is locale-specific** (text differs per language); this build is the Italian "Contenuti generati dall'AI" variant — other locales need their own captured template. `reverse_alpha_available` is just "asset present"; the registry gates on `detect`.
+
+**No committed real sample** (the real photo stays gitignored; only the flat calibration captures are committed) — `tests/test_samsung_engine.py` synthesizes a mark from the bundled alpha asset (bottom-left geometry), with `test_recovers_shifted_mark_on_texture` guarding the align-on-shift path. Samsung Galaxy AI edits are independently caught by C2PA + the `genAIType` marker in `metadata`/`identify`, so this engine is the visible-mark *removal* path; it also feeds `identify` as the medium-confidence `visible_samsung` signal via the registry (the stripped-metadata fallback).
+
+## `region_eraser.py`
+
+`region_eraser.py` — universal region eraser (`erase` CLI). `erase(image, boxes=|mask=, backend=)` accepts grayscale (2D) and RGBA (4-channel) inputs on **both** backends (`erase_cv2` and `erase_lama` each split off any alpha plane and re-attach it unchanged, and promote grayscale to BGR for processing — LaMa would otherwise crash on grayscale and drop alpha on BGRA): `boxes_to_mask` → `cv2.inpaint` (`cv2` backend, default, no deps) or big-LaMa via onnxruntime (`lama` backend, extra `lama`, `Carve/LaMa-ONNX` Apache-2.0 model downloaded on first use, never bundled). `erase_lama` crops a padded region around the mask, runs LaMa at its fixed 512² input, pastes only masked pixels back (untouched areas stay pixel-exact). Lazy `_get_lama_session` singleton; `lama_available()` guards the optional import.
+
+**LaMa-ONNX costs ~3.5-4 GB peak RAM and ~5-6 s/call on CPU** (FFC working set, not arena — `enable_cpu_mem_arena=False` does not help), so it does NOT fit a minimal droplet; the cv2 backend (tens of MB, ~30 ms) does. LaMa quality at low RAM = serverless/GPU, mirroring how raiw.cc offloads SDXL to fal.
+
+## `invisible_watermark.py`
+
+`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`
+
+`trustmark_detector.py` — `detect_trustmark(path)` decodes the OPEN, keyless **Adobe TrustMark** watermark (the soft binding behind Adobe Durable Content Credentials, `alg` `com.adobe.trustmark.P`) via the optional `trustmark` package (extra `trustmark`; pulls torch, downloads model weights on first use). Mirrors `invisible_watermark.py` (lazy singleton guarded by a double-checked `threading.Lock` so concurrent callers do not double-download the weights, top-of-module pyright pragma, returns None when absent). It detects *provenance*, not AI origin as such (TrustMark also marks human-authored content), so `identify` lists it as a watermark without setting `is_ai_generated`. Other soft-binding vendors (Digimarc/Imatag/Steg.AI/...) have no public decoder — they are only *named* via the `C2PA_SOFT_BINDINGS` scan, not decoded.
+
+**False-positive gate (added 2026-05-29):** TrustMark's `wm_present` is a BCH error-correction validity flag that spuriously validates on a content-correlated fraction of un-watermarked images — AI-generated textures trip it far more than camera photos (verified 2026-05-29 on real files: it fires on Gemini/OpenAI/Doubao output that *cannot* carry Adobe's watermark, with a random-bytes decoded secret, while signal-free camera photos did not trip it). A genuine TrustMark is a *durable* soft binding engineered to survive re-encoding, so `detect_trustmark` re-decodes after a mild JPEG round-trip (`_survives_reencode`, `_REENCODE_QUALITY` 95) and requires the same schema both times; every observed false positive collapsed (none survived even q95), so the gate is the durability property the watermark guarantees. The second decode runs only on the rare initial hit, so the cost is negligible. Do NOT remove the gate to "catch more" — a lone TrustMark hit without it is almost always content noise.
+
+## `noai/watermark_remover.py`
+
+`noai/watermark_remover.py` — the `WatermarkRemover` class has two diffusion pipelines, selected by the explicit `pipeline` ctor arg (NOT inferred from `model_id` -- both use the same SDXL base, `DEFAULT_MODEL_ID`).
+
+**`sdxl`** (renamed from `default` 2026-06-09; `default` kept as a back-compat alias via `normalize_profile`) runs plain SDXL img2img (`_run_img2img`); it is the lighter opt-down alternative (no ControlNet weights).
+
+**`controlnet`** (**the DEFAULT pipeline since 2026-06-09** for `invisible`/`all`/`batch` and both engine ctors; `_run_controlnet`, `_load_controlnet_pipeline`) runs `StableDiffusionXLControlNetImg2ImgPipeline` with the SDXL-native canny ControlNet `xinsir/controlnet-canny-sdxl-1.0` (`watermark_profiles.CONTROLNET_CANNY_MODEL`): the control image is `cv2.Canny(gray, 100, 200)` stacked to 3 channels (`_CANNY_LOW`/`_CANNY_HIGH`, prompt `_CONTROLNET_PROMPT` / `_CONTROLNET_NEGATIVE`).
+
+**Removal comes from the img2img regeneration (`strength`); the ControlNet only PRESERVES text and face STRUCTURE via the edge map.**
+
+No original pixels are copied or frozen, BUT **validation 2026-06-04 disproved the old "so SynthID does not survive" claim: SynthID CAN survive controlnet on photoreal/high-detail content.**
+
+At the shared low removal strength the canny edge-conditioning keeps the regeneration so close to the original that the pixel perturbation that destroys SynthID does not happen (oracle-confirmed: an OpenAI bracelet photo + a 9-face grid read **SynthID-detected** after controlnet at strength 0.10/0.15, but **SynthID-not-detected** after the `default` pipeline at the SAME strength + resolution -- only the pipeline differed).
+
+**But the reverse also holds: a flat-graphic logo/poster SURVIVED `default` while clearing controlnet** -- removal at the low strength is content×pipeline dependent and neither pipeline is universally safe; the real lever is a higher strength. See the controlnet Known-limitations bullet for the full table + root cause. Canny holds face STRUCTURE but NOT identity (the regenerated face drifts in likeness -- canny carries edges, not identity). The drifted cleaned face is the LEAST-AI state we can reach without re-introducing SynthID; the library does NOT ship a face-restore extra. Every restore approach we evaluated (GFPGAN-on-cleaned, PhotoMaker-V2 txt2img, InstantID txt2img, InstantID img2img-on-cleaned at three parameter sweeps, 2026-06-04 - 2026-06-08 Modal cert sweeps) regenerated the face from an ArcFace embedding via SDXL diffusion -- which makes the output face look MORE AI-generated, not less. Empirical conclusion in `docs/synthid-robust-identity-research-2026-06-08.md` "Empirical follow-up". For production face preservation, ship the cleaned image as-is. `controlnet_conditioning_scale` (ctor arg, default 1.0) is the structure-preservation knob. Same dtype rule as `default` (fp32 on cpu/mps, fp16 only on cuda/xpu; the fp16-fixed SDXL VAE `_SDXL_FP16_VAE_ID` is swapped in on fp16 GPUs -- issue #29) and the same MPS->CPU fallback (reload on cpu/fp32, drop a non-cpu generator, retry once).
+
+## `auto_config.py` (REMOVED 2026-06-09)
+
+**`auto_config.py` + the content-detection layer were REMOVED 2026-06-09.**
+
+History: `auto_config.plan()` was a content-adaptive planner that detected faces/text/edges (bundled OpenCV YuNet + PP-OCRv3 DBNet models) to route the pipeline and toggle the adaptive polish. Once `controlnet` became the default-and-only auto pipeline (it no longer downgrades a structure-less image to `sdxl`) and the adaptive polish was confirmed to **self-gate by detail level** (`humanizer.adaptive_polish` no-ops when the cleaned image already meets the input's Laplacian variance, so it does real work only on over-smoothed photo/face texture and ~nothing on text/flat), the detection no longer changed any behavior — it only annotated a `reason` string. So the whole layer was deleted: `auto_config.py`, `tests/test_auto_config.py`, and the two detection assets (`assets/face_detection_yunet_2023mar.onnx`, `assets/text_detection_ppocrv3_2023may.onnx`, ~2.6 MB).
+
+**`--auto` is now a DEPRECATED no-op** (`cli._resolve_auto_polish`): controlnet is already the default pipeline AND the adaptive polish is ON by default, so `--auto` has nothing left to do — it only prints a deprecation warning and passes `adaptive_polish` through unchanged (an explicit `--no-adaptive-polish` still wins). (Originally it re-enabled the polish; once the polish default flipped to ON the same day, the parameter-source branch became dead and was dropped.) The **adaptive polish itself lives on** in `humanizer.adaptive_polish` (CLI `--adaptive-polish/--no-adaptive-polish`, **ON by default since 2026-06-09** — it self-gates to a no-op where there is no detail deficit, so default-on is safe; uses the full-res original as the detail reference) — see the `humanizer` test note. `batch` resolves the polish once before the loop (one warning) and caches the invisible engine per pipeline (`ctx.obj["_inv_engines"]`).
+
+## `upscaler.py`
+
+`upscaler.py` — optional Real-ESRGAN pre-diffusion super-resolution for small inputs (spandrel boundary, top-of-file pyright pragma). `is_available()` gates on spandrel+torch (via `importlib.util.find_spec`); `upscale(bgr, device=None)` loads a lazily-built spandrel `ImageModelDescriptor` singleton (double-checked lock) and upscales by the model's native factor (x2), with a non-CPU→CPU device fallback mirroring the diffusion engine's MPS→CPU retry. Weights (`RealESRGAN_x2plus.pth`, BSD-3-Clause) download on first use to the `torch.hub` checkpoints cache; never bundled. Used only when UPscaling to the `min_resolution` floor (a `max_resolution` downscale always uses Lanczos). The wiring is `InvisibleEngine._esrgan_upscale(pil, target)` — Real-ESRGAN at native factor, then a Lanczos resize to the exact target, falling back to a plain Lanczos resize if the extra is absent or the model errors (so an optional upscaler can never break removal). The default `--upscaler` is `lanczos` (cv2, no deps).
+
+**ESRGAN is a generic photo/texture GAN with no face/glyph prior**, so it best fits photo/texture content and can degrade faces (glassy/asymmetric eyes -- the diffusion pass regenerates faces so the full-pipeline final recovers) and thin/small text (the GAN invents wrong strokes, and low-strength diffusion will not fix it). Verified 2026-06-04: isolated upscale lap-var ~5x Lanczos on faces+textures but glassy eyes; end-to-end `invisible` final lap-var 1634 vs Lanczos 663 with natural faces (diffusion cleaned the artifact). Kept a **manual opt-in knob** (the auto plan never selects it) with `lanczos` the default; not content-gated by design (use Lanczos for text-heavy inputs). spandrel is MIT and pulls no basicsr. Unit-tested without the model: `tests/test_upscaler.py` (availability guard + the not-installed RuntimeError) and `tests/test_invisible_engine.py::TestEsrganUpscale` (the three `_esrgan_upscale` branches via a monkeypatched `upscaler`).
+
+## `image_io.py`
+
+`image_io.py` — Unicode-safe cv2 IO (issue #17). `imread(path, flags=None)` / `imwrite(path, img)` wrap `np.fromfile`+`cv2.imdecode` / `cv2.imencode`+`tofile` so non-ASCII paths work on Windows -- bare `cv2.imread`/`cv2.imwrite` use the platform ANSI code-page API there and fail (empty decode + `can't open/read file`) on Chinese/Cyrillic/accented filenames. `imread` keeps `cv2.imread` semantics (defaults to `IMREAD_COLOR`, returns `None` on missing/empty/undecodable).
+
+**Every cv2 file read/write in the package routes through here; do not call `cv2.imread`/`cv2.imwrite` directly.**
+
+`imwrite` returns `False` on an unwritable path (`OSError` caught) instead of raising, matching `cv2.imwrite` semantics. macOS/Linux already accept UTF-8 paths, so it is behavior-neutral there (the bug only reproduces on Windows).
+
+**`to_bgr(image)` (added 2026-06-09)** is the shared channel normalizer: promotes 2D grayscale / (h,w,1) / 4-channel BGRA to 3-channel BGR (a 3-channel input is returned unchanged, no copy). Use it instead of inlining the `cvtColor(GRAY2BGR/BGRA2BGR)` branch — the gemini engine and the `TextMarkEngine` base both route through it so a grayscale/BGRA input (a real Gemini-app export is opaque RGBA) does not crash the `axis=2` channel reductions. cv2/numpy are imported lazily inside the functions, so the module is cheap to import in a bare env.

docs/release-and-distribution.md

@@ -0,0 +1,25 @@
+# Release and distribution
+
+> Relocated verbatim from `CLAUDE.md` on 2026-06-11 to keep the always-loaded
+> context small. Long single-line entries were reformatted into paragraphs;
+> no content was changed or summarized.
+
+Release flow and every distribution channel (PyPI, Homebrew tap, conda-forge,
+ComfyUI Registry, HF Space), plus sdist/build-backend history. The CI summary
+stays in `CLAUDE.md`; read this before cutting a release.
+
+`publish.yml` stays release-only and now verifies the release tag matches the `pyproject.toml` version (fails the build on a mismatch) before building, then uploads via `uv publish` (PyPI trusted publishing over OIDC, no token — replaced the `pypa/gh-action-pypi-publish` action so the upload no longer depends on that action's bundled twine accepting the Metadata-Version; the `id-token: write` permission + `pypi` environment + workflow filename are unchanged, so PyPI's trusted-publisher entry still matches).
+
+**Release flow:** bump the version in `pyproject.toml` + `src/remove_ai_watermarks/__init__.py` + `uv.lock` (the project's own `[[package]]` entry — find it with `grep -n 'name = "remove-ai-watermarks"' uv.lock`, the `version =` line right below it, ~line 2246), commit `chore(release): vX.Y.Z`, `git tag -a vX.Y.Z -m vX.Y.Z` (annotated — `git tag` without `-m` errors here), push `main` + the tag, then `gh release create vX.Y.Z` — **PyPI publish triggers on the GitHub Release `published` event, NOT on the tag push**, so the tag alone does not publish.
+
+**After the PyPI sdist is live, bump the Homebrew formula** in the separate public tap repo `wiltodelta/homebrew-tap` (`Formula/remove-ai-watermarks.rb`): update `url` to the new sdist URL (from `https://pypi.org/pypi/remove-ai-watermarks/<version>/json`, the `sdist` entry's `url`) and `sha256` to its hash, commit + push there — otherwise `brew install wiltodelta/tap/remove-ai-watermarks` keeps installing the old version. The formula is a core-only venv that pip-installs the sdist (no vendored resources, so pip pulls the binary numpy/opencv wheels per platform at install time); only those two lines change per release.
+
+**This is now AUTOMATED:** the main repo's `.github/workflows/distribute.yml` fires on the GitHub Release `published` event, waits for the sdist to appear on PyPI (poll loop, the Release event races publish.yml's upload), rewrites the formula's `url`+`sha256`, and pushes to the tap using the `HOMEBREW_TAP_TOKEN` repo secret (a fine-grained PAT with Contents:write on `homebrew-tap`). The SAME workflow also factory-rebuilds the HF Space (`HfApi.restart_space(..., factory_reboot=True)`, `HF_TOKEN` secret) so the Space reinstalls the new sdist (it pins `remove-ai-watermarks>=...` and only re-resolves on a rebuild). The manual Homebrew steps above are the fallback / what the workflow automates — a normal release needs no Homebrew or HF action.
+
+**Other distribution channels:** (1) **conda-forge** — recipe source of truth committed at `packaging/conda/recipe.yaml` (v1 `recipe.yaml`, noarch core-only: pillow/piexif/numpy/py-opencv/click/python-dotenv); the initial submission is `conda-forge/staged-recipes` PR #33674 (went green only after **`pip_check: false`** in the python test — rattler-build's `pip check` defaults to ON and fails on the ancient conda-forge `piexif py_2` build's stale metadata with "piexif 1.1.3 is not supported on this platform", though the package installs/imports/works; keep it disabled). Once that merges and the `remove-ai-watermarks-feedstock` exists, the `regro-cf-autotick-bot` auto-opens a version-bump PR on the feedstock when each new PyPI sdist is detected — just review + merge it (hand-edit only if run-deps changed; keep `packaging/conda/recipe.yaml` in sync as the reference copy). (2) **ComfyUI Registry** — the node package is a SEPARATE repo `wiltodelta/ComfyUI-remove-ai-watermarks` with its OWN `pyproject.toml` `version` (independent of the library version). Publish a new node version by bumping that `version` in the node repo's `pyproject.toml` and pushing to `main` — the node repo's `.github/workflows/publish.yml` (`Comfy-Org/publish-node-action@main`, triggered on a push that touches `pyproject.toml`, secret `COMFY_REGISTRY_TOKEN`) **auto-publishes** it; `comfy node publish --token <registry-PAT>` is the manual/local fallback. It is NOT auto-published on a library release (the node has its own version), so only bump it when the node code or its `remove-ai-watermarks>=` dependency floor changes.
+
+**Sdist must exclude `data/`** (`[tool.hatch.build.targets.sdist] exclude = ["/data"]`): hatchling's default sdist bundles all VCS-tracked files, so the committed `data/` test corpora (the multi-hundred-MB synthid_corpus images + the visible-mark captures) pushed the **0.8.0** sdist past PyPI's per-project file-size limit (400 "File too large") — the wheel uploaded but the sdist was rejected, so 0.8.0 shipped wheel-only and 0.8.1 carried the fix. The wheel only ships `src/` (via `[tool.hatch.build.targets.wheel] packages`), so it was never affected.
+
+**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 unpinned `hatchling`** (`[build-system] requires`) since 2026-06-09. History: it was pinned `<1.31` because hatchling 1.30.0 made Metadata-Version 2.5 (PEP 794) the default and the twine bundled in `pypa/gh-action-pypi-publish@release/v1` rejected it (`"'2.5' is not a valid Metadata-Version"`), which **failed the v0.8.3 PyPI upload on 2026-06-01**; hatchling 1.30.1 reverted the default to 2.4. After the workflow moved to `uv publish` (whose uploader accepts 2.5) the pin was belt-and-suspenders only, and once v0.9.0 + v0.10.0 both published wheel+sdist through that path (verified on PyPI) it was dropped. If a future hatchling flips the default to 2.5 again and some consumer chokes, re-pin with a dated comment.

docs/research-doubao-distillation.md

@@ -0,0 +1,21 @@
+# Doubao clean-reverse-alpha distillation (re-investigated 2026-05-29)
+
+> Relocated verbatim from `CLAUDE.md` on 2026-06-11 to keep the always-loaded
+> context small. Long single-line entries were reformatted into paragraphs;
+> no content was changed or summarized.
+
+**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` section in `docs/module-internals.md`). 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` section in `docs/module-internals.md`. 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.

docs/synthid.md

@@ -382,12 +382,10 @@ the payload, reconstituting SynthID in text. The lesson held and shaped the
 current design: **content is preserved by REGENERATING it under structural
 conditioning, never by copying original pixels.**
 
-Both preservation features below are **EXPERIMENTAL and opt-in (off by default)**;
-the plain `default` SDXL img2img pass is the shippable path.
-
-- **Text + structure:** `--pipeline controlnet` (SDXL img2img + a canny ControlNet,
-  experimental/opt-in) conditions the regeneration on the edge map, so text and
-  structure stay sharp while every pixel is still regenerated. Text legibility is
+- **Text + structure:** `--pipeline controlnet` (SDXL img2img + a canny ControlNet) is
+  **THE DEFAULT pipeline since 2026-06-09** (`--pipeline default` opts down to plain
+  SDXL img2img for inputs without text/faces). It conditions the regeneration on the
+  edge map, so text and structure stay sharp while every pixel is still regenerated. Text legibility is
   better than plain img2img at the same strength (text stays readable where plain
   garbles it). **BUT removal efficacy at the low vendor-adaptive strength is CONTENT ×
   PIPELINE dependent and NEITHER pipeline clears all content -- oracle-validated
@@ -407,7 +405,13 @@ the plain `default` SDXL img2img pass is the shippable path.
   removal guarantee at today's strength -- pick by what you must PRESERVE (controlnet
   for text/structure), then raise strength until the oracle reads clean. (The earlier
   "reads clean on the oracle" claim held only for the one flat/text-background case it
-  was checked on; it does not generalize.)
+  was checked on; it does not generalize.) **UPDATE 2026-06-09: the default strengths
+  were raised and made pipeline-aware (controlnet ladder = the certified
+  0.20/0.30/0.30 floors, applied to BOTH pipelines as a single ladder -- see §5.2 for
+  why one ladder covers plain `sdxl` too) and controlnet is now the default pipeline.
+  The plain-SDXL profile was also renamed `default` -> `sdxl` (`default` stays as an
+  alias). The 0.10/0.15 numbers in this analysis are the PRE-raise values it was
+  measured at. See §5.2.**
 - **Face identity:** canny holds face *structure* but not *identity*. Shipped as the
   optional `--restore-faces` GFPGAN post-pass (`face_restore.py`, the `restore`
   extra, experimental/opt-in, off by default). It runs GFPGAN on the ORIGINAL
@@ -448,14 +452,25 @@ study (section 2.2) gives empirical floors:
   resolution stack). Use a GPU or `--max-resolution 1536`.
 
 The default is **vendor-adaptive** (`watermark_profiles.resolve_strength` +
-`vendor_for_strength`): the tool reads the C2PA issuer on the original input and
-picks `OPENAI_STRENGTH` 0.10 / `GEMINI_STRENGTH` 0.15 / `UNKNOWN_STRENGTH` 0.15.
-This uses the vendor signal we DO have locally (the C2PA SynthID proxy) to avoid
-the overkill of a single high default on OpenAI images, without needing a local
-pixel detector. An explicit `--strength` always wins. If the watermark still
-survives (e.g. a large native Gemini beyond the capped-1536 validation), raise
-toward 0.30 then 0.35-0.40 (0.40 visibly corrupts dense text), using the lowest
-value that reads clean on the oracle.
+`vendor_for_strength`): the tool reads the C2PA issuer on the original input and picks
+`OPENAI_STRENGTH` 0.20 / `GEMINI_STRENGTH` 0.30 / `UNKNOWN_STRENGTH` 0.30. **The SAME
+ladder applies to both pipelines** (`sdxl` and `controlnet`) -- these are the
+oracle-certified controlnet floors (§5.5, the 2026-06-04 Modal cert). Why one ladder
+covers plain `sdxl` too: the certification was run on controlnet and does NOT transfer
+by symmetry (the two pipelines have OPPOSITE hard cases -- controlnet leaves SynthID on
+photoreal, `sdxl` on flat graphics, the §5.1 content-x-pipeline table), BUT on its own
+hard case (flat fills) `sdxl` is the WEAKER remover (plain img2img barely perturbs a
+flat region at low strength), so it needs AT LEAST controlnet's strength -- the
+certified floor is therefore the right floor for `sdxl` too. This is a MARGIN argument
+for `sdxl`, not a separate certification (no local SynthID detector to self-verify).
+The higher strength costs little quality where it matters, because `controlnet` is now
+the default pipeline, so `sdxl` is reached only via an explicit `--pipeline sdxl` (a
+deliberate opt-down), where over-regeneration has no faces/text to damage.
+This uses the vendor signal we DO have locally (the C2PA SynthID proxy) to avoid the
+overkill of a single high default on OpenAI images, without needing a local pixel
+detector. An explicit `--strength` always wins. If the watermark still survives (e.g. a
+large native Gemini beyond the capped-1536 validation), raise toward 0.35-0.40 (0.40
+visibly corrupts dense text), using the lowest value that reads clean on the oracle.
 
 ### 5.3 Test methodology
 

docs/watermarking-landscape.md

@@ -0,0 +1,40 @@
+# Watermarking landscape (research 2026-05-24)
+
+> Relocated verbatim from `CLAUDE.md` on 2026-06-11 to keep the always-loaded
+> context small. Long single-line entries were reformatted into paragraphs;
+> no content was changed or summarized.
+
+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). It ALSO burns a **visible** localized wordmark into the pixels — a sparkle + "generated with AI" string in the bottom-LEFT corner (issue #37; the Italian "✦ Contenuti generati dall'AI" variant is calibrated) — removed by `samsung_engine.py` / `visible --mark samsung` (reverse-alpha, see the engine bullet); detection feeds `identify` as the medium `visible_samsung` signal. The string is locale-specific, so each locale needs its own captured alpha template.
+
+**ASUS Gallery** also signs edited photos as C2PA (`com.asus.gallery`) but with no AI source type — a signer, not an AI marker.
+
+**Black Forest Labs (FLUX)** API output signs C2PA: `claim_generator_info "Black Forest Labs API"` + a `c2pa.ai_generated_content` assertion + `trainedAlgorithmicMedia` (issuer `b"Black Forest Labs"` added to `C2PA_ISSUERS`, platform "Black Forest Labs (FLUX)").
+
+**ByteDance Volcano Engine (Volcengine)** — the cloud behind Doubao / Jimeng — signs its AI image output with a cert from `certificate_center@volcengine.com` + `trainedAlgorithmicMedia` (issuer `b"volcengine"` → "ByteDance (Volcano Engine)", platform "ByteDance (Doubao / Jimeng / Volcano Engine)"); note this is the C2PA-signed surface, distinct from the XMP/PNG TC260 `AIGC` label Doubao also uses. All three verified on real signed files 2026-05-29.
+- **EXIF/XMP generator tag (caught by `exif_generator`):** **Ideogram** writes EXIF `Make="Ideogram AI"` (collected 2026-05-24 — no C2PA, no SynthID, no imwatermark; the Make tag is the only signal).
+- **xAI / Grok — its own EXIF signature scheme, NOT C2PA (DETECTED by `metadata.xai_signature`, built 2026-05-26).**
+
+Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC** — only EXIF `Artist` = a UUID and EXIF `ImageDescription` = `Signature: <base64>` (a crypto signature, unverifiable locally without xAI's public key). This empirically kills the earlier unverified "xAI signs C2PA as xAI" lead — xAI is not even a C2PA member. `exif_generator` misses it (neither field holds an `AI_GENERATOR_TOKENS` token), so a dedicated detector `xai_signature(path)` matches the pair (`ImageDescription ~ ^Signature: [A-Za-z0-9+/=]{64,}` AND UUID `Artist`); wired into `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify` (signal `xai_signature`, platform "xAI (Grok / Aurora)").
+
+**Format confirmed stable across n=3 genuine generations:** exactly three EXIF tags (`Artist`, `ExifOffset`, `ImageDescription`), `Signature:` prefix constant, base64 payload 300-1004 chars. Two capture facts: (a) the `Artist` UUID **equals the public image id** in the asset URL (`https://imagine-public.x.ai/imagine-public/images/<uuid>.jpg`), so it is NOT a private per-user secret — only the `Signature` blob is; (b) the Grok web-UI image is a re-encoded **WebP with no signature** — the EXIF survives only in the *original* JPEG (download button or that public tokenless URL), which is why screenshots / re-encodes are metadata-stripped. A real fixture `data/samples/grok-1.jpg` plus **synthetic** JPEG fixtures (fake UUID + fake `Signature:` blob) cover the detector; never add a real Grok image carrying private content (the repo is public).
+
+**Stripped on removal too:** `remove_ai_metadata` now calls `_scrub_ai_exif` on the JPEG EXIF, which deletes the xAI Signature+UUID-Artist pair **and** any `Software`/`Make`/`Artist`/`ImageDescription` tag holding an `AI_GENERATOR_TOKENS` token (so Ideogram's `Make="Ideogram AI"` is scrubbed too), while keeping genuine camera/editor EXIF. The shared `_is_xai_signature_pair` helper (module-level compiled regexes) is the single source of truth for the pattern, used by both `xai_signature` and `_scrub_ai_exif`. (AVIF/HEIF/JXL still strip only C2PA boxes via `isobmff`, not EXIF — unchanged.)
+- **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`).
+
+**Doubao** (ByteDance) uses it (verified on the real #13 sample 2026-05-25; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **four serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on the corpus 2026-05-30) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on the corpus 2026-05-28, `ContentProducer="doubao"`), a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on the corpus 2026-05-30, `ContentProducer="001191440300708461136T1308L"`), **and** a bare `AIGC{...}` blob (the label glued straight to its JSON, no `"AIGC":` key wrapper) embedded in a **JPEG APP segment near the JFIF header** — confirmed on the corpus 2026-06-10 (`ContentProducer="00119144030008867405X210002"`; 3 files read `unknown` before this form was added). The two raw-JSON forms are scanned in one loop (`'"AIGC"'` then `AIGC{`) that **falls through on a non-TC260 / undecodable hit instead of returning** — a quoted `"AIGC"` can appear later in an XMP packet while the real label is a bare `AIGC{...}` earlier in the file, so an unconditional early return on the quoted form would shadow the bare form (the exact bug behind the 06-10 misses). All three generic forms (the PNG chunk, the bare `{"AIGC":...}` object, and the bare `AIGC{...}` blob) are gated on at least one TC260 field (`_TC260_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
+- **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.

maintain.sh

@@ -7,5 +7,7 @@ uv run uv-outdated
 uv run uv-secure --ignore-unfixed
 uv run ruff check --fix
 uv run ruff format
-uv run pyright
+# Scoped to src/: a full-project pyright run OOM-crashes node on this ML-heavy
+# repo (see CLAUDE.md "Test and lint"); src/ is the authoritative strict gate.
+uv run pyright src/
 uv run pytest -n auto

packaging/conda/recipe.yaml

@@ -0,0 +1,63 @@
+schema_version: 1
+
+context:
+  version: "0.10.1"
+  python_min: "3.10"
+
+package:
+  name: remove-ai-watermarks
+  version: ${{ version }}
+
+source:
+  url: https://pypi.org/packages/source/r/remove-ai-watermarks/remove_ai_watermarks-${{ version }}.tar.gz
+  sha256: ec92b450363d947cd897f0b75c18e75c2988ff79314ea247333ba892470b5a77
+
+build:
+  noarch: python
+  number: 0
+  script: python -m pip install . -vv --no-deps --no-build-isolation
+
+requirements:
+  host:
+    - python ${{ python_min }}.*
+    - pip
+    - hatchling
+  run:
+    - python >=${{ python_min }}
+    - pillow >=10.0.0
+    - piexif >=1.1.3
+    - numpy >=1.24.0
+    - py-opencv >=4.8.0
+    - click >=8.0.0
+    - python-dotenv >=1.0.0
+
+tests:
+  - python:
+      imports:
+        - remove_ai_watermarks
+        - remove_ai_watermarks.identify
+        - remove_ai_watermarks.metadata
+      python_version: ${{ python_min }}.*
+      # pip_check defaults to true; disable it explicitly. `pip check` fails on
+      # the conda-forge piexif `py_2` build, whose stale 2019 metadata pip reads
+      # as "piexif 1.1.3 is not supported on this platform" -- even though the
+      # package installs, imports, and works. The imports test verifies loading.
+      pip_check: false
+
+about:
+  homepage: https://github.com/wiltodelta/remove-ai-watermarks
+  summary: Remove visible and invisible AI watermarks from images
+  description: |
+    Detect and remove visible AI watermarks (Gemini / Nano Banana sparkle,
+    ByteDance Doubao and Jimeng, Samsung Galaxy AI) and strip AI-provenance
+    metadata (C2PA, EXIF, IPTC, PNG text chunks) from images. The core package
+    covers the identify / metadata / visible / erase command surface; optional
+    pip extras add SynthID diffusion removal and additional invisible-watermark
+    detectors.
+  license: Apache-2.0
+  license_file: LICENSE
+  repository: https://github.com/wiltodelta/remove-ai-watermarks
+
+extra:
+  recipe-maintainers:
+    - wiltodelta

pyproject.toml

@@ -1,19 +1,48 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.9.0"
-description = "Remove visible and invisible AI watermarks from images (Gemini / Nano Banana, ChatGPT, Stable Diffusion)"
+version = "0.11.2"
+description = "AI watermark remover: strip visible and invisible AI watermarks (Gemini / Nano Banana sparkle, SynthID) and provenance metadata (C2PA, EXIF) from images"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "Apache-2.0"}
+keywords = [
+    "ai-watermark",
+    "ai-watermark-remover",
+    "watermark-remover",
+    "watermark-removal",
+    "remove-watermark",
+    "synthid",
+    "c2pa",
+    "content-credentials",
+    "nano-banana",
+    "gemini",
+    "gemini-watermark",
+    "ai-metadata",
+    "metadata-removal",
+    "provenance",
+    "exif",
+    "stable-diffusion",
+    "comfyui",
+    "ai-detection",
+]
 classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Graphics",
+    "Topic :: Multimedia :: Graphics :: Graphics Conversion",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Security",
+    "Topic :: Utilities",
 ]
 dependencies = [
     "pillow>=10.0.0",
@@ -91,19 +120,17 @@ esrgan = [
 dev = [
     "pytest>=8.0.0",
     "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.5.0",
     "ruff>=0.4.0",
     "pyright>=1.1.0",
     "invisible-watermark>=0.2.0",
+    # maintain.sh helpers; they only support newer Pythons, so gate them by
+    # marker to keep the py3.10 resolution (and CI matrix) solvable.
+    "uv-outdated>=0.1.0; python_version >= '3.12'",
+    "uv-secure>=0.12.0; python_version >= '3.12'",
 ]
 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
@@ -120,18 +147,7 @@ remove-ai-watermarks = "remove_ai_watermarks.cli:main"
 Repository = "https://github.com/wiltodelta/remove-ai-watermarks"
 
 [build-system]
-# Pin hatchling < 1.31. hatchling 1.30.0 made Metadata-Version 2.5 (PEP 794) the
-# default, which the twine bundled in pypa/gh-action-pypi-publish@release/v1 rejects
-# ("'2.5' is not a valid Metadata-Version"), failing the v0.8.3 PyPI upload
-# (2026-06-01) when unpinned requires = ["hatchling"] pulled 1.30.0. hatchling 1.30.1
-# reverted the default to 2.4 ("kept at 2.4 until more tools support 2.5"), and
-# 1.27-1.29 were always 2.4 -- so < 1.31 keeps `uv build` on a 2.4-emitting hatchling
-# (it resolves to the latest allowed, 1.30.1). The publish workflow now uses
-# `uv publish`, whose uploader accepts 2.5, so this pin is belt-and-suspenders, not
-# load-bearing: keeping it makes the first uv-publish release ship 2.4 metadata
-# (isolating the uploader swap from the metadata-version bump). Drop to
-# `requires = ["hatchling"]` once that release confirms the path.
-requires = ["hatchling<1.31"]
+requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]

src/remove_ai_watermarks/__init__.py

@@ -11,4 +11,4 @@ _os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
 _warnings.filterwarnings("ignore", message=r".*ImageProcessorFast.*")
 
 
-__version__ = "0.9.0"
+__version__ = "0.11.2"

src/remove_ai_watermarks/_text_mark_engine.py

@@ -0,0 +1,349 @@
+"""Shared base for the reverse-alpha visible text-mark engines.
+
+The Doubao "豆包AI生成", Jimeng "★ 即梦AI", and Samsung "✦ Contenuti generati
+dall'AI" marks are the SAME algorithm: anchor a bottom-corner box by width-relative
+geometry, extract the light low-saturation glyph candidate, detect by matching the
+bundled alpha-glyph silhouette via ``TM_CCOEFF_NORMED``, and remove by inverting the
+alpha blend ``original = (wm - a*logo)/(1-a)`` (always trying fixed AND NCC-aligned
+placement, keeping the lower-residual one) plus a thin footprint inpaint.
+
+They differ ONLY in a bounded set of tuned values captured by :class:`TextMarkConfig`:
+the constants, the bundled asset, the corner (Doubao/Jimeng bottom-right, Samsung
+bottom-left), and a few structural knobs (the morphology-open kernel size and the
+minimum glyph width used by the alignment / template-match). Each engine module is a
+thin :class:`TextMarkEngine` subclass plus the test-facing module constants/helpers.
+
+Gemini stays a SEPARATE engine (``gemini_engine``): its multi-size fixed-slot sparkle
+model is genuinely different, not a tuned variant of this one.
+"""
+
+# cv2/numpy boundary: third-party libs ship no usable element types; relax the
+# unknown-type rules for this file only.
+# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false, reportOptionalMemberAccess=false, reportOptionalCall=false, reportOptionalSubscript=false, reportOptionalOperand=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false, reportPrivateUsage=false, reportInvalidTypeForm=false, reportConstantRedefinition=false, reportUnnecessaryComparison=false
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+import cv2
+import numpy as np
+
+from remove_ai_watermarks import image_io
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class TextMarkConfig:
+    """All per-mark tuning for a reverse-alpha text-mark engine."""
+
+    name: str  # short label for log lines (e.g. "Doubao")
+    asset_name: str  # bundled alpha PNG under assets/ (e.g. "doubao_alpha.png")
+    corner: Literal["br", "bl"]  # bottom-right (Doubao/Jimeng) or bottom-left (Samsung)
+    margin_floor: int  # min margin in px for locate (4 for br marks, 2 for Samsung)
+    # locate geometry (fraction of image WIDTH)
+    width_frac: float
+    height_frac: float
+    margin_x_frac: float  # right margin (br) or left margin (bl)
+    margin_bottom_frac: float
+    # glyph appearance
+    max_saturation: float
+    logo_min_luma: float
+    tophat_delta: float
+    morph_open_size: int  # MORPH_OPEN kernel side (5 for br marks, 3 for Samsung)
+    # detection
+    detect_min_coverage: float
+    detect_ncc_threshold: float
+    # alpha-map geometry (fraction of WIDTH) emitted by scripts/visible_alpha_solve.py
+    alpha_width_frac: float
+    alpha_height_frac: float
+    alpha_margin_x_frac: float
+    alpha_margin_bottom_frac: float
+    alpha_align_search: tuple[float, float, int]  # np.linspace(start, stop, num) scale search
+    min_gw: int  # minimum glyph width for the template match / align search (8 br, 16 Samsung)
+    alpha_logo_bgr: tuple[float, float, float] = (255.0, 255.0, 255.0)
+    # residual inpaint over the glyph footprint (thin)
+    residual_alpha_floor: float = 0.05
+    residual_dilate: int = 5
+    residual_inpaint_radius: int = 2
+
+
+@dataclass
+class TextMarkLocation:
+    """Located watermark box, in absolute pixel coordinates."""
+
+    x: int
+    y: int
+    w: int
+    h: int
+    is_fallback: bool = True  # geometry anchor (no template match) -> always True for now
+
+    @property
+    def bbox(self) -> tuple[int, int, int, int]:
+        return self.x, self.y, self.w, self.h
+
+
+@dataclass
+class TextMarkDetection:
+    """Result of visible text-mark detection."""
+
+    detected: bool = False
+    confidence: float = 0.0
+    region: tuple[int, int, int, int] = (0, 0, 0, 0)
+    coverage: float = 0.0  # fraction of the box occupied by glyph pixels
+
+
+# Alpha / silhouette templates, cached per asset name (the originals cached per
+# module global; this keys by asset so the three engines share the loader without
+# re-reading). Only SUCCESSFUL loads are cached, so a missing asset is retried.
+_alpha_cache: dict[str, NDArray[Any]] = {}
+_silhouette_cache: dict[str, NDArray[Any]] = {}
+
+
+def load_alpha_template(asset_name: str) -> NDArray[Any] | None:
+    """Lazily load the bundled alpha template (float [0,1]) for ``asset_name``, or None."""
+    cached = _alpha_cache.get(asset_name)
+    if cached is not None:
+        return cached
+    path = Path(__file__).parent / "assets" / asset_name
+    img = image_io.imread(str(path), cv2.IMREAD_GRAYSCALE)
+    if img is None:
+        return None
+    _alpha_cache[asset_name] = img.astype(np.float32) / 255.0
+    return _alpha_cache[asset_name]
+
+
+def glyph_silhouette(asset_name: str) -> NDArray[Any] | None:
+    """Binary glyph silhouette (255 = glyph) from the bundled alpha map, or None."""
+    cached = _silhouette_cache.get(asset_name)
+    if cached is not None:
+        return cached
+    at = load_alpha_template(asset_name)
+    if at is None:
+        return None
+    _silhouette_cache[asset_name] = (at > 0.15).astype(np.uint8) * 255
+    return _silhouette_cache[asset_name]
+
+
+def template_match_score(box_mask: NDArray[Any], image_width: int, config: TextMarkConfig) -> float:
+    """Zero-mean normalized correlation of the alpha-template glyph silhouette
+    (scaled to the mark's expected size) against the candidate ``box_mask``.
+
+    ``TM_CCOEFF_NORMED`` keys on glyph SHAPE, not coverage, so a dense textured
+    corner does not score highly -- only the actual glyph shape does.
+    """
+    sil = glyph_silhouette(config.asset_name)
+    if sil is None or box_mask.size == 0:
+        return 0.0
+    gw = min(box_mask.shape[1] - 1, max(config.min_gw, int(config.alpha_width_frac * image_width)))
+    gh = min(box_mask.shape[0] - 1, max(4, int(config.alpha_height_frac * image_width)))
+    if gw < config.min_gw or gh < 4:
+        return 0.0
+    template = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_NEAREST)
+    return float(cv2.matchTemplate(box_mask, template, cv2.TM_CCOEFF_NORMED).max())
+
+
+class TextMarkEngine:
+    """Reverse-alpha visible text-mark remover (locate -> mask -> detect -> reverse-alpha)."""
+
+    def __init__(self, config: TextMarkConfig) -> None:
+        self.config = config
+
+    # ── Templates (delegate to the asset-keyed module cache) ────────────
+
+    def _alpha_template(self) -> NDArray[Any] | None:
+        return load_alpha_template(self.config.asset_name)
+
+    def _glyph_silhouette(self) -> NDArray[Any] | None:
+        return glyph_silhouette(self.config.asset_name)
+
+    def _template_match_score(self, box_mask: NDArray[Any], image_width: int) -> float:
+        return template_match_score(box_mask, image_width, self.config)
+
+    # ── Locate ──────────────────────────────────────────────────────────
+
+    def locate(self, image: NDArray[Any]) -> TextMarkLocation:
+        """Anchor the watermark box in the configured bottom corner by geometry."""
+        c = self.config
+        h, w = image.shape[:2]
+        wm_w = max(40, int(w * c.width_frac))
+        wm_h = max(16, int(w * c.height_frac))
+        margin_x = max(c.margin_floor, int(w * c.margin_x_frac))
+        margin_b = max(c.margin_floor, int(w * c.margin_bottom_frac))
+        x = max(0, w - margin_x - wm_w) if c.corner == "br" else min(margin_x, max(0, w - wm_w))
+        y = max(0, h - margin_b - wm_h)
+        wm_w = min(wm_w, w - x)
+        wm_h = min(wm_h, h - y)
+        return TextMarkLocation(x=x, y=y, w=wm_w, h=wm_h, is_fallback=True)
+
+    # ── Mask ────────────────────────────────────────────────────────────
+
+    def extract_mask(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any]:
+        """Build a full-image uint8 mask (255 = watermark glyph) for the box.
+
+        Polarity-aware: the mark is a light, low-saturation gray rendered brighter
+        than the local background (white top-hat), so a white-paper document is left
+        untouched (nothing brighter than its surroundings is masked there).
+        """
+        c = self.config
+        h, w = image.shape[:2]
+        x, y, bw, bh = loc.bbox
+        # A degenerate ROI (a sliver from an extremely wide/short image) cannot hold
+        # the mark and would feed cv2's GaussianBlur/morphology a ~1-px-tall array,
+        # which can fault native code on some platforms. Skip the cv2 pipeline.
+        if bh < 16 or bw < 16:
+            return np.zeros((h, w), np.uint8)
+        # Normalize the ROI to 3-channel BGR (grayscale / BGRA would break axis=2).
+        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
+
+        luma = roi.mean(axis=2)
+        sat = roi.max(axis=2) - roi.min(axis=2)
+        grayish = sat < c.max_saturation
+
+        # Local background model: a strong Gaussian blur (sigma ~ box height); the
+        # white top-hat (luma - local_bg) lights up bright thin strokes regardless
+        # of the absolute background level.
+        sigma = max(4.0, bh * 0.4)
+        local_bg = cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
+        tophat = luma - local_bg
+
+        cand = grayish & (tophat > c.tophat_delta) & (luma > c.logo_min_luma)
+        glyph = cand.astype(np.uint8) * 255
+        glyph = cv2.morphologyEx(glyph, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))
+        k = c.morph_open_size
+        glyph = cv2.morphologyEx(glyph, cv2.MORPH_OPEN, np.ones((k, k), np.uint8))
+
+        mask = np.zeros((h, w), np.uint8)
+        mask[y : y + bh, x : x + bw] = glyph
+        return mask
+
+    # ── Detect ──────────────────────────────────────────────────────────
+
+    def detect(self, image: NDArray[Any]) -> TextMarkDetection:
+        """Detect the mark by matching the alpha-template glyph silhouette against
+        the corner candidate (``TM_CCOEFF_NORMED``); keys on glyph SHAPE, not coverage."""
+        c = self.config
+        det = TextMarkDetection()
+        if image is None or image.size == 0:
+            return det
+        loc = self.locate(image)
+        mask = self.extract_mask(image, loc)
+        x, y, bw, bh = loc.bbox
+        box = mask[y : y + bh, x : x + bw]
+        coverage = float((box > 0).sum()) / float(max(1, bw * bh))
+        det.region = loc.bbox
+        det.coverage = coverage
+        if coverage >= c.detect_min_coverage:
+            score = self._template_match_score(box, image.shape[1])
+            det.confidence = score
+            det.detected = score >= c.detect_ncc_threshold
+            logger.debug("%s detect: coverage=%.3f ncc=%.2f detected=%s", c.name, coverage, score, det.detected)
+        return det
+
+    # ── Reverse-alpha (recovery + thin residual inpaint) ────────────────
+
+    def reverse_alpha_available(self, image: NDArray[Any]) -> bool:
+        """True if the bundled alpha map is loadable (NCC alignment places it at any
+        resolution; the caller still gates on ``detect`` so a clean corner is untouched)."""
+        return image is not None and image.size > 0 and self._alpha_template() is not None
+
+    def _fixed_alpha_map(self, image: NDArray[Any]) -> tuple[NDArray[Any], tuple[int, int, int, int]] | None:
+        """Place the template by fixed width-relative geometry (pixel-exact at the
+        captured width)."""
+        c = self.config
+        at = self._alpha_template()
+        if at is None:
+            return None
+        h, w = image.shape[:2]
+        # Clamp both dims so a wide/short image cannot overflow the slice assignment.
+        gw = min(w, max(1, int(c.alpha_width_frac * w)))
+        gh = min(h, max(1, int(c.alpha_height_frac * w)))
+        if c.corner == "br":
+            ax = max(0, w - int(c.alpha_margin_x_frac * w) - gw)
+        else:  # bottom-left
+            ax = min(max(0, int(c.alpha_margin_x_frac * w)), max(0, w - gw))
+        ay = max(0, h - int(c.alpha_margin_bottom_frac * w) - gh)
+        amap = np.zeros((h, w), np.float32)
+        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh), interpolation=cv2.INTER_LINEAR)
+        return amap, (ax, ay, gw, gh)
+
+    def _aligned_alpha_map(self, image: NDArray[Any]) -> tuple[NDArray[Any], tuple[int, int, int, int]] | None:
+        """Register the captured template to the actual mark via a TM_CCOEFF_NORMED
+        scale + position search. Returns ``(alpha_map, glyph_bbox)`` or None."""
+        c = self.config
+        at = self._alpha_template()
+        sil = self._glyph_silhouette()
+        if at is None or sil is None:
+            return None
+        h, w = image.shape[:2]
+        loc = self.locate(image)
+        bx, by, bw, bh = loc.bbox
+        box_mask = self.extract_mask(image, loc)[by : by + bh, bx : bx + bw]
+        expected = c.alpha_width_frac * w
+        best: tuple[float, int, int, int, int] | None = None
+        for scale in np.linspace(*c.alpha_align_search):
+            gw, gh = int(expected * scale), int(c.alpha_height_frac * w * scale)
+            if gw < c.min_gw or gh < 4 or gw >= bw or gh >= bh:
+                continue
+            t = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_NEAREST)
+            _, score, _, top_left = cv2.minMaxLoc(cv2.matchTemplate(box_mask, t, cv2.TM_CCOEFF_NORMED))
+            if best is None or score > best[0]:
+                best = (score, gw, gh, top_left[0], top_left[1])
+        if best is None:
+            return None
+        _, gw, gh, ox, oy = best
+        ax, ay = bx + ox, by + oy
+        amap = np.zeros((h, w), np.float32)
+        amap[ay : ay + gh, ax : ax + gw] = cv2.resize(at, (gw, gh), interpolation=cv2.INTER_LINEAR)
+        return amap, (ax, ay, gw, gh)
+
+    def _apply_reverse_alpha(self, image: NDArray[Any], amap: NDArray[Any]) -> NDArray[Any]:
+        """Invert the alpha blend with ``amap``: ``original = (wm - a*logo)/(1-a)``."""
+        a3 = np.clip(amap, 0.0, 1.0)[:, :, None]
+        logo = np.array(self.config.alpha_logo_bgr, np.float32)
+        return np.clip((image.astype(np.float32) - a3 * logo) / np.clip(1.0 - a3, 0.25, 1.0), 0, 255).astype(np.uint8)
+
+    def remove_watermark_reverse_alpha(self, image: NDArray[Any], *, residual_inpaint: bool = True) -> NDArray[Any]:
+        """Recover the original pixels by inverting the alpha blend, then clear the
+        residual outline with a thin inpaint over the glyph footprint.
+
+        Placement: fixed geometry AND the NCC-aligned placement are always tried and
+        the one leaving the least residual mark (lowest re-``detect`` confidence) is
+        kept -- the mark re-rasterizes a few px per image, so fixed geometry alone is
+        not reliable. A single capture cannot pixel-cancel the mark on every image, so
+        a deliberately THIN residual inpaint (``residual_*``) follows: reverse-alpha
+        has already recovered the true background under the mark, so the inpaint only
+        finishes the residual edges instead of smearing the whole footprint. Call only
+        when :meth:`reverse_alpha_available` and the mark is detected.
+        """
+        c = self.config
+        # Normalize to 3-channel BGR (the reverse-alpha math assumes a 3-channel logo).
+        image = image_io.to_bgr(image)
+        # An image too small to hold the mark would make the geometry boxes degenerate
+        # and feed cv2.resize a ~1-px-tall target; skip cv2 entirely.
+        h, w = image.shape[:2]
+        if h < 32 or w < 64:
+            return image.copy()
+        maps = [m for m in (self._fixed_alpha_map(image), self._aligned_alpha_map(image)) if m is not None]
+        if not maps:
+            return image.copy()
+        best_out: NDArray[Any] | None = None
+        best_amap: NDArray[Any] | None = None
+        best_residual = float("inf")
+        for amap, _region in maps:
+            out = self._apply_reverse_alpha(image, amap)
+            residual = self.detect(out).confidence
+            if residual < best_residual:
+                best_residual, best_out, best_amap = residual, out, amap
+        if best_out is None or best_amap is None:  # pragma: no cover - maps is non-empty
+            return image.copy()
+        if residual_inpaint:
+            kernel = np.ones((c.residual_dilate, c.residual_dilate), np.uint8)
+            rm = cv2.dilate((best_amap > c.residual_alpha_floor).astype(np.uint8) * 255, kernel)
+            best_out = cv2.inpaint(best_out, rm, c.residual_inpaint_radius, cv2.INPAINT_NS)
+        return best_out

src/remove_ai_watermarks/auto_config.py

@@ -1,267 +0,0 @@
-"""Automatic pipeline planning for the ``--auto`` quality mode.
-
-``plan(image_path)`` inspects the INPUT image (before the diffusion model loads)
-and returns the quality modes to use, so the pipeline can adapt to content. It is
-meant to run as the FIRST step of the invisible/all pipeline, wherever that pipeline
-runs (locally, or the raiw.cc Modal GPU worker) -- never on a memory-constrained web
-host (image work there OOM-crashes the container).
-
-Routing is **quality-priority**: ControlNet (text/face-structure preservation) is the
-default; it is only skipped for a clearly structure-less image (no face, no text,
-near-zero edges), where plain SDXL is cheaper and just as good. PhotoMaker face
-restoration is enabled when a face is present. When a smoothing pass (controlnet or
-face restore) ran, the **adaptive polish** (``humanizer.adaptive_polish``) restores
-the input's detail level -- a capped unsharp + edge-masked grain targeting the input's
-Laplacian variance -- to counter the over-smoothed "AI look". It is self-limiting on
-text/graphics (already high-frequency, so almost no polish) and spares text/edges by
-masking the grain.
-
-Detection is **cv2-only and torch-free**: OpenCV YuNet (``cv2.FaceDetectorYN``) for
-faces -- a 232 KB MIT-licensed model bundled in ``assets/`` -- DBNet (PP-OCRv3
-differentiable-binarization via ``cv2.dnn.TextDetectionModel_DB``, a 2.4 MB Apache-2.0
-model bundled in ``assets/``) for text, and a Canny ``edge_density``. The whole planner
-peaks ~100 MB RSS in a few ms, so it adds nothing meaningful to a GPU run and runs
-anywhere the pipeline runs.
-
-The text detector falls back to the old MSER region heuristic if the DBNet model can't
-load. Either way text only ever ADDS controlnet, so a miss is backstopped by the
-edge-density route and a false positive only costs a controlnet run.
-"""
-
-# cv2/numpy boundary: cv2 ships no usable element types; relax the unknown-type rules
-# for this file only.
-# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false, reportOptionalMemberAccess=false, reportOptionalCall=false, reportOptionalSubscript=false, reportOptionalOperand=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false, reportPrivateUsage=false, reportInvalidTypeForm=false, reportConstantRedefinition=false, reportUnnecessaryComparison=false
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from numpy.typing import NDArray
-
-logger = logging.getLogger(__name__)
-
-# ── Routing thresholds (tunable; quality-priority -> controlnet unless clearly flat) ──
-# Canny edge-density below this, AND no face AND no text -> plain SDXL (nothing to
-# preserve). The headshot measures ~0.022, a busy photo higher; only a near-flat
-# gradient/solid image falls under 0.008.
-_STRUCTURELESS_EDGE_MAX = 0.008
-# MSER regions per megapixel above this -> likely text. The MSER path is now only the
-# FALLBACK when the bundled DBNet model can't load; DBNet (below) is the primary text
-# detector. Rough heuristic: a no-text portrait measures a few hundred/MP, dense text
-# far more. Set high so it rarely false-fires; text only ever ADDS controlnet.
-_TEXT_MSER_PER_MP = 1500.0
-_FACE_SCORE = 0.6  # YuNet confidence for a face to count
-# Downscale the long side to this for DETECTION only (faces stay detectable down to
-# ~10px, and this bounds YuNet/DBNet/MSER cost on huge inputs). Removal runs at full res.
-_DETECT_MAX_SIDE = 1024
-
-# DBNet (PP-OCRv3 differentiable-binarization) text-region detector via cv2.dnn -- the
-# primary "has meaningful text" signal. The model is the shared PP-OCRv3 detection net
-# from OpenCV Zoo (Apache-2.0); en/cn variants are byte-identical, so it is bundled
-# language-neutral. cv2.dnn is core OpenCV, so this adds NO new pip dependency.
-_DBNET_ASSET = "text_detection_ppocrv3_2023may.onnx"  # Apache-2.0 (OpenCV Zoo PP-OCRv3 DB)
-_DBNET_BINARY_THRESHOLD = 0.3
-_DBNET_POLYGON_THRESHOLD = 0.5
-_DBNET_MAX_CANDIDATES = 200
-_DBNET_UNCLIP_RATIO = 2.0
-_DBNET_INPUT_SIDE = 736  # square input, multiple of 32 (PP-OCRv3 default)
-_DBNET_MEAN = (122.67891434, 116.66876762, 104.00698793)  # ImageNet mean * 255
-_dbnet: Any = None  # lazy singleton; set to False after a load failure (-> MSER fallback)
-
-# When a smoothing pass ran (controlnet or face restore), the adaptive polish
-# (humanizer.adaptive_polish) restores the input's detail level, sparing text --
-# replacing the old fixed unsharp/grain which over-/under-corrected and speckled text.
-_UPSCALE_FLOOR = 1024
-
-_YUNET_ASSET = "face_detection_yunet_2023mar.onnx"  # MIT (Shiqi Yu), OpenCV Zoo
-_yunet: Any = None  # lazy singleton
-
-
-@dataclass(frozen=True)
-class AutoConfig:
-    """Resolved quality modes from content analysis (the ``--auto`` plan)."""
-
-    pipeline: str  # "default" | "controlnet"
-    adaptive_polish: bool  # restore the input's detail level (sharpen + masked grain), sparing text
-    unsharp: float  # fixed-polish knobs, 0 in auto (the adaptive polish replaces them)
-    humanize: float
-    min_resolution: int
-    # signals retained for logging / debugging a bad pick
-    has_face: bool
-    has_text: bool
-    edge_density: float
-    width: int
-    height: int
-
-    @property
-    def reason(self) -> str:
-        """One-line human-readable summary of the plan (logged per image)."""
-        bits = ["face" if self.has_face else "no-face"]
-        if self.has_text:
-            bits.append("text")
-        bits.append(f"edges={self.edge_density:.3f}")
-        if self.adaptive_polish:
-            polish = ", adaptive polish"
-        elif self.unsharp or self.humanize:
-            polish = f", unsharp {self.unsharp}/grain {self.humanize}"
-        else:
-            polish = ""
-        return f"{'+'.join(bits)} -> {self.pipeline} pipeline{polish}"
-
-
-def _to_bgr(image: NDArray[Any]) -> NDArray[Any]:
-    """Normalize a 2D grayscale or 4-channel BGRA array to 3-channel BGR."""
-    import cv2
-
-    if image.ndim == 2:
-        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
-    if image.shape[2] == 4:
-        return cv2.cvtColor(image, cv2.COLOR_BGRA2BGR)
-    return image
-
-
-def _to_gray(image: NDArray[Any]) -> NDArray[Any]:
-    """Single-channel grayscale; passes a 2D (already-gray) input through unchanged."""
-    import cv2
-
-    if image.ndim == 3 and image.shape[2] >= 3:
-        return cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
-    return image
-
-
-def _downscale_for_detection(image: NDArray[Any]) -> NDArray[Any]:
-    """Shrink the long side to ``_DETECT_MAX_SIDE`` for cheap, bounded detection."""
-    import cv2
-
-    h, w = image.shape[:2]
-    long_side = max(h, w)
-    if long_side <= _DETECT_MAX_SIDE:
-        return image
-    scale = _DETECT_MAX_SIDE / long_side
-    return cv2.resize(image, (max(1, round(w * scale)), max(1, round(h * scale))), interpolation=cv2.INTER_AREA)
-
-
-def detect_face(image: NDArray[Any]) -> bool:
-    """True if OpenCV YuNet finds at least one face. cv2-only, torch-free."""
-    import cv2
-
-    global _yunet
-    img = _to_bgr(image)
-    h, w = img.shape[:2]
-    if h < 1 or w < 1:
-        return False
-    try:
-        if _yunet is None:
-            model = Path(__file__).parent / "assets" / _YUNET_ASSET
-            _yunet = cv2.FaceDetectorYN.create(str(model), "", (w, h), _FACE_SCORE, 0.3, 5000)
-        _yunet.setInputSize((w, h))
-        _, faces = _yunet.detect(img)
-    except cv2.error as e:  # malformed input / model
-        logger.debug("YuNet face detect failed (%s); assuming no face", e)
-        return False
-    return faces is not None and len(faces) > 0
-
-
-def _detect_text_dbnet(image: NDArray[Any]) -> bool | None:
-    """DBNet (PP-OCRv3) text-region presence via cv2.dnn.
-
-    Returns True/False on a successful run, or None if the bundled model can't load
-    (the caller then falls back to the MSER heuristic). Loads once, lazily.
-    """
-    import cv2
-
-    global _dbnet
-    if _dbnet is False:  # a prior load failed; skip straight to the MSER fallback
-        return None
-    img = _to_bgr(image)
-    h, w = img.shape[:2]
-    if h < 1 or w < 1:
-        return False
-    try:
-        if _dbnet is None:
-            model = Path(__file__).parent / "assets" / _DBNET_ASSET
-            net = cv2.dnn.TextDetectionModel_DB(str(model))
-            net.setBinaryThreshold(_DBNET_BINARY_THRESHOLD)
-            net.setPolygonThreshold(_DBNET_POLYGON_THRESHOLD)
-            net.setMaxCandidates(_DBNET_MAX_CANDIDATES)
-            net.setUnclipRatio(_DBNET_UNCLIP_RATIO)
-            net.setInputParams(1.0 / 255.0, (_DBNET_INPUT_SIDE, _DBNET_INPUT_SIDE), _DBNET_MEAN)
-            _dbnet = net
-        boxes, _ = _dbnet.detect(img)
-    except Exception as e:  # model load / inference can raise cv2.error or others
-        logger.debug("DBNet text detect failed (%s); falling back to MSER", e)
-        _dbnet = False
-        return None
-    return boxes is not None and len(boxes) > 0
-
-
-def _detect_text_mser(image: NDArray[Any]) -> bool:
-    """Fallback MSER-based text-presence heuristic (used only if DBNet can't load)."""
-    import cv2
-
-    gray = _to_gray(image)
-    h, w = gray.shape[:2]
-    try:
-        regions, _ = cv2.MSER_create().detectRegions(gray)
-    except cv2.error:
-        return False
-    per_mp = len(regions) / max(1e-6, (h * w) / 1e6)
-    return per_mp > _TEXT_MSER_PER_MP
-
-
-def detect_text(image: NDArray[Any]) -> bool:
-    """Text-presence: DBNet (cv2.dnn) when the bundled model loads, else the MSER heuristic."""
-    dbnet = _detect_text_dbnet(image)
-    return _detect_text_mser(image) if dbnet is None else dbnet
-
-
-def edge_density(image: NDArray[Any]) -> float:
-    """Fraction of Canny edge pixels -- a cheap 'has structure' proxy in [0, 1]."""
-    import cv2
-
-    gray = _to_gray(image)
-    edges = cv2.Canny(gray, 100, 200)
-    return float((edges > 0).mean())
-
-
-def plan(image_path: Path) -> AutoConfig | None:
-    """Inspect the input image and return the quality modes, or None if unreadable.
-
-    Pure analysis: loads the image, runs the cv2 detectors on a downscaled copy, and
-    applies the quality-priority routing rules. Safe to call wherever the pipeline
-    runs; no diffusion model is loaded.
-    """
-    from remove_ai_watermarks import image_io
-
-    image = image_io.imread(image_path)
-    if image is None:
-        return None
-
-    h, w = image.shape[:2]
-    small = _downscale_for_detection(image)
-    gray = _to_gray(small)  # convert once; edge density + the MSER fallback use gray
-    has_face = detect_face(small)  # YuNet needs the 3-channel image
-    has_text = detect_text(small)  # DBNet wants BGR; the MSER fallback grays it internally
-    edges = edge_density(gray)
-
-    structureless = (not has_face) and (not has_text) and edges < _STRUCTURELESS_EDGE_MAX
-    pipeline = "default" if structureless else "controlnet"
-    smoothing = pipeline == "controlnet"
-
-    cfg = AutoConfig(
-        pipeline=pipeline,
-        adaptive_polish=smoothing,  # adaptive (detail-targeted) polish when a smoothing pass ran
-        unsharp=0.0,
-        humanize=0.0,
-        min_resolution=_UPSCALE_FLOOR,
-        has_face=has_face,
-        has_text=has_text,
-        edge_density=edges,
-        width=w,
-        height=h,
-    )
-    logger.debug("auto plan for %s: %s", image_path, cfg.reason)
-    return cfg

src/remove_ai_watermarks/cli.py

@@ -13,19 +13,23 @@ import json
 import logging
 import time
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, NoReturn
 
 import click
 
 from remove_ai_watermarks import __version__, watermark_registry
-from remove_ai_watermarks.noai.watermark_profiles import resolve_strength, vendor_for_strength
+from remove_ai_watermarks.noai.constants import SUPPORTED_FORMATS
+from remove_ai_watermarks.noai.watermark_profiles import (
+    resolve_strength,
+    strength_default_help,
+    vendor_for_strength,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Generator
 
     from numpy.typing import NDArray
 
-    from remove_ai_watermarks.gemini_engine import DetectionResult
 
 # --- plain-text output layer (replaces rich: no colors, no markup, no boxes) ---
 
@@ -103,8 +107,6 @@ Progress = _Progress
 SpinnerColumn = BarColumn = TextColumn = TimeElapsedColumn = _column
 console = _Console()
 
-SUPPORTED_FORMATS = {".png", ".jpg", ".jpeg", ".webp"}
-
 
 def _setup_logging(verbose: bool) -> None:
     level = logging.DEBUG if verbose else logging.WARNING
@@ -143,8 +145,8 @@ _controlnet_scale_option = click.option(
     "--controlnet-scale",
     type=float,
     default=1.0,
-    help="ControlNet conditioning scale (structure/text preservation strength), controlnet pipeline "
-    "only (EXPERIMENTAL).",
+    help="ControlNet conditioning scale (structure/text preservation strength); "
+    "applies to the controlnet pipeline (the default). Higher = closer to original structure.",
 )
 
 _min_resolution_option = click.option(
@@ -173,48 +175,103 @@ _auto_option = click.option(
     "--auto",
     is_flag=True,
     default=False,
-    help="Auto-pick the pipeline, face restore, and adaptive polish from image content. "
-    "Every choice is overridable -- an explicit --pipeline / --adaptive-polish "
-    "always wins. EXPERIMENTAL.",
+    help="DEPRECATED: controlnet is already the default pipeline, so --auto now only "
+    "enables --adaptive-polish (the content detectors were removed). Use "
+    "--adaptive-polish instead.",
 )
 
 _adaptive_polish_option = click.option(
     "--adaptive-polish/--no-adaptive-polish",
-    default=False,
+    default=True,
     help="Restore the input's detail level after removal (capped unsharp + edge-masked grain "
-    "targeting the input's sharpness, sparing text). On by default under --auto; pass "
-    "--no-adaptive-polish to disable it there, or --adaptive-polish to use it without --auto. "
-    "Independent of the fixed --unsharp/--humanize. EXPERIMENTAL.",
+    "targeting the input's sharpness, sparing text), countering the over-smoothed look. ON by "
+    "default; it self-limits where there is no detail deficit (text/flat graphics), so it is a "
+    "no-op there. Pass --no-adaptive-polish to disable. Independent of --unsharp/--humanize.",
+)
+
+# HuggingFace model + CFG knobs, shared by the diffusion commands (invisible/all/batch)
+# so the surface stays identical across them.
+_model_option = click.option(
+    "--model",
+    type=str,
+    default=None,
+    help="HuggingFace model ID for the diffusion pipeline. Default: the SDXL base checkpoint.",
+)
+_guidance_scale_option = click.option(
+    "--guidance-scale",
+    type=float,
+    default=None,
+    help="Classifier-free guidance scale (CFG). Default: 7.5 (the library default). "
+    "Lower = follow the prompt less / stay closer to the input.",
 )
 
 
-def _apply_auto(
-    ctx: click.Context,
-    source: Path,
-    pipeline: str,
-    adaptive_polish: bool,
-) -> tuple[str, bool]:
-    """Resolve ``--auto``: plan the three content-adaptive modes (pipeline, face
-    restore, adaptive polish) from the image, overriding only the ones the user left
-    at their default (an explicit flag always wins). The fixed ``--unsharp``/
-    ``--humanize`` filters are independent and untouched. Prints the chosen plan.
+def _normalize_pipeline(ctx: click.Context, param: click.Parameter, value: str | None) -> str | None:
+    """Resolve the legacy ``default`` profile name to ``sdxl`` (click option callback).
+
+    Emits a one-line deprecation notice when the user explicitly passes the outdated
+    ``default`` value, pointing at the two current choices (``sdxl`` / ``controlnet``).
     """
-    from remove_ai_watermarks import auto_config
+    if value is None:
+        return None
+    from remove_ai_watermarks.noai.watermark_profiles import normalize_profile
 
-    cfg = auto_config.plan(source)
-    if cfg is None:
-        console.print("  Auto: could not read image; using defaults")
-        return pipeline, adaptive_polish
+    normalized = normalize_profile(value)
+    if value.strip().lower() == "default":
+        click.echo(
+            "Warning: --pipeline default is deprecated and maps to 'sdxl'. "
+            "Use --pipeline sdxl (plain SDXL) or --pipeline controlnet (the default).",
+            err=True,
+        )
+    return normalized
 
-    def _is_default(name: str) -> bool:
-        return ctx.get_parameter_source(name) == click.core.ParameterSource.DEFAULT
 
-    if _is_default("pipeline"):
-        pipeline = cfg.pipeline
-    if _is_default("adaptive_polish"):
-        adaptive_polish = cfg.adaptive_polish
-    console.print(f"  Auto: {cfg.reason}")
-    return pipeline, adaptive_polish
+# ``controlnet`` (the default-SELECTED value) and ``sdxl`` (plain SDXL img2img) are the
+# two current profiles; ``default`` is an OUTDATED back-compat alias for ``sdxl``
+# (warned + normalized away by _normalize_pipeline).
+_PIPELINE_CHOICES = ["sdxl", "controlnet", "default"]
+_PIPELINE_HELP = (
+    "Pipeline profile. controlnet (DEFAULT) = SDXL + canny ControlNet that preserves "
+    "text/faces via edge conditioning while removing SynthID; sdxl = plain SDXL img2img "
+    "(lighter, no extra model download, but leaves SynthID on flat-graphic content). "
+    "('default' is an OUTDATED alias for 'sdxl' -- use sdxl or controlnet.)"
+)
+
+# Shared --pipeline / --strength decorators so the three diffusion commands
+# (invisible/all/batch) keep an identical surface and the strength help can never
+# drift from the watermark_profiles constants (strength_default_help derives it).
+_pipeline_option = click.option(
+    "--pipeline",
+    type=click.Choice(_PIPELINE_CHOICES),
+    default="controlnet",
+    callback=_normalize_pipeline,
+    help=_PIPELINE_HELP,
+)
+_strength_option = click.option(
+    "--strength",
+    type=float,
+    default=None,
+    help=f"Denoising strength (0.0-1.0). Default: {strength_default_help()}.",
+)
+
+
+def _resolve_auto_polish(auto: bool, adaptive_polish: bool) -> bool:
+    """Warn on the retired ``--auto`` flag, returning ``adaptive_polish`` unchanged.
+
+    ``--auto`` used to plan the pipeline + polish from content detection, but the
+    pipeline is now always controlnet (the default) and the adaptive polish is ON by
+    default (it self-gates by detail level), so the content detectors were removed and
+    ``--auto`` is now a no-op alias: the polish it used to enable is already the default,
+    and an explicit ``--no-adaptive-polish`` still wins. So it only emits a deprecation
+    warning and passes ``adaptive_polish`` through.
+    """
+    if auto:
+        click.echo(
+            "Warning: --auto is deprecated and now does nothing (the adaptive polish it "
+            "enabled is ON by default). Use --no-adaptive-polish to turn the polish off.",
+            err=True,
+        )
+    return adaptive_polish
 
 
 def _warn_if_esrgan_unavailable(upscaler: str) -> None:
@@ -232,15 +289,71 @@ def _warn_if_esrgan_unavailable(upscaler: str) -> None:
         console.print("  Note: --upscaler esrgan needs the 'esrgan' extra; falling back to Lanczos.")
 
 
-def _watermark_region(det: DetectionResult, width: int, height: int) -> tuple[int, int, int, int]:
-    """Pick a watermark bbox: detector's region if confident, else the default config slot."""
-    if det.confidence > 0.15:
-        return det.region
-    from remove_ai_watermarks.gemini_engine import get_watermark_config
+def _remove_visible_auto(
+    image: NDArray[Any],
+    *,
+    inpaint: bool = True,
+    inpaint_method: str = "ns",
+    inpaint_strength: float = 0.85,
+) -> tuple[NDArray[Any], str | None]:
+    """Remove the strongest auto-detected visible mark via the registry.
 
-    config = get_watermark_config(width, height)
-    px, py = config.get_position(width, height)
-    return (px, py, config.logo_size, config.logo_size)
+    Routes the ``all``/``batch`` visible step through the same registry path the
+    standalone ``visible`` command uses, so EVERY registered mark is handled (the
+    Gemini sparkle AND the Doubao/Jimeng/Samsung text marks), not just the sparkle.
+    Returns ``(result, label-or-None)``; when no ``in_auto`` mark fires the image is
+    returned unchanged with ``None``. ``inpaint*`` tune the Gemini edge-residual
+    cleanup only (the text engines ignore them).
+    """
+    from remove_ai_watermarks import watermark_registry
+
+    best = watermark_registry.best_auto_mark(image)
+    if best is None:
+        return image, None
+    method: Literal["telea", "ns"] = "ns" if inpaint_method == "ns" else "telea"
+    result, _ = watermark_registry.get_mark(best.key).remove(
+        image, inpaint_method=method, inpaint=inpaint, inpaint_strength=inpaint_strength, force=False
+    )
+    return result, best.label
+
+
+# Exit code for the standalone ``visible`` command when no visible mark was
+# removed -- distinct from success (0) and a hard error (1) so a wrapping
+# service can tell "nothing to do here" apart and surface guidance instead of
+# re-serving the unchanged input as a finished result.
+EXIT_NO_VISIBLE_MARK = 2
+
+
+def _no_visible_mark_exit(source: Path) -> NoReturn:
+    """Explain why no visible watermark was removed, then exit non-zero.
+
+    The visible registry handles only known visual marks (the Gemini sparkle and
+    the Doubao/Jimeng/Samsung text strips). Most real uploads carry no such mark
+    -- frequently an invisible/metadata watermark instead (e.g. an OpenAI or
+    Gemini image whose only signal is C2PA + SynthID). Returning the input
+    unchanged with exit 0 reads as success to a caller and re-serves the
+    watermarked image -- the recurring "it didn't work" report. Instead, run a
+    cheap metadata-only :func:`identify`, tell the user what the image actually
+    carries and which command removes it, and exit
+    :data:`EXIT_NO_VISIBLE_MARK`.
+    """
+    from remove_ai_watermarks.identify import identify
+
+    report = identify(source, check_visible=False, check_invisible=False)
+    if report.is_ai_generated and report.watermarks:
+        plat = report.platform or "an unidentified platform"
+        console.print(
+            f"  This image carries an invisible/metadata watermark ({plat}), not a visible mark,\n"
+            "  so the 'visible' command cannot remove it. Run the full pipeline instead:\n"
+            f"    remove-ai-watermarks all {source.name}"
+        )
+    else:
+        console.print(
+            "  No AI provenance signal found either. If there is a logo or object to remove,\n"
+            "  target it directly with the region eraser:\n"
+            f"    remove-ai-watermarks erase {source.name} --region x,y,w,h"
+        )
+    raise SystemExit(EXIT_NO_VISIBLE_MARK)
 
 
 def _read_bgr_and_alpha(path: Path) -> tuple[NDArray[Any] | None, NDArray[Any] | None]:
@@ -376,10 +489,9 @@ def cmd_visible(
     if mark == "auto":
         best = registry.best_auto_mark(image)
         if best is None:
-            console.print("  Warning: No known visible mark detected (gemini / doubao).")
+            console.print("  No known visible mark detected (gemini / doubao / jimeng / samsung).")
             if detect:
-                console.print("  Skipping. Use --mark <name> --no-detect to force.")
-                raise SystemExit(0)
+                _no_visible_mark_exit(source)
             target = "gemini"  # forced (no-detect): fall back to the default mark
         else:
             target = best.key
@@ -390,8 +502,8 @@ def cmd_visible(
     chosen = registry.get_mark(target)
     det = chosen.detect(image)
     if detect and not det.detected:
-        console.print(f"  Warning: {chosen.label} not detected  (conf {det.confidence:.2f}). Use --no-detect to force.")
-        raise SystemExit(0)
+        console.print(f"  {chosen.label} not detected  (conf {det.confidence:.2f}). Use --no-detect to force.")
+        _no_visible_mark_exit(source)
     if det.detected:
         console.print(f"  {chosen.label} detected  ({chosen.location}, conf {det.confidence:.2f})")
 
@@ -524,21 +636,9 @@ def cmd_erase(
 @click.option(
     "-o", "--output", type=click.Path(path_type=Path), default=None, help="Output path (default: <source>_clean.<ext>)."
 )
-@click.option(
-    "--strength",
-    type=float,
-    default=None,
-    help="Denoising strength (0.0-1.0). Default: vendor-adaptive (OpenAI 0.10 / Google 0.15 / "
-    "unknown 0.15, from the C2PA issuer).",
-)
+@_strength_option
 @click.option("--steps", type=int, default=50, help="Number of denoising steps. Default: 50.")
-@click.option(
-    "--pipeline",
-    type=click.Choice(["default", "controlnet"]),
-    default="default",
-    help="Pipeline profile (default=SDXL img2img; controlnet=SDXL + canny ControlNet that preserves "
-    "text/faces via edge conditioning while removing SynthID, EXPERIMENTAL).",
-)
+@_pipeline_option
 @click.option(
     "--device",
     type=click.Choice(["auto", "cpu", "mps", "cuda", "xpu"]),
@@ -560,6 +660,8 @@ def cmd_erase(
 @_min_resolution_option
 @_unsharp_option
 @_upscaler_option
+@_model_option
+@_guidance_scale_option
 @_auto_option
 @_adaptive_polish_option
 @click.pass_context
@@ -579,6 +681,8 @@ def cmd_invisible(
     min_resolution: int,
     controlnet_scale: float,
     upscaler: str,
+    model: str | None,
+    guidance_scale: float | None,
     auto: bool,
     adaptive_polish: bool,
 ) -> None:
@@ -599,8 +703,7 @@ def cmd_invisible(
 
     source = _validate_image(source)
     _warn_if_esrgan_unavailable(upscaler)
-    if auto:
-        pipeline, adaptive_polish = _apply_auto(ctx, source, pipeline, adaptive_polish)
+    adaptive_polish = _resolve_auto_polish(auto, adaptive_polish)
     if output is None:
         output = source.with_stem(source.stem + "_clean")
 
@@ -610,6 +713,7 @@ def cmd_invisible(
         console.print(f"  {msg}")
 
     engine = InvisibleEngine(
+        model_id=model,
         device=device_str,
         pipeline=pipeline,
         hf_token=hf_token,
@@ -630,7 +734,7 @@ def cmd_invisible(
         output_path=output,
         strength=strength,
         num_inference_steps=steps,
-        guidance_scale=None,
+        guidance_scale=guidance_scale,
         seed=seed,
         humanize=humanize,
         unsharp=unsharp,
@@ -781,21 +885,10 @@ def cmd_identify(ctx: click.Context, source: Path, no_visible: bool, as_json: bo
 @click.option(
     "--inpaint-method", type=click.Choice(["ns", "telea", "gaussian"]), default="ns", help="Inpainting method."
 )
-@click.option(
-    "--strength",
-    type=float,
-    default=None,
-    help="Invisible watermark denoising strength. Default: vendor-adaptive (OpenAI 0.10 / Google 0.15 / unknown 0.15).",
-)
+@_strength_option
 @click.option("--steps", type=int, default=50, help="Number of denoising steps for invisible removal.")
-@click.option(
-    "--pipeline",
-    type=click.Choice(["default", "controlnet"]),
-    default="default",
-    help="Pipeline profile (default=SDXL img2img; controlnet=SDXL + canny ControlNet that preserves "
-    "text/faces via edge conditioning while removing SynthID, EXPERIMENTAL).",
-)
-@click.option("--model", type=str, default=None, help="HuggingFace model ID for invisible removal.")
+@_pipeline_option
+@_model_option
 @click.option(
     "--device",
     type=click.Choice(["auto", "cpu", "mps", "cuda", "xpu"]),
@@ -817,6 +910,7 @@ def cmd_identify(ctx: click.Context, source: Path, no_visible: bool, as_json: bo
 @_min_resolution_option
 @_unsharp_option
 @_upscaler_option
+@_guidance_scale_option
 @_auto_option
 @_adaptive_polish_option
 @click.pass_context
@@ -839,6 +933,7 @@ def cmd_all(
     min_resolution: int,
     controlnet_scale: float,
     upscaler: str,
+    guidance_scale: float | None,
     auto: bool,
     adaptive_polish: bool,
 ) -> None:
@@ -851,19 +946,23 @@ def cmd_all(
 
     If invisible watermark deps are not installed, skips step 2 with a warning.
     """
-    from remove_ai_watermarks.gemini_engine import GeminiEngine
-
     _banner()
     source = _validate_image(source)
     _warn_if_esrgan_unavailable(upscaler)
-    if auto:
-        pipeline, adaptive_polish = _apply_auto(ctx, source, pipeline, adaptive_polish)
+    adaptive_polish = _resolve_auto_polish(auto, adaptive_polish)
 
     if output is None:
         output = source.with_stem(source.stem + "_clean")
 
     t0 = time.monotonic()
 
+    # Tracks whether step 2 (invisible / SynthID removal) was skipped because the
+    # GPU extra is missing. A skipped step 2 still produces an output file (visible
+    # mark + metadata stripped), so without a loud end-of-run notice + non-zero exit
+    # the user mistakes it for a clean result and ships an image that still carries
+    # the invisible watermark (recurring reports: #14, #47).
+    synthid_skipped = False
+
     # Use a temp file for intermediate results so the user doesn't see
     # a partial output file during long model downloads.
     import tempfile
@@ -877,7 +976,6 @@ def cmd_all(
 
         # -- Step 1: Visible watermark --------------------------------
         console.print("\n  1) Visible watermark removal")
-        engine = GeminiEngine()
         image, alpha = _read_bgr_and_alpha(source)
         if image is None:
             console.print(f"Error: Failed to read image: {source}")
@@ -887,15 +985,10 @@ def cmd_all(
         console.print(f"    Input: {source.name}  ({w}x{h})")
 
         with console.status("Removing visible watermark..."):
-            det = engine.detect_watermark(image)
-            if det.detected:
-                result = engine.remove_watermark(image)
-                if inpaint:
-                    region = _watermark_region(det, w, h)
-                    result = engine.inpaint_residual(result, region, method=inpaint_method)
-                console.print("    Visible watermark removed")
+            result, removed_label = _remove_visible_auto(image, inpaint=inpaint, inpaint_method=inpaint_method)
+            if removed_label is not None:
+                console.print(f"    Visible watermark removed ({removed_label})")
             else:
-                result = image.copy()
                 console.print("    Skipped (no visible watermark detected)")
 
         # Save to temp file for invisible engine input (preserve alpha if present)
@@ -906,6 +999,7 @@ def cmd_all(
         from remove_ai_watermarks.invisible_engine import is_available as invisible_available
 
         if not invisible_available():
+            synthid_skipped = True
             console.print(
                 "    Warning: Skipped - GPU dependencies not installed.\n"
                 "    Install them with: pip install 'remove-ai-watermarks[gpu]'"
@@ -937,6 +1031,7 @@ def cmd_all(
                 output_path=tmp_path,
                 strength=strength,
                 num_inference_steps=steps,
+                guidance_scale=guidance_scale,
                 seed=seed,
                 humanize=humanize,
                 unsharp=unsharp,
@@ -979,6 +1074,24 @@ def cmd_all(
     size_kb = output.stat().st_size / 1024
     console.print(f"\n  Done: {output}  ({size_kb:.0f} KB, {elapsed:.1f}s total)")
 
+    # A skipped invisible step is the single most common "it didn't work" report:
+    # the output looks processed but still carries the SynthID watermark. Make that
+    # impossible to miss -- a prominent banner plus a non-zero exit so scripts and
+    # batch callers can detect the incomplete run instead of trusting the file.
+    if synthid_skipped:
+        console.print(
+            "\n  =====================================================================\n"
+            "  WARNING: the invisible (SynthID) watermark was NOT removed.\n"
+            "  Step 2 was skipped because the GPU dependencies are not installed,\n"
+            "  so this output still carries the invisible watermark -- only the\n"
+            "  visible mark and metadata were stripped.\n"
+            "\n"
+            "  Install the extra and rerun to remove it:\n"
+            "    pip install 'remove-ai-watermarks[gpu]'\n"
+            "  ====================================================================="
+        )
+        raise SystemExit(1)
+
 
 # -- Batch command ----------------------------------------------------
 
@@ -1001,7 +1114,8 @@ def _process_batch_image(
     min_resolution: int = 1024,
     controlnet_scale: float = 1.0,
     upscaler: str = "lanczos",
-    auto: bool = False,
+    model: str | None = None,
+    guidance_scale: float | None = None,
     adaptive_polish: bool = False,
 ) -> None:
     """Process a single image for batch mode.
@@ -1015,27 +1129,15 @@ def _process_batch_image(
     saved_alpha: NDArray[Any] | None = None
 
     if mode in ("visible", "all"):
-        from remove_ai_watermarks.gemini_engine import GeminiEngine
-
-        if "_vis_engine" not in ctx.obj:
-            ctx.obj["_vis_engine"] = GeminiEngine()
-        engine = ctx.obj["_vis_engine"]
-        read_path = img_path
-        if mode == "all" and out_path.exists():
-            read_path = out_path
-        image, alpha = _read_bgr_and_alpha(read_path)
+        # Always read the ORIGINAL source: the visible pass is the first step, so a
+        # stale out_path from a previous run must not be re-processed as if it were
+        # the input. (The invisible step below reads out_path for `all` -- that chain
+        # is within a single run.)
+        image, alpha = _read_bgr_and_alpha(img_path)
         if image is None:
             raise ValueError("Failed to read image")
 
-        det = engine.detect_watermark(image)
-        if det.detected:
-            result = engine.remove_watermark(image)
-            if inpaint:
-                h, w = image.shape[:2]
-                region = _watermark_region(det, w, h)
-                result = engine.inpaint_residual(result, region)
-        else:
-            result = image.copy()
+        result, _ = _remove_visible_auto(image, inpaint=inpaint)
 
         _write_bgr_with_alpha(out_path, result, alpha)
         saved_alpha = alpha
@@ -1048,14 +1150,12 @@ def _process_batch_image(
         if invisible_available():
             from remove_ai_watermarks.invisible_engine import InvisibleEngine
 
-            # --auto re-plans the pipeline / face-restore / polish per image; only the
-            # pipeline choice changes the engine ctor, so cache one engine per pipeline
-            # (controlnet vs default) rather than a single shared instance.
-            if auto:
-                pipeline, adaptive_polish = _apply_auto(ctx, img_path, pipeline, adaptive_polish)
+            # Cache the engine in ctx.obj so the batch builds it once (pipeline is a
+            # single CLI value, constant across the run).
             engines = ctx.obj.setdefault("_inv_engines", {})
             if pipeline not in engines:
                 engines[pipeline] = InvisibleEngine(
+                    model_id=model,
                     device=None if device == "auto" else device,
                     pipeline=pipeline,
                     hf_token=hf_token,
@@ -1067,6 +1167,7 @@ def _process_batch_image(
                 out_path,
                 strength=strength,
                 num_inference_steps=steps,
+                guidance_scale=guidance_scale,
                 seed=seed,
                 humanize=humanize,
                 unsharp=unsharp,
@@ -1104,19 +1205,13 @@ def _process_batch_image(
 @click.option(
     "--mode", type=click.Choice(["visible", "invisible", "metadata", "all"]), default="visible", help="Processing mode."
 )
-@click.option("--strength", type=float, default=None, help="Denoising strength (invisible mode).")
+@_strength_option
 @click.option("--steps", type=int, default=50, help="Number of denoising steps (invisible mode).")
 @click.option("--inpaint/--no-inpaint", default=True, help="Apply inpainting (visible mode).")
 @click.option(
     "--humanize", type=float, default=0.0, help="Analog Humanizer film grain intensity (0 = off, typical: 2.0-6.0)."
 )
-@click.option(
-    "--pipeline",
-    type=click.Choice(["default", "controlnet"]),
-    default="default",
-    help="Pipeline profile (default=SDXL img2img; controlnet=SDXL + canny ControlNet that preserves "
-    "text/faces via edge conditioning while removing SynthID, EXPERIMENTAL).",
-)
+@_pipeline_option
 @click.option(
     "--device",
     type=click.Choice(["auto", "cpu", "mps", "cuda", "xpu"]),
@@ -1135,6 +1230,8 @@ def _process_batch_image(
 @_unsharp_option
 @_upscaler_option
 @_controlnet_scale_option
+@_model_option
+@_guidance_scale_option
 @_auto_option
 @_adaptive_polish_option
 @click.pass_context
@@ -1156,6 +1253,8 @@ def cmd_batch(
     min_resolution: int,
     controlnet_scale: float,
     upscaler: str,
+    model: str | None,
+    guidance_scale: float | None,
     auto: bool,
     adaptive_polish: bool,
 ) -> None:
@@ -1177,6 +1276,7 @@ def cmd_batch(
     console.print(f"  Mode: {mode}")
     if mode in ("invisible", "all"):
         _warn_if_esrgan_unavailable(upscaler)
+    adaptive_polish = _resolve_auto_polish(auto, adaptive_polish)
 
     processed = 0
     errors = 0
@@ -1214,7 +1314,8 @@ def cmd_batch(
                     min_resolution=min_resolution,
                     controlnet_scale=controlnet_scale,
                     upscaler=upscaler,
-                    auto=auto,
+                    model=model,
+                    guidance_scale=guidance_scale,
                     adaptive_polish=adaptive_polish,
                 )
                 processed += 1

src/remove_ai_watermarks/doubao_engine.py

@@ -4,417 +4,122 @@ 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.
+Removal is **reverse-alpha blending** against a captured alpha map
+(``original = (wm - a*logo)/(1-a)``), always NCC-aligned to the actual mark plus a
+thin residual inpaint over the glyph footprint. This is one of the three text-mark
+engines that share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`;
+this module supplies only Doubao's tuned :class:`TextMarkConfig` (bottom-right corner,
+``assets/doubao_alpha.png`` rebuilt by ``scripts/visible_alpha_solve.py``). Arbitrary-
+region inpainting still lives in ``region_eraser`` / the ``erase`` command.
 """
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
 
-# 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
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
 
 if TYPE_CHECKING:
     from pathlib import Path
 
     from numpy.typing import NDArray
 
-logger = logging.getLogger(__name__)
-
-
-# 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.
+# Locate geometry as a fraction of image WIDTH (the mark scales with width, anchored
+# bottom-right). The box is GENEROUSLY wider than the mark and reaches close to the
+# corner so a per-image re-rasterization shift stays inside the NCC alignment search.
 WM_WIDTH_FRAC = 0.22
 WM_HEIGHT_FRAC = 0.075
 MARGIN_RIGHT_FRAC = 0.004
 MARGIN_BOTTOM_FRAC = 0.004
 
-# Glyph appearance: the label is a low-saturation light gray, rendered brighter
-# than the surrounding content (the common case: a generated photo/illustration).
-# We detect it as a local bright feature (white top-hat: brighter than a blurred
-# local background) intersected with the grayish + minimum-brightness tests.
-# This is polarity-correct for bright-on-darker backgrounds and, crucially,
-# leaves white-paper documents untouched (there the mark is not brighter than
-# its surroundings, so nothing is masked rather than damaging the document text).
+# Glyph appearance: a light, low-saturation gray rendered brighter than the local
+# background (white top-hat), so a white-paper document is left untouched.
 MAX_SATURATION = 55  # max channel spread to count a pixel as "grayish"
 LOGO_MIN_LUMA = 150  # glyphs are at least this bright in absolute terms
 TOPHAT_DELTA = 12  # glyph must exceed the local background by this many levels
 
-# Detection 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.
+# Shape-consistent detection: match the bundled alpha glyph silhouette against the
+# corner candidate via TM_CCOEFF_NORMED (keys on glyph SHAPE, not coverage; #23).
 DETECT_MIN_COVERAGE = 0.04
 DETECT_NCC_THRESHOLD = 0.4
 
-# ── 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.
+# Reverse-alpha geometry, emitted by scripts/visible_alpha_solve.py at the captured
+# width. Removal always tries fixed AND NCC-aligned placement and keeps the lower
+# residual, then a thin footprint inpaint clears the leftover edges.
 _ALPHA_NATIVE_WIDTH = 2048
 _ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
 _ALPHA_WIDTH_FRAC = 0.1636  # asset width / image width -- the alignment scale seed
 _ALPHA_HEIGHT_FRAC = 0.0405
-# 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
+
+_CONFIG = TextMarkConfig(
+    name="Doubao",
+    asset_name="doubao_alpha.png",
+    corner="br",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_RIGHT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    alpha_margin_x_frac=_ALPHA_MARGIN_RIGHT_FRAC,
+    alpha_margin_bottom_frac=_ALPHA_MARGIN_BOTTOM_FRAC,
+    alpha_align_search=_ALPHA_ALIGN_SEARCH,
+    min_gw=8,
+    alpha_logo_bgr=_ALPHA_LOGO_BGR,
+    residual_alpha_floor=_RESIDUAL_ALPHA_FLOOR,
+    residual_dilate=_RESIDUAL_DILATE,
+    residual_inpaint_radius=_RESIDUAL_INPAINT_RADIUS,
+)
+
+# Doubao-specific aliases for the shared detection result/engine.
+DoubaoDetection = TextMarkDetection
 
 
 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
+    """The bundled Doubao alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
 def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "豆包AI生成" silhouette (255 = glyph) from the 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
+    """Binary "豆包AI生成" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
 def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
-    """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())
+    """TM_CCOEFF_NORMED of the Doubao glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, image_width, _CONFIG)
 
 
-class DoubaoEngine:
-    """Remove the visible Doubao "豆包AI生成" watermark (locate -> mask -> inpaint)."""
+class DoubaoEngine(TextMarkEngine):
+    """Remove the visible Doubao "豆包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]) -> 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 __init__(self) -> None:
+        super().__init__(_CONFIG)
 
 
 def load_image_bgr(path: str | Path) -> NDArray[Any]:
     """Read an image as BGR ndarray (helper for scripts/tests)."""
     from remove_ai_watermarks import image_io
 
-    img = image_io.imread(path, cv2.IMREAD_COLOR)
+    img = image_io.imread(path)
     if img is None:
         raise FileNotFoundError(f"Failed to read image: {path}")
     return img

src/remove_ai_watermarks/gemini_engine.py

@@ -28,6 +28,8 @@ from typing import TYPE_CHECKING, Any, Literal
 import cv2
 import numpy as np
 
+from remove_ai_watermarks import image_io
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -216,6 +218,16 @@ class GeminiEngine:
     _CORNER_PROMOTE_MIN = 96
     _CORNER_PROMOTE_MAX = 384
 
+    # Number of top size-weighted spatial candidates scored by full fusion before one
+    # is selected. The single size-weighted argmax can bury a genuine mid-size sparkle
+    # under a LARGER, lower-fidelity shape match (the 256->512 search-widening
+    # regression: a real corner sparkle at raw ~0.77 lost to a decoy at raw ~0.63).
+    # Scoring the top-K by gradient-bearing fusion rescues it. Top-K (NOT the raw-NCC
+    # argmax) keeps the tiny-patch suppression intact: a coincidental 16 px match never
+    # ranks in the size-weighted top-K, so widening selection cannot add a false
+    # positive on non-Gemini content (verified on the doubao/jimeng visible corpora).
+    _SELECT_TOPK = 3
+
     def __init__(self, logo_value: float = 255.0) -> None:
         """Initialize the engine with embedded alpha maps.
 
@@ -290,6 +302,11 @@ class GeminiEngine:
         if image is None or image.size == 0:
             return result
 
+        # Normalize to 3-channel BGR: the multi-scale search tolerates grayscale, but
+        # the FP-gate / alpha-gain helpers (_core_and_bg) reduce over axis=2 and would
+        # crash on a 2D/BGRA input reaching this public entry point (e.g. via the
+        # registry detect adapter or the library API).
+        image = image_io.to_bgr(image)
         h, w = image.shape[:2]
         base_size = force_size or get_watermark_size(w, h)
         result.size = base_size
@@ -309,91 +326,65 @@ class GeminiEngine:
 
         gray_sr_f = gray_sr.astype(np.float32) / 255.0
 
-        # Phase 1 & 2: multi-scale spatial NCC search, size-weighted argmax.
-        best_scale = 0
-        best_score = -1.0
-        best_raw_ncc = -1.0
-        best_loc = (0, 0)
+        # Phase 1 & 2: multi-scale spatial NCC search. The size weight (mimicking the
+        # C++ vendor weight) overcomes the NCC bias toward tiny patches, but its single
+        # argmax can bury a genuine mid-size sparkle under a LARGER, lower-fidelity
+        # shape match (the 256->512 search-widening regression). So score the top-K
+        # size-weighted candidates by the FULL fusion and keep the highest -- the
+        # gradient term separates a true white sparkle from a shape-only decoy. See
+        # _SELECT_TOPK for why top-K (not the raw-NCC argmax) preserves tiny-patch
+        # suppression and so cannot add a false positive on non-Gemini content.
+        scored: list[tuple[float, int, int, int, float]] = []  # (adj, scale, raw, x, y)
         for scale, max_val, max_loc in self._scan_scales(gray_sr_f):
-            # Size-adjusted score to overcome NCC bias toward tiny patches (mimics C++ weight)
-            weight = min(1.0, (scale / 96.0) ** 0.5)
-            adj_val = max_val * weight
-            if adj_val > best_score:
-                best_score = adj_val
-                best_scale = scale
-                best_loc = max_loc
-                best_raw_ncc = max_val
+            adj_val = max_val * min(1.0, (scale / 96.0) ** 0.5)
+            scored.append((adj_val, scale, max_val, sx1 + max_loc[0], sy1 + max_loc[1]))
+        scored.sort(reverse=True)
 
-        # Exact dynamic location & size
-        pos_x = sx1 + best_loc[0]
-        pos_y = sy1 + best_loc[1]
+        # Top-K candidates at distinct locations (NMS: drop a lower-ranked match that
+        # overlaps an already-kept one -- the same sparkle matches at adjacent scales).
+        candidates: list[tuple[int, int, int, float]] = []
+        for _adj, scale, raw, x, y in scored:
+            if any(
+                abs(x - px) < 0.5 * max(scale, ps) and abs(y - py) < 0.5 * max(scale, ps)
+                for ps, px, py, _ in candidates
+            ):
+                continue
+            candidates.append((scale, x, y, raw))
+            if len(candidates) >= self._SELECT_TOPK:
+                break
 
-        # Corner promotion: a near-perfect but small sparkle in the bottom-right
-        # corner is otherwise outranked by a larger, mediocre size-weighted match
-        # (see _CORNER_PROMOTE_NCC). Override the global pick with it when present.
-        promoted = self._corner_promote(image, best_raw_ncc)
+        # Corner promotion: a near-perfect small bottom-right sparkle the size weight
+        # buries even below the top-K (see _CORNER_PROMOTE_NCC) -- add it as a candidate.
+        promoted = self._corner_promote(image, candidates[0][3] if candidates else -1.0)
         if promoted is not None:
-            best_scale, pos_x, pos_y, best_raw_ncc = promoted
+            candidates.append(promoted)
+
+        # Select the candidate with the highest full-fusion confidence (pre-FP-gate).
+        best_scale, pos_x, pos_y, best_raw_ncc = candidates[0]
+        grad_score, var_score, best_fused = 0.0, 0.0, -1.0
+        for c_scale, c_x, c_y, c_raw in candidates:
+            if c_raw < 0.25:
+                c_grad, c_var, c_fused = 0.0, 0.0, max(0.0, c_raw * 0.5)
+            else:
+                c_grad, c_var = self._grad_var_scores(image, c_scale, c_x, c_y)
+                c_fused = c_raw * 0.50 + c_grad * 0.30 + c_var * 0.20
+            if c_fused > best_fused:
+                best_fused = c_fused
+                best_scale, pos_x, pos_y = c_scale, c_x, c_y
+                best_raw_ncc, grad_score, var_score = c_raw, c_grad, c_var
 
         result.region = (pos_x, pos_y, best_scale, best_scale)
         result.spatial_score = float(best_raw_ncc)
-
-        # Generate exact alpha map for matched size
-        alpha_region = self.get_interpolated_alpha(best_scale)
-
-        # Extract exactly the matched region for Gradient & Variance analysis
-        x1 = pos_x
-        y1 = pos_y
-        x2 = min(w, x1 + best_scale)
-        y2 = min(h, y1 + best_scale)
-
-        region = image[y1:y2, x1:x2]
-        if len(region.shape) == 3 and region.shape[2] >= 3:
-            gray_region = cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
-        else:
-            gray_region = region.copy()
-
-        gray_f = gray_region.astype(np.float32) / 255.0
-
-        # Adjust alpha_region if clipped by image boundary (rare, but possible)
-        ay1, ax1 = 0, 0
-        alpha_region = alpha_region[ay1 : ay1 + (y2 - y1), ax1 : ax1 + (x2 - x1)]
+        result.gradient_score = float(grad_score)
+        result.variance_score = float(var_score)
 
         if result.spatial_score < 0.25:
             result.confidence = float(max(0.0, result.spatial_score * 0.5))
             return result
 
-        # ── Stage 2: Gradient NCC ────────────────────────────────────
-        img_gx = cv2.Sobel(gray_f, cv2.CV_32F, 1, 0, ksize=3)
-        img_gy = cv2.Sobel(gray_f, cv2.CV_32F, 0, 1, ksize=3)
-        img_gmag = cv2.magnitude(img_gx, img_gy)
-
-        alpha_gx = cv2.Sobel(alpha_region, cv2.CV_32F, 1, 0, ksize=3)
-        alpha_gy = cv2.Sobel(alpha_region, cv2.CV_32F, 0, 1, ksize=3)
-        alpha_gmag = cv2.magnitude(alpha_gx, alpha_gy)
-
-        grad_match = cv2.matchTemplate(img_gmag, alpha_gmag, cv2.TM_CCOEFF_NORMED)
-        _, grad_score, _, _ = cv2.minMaxLoc(grad_match)
-        result.gradient_score = float(grad_score)
-
-        # ── Stage 3: Variance Analysis ───────────────────────────────
-        var_score = 0.0
-        ref_h = min(y1, best_scale)
-
-        if ref_h > 8:
-            ref_region = image[y1 - ref_h : y1, x1:x2]
-            gray_ref = cv2.cvtColor(ref_region, cv2.COLOR_BGR2GRAY) if len(ref_region.shape) == 3 else ref_region
-
-            _, s_wm = cv2.meanStdDev(gray_region)
-            _, s_ref = cv2.meanStdDev(gray_ref)
-
-            if s_ref[0][0] > 5.0:
-                var_score = max(0.0, min(1.0, 1.0 - (s_wm[0][0] / s_ref[0][0])))
-
-        result.variance_score = float(var_score)
-
         # ── Fusion ───────────────────────────────────────────────────
-        confidence = result.spatial_score * 0.50 + result.gradient_score * 0.30 + var_score * 0.20
+        # best_fused is the selected candidate's spatial*0.5 + grad*0.3 + var*0.2.
+        confidence = best_fused
 
         # False-positive gate: a low-confidence shape match whose core is NOT brighter
         # than its surroundings is a content false positive, not a white sparkle overlay.
@@ -422,6 +413,49 @@ class GeminiEngine:
 
         return result
 
+    def _grad_var_scores(
+        self,
+        image: NDArray[Any],
+        scale: int,
+        pos_x: int,
+        pos_y: int,
+    ) -> tuple[float, float]:
+        """Return ``(gradient_score, variance_score)`` for a candidate sparkle.
+
+        Factored out of ``detect_watermark`` so each top-K candidate can be scored by
+        the full fusion before one is selected. The gradient NCC correlates
+        Sobel-magnitude maps (shape fidelity, contrast-robust); the variance score
+        rewards a flat overlay region against the row band above it.
+        """
+        h, w = image.shape[:2]
+        x1, y1 = pos_x, pos_y
+        x2, y2 = min(w, x1 + scale), min(h, y1 + scale)
+        region = image[y1:y2, x1:x2]
+        gray_region = cv2.cvtColor(region, cv2.COLOR_BGR2GRAY) if region.ndim == 3 and region.shape[2] >= 3 else region
+        gray_f = gray_region.astype(np.float32) / 255.0
+        alpha_region = self.get_interpolated_alpha(scale)[: y2 - y1, : x2 - x1]
+
+        # ── Gradient NCC ──
+        img_gmag = cv2.magnitude(
+            cv2.Sobel(gray_f, cv2.CV_32F, 1, 0, ksize=3), cv2.Sobel(gray_f, cv2.CV_32F, 0, 1, ksize=3)
+        )
+        alpha_gmag = cv2.magnitude(
+            cv2.Sobel(alpha_region, cv2.CV_32F, 1, 0, ksize=3), cv2.Sobel(alpha_region, cv2.CV_32F, 0, 1, ksize=3)
+        )
+        _, grad_score, _, _ = cv2.minMaxLoc(cv2.matchTemplate(img_gmag, alpha_gmag, cv2.TM_CCOEFF_NORMED))
+
+        # ── Variance ──
+        var_score = 0.0
+        ref_h = min(y1, scale)
+        if ref_h > 8:
+            ref_region = image[y1 - ref_h : y1, x1:x2]
+            gray_ref = cv2.cvtColor(ref_region, cv2.COLOR_BGR2GRAY) if ref_region.ndim == 3 else ref_region
+            _, s_wm = cv2.meanStdDev(gray_region)
+            _, s_ref = cv2.meanStdDev(gray_ref)
+            if s_ref[0][0] > 5.0:
+                var_score = max(0.0, min(1.0, 1.0 - (s_wm[0][0] / s_ref[0][0])))
+        return float(grad_score), float(var_score)
+
     def _corner_promote(
         self,
         image: NDArray[Any],
@@ -481,17 +515,10 @@ class GeminiEngine:
             Cleaned BGR image as numpy array, or an unmodified copy when no
             watermark is detected.
         """
-        result = image.copy()
-
         # 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)
+        result = image_io.to_bgr(image.copy())
 
         size = force_size or get_watermark_size(result.shape[1], result.shape[0])
 
@@ -554,7 +581,9 @@ class GeminiEngine:
         Returns:
             Cleaned BGR image.
         """
-        result = image.copy()
+        # Same channel normalization as remove_watermark: the reverse-alpha blend
+        # assumes 3-channel BGR (a grayscale/BGRA input would mis-broadcast).
+        result = image_io.to_bgr(image.copy())
         x, y, rw, rh = region
 
         # Check standard sizes

src/remove_ai_watermarks/humanizer.py

@@ -2,8 +2,8 @@
 
 ``apply_analog_humanizer`` injects film grain and chromatic aberration to defeat
 digital AI-perfection classifiers (ported from NeuralBleach); ``unsharp_mask``
-counters the soft, over-smoothed look that diffusion + face-restoration leave
-behind (itself a common "this is AI" tell).
+counters the soft, over-smoothed look that the diffusion pass leaves behind
+(itself a common "this is AI" tell).
 """
 
 # cv2/numpy boundary: third-party libs ship no usable element types; relax the
@@ -63,7 +63,7 @@ def apply_analog_humanizer(image: NDArray, grain_intensity: float = 4.0, chromat
 def unsharp_mask(image: NDArray, amount: float = 0.5, sigma: float = 1.0) -> NDArray:
     """Sharpen via unsharp masking: ``out = image + amount * (image - blur(image))``.
 
-    Counters the soft, over-smoothed look of the diffusion + GFPGAN passes, which
+    Counters the soft, over-smoothed look of the diffusion pass, which
     reads as an AI tell. ``amount`` 0 = no-op (returns an unchanged copy); ~0.5-0.8
     is a safe range -- higher risks bright edge halos that are their own artifact.
     ``sigma`` is the Gaussian radius of the unsharp kernel.

src/remove_ai_watermarks/identify.py

@@ -30,6 +30,7 @@ from remove_ai_watermarks.metadata import (
     IPTC_AI_FIELD_MARKERS,
     IPTC_AI_MARKERS,
     aigc_label,
+    c2pa_cloud_manifest_in,
     c2pa_marker_in,
     exif_generator,
     get_ai_metadata,
@@ -96,6 +97,13 @@ _HF_JOB_CAVEAT = (
     "generation) but names neither the model nor the content type, so it is a "
     "medium-confidence signal, not proof the pixels are AI-generated."
 )
+_C2PA_CLOUD_CAVEAT = (
+    "The embedded C2PA manifest is absent but an XMP provenance pointer to the "
+    "vendor's cloud manifest store survives, so the Content Credentials remain "
+    "recoverable server-side -- stripping the file no longer removes the provenance. "
+    "It marks Content Credentials, not AI origin: the cloud manifest may describe a "
+    "human edit, and reading it needs a network fetch this tool does not make."
+)
 _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 "
@@ -285,7 +293,12 @@ def _vendor_of(text: str | None) -> str | None:
 # chain like Adobe over a Gemini original) legitimately names several vendors in
 # one valid chain and must not read as spoofing. Families not listed here are each
 # their own independent source (EXIF/XMP generator, IPTC AISystemUsed, AIGC, ...).
-_CLASH_SOURCE: dict[str, str] = {"c2pa": "c2pa_manifest", "synthid": "c2pa_manifest"}
+# The single C2PA-manifest source shared by the issuer attribution and the SynthID
+# proxy (both inferred from the same embedded manifest). Rule 2 keys off it too:
+# the camera device label is read from this manifest, so an AI marker is a clash
+# only when its source differs from this (i.e. it is genuinely independent).
+_C2PA_MANIFEST_SOURCE = "c2pa_manifest"
+_CLASH_SOURCE: dict[str, str] = {"c2pa": _C2PA_MANIFEST_SOURCE, "synthid": _C2PA_MANIFEST_SOURCE}
 
 
 def _integrity_clashes(
@@ -326,7 +339,16 @@ def _integrity_clashes(
             + " -- one provenance set was likely spoofed, transplanted, or laundered."
         )
 
-    if camera_label and camera_has_ai_marker:
+    # Rule 2: a camera-capture C2PA device next to an AI-generation marker. Only
+    # an AI marker from a source INDEPENDENT of the camera's own C2PA manifest is
+    # a contradiction. A device that both captures and runs on-device generative
+    # AI (Google Pixel Magic Editor / Pixel Studio) records the capture and the
+    # AI edit in ONE manifest, so the AI vendor is named only from that same
+    # manifest (c2pa issuer + synthid proxy) -- a legitimate edit chain, not a
+    # spoof. An EXIF/XMP generator, IPTC field, TC260 AIGC label, or second
+    # manifest naming AI on a camera capture is the real laundering tell.
+    independent_ai_marker = any(grp != _C2PA_MANIFEST_SOURCE for grp in source.values())
+    if camera_label and camera_has_ai_marker and independent_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 "
@@ -483,6 +505,21 @@ def identify(image_path: Path, *, check_visible: bool = True, check_invisible: b
         if c2pa_is_ai and (v := (_vendor_of(_attribute_platform(issuers, is_ai=True)) or _vendor_of(generator))):
             ai_vendor_claims["c2pa"] = v
 
+    # ── C2PA cloud-manifest reference (Durable Content Credentials) ─
+    # An XMP dcterms:provenance pointer to a vendor manifest store survives even
+    # when the embedded manifest is stripped, so the credentials stay recoverable
+    # server-side (C2PA 2.4). Provenance only -- it does NOT assert AI (the cloud
+    # manifest may describe a human edit), so it is excluded from ai_from_metadata
+    # and the clash vendors. Skip when an embedded manifest already attributed it.
+    if not has_c2pa and (cloud_vendor := c2pa_cloud_manifest_in(head)):
+        signals.append(Signal("c2pa_cloud", f"cloud manifest store: {cloud_vendor}", "medium"))
+        watermarks.append(
+            f"C2PA Durable Content Credentials (cloud manifest at {cloud_vendor}; embedded manifest absent)"
+        )
+        caveats.append(_C2PA_CLOUD_CAVEAT)
+        if platform is None:
+            platform = f"C2PA signer: {cloud_vendor} (cloud manifest)"
+
     # ── 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.

src/remove_ai_watermarks/image_io.py

@@ -49,6 +49,25 @@ def imread(path: str | Path, flags: int | None = None) -> NDArray[Any] | None:
     return cv2.imdecode(data, flags)
 
 
+def to_bgr(image: NDArray[Any]) -> NDArray[Any]:
+    """Return a 3-channel BGR view of ``image``, promoting grayscale and BGRA.
+
+    The cv2-based engines (sparkle + the reverse-alpha text marks) assume a
+    3-channel BGR array for their channel reductions (``mean(axis=2)``, the
+    per-pixel logo subtraction). A 2D grayscale or 4-channel BGRA input -- a real
+    Gemini-app export is opaque RGBA -- would otherwise crash or mis-broadcast.
+    Centralizes the shape coercion that was inlined across the engines. A 3-channel
+    input is returned unchanged (no copy).
+    """
+    import cv2
+
+    if image.ndim == 2 or image.shape[2] == 1:
+        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+    if image.shape[2] == 4:
+        return cv2.cvtColor(image, cv2.COLOR_BGRA2BGR)
+    return image
+
+
 def imwrite(path: str | Path, img: NDArray[Any]) -> bool:
     """Unicode-safe ``cv2.imwrite``.
 

src/remove_ai_watermarks/invisible_engine.py

@@ -19,6 +19,8 @@ import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from .noai.watermark_profiles import DEFAULT_MODEL_ID as DEFAULT_SDXL_MODEL_ID
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -37,9 +39,9 @@ logger = logging.getLogger(__name__)
 
 def is_available() -> bool:
     """Check if invisible watermark removal dependencies are installed."""
-    import importlib.util
+    from .optional_deps import module_available
 
-    return importlib.util.find_spec("diffusers") is not None and importlib.util.find_spec("torch") is not None
+    return module_available("diffusers", "torch")
 
 
 def _target_size(width: int, height: int, max_resolution: int, min_resolution: int = 0) -> tuple[int, int] | None:
@@ -83,13 +85,13 @@ class InvisibleEngine:
 
     # SDXL base is the default since May 2026; the vendor-adaptive strength
     # removes the current SynthID (see watermark_profiles + docs/synthid.md).
-    DEFAULT_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
+    DEFAULT_MODEL_ID = DEFAULT_SDXL_MODEL_ID
 
     def __init__(
         self,
         model_id: str | None = None,
         device: str | None = None,
-        pipeline: str = "default",
+        pipeline: str = "controlnet",
         hf_token: str | None = None,
         progress_callback: Callable[[str], None] | None = None,
         controlnet_conditioning_scale: float = 1.0,
@@ -99,9 +101,10 @@ class InvisibleEngine:
         Args:
             model_id: HuggingFace model ID. None = use the SDXL base default.
             device: Device for inference (auto/cpu/mps/cuda/xpu). None = auto.
-            pipeline: Pipeline profile. "default" (plain SDXL img2img) or
-                "controlnet" (SDXL + canny ControlNet that preserves text/face
-                structure via edge conditioning while removing SynthID).
+            pipeline: Pipeline profile. "controlnet" (DEFAULT; SDXL + canny ControlNet
+                that preserves text/face structure via edge conditioning while removing
+                SynthID) or "sdxl" (plain SDXL img2img, lighter but leaves SynthID on
+                flat-graphic content). "default" is a back-compat alias for "sdxl".
             hf_token: HuggingFace API token.
             progress_callback: Optional callback for progress messages.
             controlnet_conditioning_scale: ControlNet structure-preservation
@@ -175,19 +178,18 @@ class InvisibleEngine:
             output_path: Output path (None = overwrite source).
             strength: Denoising strength (0.0-1.0). None -> the vendor-adaptive
                 default.
-            steps: Number of denoising steps.
+            num_inference_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).
             unsharp: Final unsharp-mask sharpening strength (0 = off, default).
                 Applied last to counter the soft / over-smoothed look of the
                 diffusion pass; ~0.5-0.8 is a safe range, higher risks edge halos.
-            adaptive_polish: When True (the --auto mode default), restore the input's
-                detail level in the softened output instead of fixed unsharp/humanize:
-                a capped unsharp + edge-masked grain targeting the input's Laplacian
-                variance (self-limiting on text/graphics). Runs LAST, after face
-                restoration. The fixed ``humanize``/``unsharp`` knobs are normally 0
-                when this is on.
+            adaptive_polish: When True (the CLI default), restore the input's detail
+                level in the softened output: a capped unsharp + edge-masked grain
+                targeting the input's Laplacian variance. Self-limiting -- a no-op when
+                the output already meets the input's detail level (text/flat graphics),
+                so it only acts on over-smoothed photo/face texture. Runs LAST.
             max_resolution: Cap the long side (px) before diffusion. 0 (default)
                 = no cap. Set a positive value only to bound GPU/MPS memory on
                 very large inputs (it reintroduces a lossy downscale->upscale
@@ -261,8 +263,14 @@ class InvisibleEngine:
                 vendor=vendor,
             )
 
-            # Post-processing: optional Humanizer, then restore original resolution.
-            if humanize > 0.0:
+            # Post-processing chain: decode the diffusion output ONCE, apply the
+            # optional stages in memory in order (humanize -> restore original
+            # resolution -> unsharp -> adaptive polish), and write ONCE. Previously
+            # each stage independently imread/imwrote the full-res output, so a run
+            # with several stages PNG-decoded+re-encoded the same image 2-4 times.
+            # PNG is lossless, so the single-write output is byte-identical.
+            needs_restore = target is not None  # the input was resized before diffusion
+            if humanize > 0.0 or unsharp > 0.0 or adaptive_polish or needs_restore:
                 import cv2
 
                 from remove_ai_watermarks import image_io
@@ -271,67 +279,43 @@ class InvisibleEngine:
                 if out_cv is None:
                     return out_path
 
-                if self._progress_callback:
-                    self._progress_callback(f"Applying Analog Humanizer (grain: {humanize})...")
-                from remove_ai_watermarks.humanizer import apply_analog_humanizer
+                if humanize > 0.0:
+                    if self._progress_callback:
+                        self._progress_callback(f"Applying Analog Humanizer (grain: {humanize})...")
+                    from remove_ai_watermarks.humanizer import apply_analog_humanizer
 
-                out_cv = apply_analog_humanizer(out_cv, grain_intensity=humanize, chromatic_shift=1)
+                    out_cv = apply_analog_humanizer(out_cv, grain_intensity=humanize, chromatic_shift=1)
 
-                # Restore original resolution
+                # Restore original resolution if the input was resized for diffusion.
                 if (out_cv.shape[1], out_cv.shape[0]) != orig_size:
                     if self._progress_callback:
                         self._progress_callback(
                             f"Upscaling result back to original resolution {orig_size[0]}x{orig_size[1]}..."
                         )
-                    # Using INTER_LANCZOS4 for high-quality upscaling back to original
                     out_cv = cv2.resize(out_cv, orig_size, interpolation=cv2.INTER_LANCZOS4)
 
-                image_io.imwrite(out_path, out_cv)
-
-            else:
-                # No humanize: still restore the original size if it was capped.
-                import cv2
-
-                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)
-                    image_io.imwrite(out_path, out_cv)
-
-            # Final sharpening.
-            if unsharp > 0.0:
-                import cv2
-
-                from remove_ai_watermarks import image_io
-                from remove_ai_watermarks.humanizer import unsharp_mask
-
-                out_cv = image_io.imread(out_path, cv2.IMREAD_COLOR)
-                if out_cv is not None:
+                if unsharp > 0.0:
                     if self._progress_callback:
                         self._progress_callback(f"Sharpening (unsharp mask: {unsharp})...")
-                    image_io.imwrite(out_path, unsharp_mask(out_cv, amount=unsharp))
+                    from remove_ai_watermarks.humanizer import unsharp_mask
 
-            # Adaptive polish (--auto): restore the input's detail level in the softened
-            # output, sparing text/edges. Replaces the fixed unsharp/humanize knobs.
-            if adaptive_polish:
-                import cv2
-                import numpy as np
+                    out_cv = unsharp_mask(out_cv, amount=unsharp)
 
-                from remove_ai_watermarks import humanizer, image_io
+                # Adaptive polish (CLI default): restore the input's detail level in the
+                # softened output, sparing text/edges. Self-limiting where no deficit.
+                if adaptive_polish:
+                    import numpy as np
+
+                    from remove_ai_watermarks import humanizer
 
-                out_cv = image_io.imread(out_path, cv2.IMREAD_COLOR)
-                if out_cv is not None:
                     ref = cv2.cvtColor(np.array(reference_pil.convert("RGB")), cv2.COLOR_RGB2BGR)
                     if (ref.shape[1], ref.shape[0]) != (out_cv.shape[1], out_cv.shape[0]):
                         ref = cv2.resize(ref, (out_cv.shape[1], out_cv.shape[0]), interpolation=cv2.INTER_LANCZOS4)
                     if self._progress_callback:
                         self._progress_callback("Adaptive polish (sharpen + grain to the input's detail level)...")
-                    image_io.imwrite(out_path, humanizer.adaptive_polish(out_cv, ref, seed=seed))
+                    out_cv = humanizer.adaptive_polish(out_cv, ref, seed=seed)
+
+                image_io.imwrite(out_path, out_cv)
 
             return out_path
         finally:

src/remove_ai_watermarks/invisible_watermark.py

@@ -50,9 +50,9 @@ _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
+    from .optional_deps import module_available
 
-    return importlib.util.find_spec("imwatermark") is not None
+    return module_available("imwatermark")
 
 
 def _bits_match(value: int, ref: int, width: int = 48) -> int:

src/remove_ai_watermarks/jimeng_engine.py

@@ -1,415 +1,109 @@
-"""Jimeng (即梦AI) visible watermark removal engine.
+"""Jimeng / Dreamina 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.
+Jimeng (即梦AI, ByteDance) stamps generated images with a visible "★ 即梦AI" wordmark
+in the bottom-right corner -- a near-white semi-transparent overlay, the same overlay
+class as the Doubao text strip.
 
-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.
+Removal is **reverse-alpha blending** against a captured alpha map
+(``original = (wm - a*logo)/(1-a)``), always NCC-aligned to the actual mark plus a thin
+residual inpaint over the glyph footprint. This is one of the three text-mark engines
+that share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
+supplies only Jimeng's tuned :class:`TextMarkConfig` (bottom-right corner,
+``assets/jimeng_alpha.png`` rebuilt by ``scripts/visible_alpha_solve.py`` from the gray
+capture). Jimeng images are also caught by the China TC260 AIGC metadata label, so this
+is the visible-mark *removal* path, not a new ``identify`` signal.
 """
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
 
-# 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
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
-logger = logging.getLogger(__name__)
-
-
-# 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.
+# Locate geometry as a fraction of image WIDTH (mark scales with width, bottom-right).
 WM_WIDTH_FRAC = 0.27
 WM_HEIGHT_FRAC = 0.092
 MARGIN_RIGHT_FRAC = 0.008
 MARGIN_BOTTOM_FRAC = 0.010
 
-# Glyph appearance: a 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
+# Glyph appearance: a light, low-saturation gray brighter than the local background.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 150
+TOPHAT_DELTA = 12
 
-# 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.
+# Shape-consistent detection. Threshold 0.45 cleanly separates real Jimeng marks
+# (>=0.81) from the Doubao strip (0.21), so the two ByteDance marks do not cross-fire.
 DETECT_MIN_COVERAGE = 0.02
 DETECT_NCC_THRESHOLD = 0.45
 
-# ── Reverse-alpha (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.
+# Reverse-alpha geometry, emitted by scripts/visible_alpha_solve.py from the gray
+# capture at the captured width.
 _ALPHA_NATIVE_WIDTH = 2048
 _ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
-# 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
+
+_CONFIG = TextMarkConfig(
+    name="Jimeng",
+    asset_name="jimeng_alpha.png",
+    corner="br",
+    margin_floor=4,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_RIGHT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=5,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    alpha_margin_x_frac=_ALPHA_MARGIN_RIGHT_FRAC,
+    alpha_margin_bottom_frac=_ALPHA_MARGIN_BOTTOM_FRAC,
+    alpha_align_search=_ALPHA_ALIGN_SEARCH,
+    min_gw=8,
+    alpha_logo_bgr=_ALPHA_LOGO_BGR,
+    residual_alpha_floor=_RESIDUAL_ALPHA_FLOOR,
+    residual_dilate=_RESIDUAL_DILATE,
+    residual_inpaint_radius=_RESIDUAL_INPAINT_RADIUS,
+)
+
+JimengDetection = TextMarkDetection
 
 
 def _alpha_template() -> NDArray[Any] | None:
-    """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
+    """The bundled Jimeng alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
 def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "即梦AI" silhouette (255 = glyph) from the 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
+    """Binary "即梦AI" silhouette (255 = glyph) from the alpha map, or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
 def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
-    """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())
+    """TM_CCOEFF_NORMED of the Jimeng glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, image_width, _CONFIG)
 
 
-class JimengEngine:
-    """Remove the visible Jimeng "即梦AI" watermark (locate -> mask -> reverse-alpha)."""
+class JimengEngine(TextMarkEngine):
+    """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
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)

src/remove_ai_watermarks/metadata.py

@@ -9,6 +9,7 @@ For metadata-only operations, the heavy ML dependencies are NOT required.
 from __future__ import annotations
 
 import contextlib
+import functools
 import logging
 import re
 import struct
@@ -19,6 +20,11 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+# Smaller scan_head window for the cheap marker checks (has_ai_metadata,
+# samsung_genai); the full-detail scans use scan_head's 1 MB default. Sharing
+# one constant also keeps both call sites on the same memoized cache entry.
+_QUICK_SCAN_BYTES = 512 * 1024
+
 # ── Known AI metadata keys ──────────────────────────────────────────
 
 AI_METADATA_KEYS: frozenset[str] = frozenset(
@@ -209,7 +215,10 @@ def _png_late_metadata(image_path: Path, window: int) -> bytes:
                 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
+                # Advance by the CLAMPED length: a malformed/inflated `length` that
+                # overshoots EOF must not push `pos` past the file and abort the scan
+                # (which would silently skip a genuine AI-label chunk after it).
+                pos = data_start + safe_length + 4  # data + CRC
     except OSError as exc:
         logger.debug("PNG late-metadata scan failed on %s: %s", image_path, exc)
         return b""
@@ -227,7 +236,29 @@ def scan_head(image_path: Path, size: int = 1024 * 1024) -> bytes:
     non-faststart MP4 manifest, or a PNG XMP packet appended after the pixels --
     which a fixed first-MB read would miss. For other inputs, and for files that
     fit within ``size``, it is exactly ``f.read(size)`` -- behavior-neutral.
+
+    The result is memoized per (path, size, mtime): one ``identify``/``get_ai_metadata``
+    call fans out to ~8 byte-scan detectors that each call this on the same file, so
+    the cache turns those repeated reads into one. The mtime key invalidates the entry
+    when the file changes; the small ``maxsize`` bounds memory to a few MB.
     """
+    try:
+        mtime = image_path.stat().st_mtime_ns
+    except OSError:
+        # No stat (e.g. a pipe, or a race): read uncached rather than fail.
+        return _scan_head_impl(image_path, size)
+    return _scan_head_cached(str(image_path), size, mtime)
+
+
+@functools.lru_cache(maxsize=8)
+def _scan_head_cached(path_str: str, size: int, _mtime_ns: int) -> bytes:
+    """Cache shim: ``_mtime_ns`` is part of the key only (invalidates on change)."""
+    from pathlib import Path as _Path
+
+    return _scan_head_impl(_Path(path_str), size)
+
+
+def _scan_head_impl(image_path: Path, size: int) -> bytes:
     with open(image_path, "rb") as f:
         head = f.read(size)
     # Lazy import: isobmff imports this module's constants at top level.
@@ -280,7 +311,7 @@ def has_ai_metadata(image_path: Path) -> bool:
 
     # 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)
+    data = scan_head(image_path, _QUICK_SCAN_BYTES)
     if c2pa_marker_in(data):
         return True
     if any(marker in data for marker in AIGC_MARKERS):
@@ -312,13 +343,16 @@ def aigc_label(image_path: Path) -> dict[str, str] | None:
       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.
+      scan head; and
+    - a bare ``AIGC{...}`` blob (the label glued straight to its JSON, no
+      ``"AIGC":`` key wrapper) embedded in a JPEG APP segment near the JFIF
+      header by some China-served generators.
 
     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.
+    or None. The generic forms (the PNG-chunk key ``AIGC``, the bare
+    ``{"AIGC":...}`` object, and the bare ``AIGC{...}`` blob) 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
@@ -362,24 +396,76 @@ def aigc_label(image_path: Path) -> dict[str, str] | None:
         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)
+    # Generic raw-JSON forms the PNG-chunk and XMP paths above both miss, each
+    # gated on a TC260 field: the ``"AIGC":{...}`` key wrapper (as written into
+    # JPEG EXIF UserComment) and the bare ``AIGC{...}`` blob (the label glued
+    # straight to its JSON, no key wrapper, in a JPEG APP segment near the JFIF
+    # header). `raw_decode` brace-matches the inner object (respecting nested
+    # braces / quoted strings); `_parse` applies the same dict coercion + TC260
+    # gate as the PNG-chunk path. A non-matching hit (no TC260 field, or an
+    # undecodable brace) must FALL THROUGH to the next form, never short-circuit:
+    # a quoted ``"AIGC"`` can appear later in an XMP packet while the real label
+    # is a bare ``AIGC{...}`` blob earlier in the file, so an unconditional return
+    # on the quoted form would shadow the bare form.
+    text = data.decode("latin-1")
+    for needle in ('"AIGC"', "AIGC{"):
+        start = text.find(needle)
+        if start == -1:
+            continue
+        # First brace at/after the needle: the object brace for ``"AIGC":{`` and
+        # the glued brace (at start+4) for the bare ``AIGC{`` -- one search covers both.
+        brace = text.find("{", start)
+        if brace == -1:
+            continue
+        try:
+            _, end = json.JSONDecoder().raw_decode(text, brace)
+        except ValueError:
+            continue
+        if result := _parse(text[brace:end], require_tc260_field=True):
+            return result
     return None
 
 
+# C2PA "Durable Content Credentials" manifest repositories (C2PA 2.4). When the
+# embedded manifest is stripped, an XMP ``dcterms:provenance`` URL can still point
+# at the vendor's cloud manifest store, from which the credentials are recoverable
+# server-side via the file's soft binding. Host -> vendor label. Verified on real
+# files: Adobe's Content Authenticity cloud store.
+_C2PA_MANIFEST_REPOSITORIES: tuple[tuple[bytes, str], ...] = (
+    (b"cai-manifests.adobe.com", "Adobe Content Authenticity"),
+)
+
+
+def c2pa_cloud_manifest_in(data: bytes) -> str | None:
+    """Return a C2PA cloud-manifest vendor label if ``data`` carries an XMP
+    ``dcterms:provenance`` pointer to a known manifest repository, else None.
+
+    The shared byte-scan (mirroring ``soft_binding_vendors_in``), so a caller that
+    already holds the scan head (``identify``) reuses it instead of re-reading.
+    """
+    if b"dcterms:provenance" not in data:
+        return None
+    for host, vendor in _C2PA_MANIFEST_REPOSITORIES:
+        if host in data:
+            return vendor
+    return None
+
+
+def c2pa_cloud_manifest(image_path: Path) -> str | None:
+    """Return a C2PA cloud-manifest vendor label if the file carries only an XMP
+    ``dcterms:provenance`` pointer to a manifest repository (C2PA 2.4 Durable
+    Content Credentials), else None.
+
+    This fires on the laundering case where the *embedded* manifest was stripped
+    but the XMP cloud reference survives, so the Content Credentials remain
+    recoverable server-side. It is provenance, NOT an AI assertion: the cloud
+    manifest can describe a human edit as easily as an AI generation, and reading
+    its contents needs a network fetch we do not do. ``identify`` surfaces it as a
+    provenance signal without setting ``is_ai_generated``.
+    """
+    return c2pa_cloud_manifest_in(scan_head(image_path, _QUICK_SCAN_BYTES))
+
+
 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.
@@ -427,7 +513,7 @@ def samsung_genai(image_path: Path) -> int | None:
     gated on the ``PhotoEditor_Re_Edit_Data`` container so an incidental
     ``genAIType`` token cannot false-positive.
     """
-    head = scan_head(image_path, 512 * 1024)
+    head = scan_head(image_path, _QUICK_SCAN_BYTES)
     if _SAMSUNG_EDITOR_MARKER not in head:
         return None
     m = _SAMSUNG_GENAI_RE.search(head)

src/remove_ai_watermarks/noai/img2img_runner.py

@@ -52,7 +52,16 @@ def run_img2img(
         )
         done_ev.set()
         return result.images[0]
-    except TypeError:
+    except TypeError as exc:
+        # The only TypeError we retry is the deprecated-callback case: `_call_pipeline`
+        # passes the legacy `callback`/`callback_steps` kwargs, and a diffusers version
+        # that removed them raises TypeError("... unexpected keyword argument
+        # 'callback'"). We then re-run once WITHOUT the progress callback. Any OTHER
+        # TypeError (e.g. a bad control_image/dtype in the forward pass) is a real error
+        # -- re-raise it instead of silently re-running the whole diffusion pass and
+        # masking the cause.
+        if "callback" not in str(exc):
+            raise
         first_step.set()
         result = _call_pipeline(
             pipeline, image, strength, num_inference_steps, guidance_scale, generator, None, extra_kwargs

src/remove_ai_watermarks/noai/watermark_profiles.py

@@ -12,34 +12,55 @@ if TYPE_CHECKING:
 
 DEFAULT_MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
 
+# Canonical pipeline-profile names + the back-compat alias. The plain SDXL img2img
+# profile is ``sdxl``; ``default`` is kept as an accepted alias (it was the profile's
+# name before ``controlnet`` became the default-selected pipeline, 2026-06-09).
+SDXL_PROFILE = "sdxl"
+_PROFILE_ALIASES = {"default": SDXL_PROFILE}
+
+
+def normalize_profile(profile: str) -> str:
+    """Canonicalize a pipeline-profile name, resolving the ``default`` -> ``sdxl`` alias."""
+    normalized = profile.strip().lower()
+    return _PROFILE_ALIASES.get(normalized, normalized)
+
+
 # The SDXL-native canny ControlNet used by the ``controlnet`` pipeline. The
 # ControlNet is an add-on to the SDXL base checkpoint (DEFAULT_MODEL_ID), not a
-# separate base model, so both the ``default`` and ``controlnet`` profiles load
-# the same base weights and share the same vendor-adaptive strength.
+# separate base model, so both the ``sdxl`` and ``controlnet`` profiles load the
+# same base weights and share the same vendor-adaptive strength ladder (see below).
 CONTROLNET_CANNY_MODEL = "xinsir/controlnet-canny-sdxl-1.0"
 
 # Vendor-adaptive default denoising strength for the SDXL img2img scrub, overridable
 # from the CLI (`--strength`). The right strength depends on which vendor's SynthID is
-# present, detected from the C2PA issuer (metadata.synthid_source). Oracle-verified
-# controlled study (2026-06-01, clean v0.8.6, per-image openai.com/verify or Gemini-app
-# verdict; see docs/synthid.md section 2.2):
-#   - OpenAI gpt-image: removed at 0.05 across 1024-1600 (n=4), resolution-independent.
-#     OPENAI_STRENGTH 0.10 = the 0.05 floor plus a 2x margin (keeps quality high).
-#   - Google Gemini: removed at 0.15 on the capped-1536 path (n=4); 0.05/0.10 do NOT
-#     clear. GEMINI_STRENGTH 0.15. CAVEAT: 0.15 was validated only on
-#     `--max-resolution 1536`; native 2816 (the default path) was not locally
-#     measurable (OOM on Apple Silicon) and may need more -- pending GPU validation on
-#     the raiw.cc backend. If a native large Gemini still verifies positive at 0.15,
-#     raise `--strength`.
-#   - Unknown vendor (metadata stripped, or non-OpenAI/Google C2PA): UNKNOWN_STRENGTH
-#     0.15, the safe middle that clears both vendors at the tested resolutions.
-# The dominant factor is VENDOR, not resolution: Google's SynthID is ~3x more robust
-# than OpenAI's. The ``controlnet`` pipeline shares these strengths (same SDXL base; the
-# canny ControlNet only preserves structure, the strength still drives removal).
-OPENAI_STRENGTH = 0.10
-GEMINI_STRENGTH = 0.15
-UNKNOWN_STRENGTH = 0.15
-# Backwards-compatible alias: the vendor-unknown default (what a caller gets without a
+# present (detected from the C2PA issuer, metadata.synthid_source). The SAME ladder
+# applies to BOTH pipelines (`sdxl` plain img2img and `controlnet`) -- see "why one
+# ladder" below.
+#
+# Data basis (see docs/synthid.md sections 2.2 / 5.5): the values are the ORACLE-
+# CERTIFIED controlnet floors (2026-06-04, isolated Modal cert app, each vendor on its
+# own verifier): OpenAI 0.20 (2 photoreal x 3 seeds = 6/6 clean, resolution-independent),
+# Google 0.30 (clean on 2/2 seeds, validated ONLY at <= 1536 -- Gemini is resolution-
+# sensitive, native ~2816 likely needs ~0.35+). Unknown vendor gets the Google (more
+# robust watermark) value: safe-by-default.
+#
+# Why ONE ladder for both pipelines (2026-06-09): the certification was run on
+# controlnet, and it does NOT transfer to `sdxl` by symmetry -- the two pipelines have
+# OPPOSITE hard cases (controlnet leaves SynthID on photoreal, `sdxl` leaves it on flat
+# graphics; the content-x-pipeline table in docs/synthid.md §5.1). BUT on its OWN hard
+# case (flat fills) `sdxl` is the WEAKER remover -- plain img2img at low strength barely
+# perturbs a flat region -- so it needs AT LEAST as much strength as controlnet, not
+# less. Hence the certified controlnet floor is the right floor for `sdxl` too. The
+# higher strength costs little quality where it matters: `controlnet` is now the default
+# pipeline, so `sdxl` is reached only for structure-less inputs (via `--auto`) or an
+# explicit `--pipeline sdxl`, where over-regeneration has no faces/text to damage. NOTE:
+# this is a MARGIN argument for `sdxl`, not a fresh certification -- there is no local
+# SynthID detector, so if an oracle still reads SynthID on a flat `sdxl` output, raise
+# `--strength`.
+OPENAI_STRENGTH = 0.20
+GEMINI_STRENGTH = 0.30
+UNKNOWN_STRENGTH = 0.30
+# Backwards-compatible alias: the vendor-unknown value (what a caller gets without a
 # detected vendor). Kept as DEFAULT_STRENGTH for existing references.
 DEFAULT_STRENGTH = UNKNOWN_STRENGTH
 
@@ -47,17 +68,29 @@ DEFAULT_STRENGTH = UNKNOWN_STRENGTH
 _VENDOR_STRENGTH = {"openai": OPENAI_STRENGTH, "google": GEMINI_STRENGTH}
 
 
+def strength_default_help() -> str:
+    """One-line description of the vendor-adaptive default, derived from the constants.
+
+    Single source of truth for the CLI ``--strength`` help so the numbers can never
+    drift from the actual ladder (they did once when the per-pipeline split was unified).
+    """
+    return (
+        f"vendor-adaptive (OpenAI {OPENAI_STRENGTH} / Google {GEMINI_STRENGTH} / "
+        f"unknown {UNKNOWN_STRENGTH}, from the C2PA issuer; same ladder for both pipelines)"
+    )
+
+
 def resolve_strength(strength: float | None, vendor: str | None = None) -> float:
     """Resolve the denoising strength, applying the vendor default when unset.
 
     ``None`` means "the user did not pass ``--strength``", which resolves
     **vendor-adaptively**: ``vendor`` (``"openai"`` / ``"google"`` / None, from
     ``vendor_for_strength``) selects ``OPENAI_STRENGTH`` / ``GEMINI_STRENGTH`` /
-    ``UNKNOWN_STRENGTH``. An explicit value always wins (including ``0.0`` -- the check
-    is ``is None``, not falsiness). The ``default`` and ``controlnet`` profiles share
-    the same SDXL base (the ControlNet only preserves structure), so the default does
-    NOT depend on the profile. Shared by the CLI (for display) and the engine (for
-    execution) so the two never disagree -- both must pass the SAME ``vendor``.
+    ``UNKNOWN_STRENGTH``. The same ladder applies to both pipelines (see the module
+    comment for why one ladder is correct). An explicit value always wins (including
+    ``0.0`` -- the check is ``is None``, not falsiness). Shared by the CLI (for display)
+    and the engine (for execution) so the two never disagree -- both must pass the SAME
+    ``vendor``.
     """
     if strength is not None:
         return strength
@@ -85,16 +118,3 @@ def vendor_for_strength(image_path: Path) -> Literal["openai", "google"] | None:
     if "openai" in src:
         return "openai"
     return None
-
-
-def get_model_id_for_profile(profile: str) -> str:
-    """Map CLI model profile names to concrete Hugging Face model IDs.
-
-    Both ``default`` and ``controlnet`` use the SDXL base checkpoint -- the canny
-    ControlNet (``CONTROLNET_CANNY_MODEL``) is an add-on loaded on top of it, not a
-    separate base model.
-    """
-    normalized = profile.strip().lower()
-    if normalized in ("default", "controlnet"):
-        return DEFAULT_MODEL_ID
-    raise ValueError(f"Unknown model profile '{profile}'. Use one of: default, controlnet.")

src/remove_ai_watermarks/noai/watermark_remover.py

@@ -1,13 +1,17 @@
 """Watermark removal using diffusion model regeneration attack.
 
 Two pipelines:
-1. ``default`` -- plain SDXL img2img. Partial-noise regeneration scrubs the
-   invisible watermark; ``strength`` controls how much is regenerated.
-2. ``controlnet`` -- SDXL img2img with a canny ControlNet. The watermark REMOVAL
-   still comes from the img2img regeneration (``strength``); the ControlNet only
-   PRESERVES structure (text/faces) by conditioning on the edge map. No original
-   pixels are ever copied or frozen, so SynthID does not survive.
+1. ``controlnet`` (DEFAULT) -- SDXL img2img with a canny ControlNet. The watermark
+   REMOVAL still comes from the img2img regeneration (``strength``); the ControlNet
+   only PRESERVES structure (text/faces) by conditioning on the edge map. No original
+   pixels are ever copied or frozen. Because the edge map keeps the regeneration
+   closer to the original, it needs a higher ``strength`` floor than ``default`` to
+   destroy SynthID (the certified controlnet ladder; see ``watermark_profiles``).
    ``controlnet_conditioning_scale`` is the preservation knob.
+2. ``default`` -- plain SDXL img2img. Partial-noise regeneration scrubs the
+   invisible watermark; ``strength`` controls how much is regenerated. Lighter (no
+   ControlNet weights), but at the low default strength it leaves SynthID on
+   flat-graphic content -- use it for inputs without text/faces.
 """
 
 # torch/diffusers/cv2 boundary: these libs ship no usable types for the tensor and
@@ -32,6 +36,7 @@ from remove_ai_watermarks.noai.watermark_profiles import (
     CONTROLNET_CANNY_MODEL,
     DEFAULT_MODEL_ID,
     DEFAULT_STRENGTH,
+    normalize_profile,
     resolve_strength,
 )
 
@@ -323,13 +328,14 @@ class WatermarkRemover:
         torch_dtype: Any = None,
         progress_callback: Callable[[str], None] | None = None,
         hf_token: str | None = None,
-        pipeline: str = "default",
+        pipeline: str = "controlnet",
         controlnet_conditioning_scale: float = 1.0,
     ) -> None:
         self.model_id = model_id or self.DEFAULT_MODEL_ID
         # The pipeline profile is threaded explicitly (not inferred from model_id):
-        # both "default" and "controlnet" use the same SDXL base checkpoint.
-        self.model_profile = pipeline
+        # both "sdxl" and "controlnet" use the same SDXL base checkpoint. Normalize so
+        # the legacy "default" alias resolves to "sdxl".
+        self.model_profile = normalize_profile(pipeline)
         self.controlnet_conditioning_scale = controlnet_conditioning_scale
 
         if not is_watermark_removal_available():

src/remove_ai_watermarks/optional_deps.py

@@ -0,0 +1,28 @@
+"""Shared availability guard for optional dependencies.
+
+A bare ``importlib.util.find_spec(name) is not None`` check lies when only a
+leftover data directory exists in site-packages: e.g. ``trustmark`` downloads
+model weights into its own package dir, so after the package is uninstalled
+(``uv sync`` pruning an extra) a ``trustmark/models/`` remnant survives and
+``find_spec`` resolves it to a namespace-package spec (``loader is None``)
+while the actual import fails. Every ``is_available()`` guard routes through
+``module_available`` so a pure namespace package counts as absent.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+
+
+def module_available(*names: str) -> bool:
+    """True when every named module resolves to a real, importable package.
+
+    A spec with ``loader is None`` is a pure namespace package -- for our
+    optional deps that means a stale directory remnant, not an installed
+    package -- so it is treated as not available.
+    """
+    for name in names:
+        spec = importlib.util.find_spec(name)
+        if spec is None or spec.loader is None:
+            return False
+    return True

src/remove_ai_watermarks/region_eraser.py

@@ -82,9 +82,9 @@ def erase_cv2(
 
 def lama_available() -> bool:
     """True when the optional LaMa-ONNX backend can run (onnxruntime installed)."""
-    import importlib.util
+    from .optional_deps import module_available
 
-    return importlib.util.find_spec("onnxruntime") is not None
+    return module_available("onnxruntime")
 
 
 def _get_lama_session() -> object:

src/remove_ai_watermarks/samsung_engine.py

@@ -1,394 +1,116 @@
 """Samsung Galaxy AI visible watermark removal engine.
 
-Samsung's on-device Generative AI photo edits (Generative Edit / Sketch to Image /
-Portrait Studio on Galaxy phones) stamp a visible localized wordmark -- a sparkle
-icon followed by a "generated with AI" string -- in the **bottom-left** corner: a
-light, low-opacity semi-transparent white overlay. The string is locale-specific;
-this engine is calibrated for the Italian "Contenuti generati dall'AI" variant
-(issue #37, captures from @f-liva). Other locales need their own captured alpha
-template, but the geometry and removal recipe are shared.
+Samsung's on-device Generative AI photo edits burn a visible "✦ Contenuti generati
+dall'AI" wordmark into the bottom-LEFT corner (the Italian locale variant calibrated
+here; the string is locale-specific). It is a faint, near-white semi-transparent
+overlay, the same overlay class as the Doubao/Jimeng marks but bottom-left.
 
-Like the Gemini sparkle and the Doubao / Jimeng marks 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 Samsung capture
-(see ``data/samsung_capture/``), bundled as ``assets/samsung_alpha.png`` -- the same
-careful build as Jimeng/Doubao (cubic-background fit, mean over channels, full halo
-extent, unblurred). The Samsung mark is faint (peak alpha ~0.38), so the glyph reads
-as a soft light-gray strip.
-
-The mark is anchored bottom-LEFT (Doubao/Jimeng are bottom-right) and scales with
-image WIDTH (~0.32 of width). The flat calibration captures arrive at the phone's
-flat-edit size (~1086 wide) while real photos are ~3000 wide, so a single alpha map
-cannot pixel-cancel the upscaled, per-image re-rasterized mark; removal therefore
-NCC-aligns the alpha to the actual mark (always), reverse-alphas, then clears the
-residual with a deliberately THIN inpaint over the glyph footprint -- the exact
-recipe Jimeng uses. Verified on the flat captures and a real ~2958-wide download.
-
-Detection (``detect``) matches the bundled glyph silhouette against the corner
-candidate via normalized correlation, keying on the actual mark shape rather than
-coverage heuristics. Samsung edits also carry C2PA + the Galaxy ``genAIType``
-marker (see ``metadata``/``identify``), so the visible path is the stripped-metadata
-fallback / the *removal* path, not a new ``identify`` signal.
-
-``locate`` (geometry box) and ``extract_mask`` (the candidate glyph mask the
-detector correlates) mirror the Doubao/Jimeng engines. Fast, offline, no GPU.
-Arbitrary-region inpainting still lives in ``region_eraser`` / the ``erase`` command.
+Removal is **reverse-alpha blending** against a captured alpha map
+(``original = (wm - a*logo)/(1-a)``), always NCC-aligned to the actual mark plus a thin
+residual inpaint over the glyph footprint. This is one of the three text-mark engines
+that share :class:`remove_ai_watermarks._text_mark_engine.TextMarkEngine`; this module
+supplies only Samsung's tuned :class:`TextMarkConfig` (bottom-LEFT corner, a lower glyph
+luma since the mark is faint, ``assets/samsung_alpha.png`` solved from the flat captures
+by ``scripts/visible_alpha_solve.py``). Samsung Galaxy AI edits are also caught by C2PA
++ the ``genAIType`` marker, so this is the visible-mark *removal* path; it also feeds
+``identify`` as the medium-confidence ``visible_samsung`` signal via the registry.
 """
+# The module-level _alpha_template / _glyph_silhouette / _template_match_score below
+# are thin test-facing shims (imported by tests/), so pyright's src-only pass sees them
+# as unused; the use is cross-module.
+# pyright: reportUnusedFunction=false
 
-# 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
+from remove_ai_watermarks import _text_mark_engine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
-logger = logging.getLogger(__name__)
-
-
-# Geometry as a fraction of image WIDTH. The Samsung mark scales with width and is
-# anchored bottom-LEFT. The box is intentionally generous (the glyph mask tightens
-# it and the alignment search refines position); values cover the 1086 flat captures
-# and the ~2958 real photos (both measured at width_frac ~0.31).
+# Locate geometry as a fraction of image WIDTH (mark scales with width, bottom-LEFT).
 WM_WIDTH_FRAC = 0.40
 WM_HEIGHT_FRAC = 0.060
 MARGIN_LEFT_FRAC = 0.004
 MARGIN_BOTTOM_FRAC = 0.002
 
-# Glyph appearance: a low-saturation light gray rendered brighter than the
-# surrounding content (white top-hat), same polarity logic as Doubao/Jimeng so a
-# white-paper document is left untouched. LOGO_MIN_LUMA is lower than Jimeng's
-# because the Samsung mark is fainter (peak alpha ~0.38), so on a mid/dark
-# background the glyph luma is lower; the top-hat + NCC shape gate keep precision.
-MAX_SATURATION = 55  # max channel spread to count a pixel as "grayish"
-LOGO_MIN_LUMA = 110  # glyphs are at least this bright in absolute terms
-TOPHAT_DELTA = 8  # glyph must exceed the local background by this many levels
+# Glyph appearance: a light, low-saturation gray. LOGO_MIN_LUMA is lower than Jimeng's
+# because the mark is faint (peak alpha ~0.38), so on a mid/dark background its glyph
+# luma is lower; a white-paper document is still left untouched.
+MAX_SATURATION = 55
+LOGO_MIN_LUMA = 110
+TOPHAT_DELTA = 8
 
-# Detection matches the bundled alpha-template glyph silhouette
-# (assets/samsung_alpha.png) against the candidate via zero-mean normalized
-# correlation (cv2 TM_CCOEFF_NORMED). A small coverage floor skips the template
-# match on a near-empty candidate box. The threshold is validated against the real
-# capture set and the other visible marks (Doubao/Jimeng/Gemini must not cross-fire).
+# Shape-consistent detection. Threshold 0.40; real marks ~0.79, and Doubao/Jimeng score
+# 0.0 here (and Samsung 0.0 on theirs) -- no cross-fire (the corner also differs).
 DETECT_MIN_COVERAGE = 0.01
 DETECT_NCC_THRESHOLD = 0.40
 
-# ── Reverse-alpha (recovery, Gemini/Doubao/Jimeng-style) ─────────────
-# The Samsung 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 it). The alpha map was solved from the GRAY capture by
-# scripts/visible_alpha_solve.py (cubic-background fit, mean over channels, full halo,
-# unblurred); the bundled asset (assets/samsung_alpha.png) is that template (a*255)
-# at the captured width. The mark scales with image WIDTH, and the flat captures are
-# ~2.7x smaller than real photos, so a pure width-scale is only approximate; removal
-# also registers the template to the actual mark via a TM_CCOEFF_NORMED scale+position
-# search (`_aligned_alpha_map`).
+# Reverse-alpha geometry, solved by scripts/visible_alpha_solve.py from the flat gray
+# capture (native width 1086). Real photos are ~2958 wide, so the captured glyph is
+# upscaled; width-scale + NCC-align removes it cleanly (a flat capture at the real
+# resolution would make the alpha pixel-sharp -- an open quality upgrade).
 _ALPHA_NATIVE_WIDTH = 1086
 _ALPHA_LOGO_BGR: tuple[float, float, float] = (255.0, 255.0, 255.0)
-# 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.3195  # asset width / image width -- the alignment scale seed
 _ALPHA_HEIGHT_FRAC = 0.0378
-# 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_LEFT_FRAC = 0.0110
 _ALPHA_MARGIN_BOTTOM_FRAC = 0.0064
-# Alignment scale search (np.linspace args) around the width-scaled glyph size --
-# wider than Jimeng's because the flat captures are far off the real-photo width, so
-# the per-image scale can drift more from the width-scaled seed.
+# Wider scale search: the flat capture is far off the real-photo width.
 _ALPHA_ALIGN_SEARCH = (0.85, 1.18, 23)
-# Residual inpaint footprint: a single capture upscaled to the real-photo width
-# cannot pixel-cancel the re-rasterized mark, so the glyph footprint (alpha above
-# this) is always inpainted after reverse-alpha (dilated by this kernel, INPAINT_NS).
-# Kept deliberately THIN -- reverse-alpha already recovers the true background under
-# the semi-transparent mark, so the inpaint only finishes the residual edges.
 _RESIDUAL_ALPHA_FLOOR = 0.05
 _RESIDUAL_DILATE = 5
 _RESIDUAL_INPAINT_RADIUS = 2
-_alpha_template_cache: NDArray[Any] | None = None
+
+_CONFIG = TextMarkConfig(
+    name="Samsung Galaxy AI",
+    asset_name="samsung_alpha.png",
+    corner="bl",
+    margin_floor=2,
+    width_frac=WM_WIDTH_FRAC,
+    height_frac=WM_HEIGHT_FRAC,
+    margin_x_frac=MARGIN_LEFT_FRAC,
+    margin_bottom_frac=MARGIN_BOTTOM_FRAC,
+    max_saturation=MAX_SATURATION,
+    logo_min_luma=LOGO_MIN_LUMA,
+    tophat_delta=TOPHAT_DELTA,
+    morph_open_size=3,
+    detect_min_coverage=DETECT_MIN_COVERAGE,
+    detect_ncc_threshold=DETECT_NCC_THRESHOLD,
+    alpha_width_frac=_ALPHA_WIDTH_FRAC,
+    alpha_height_frac=_ALPHA_HEIGHT_FRAC,
+    alpha_margin_x_frac=_ALPHA_MARGIN_LEFT_FRAC,
+    alpha_margin_bottom_frac=_ALPHA_MARGIN_BOTTOM_FRAC,
+    alpha_align_search=_ALPHA_ALIGN_SEARCH,
+    min_gw=16,
+    alpha_logo_bgr=_ALPHA_LOGO_BGR,
+    residual_alpha_floor=_RESIDUAL_ALPHA_FLOOR,
+    residual_dilate=_RESIDUAL_DILATE,
+    residual_inpaint_radius=_RESIDUAL_INPAINT_RADIUS,
+)
+
+SamsungDetection = TextMarkDetection
 
 
 def _alpha_template() -> NDArray[Any] | None:
-    """Lazily load the bundled Samsung 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" / "samsung_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 SamsungLocation:
-    """Located watermark box (bottom-left), 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 SamsungDetection:
-    """Result of visible Samsung Galaxy AI 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
+    """The bundled Samsung alpha template (float [0,1]), or None."""
+    return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
 def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary glyph silhouette (255 = glyph) from the bundled alpha map, used as the
-    detection template. None if the alpha asset is missing. The threshold is a
-    fraction of the (faint) peak alpha so the thin strokes survive."""
-    global _silhouette_cache
-    if _silhouette_cache is None:
-        at = _alpha_template()
-        if at is None:
-            return None
-        _silhouette_cache = (at > 0.10).astype(np.uint8) * 255
-    return _silhouette_cache
+    """Binary "Contenuti generati dall'AI" silhouette (255 = glyph), or None."""
+    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
 def _template_match_score(box_mask: NDArray[Any], image_width: int) -> float:
-    """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(16, int(_ALPHA_WIDTH_FRAC * image_width)))
-    gh = min(box_mask.shape[0] - 1, max(4, int(_ALPHA_HEIGHT_FRAC * image_width)))
-    if gw < 16 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())
+    """TM_CCOEFF_NORMED of the Samsung glyph silhouette against ``box_mask``."""
+    return _text_mark_engine.template_match_score(box_mask, image_width, _CONFIG)
 
 
-class SamsungEngine:
-    """Remove the visible Samsung Galaxy AI watermark (locate -> mask -> reverse-alpha)."""
+class SamsungEngine(TextMarkEngine):
+    """Remove the visible Samsung Galaxy AI text mark (locate -> mask -> reverse-alpha)."""
 
-    def __init__(
-        self,
-        *,
-        width_frac: float = WM_WIDTH_FRAC,
-        height_frac: float = WM_HEIGHT_FRAC,
-        margin_left_frac: float = MARGIN_LEFT_FRAC,
-        margin_bottom_frac: float = MARGIN_BOTTOM_FRAC,
-    ) -> None:
-        self.width_frac = width_frac
-        self.height_frac = height_frac
-        self.margin_left_frac = margin_left_frac
-        self.margin_bottom_frac = margin_bottom_frac
-
-    # ── Locate ────────────────────────────────────────────────────────
-
-    def locate(self, image: NDArray[Any]) -> SamsungLocation:
-        """Anchor the watermark box in the bottom-left 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_l = max(2, int(w * self.margin_left_frac))
-        margin_b = max(2, int(w * self.margin_bottom_frac))
-        x = min(margin_l, max(0, w - wm_w))
-        y = max(0, h - margin_b - wm_h)
-        wm_w = min(wm_w, w - x)
-        wm_h = min(wm_h, h - y)
-        return SamsungLocation(x=x, y=y, w=wm_w, h=wm_h, is_fallback=True)
-
-    # ── Mask ──────────────────────────────────────────────────────────
-
-    def extract_mask(self, image: NDArray[Any], loc: SamsungLocation) -> 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 (mirrors the Doubao/Jimeng
-        # guard). 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((3, 3), 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]) -> SamsungDetection:
-        """Detect the visible Samsung mark by matching the alpha-template glyph
-        silhouette against the corner candidate (TM_CCOEFF_NORMED)."""
-        det = SamsungDetection()
-        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("Samsung 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 (bottom-left)."""
-        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 = min(max(0, int(_ALPHA_MARGIN_LEFT_FRAC * w)), max(0, 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 < 16 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 -- the flat capture is far off the real-photo width and the mark
-        re-rasterizes per image, so fixed geometry alone is not reliable. A single
-        capture cannot pixel-cancel the upscaled mark, so a deliberately THIN residual
-        inpaint (``_RESIDUAL_*``) follows. 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; skip cv2 entirely (mirrors Jimeng).
-        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
+    def __init__(self) -> None:
+        super().__init__(_CONFIG)

src/remove_ai_watermarks/trustmark_detector.py

@@ -40,9 +40,9 @@ _tm_lock = threading.Lock()
 
 def is_available() -> bool:
     """True if the optional ``trustmark`` package is installed."""
-    import importlib.util
+    from .optional_deps import module_available
 
-    return importlib.util.find_spec("trustmark") is not None
+    return module_available("trustmark")
 
 
 def _decoder() -> Any:

src/remove_ai_watermarks/upscaler.py

@@ -8,8 +8,8 @@ The DEFAULT upscaler stays Lanczos (cv2, no deps); this is opt-in via the ``esrg
 extra and feeds the ``--upscaler esrgan`` path. ``spandrel`` is a pure model-loader
 (MIT) with NO basicsr dependency -- it pulls only torch/torchvision/safetensors/numpy/
 einops -- so it sidesteps the basicsr / ``torchvision.transforms.functional_tensor``
-breakage that the ``restore`` (GFPGAN) extra has to shim. Real-ESRGAN weights are
-BSD-3-Clause.
+breakage that the retired ``restore`` (GFPGAN) extra had to shim. Real-ESRGAN weights
+are BSD-3-Clause.
 
 CPU works but is slow on large inputs, so this is meant for the pre-diffusion upscale of
 SMALL inputs (and the GPU worker). On a memory-constrained host it is a no-op (the extra
@@ -21,7 +21,6 @@ is absent), and the caller falls back to Lanczos.
 # pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false, reportAttributeAccessIssue=false, reportPrivateImportUsage=false
 from __future__ import annotations
 
-import importlib.util
 import logging
 import threading
 from pathlib import Path
@@ -45,7 +44,9 @@ _lock = threading.Lock()
 
 def is_available() -> bool:
     """True if the ``esrgan`` extra (spandrel + torch) is importable."""
-    return importlib.util.find_spec("spandrel") is not None and importlib.util.find_spec("torch") is not None
+    from .optional_deps import module_available
+
+    return module_available("spandrel", "torch")
 
 
 def _model_cache_path() -> Path:

src/remove_ai_watermarks/watermark_registry.py

@@ -159,71 +159,45 @@ def _gemini_remove(
     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)
+# The three text-mark engines (Doubao/Jimeng/Samsung) share the TextMarkEngine
+# interface, so one parameterized adapter pair drives all of them -- a new
+# reverse-alpha text mark is one `_text_mark(...)` row below, not another copy-paste
+# of these bodies. Removal is reverse-alpha only: applied when the mark is detected
+# (or forced) and the alpha asset loads, otherwise skipped (no hallucination on a
+# clean corner).
+def _text_mark_detect(key: str, label: str, location: str) -> Callable[[NDArray[Any]], MarkDetection]:
+    def detect(image: NDArray[Any]) -> MarkDetection:
+        d = _engine(key).detect(image)
+        return MarkDetection(key, label, location, d.detected, d.confidence, d.region)
+
+    return detect
 
 
-def _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 _text_mark_remove(key: str) -> Callable[..., tuple[NDArray[Any], Region | None]]:
+    def remove(
+        image: NDArray[Any], _inpaint_method: InpaintMethod, _inpaint: bool, _strength: float, force: bool
+    ) -> tuple[NDArray[Any], Region | None]:
+        engine = _engine(key)
+        det = engine.detect(image)
+        if (det.detected or force) and engine.reverse_alpha_available(image):
+            return engine.remove_watermark_reverse_alpha(image), (det.region if det.detected else None)
+        return image.copy(), None
+
+    return remove
 
 
-def _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
-
-
-def _samsung_detect(image: NDArray[Any]) -> MarkDetection:
-    d = _engine("samsung").detect(image)
-    return MarkDetection("samsung", "Samsung Galaxy AI text", "bottom-left", d.detected, d.confidence, d.region)
-
-
-def _samsung_remove(
-    image: NDArray[Any], _inpaint_method: InpaintMethod, _inpaint: bool, _strength: float, force: bool
-) -> tuple[NDArray[Any], Region | None]:
-    # Reverse-alpha (with an always-on thin 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("samsung")
-    det = engine.detect(image)
-    if (det.detected or force) and engine.reverse_alpha_available(image):
-        return engine.remove_watermark_reverse_alpha(image), (det.region if det.detected else None)
-    return image.copy(), None
+def _text_mark(key: str, label: str, location: str) -> KnownMark:
+    """A reverse-alpha text-mark registry row (Doubao/Jimeng/Samsung)."""
+    return KnownMark(
+        key, label, location, True, "reverse-alpha", _text_mark_detect(key, label, location), _text_mark_remove(key)
+    )
 
 
 _REGISTRY: tuple[KnownMark, ...] = (
     KnownMark("gemini", "Google Gemini sparkle", "bottom-right", True, "reverse-alpha", _gemini_detect, _gemini_remove),
-    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
-    ),
-    KnownMark(
-        "samsung", "Samsung Galaxy AI text", "bottom-left", True, "reverse-alpha", _samsung_detect, _samsung_remove
-    ),
+    _text_mark("doubao", "Doubao 豆包AI生成 text", "bottom-right"),
+    _text_mark("jimeng", "Jimeng 即梦AI wordmark", "bottom-right"),
+    _text_mark("samsung", "Samsung Galaxy AI text", "bottom-left"),
 )
 
 

tests/test_auto_config.py

@@ -1,117 +0,0 @@
-"""Tests for the --auto pipeline planner (content-adaptive mode selection).
-
-Detection runs on synthetic images; the face-present routing is exercised by
-monkeypatching ``detect_face`` (a real detectable face fixture is private, never
-committed). The planner is cv2-only and torch-free.
-"""
-
-from __future__ import annotations
-
-import cv2
-import numpy as np
-
-from remove_ai_watermarks import auto_config, image_io
-
-
-def _write(img, tmp_path, name="x.png"):
-    p = tmp_path / name
-    image_io.imwrite(p, img)
-    return p
-
-
-class TestDetectors:
-    def test_detect_face_false_on_flat(self):
-        flat = np.full((200, 200, 3), 128, dtype=np.uint8)
-        assert auto_config.detect_face(flat) is False
-
-    def test_edge_density_flat_near_zero(self):
-        flat = np.full((200, 200, 3), 128, dtype=np.uint8)
-        assert auto_config.edge_density(flat) < 0.001
-
-    def test_edge_density_text_higher_than_blank(self):
-        blank = np.full((200, 400, 3), 255, dtype=np.uint8)
-        text = blank.copy()
-        cv2.putText(text, "HELLO AI TEXT", (10, 120), cv2.FONT_HERSHEY_SIMPLEX, 2.0, (0, 0, 0), 3)
-        assert auto_config.edge_density(text) > auto_config.edge_density(blank)
-
-    def test_dbnet_detects_text_card(self):
-        """The bundled PP-OCRv3 DBNet model fires on a clear text card and not on flat."""
-        card = np.full((300, 500, 3), 255, dtype=np.uint8)
-        cv2.putText(card, "INVOICE TOTAL 1234", (10, 170), cv2.FONT_HERSHEY_SIMPLEX, 2.0, (0, 0, 0), 4)
-        assert auto_config._detect_text_dbnet(card) is True
-        assert auto_config._detect_text_dbnet(np.full((300, 500, 3), 128, dtype=np.uint8)) is False
-
-    def test_detect_text_falls_back_to_mser_when_dbnet_unavailable(self, monkeypatch):
-        """If DBNet can't load (returns None), detect_text uses the MSER heuristic."""
-        monkeypatch.setattr(auto_config, "_detect_text_dbnet", lambda _img: None)
-        called = {}
-
-        def _fake_mser(_img):
-            called["mser"] = True
-            return True
-
-        monkeypatch.setattr(auto_config, "_detect_text_mser", _fake_mser)
-        assert auto_config.detect_text(np.full((100, 100, 3), 128, dtype=np.uint8)) is True
-        assert called.get("mser") is True
-
-
-class TestPlan:
-    def test_unreadable_returns_none(self, tmp_path):
-        assert auto_config.plan(tmp_path / "does_not_exist.png") is None
-
-    def test_flat_image_is_default_pipeline_no_polish(self, tmp_path):
-        flat = np.full((300, 300, 3), 128, dtype=np.uint8)
-        cfg = auto_config.plan(_write(flat, tmp_path))
-        assert cfg is not None
-        assert cfg.pipeline == "default"  # structure-less -> plain SDXL
-        assert cfg.adaptive_polish is False  # no smoothing pass -> no polish
-        assert cfg.unsharp == 0.0
-        assert cfg.humanize == 0.0
-        assert cfg.min_resolution == 1024
-
-    def test_text_image_uses_controlnet(self, tmp_path):
-        img = np.full((300, 500, 3), 255, dtype=np.uint8)
-        cv2.putText(img, "INVOICE TOTAL 1234", (10, 170), cv2.FONT_HERSHEY_SIMPLEX, 2.0, (0, 0, 0), 4)
-        cfg = auto_config.plan(_write(img, tmp_path))
-        assert cfg is not None
-        # Text creates edges above the structure-less floor -> controlnet preserves them.
-        assert cfg.pipeline == "controlnet"
-
-    def test_face_routes_to_controlnet_and_polish(self, tmp_path, monkeypatch):
-        monkeypatch.setattr(auto_config, "detect_face", lambda _img: True)
-        flat = np.full((300, 300, 3), 128, dtype=np.uint8)
-        cfg = auto_config.plan(_write(flat, tmp_path))
-        assert cfg is not None
-        assert cfg.has_face
-        assert cfg.pipeline == "controlnet"
-        assert cfg.adaptive_polish  # smoothing pass ran -> adaptive polish on
-        assert cfg.unsharp == 0.0  # fixed knobs off; the adaptive polish replaces them
-        assert cfg.humanize == 0.0
-
-    def test_text_signal_forces_controlnet_on_flat(self, tmp_path, monkeypatch):
-        monkeypatch.setattr(auto_config, "detect_text", lambda _img: True)
-        flat = np.full((300, 300, 3), 128, dtype=np.uint8)
-        cfg = auto_config.plan(_write(flat, tmp_path))
-        assert cfg is not None
-        assert cfg.has_text
-        assert cfg.pipeline == "controlnet"
-
-
-class TestReason:
-    def test_reason_summarizes_plan(self):
-        cfg = auto_config.AutoConfig(
-            pipeline="controlnet",
-            adaptive_polish=True,
-            unsharp=0.0,
-            humanize=0.0,
-            min_resolution=1024,
-            has_face=True,
-            has_text=False,
-            edge_density=0.05,
-            width=800,
-            height=600,
-        )
-        r = cfg.reason
-        assert "controlnet" in r
-        assert "face" in r
-        assert "adaptive polish" in r

tests/test_cli.py

@@ -125,6 +125,32 @@ class TestVisibleCommand:
         assert "visible AI watermark" in result.output
         assert "--mark" in result.output
 
+    def test_visible_auto_no_mark_exits_two_with_eraser_hint(self, runner, sample_png, tmp_path):
+        # No known visible mark and no AI provenance signal: the command must not
+        # re-serve the input as a finished result. It exits EXIT_NO_VISIBLE_MARK
+        # (2) -- distinct from success (0) and a hard error (1) -- writes no
+        # output file, and points the user at the region eraser.
+        output = tmp_path / "clean.png"
+        result = runner.invoke(main, ["visible", str(sample_png), "-o", str(output)])
+        assert result.exit_code == 2, result.output
+        assert not output.exists()
+        assert "erase" in result.output
+
+    def test_visible_auto_no_mark_routes_to_all_when_metadata(self, runner, tmp_path):
+        # An image whose only signal is an invisible/metadata watermark (here SD
+        # generation parameters) has no visible mark to remove; the command must
+        # exit 2 and upsell the full 'all' pipeline rather than the eraser.
+        img = Image.fromarray(np.random.default_rng(0).integers(0, 255, (200, 200, 3), dtype=np.uint8))
+        pnginfo = PngInfo()
+        pnginfo.add_text("parameters", "Steps: 20, Sampler: Euler, a test landscape")
+        src = tmp_path / "ai.png"
+        img.save(src, pnginfo=pnginfo)
+        output = tmp_path / "clean.png"
+        result = runner.invoke(main, ["visible", str(src), "-o", str(output)])
+        assert result.exit_code == 2, result.output
+        assert not output.exists()
+        assert "all" in result.output
+
     def test_visible_basic(self, runner, sample_png, tmp_path):
         output = tmp_path / "clean.png"
         result = runner.invoke(
@@ -277,6 +303,72 @@ class TestInvisibleCommand:
         expected = sample_png.with_stem(sample_png.stem + "_clean")
         assert expected.exists()
 
+    def test_invisible_adaptive_polish_on_by_default(self, runner, sample_png):
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png)])
+        assert result.exit_code == 0, result.output
+        # adaptive_polish is ON by default (self-gating, so a no-op where not needed).
+        assert mock_engine.remove_watermark.call_args.kwargs["adaptive_polish"] is True
+        # Default model is None (the SDXL base) and CFG is None (the library's 7.5).
+        assert mock_cls.call_args.kwargs["model_id"] is None
+        assert mock_engine.remove_watermark.call_args.kwargs["guidance_scale"] is None
+
+    def test_invisible_no_adaptive_polish_disables(self, runner, sample_png):
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png), "--no-adaptive-polish"])
+        assert result.exit_code == 0, result.output
+        assert mock_engine.remove_watermark.call_args.kwargs["adaptive_polish"] is False
+
+    def test_invisible_model_and_guidance_scale_flow_to_engine(self, runner, sample_png):
+        mock_cls, mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(
+                main,
+                ["invisible", str(sample_png), "--model", "org/custom-sdxl", "--guidance-scale", "5.5"],
+            )
+        assert result.exit_code == 0, result.output
+        assert mock_cls.call_args.kwargs["model_id"] == "org/custom-sdxl"
+        assert mock_engine.remove_watermark.call_args.kwargs["guidance_scale"] == 5.5
+
+    def test_pipeline_default_alias_warns_and_maps_to_sdxl(self, runner, sample_png):
+        mock_cls, _mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png), "--pipeline", "default"])
+        assert result.exit_code == 0, result.output
+        # The legacy value warns and is normalized to "sdxl" before the engine is built.
+        assert "deprecated" in result.output.lower()
+        assert mock_cls.call_args.kwargs["pipeline"] == "sdxl"
+
+    def test_pipeline_sdxl_does_not_warn(self, runner, sample_png):
+        mock_cls, _mock_engine = _mock_invisible_engine()
+        with (
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+        ):
+            result = runner.invoke(main, ["invisible", str(sample_png), "--pipeline", "sdxl"])
+        assert result.exit_code == 0, result.output
+        assert "deprecated" not in result.output.lower()
+        assert mock_cls.call_args.kwargs["pipeline"] == "sdxl"
+
     def test_invisible_nonexistent_file(self, runner):
         result = runner.invoke(main, ["invisible", "/nonexistent/file.png"])
         assert result.exit_code != 0
@@ -296,6 +388,7 @@ class TestAllCommand:
         with (
             patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
             patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
         ):
             result = runner.invoke(
                 main,
@@ -308,6 +401,35 @@ class TestAllCommand:
         result = runner.invoke(main, ["all", "/nonexistent/file.png"])
         assert result.exit_code != 0
 
+    def test_all_visible_step_uses_registry(self, runner, sample_png, tmp_path):
+        """Regression (#1): the `all` visible step must route through the registry
+        (best_auto_mark), so Doubao/Jimeng/Samsung text marks are handled -- not just
+        the Gemini sparkle via a hardcoded GeminiEngine."""
+        mock_cls, _mock_engine = _mock_invisible_engine()
+        output = tmp_path / "clean.png"
+        with (
+            patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
+            patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
+            patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
+            patch("remove_ai_watermarks.watermark_registry.best_auto_mark", return_value=None) as mock_best,
+        ):
+            result = runner.invoke(main, ["all", str(sample_png), "-o", str(output)])
+        assert result.exit_code == 0, result.output
+        mock_best.assert_called()  # the registry auto-detector drove the visible pass
+
+    def test_all_loud_warning_and_nonzero_exit_when_gpu_missing(self, runner, sample_png, tmp_path):
+        """Regression (#14/#47): when the GPU extra is absent the invisible step is
+        skipped, but the output still looks processed -- the run must fail loudly
+        (prominent banner + non-zero exit) so a skipped SynthID pass is not mistaken
+        for a clean result. The output file is still written (visible + metadata)."""
+        output = tmp_path / "clean.png"
+        with patch("remove_ai_watermarks.invisible_engine.is_available", return_value=False):
+            result = runner.invoke(main, ["all", str(sample_png), "-o", str(output)])
+        assert result.exit_code != 0, result.output
+        assert "NOT removed" in result.output
+        assert "remove-ai-watermarks[gpu]" in result.output
+        assert output.exists()  # visible + metadata still produced a file
+
     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).
@@ -514,32 +636,17 @@ class TestBatchCommand:
         assert out[0, 0, 3] == 0
         assert out[100, 100, 3] == 255
 
-    def test_batch_auto_plans_pipeline_per_image(self, runner, tmp_path):
-        """--auto in batch re-plans the pipeline/restore/polish per image and
-        builds one engine per resolved pipeline."""
-        from remove_ai_watermarks import auto_config
-
+    def test_batch_auto_is_deprecated_and_enables_polish(self, runner, tmp_path):
+        """--auto is retired: it warns and just enables the adaptive polish (the
+        pipeline is always the default controlnet now)."""
         input_dir = _make_batch_dir(tmp_path, count=2)
         output_dir = tmp_path / "output"
-        plan = auto_config.AutoConfig(
-            pipeline="controlnet",
-            adaptive_polish=True,
-            unsharp=0.0,
-            humanize=0.0,
-            min_resolution=1024,
-            has_face=True,
-            has_text=False,
-            edge_density=0.05,
-            width=200,
-            height=200,
-        )
         mock_cls, mock_engine = _mock_invisible_engine()
         with (
             patch("remove_ai_watermarks.cli.InvisibleEngine", mock_cls, create=True),
             patch("remove_ai_watermarks.invisible_engine.InvisibleEngine", mock_cls),
             patch("remove_ai_watermarks.cli.invisible_available", return_value=True, create=True),
             patch("remove_ai_watermarks.invisible_engine.is_available", return_value=True),
-            patch("remove_ai_watermarks.auto_config.plan", return_value=plan),
         ):
             result = runner.invoke(
                 main,
@@ -547,9 +654,9 @@ class TestBatchCommand:
             )
         assert result.exit_code == 0, result.output
         assert "2 processed" in result.output
-        # Engine built with the auto-resolved controlnet pipeline.
+        assert "deprecated" in result.output.lower()
+        # Pipeline stays the default controlnet; --auto only turned the polish on.
         assert mock_cls.call_args.kwargs["pipeline"] == "controlnet"
-        # The auto plan's adaptive polish reached the engine call.
         assert mock_engine.remove_watermark.call_args.kwargs["adaptive_polish"] is True
 
     def test_batch_default_output_dir(self, runner, tmp_path):

tests/test_gemini_engine.py

@@ -124,6 +124,19 @@ class TestGeminiEngine:
         result = self.engine.remove_watermark_custom(image, (10, 10, 48, 48))
         assert result.shape == image.shape
 
+    def test_detect_on_grayscale_does_not_crash(self):
+        # A 2D grayscale array reaching detect_watermark (registry adapter / library
+        # API) must not crash the FP-gate's axis=2 reduction; it is normalized to BGR.
+        gray = np.full((300, 300), 100, dtype=np.uint8)
+        result = self.engine.detect_watermark(gray)
+        assert result is not None
+
+    def test_remove_on_bgra_returns_3_channel(self):
+        bgra = np.zeros((300, 300, 4), dtype=np.uint8)
+        bgra[..., 3] = 255
+        result = self.engine.remove_watermark(bgra)
+        assert result.shape == (300, 300, 3)
+
     def test_remove_watermark_custom_large_region(self, tmp_image_path):
         image = cv2.imread(str(tmp_image_path), cv2.IMREAD_COLOR)
         result = self.engine.remove_watermark_custom(image, (10, 10, 96, 96))
@@ -526,20 +539,72 @@ class TestCornerPromotion:
         assert abs(det.region[0] - self._CORNER[0]) < 16
         assert abs(det.region[1] - self._CORNER[1]) < 16
 
-    def test_promotion_is_what_rescues_it(self, monkeypatch):
-        """Guard the mechanism: disabling the override mislocalizes to the decoy.
+    def test_size_weighted_search_alone_traps_on_the_decoy(self):
+        """Guard the mechanism: the size-weighted argmax ALONE mislocalizes to the decoy.
 
-        Proves the scene genuinely needs the override (so the localization test above
-        is not a fluke): with the gate set unreachable the larger decoy wins.
+        Proves the scene genuinely needs the dual-candidate fusion selection (so the
+        localization test above is not a fluke): replicating the old size-weighted-only
+        pick lands on the larger left-side decoy, while ``detect_watermark`` -- which
+        scores all top-K candidates by full fusion -- lands on the corner sparkle.
         """
         scene = self._scene()
+        h, w = scene.shape[:2]
+        ss = min(min(w, h), 512)
+        sx1, sy1 = max(0, w - ss), max(0, h - ss)
+        gray = cv2.cvtColor(scene[sy1:h, sx1:w], cv2.COLOR_BGR2GRAY).astype(np.float32) / 255.0
+        best = (-1.0, (0, 0))
+        for scale, max_val, max_loc in self.engine._scan_scales(gray):
+            adj = max_val * min(1.0, (scale / 96.0) ** 0.5)
+            if adj > best[0]:
+                best = (adj, max_loc)
+        weighted_region = (sx1 + best[1][0], sy1 + best[1][1])
+        assert not self._in_bottom_right((*weighted_region, 0, 0)), "size-weighted argmax expected to hit the decoy"
+        # The full detector, scoring both candidates by fusion, rescues the corner.
         assert self._in_bottom_right(self.engine.detect_watermark(scene).region)
-        monkeypatch.setattr(GeminiEngine, "_CORNER_PROMOTE_NCC", 2.0)
-        assert not self._in_bottom_right(self.engine.detect_watermark(scene).region), (
-            "decoy expected to win without the override"
-        )
 
     def test_no_promotion_on_clean_flat_image(self):
         """A flat image with no sparkle yields no corner match to promote."""
         flat = np.full((self._H, self._W, 3), 40, dtype=np.uint8)
         assert self.engine._corner_promote(flat, -1.0) is None
+
+    def test_low_gradient_decoy_loses_to_high_gradient_corner_sparkle(self, monkeypatch):
+        """Regression (reporter 2026-06-12, v0.7.2 detected / v0.8-0.11 missed): the
+        256->512 search widening let a large, low-gradient size-weighted match outrank
+        a smaller, high-gradient corner sparkle whose raw NCC (~0.77) sits BELOW the
+        0.85 corner-promote gate -- so a real Gemini sparkle on light bedding read as
+        clean. The detector now scores all top-K candidates by full fusion and keeps
+        the highest; the gradient term (~0.04 on flat content vs ~1.0 on a true
+        sparkle) rescues the corner. Mirrors the real signature:
+        decoy spatial 0.63 / grad 0.04 vs corner spatial 0.78 / grad 0.96.
+        """
+        eng = self.engine
+        size = 500
+        img = np.full((size, size, 3), 225, dtype=np.float32)
+        # Low-gradient smooth bright blob = a content false match the size weight favors.
+        blob = np.zeros((size, size), np.float32)
+        cv2.circle(blob, (89, 89), 60, 1.0, -1)
+        blob = cv2.GaussianBlur(blob, (0, 0), 30)
+        img += (blob * 25)[:, :, None]
+        # A real, high-gradient sparkle in the bottom-right corner.
+        cx, cy, cs = 430, 430, 48
+        tmpl = cv2.resize(eng._alpha_large, (cs, cs), interpolation=cv2.INTER_AREA)
+        a = (tmpl * 0.6)[:, :, None]
+        img[cy : cy + cs, cx : cx + cs] = a * 255.0 + (1.0 - a) * img[cy : cy + cs, cx : cx + cs]
+        img = np.clip(img, 0, 255).astype(np.uint8)
+        dx, dy, ds = 40, 40, 98
+
+        # The two locations carry the real-signature gradient split.
+        assert eng._grad_var_scores(img, ds, dx, dy)[0] < 0.1  # decoy: shape-only, ~0.04
+        assert eng._grad_var_scores(img, cs, cx, cy)[0] > 0.8  # corner sparkle: ~1.0
+
+        def fake_scan(_self, _gray):
+            yield ds, 0.66, (dx, dy)  # large, low-fidelity: size-weighted adj 0.66 -> winner
+            yield cs, 0.80, (cx, cy)  # small sparkle: raw 0.80 but adj 0.57 -> size-weight loses
+
+        monkeypatch.setattr(GeminiEngine, "_scan_scales", fake_scan)
+        det = eng.detect_watermark(img)
+        # Full-fusion selection keeps the high-gradient corner sparkle, not the decoy.
+        assert det.detected
+        assert det.confidence >= 0.5
+        assert abs(det.region[0] - cx) < 4, f"localized to decoy: {det.region}"
+        assert abs(det.region[1] - cy) < 4, f"localized to decoy: {det.region}"

tests/test_identify.py

@@ -772,6 +772,31 @@ class TestIntegrityClashesHelper:
         # must NOT raise a clash.
         assert _integrity_clashes({}, "Leica (camera, C2PA capture)", camera_has_ai_marker=False) == []
 
+    def test_pixel_generative_edit_same_manifest_no_clash(self):
+        # A Google Pixel that BOTH captures and runs on-device generative AI
+        # (Magic Editor / Pixel Studio) records the capture and the AI edit in
+        # ONE C2PA manifest -- the AI vendor is named only from that same
+        # manifest (c2pa / synthid), independent of nothing. That is a legitimate
+        # edit chain, NOT a camera-vs-AI contradiction, so rule 2 must stay quiet.
+        assert (
+            _integrity_clashes(
+                {"c2pa": "Google", "synthid": "Google"},
+                "Google Pixel (camera, C2PA capture)",
+                camera_has_ai_marker=True,
+            )
+            == []
+        )
+
+    def test_camera_plus_independent_ai_marker_still_clashes(self):
+        # But a camera capture next to an AI marker from a genuinely INDEPENDENT
+        # source (EXIF/XMP generator, TC260 AIGC, ...) is still a laundering tell.
+        clashes = _integrity_clashes(
+            {"c2pa": "Google", "aigc": "China AIGC (TC260)"},
+            "Google Pixel (camera, C2PA capture)",
+            camera_has_ai_marker=True,
+        )
+        assert any("Camera-capture" in c for c in clashes)
+
 
 class TestIntegrityClashEndToEnd:
     def _c2pa_jpeg(self, tmp_path: Path, blob: bytes) -> Path:
@@ -806,6 +831,22 @@ class TestIntegrityClashEndToEnd:
         assert r.platform == "Google Pixel (camera, C2PA capture)"
         assert any("Camera-capture C2PA credentials" in c and "AI-generation markers" in c for c in r.integrity_clashes)
 
+    def test_pixel_generative_edit_no_clash(self, tmp_path: Path):
+        # A real Google Pixel generative edit (Magic Editor / Pixel Studio) signs
+        # ONE manifest carrying both the Pixel Camera capture and a Google
+        # Generative AI edit (trainedAlgorithmicMedia + "Applied imperceptible
+        # SynthID watermark"). The AI marker lives in the SAME manifest as the
+        # device, so it is an edit chain, not a camera-vs-AI contradiction.
+        path = self._c2pa_jpeg(
+            tmp_path,
+            b"Pixel Camera ... Created by Pixel Camera ... computationalCapture ... "
+            b"Created by Google Generative AI ... trainedAlgorithmicMedia ... "
+            b"Applied imperceptible SynthID watermark",
+        )
+        r = identify(path, check_visible=False, check_invisible=False)
+        assert r.is_ai_generated is True
+        assert r.integrity_clashes == []
+
     def test_clash_serializes_to_json(self, tmp_path: Path):
         path = self._c2pa_jpeg(tmp_path, b"OpenAI ... trainedAlgorithmicMedia ... TC260:AIGC label")
         r = identify(path, check_visible=False, check_invisible=False)

tests/test_image_io.py

@@ -59,6 +59,32 @@ class TestUnicodeRoundTrip:
         assert np.array_equal(out, src)
 
 
+class TestToBgr:
+    def test_grayscale_2d_promoted_to_bgr(self) -> None:
+        gray = np.full((4, 5), 120, dtype=np.uint8)
+        out = image_io.to_bgr(gray)
+        assert out.shape == (4, 5, 3)
+        # GRAY2BGR replicates the channel, so all three match the source.
+        assert np.array_equal(out[..., 0], gray)
+        assert np.array_equal(out[..., 0], out[..., 2])
+
+    def test_single_channel_3d_promoted(self) -> None:
+        gray = np.full((4, 5, 1), 7, dtype=np.uint8)
+        assert image_io.to_bgr(gray).shape == (4, 5, 3)
+
+    def test_bgra_dropped_to_bgr(self) -> None:
+        bgra = np.zeros((4, 5, 4), dtype=np.uint8)
+        bgra[..., :3] = (10, 120, 240)
+        out = image_io.to_bgr(bgra)
+        assert out.shape == (4, 5, 3)
+        assert np.array_equal(out, bgra[..., :3])
+
+    def test_bgr_returned_unchanged(self) -> None:
+        bgr = _make_bgr()
+        out = image_io.to_bgr(bgr)
+        assert out is bgr  # 3-channel: no copy
+
+
 class TestFailureSemantics:
     def test_missing_file_returns_none(self, tmp_path: Path) -> None:
         assert image_io.imread(tmp_path / "does-not-exist-不存在.png") is None

tests/test_metadata.py

@@ -790,6 +790,42 @@ class TestAIGCLabel:
     def test_has_ai_metadata_detects_raw_json_exif_form(self, tmp_path: Path):
         assert has_ai_metadata(self._aigc_exif_jpeg(tmp_path))
 
+    def _aigc_bare_jpeg(self, tmp_path: Path, producer: str = "00119144030008867405X210002") -> Path:
+        """Some China-served generators glue the TC260 label straight to its JSON
+        as a bare ``AIGC{...}`` blob inside a JPEG APP segment (no ``"AIGC":``
+        key wrapper, no PNG chunk, no namespaced XMP) -- seen near the JFIF
+        header on real 2026-06 downloads."""
+        p = tmp_path / "aigc_bare.jpg"
+        Image.new("RGB", (32, 32)).save(p)
+        raw = p.read_bytes()
+        blob = b'AIGC{"Label":"1","ContentProducer":"' + producer.encode() + b'","ProduceID":"8F995586"}'
+        segment = b"\xff\xe9" + (len(blob) + 2).to_bytes(2, "big") + blob  # APP9
+        p.write_bytes(raw[:2] + segment + raw[2:])  # splice after SOI
+        return p
+
+    def test_parses_bare_aigc_jpeg_segment_form(self, tmp_path: Path):
+        from remove_ai_watermarks.metadata import aigc_label
+
+        info = aigc_label(self._aigc_bare_jpeg(tmp_path))
+        assert info is not None
+        assert info["Label"] == "1"
+        assert info["ContentProducer"] == "00119144030008867405X210002"
+
+    def test_has_ai_metadata_detects_bare_aigc_jpeg_form(self, tmp_path: Path):
+        assert has_ai_metadata(self._aigc_bare_jpeg(tmp_path))
+
+    def test_bare_aigc_without_tc260_field_ignored(self, tmp_path: Path):
+        """A bare ``AIGC{...}`` blob with no TC260 field must not false-positive."""
+        from remove_ai_watermarks.metadata import aigc_label
+
+        p = tmp_path / "bare_unrelated.jpg"
+        Image.new("RGB", (32, 32)).save(p)
+        raw = p.read_bytes()
+        blob = b'AIGC{"unrelated":"value"}'
+        segment = b"\xff\xe9" + (len(blob) + 2).to_bytes(2, "big") + blob
+        p.write_bytes(raw[:2] + segment + raw[2:])
+        assert aigc_label(p) is None
+
     def test_raw_json_without_tc260_field_ignored(self, tmp_path: Path):
         """A bare ``{"AIGC":{...}}`` object with no TC260 field must not fire."""
         import json
@@ -1185,3 +1221,49 @@ class TestFfmpegMetadataStrip:
         remove_ai_metadata(src, out)
         assert out.exists()
         assert b"Suno AI generated" not in out.read_bytes()  # tag stripped, audio kept
+
+
+class TestC2paCloudManifest:
+    """C2PA 2.4 Durable Content Credentials: an XMP dcterms:provenance pointer to
+    a vendor cloud manifest store survives when the embedded manifest is stripped."""
+
+    def _cloud_png(self, tmp_path: Path, host: bytes = b"cai-manifests.adobe.com") -> Path:
+        xmp = (
+            b'<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?><x:xmpmeta xmlns:x="adobe:ns:meta/">'
+            b'<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">'
+            b'<rdf:Description rdf:about="" xmlns:dcterms="http://purl.org/dc/terms/" '
+            b'dcterms:provenance="https://' + host + b'/manifests/urn-c2pa-abc123"> </rdf:Description>'
+            b'</rdf:RDF></x:xmpmeta><?xpacket end="w"?>'
+        )
+        p = tmp_path / "cloud.png"
+        img = Image.new("RGB", (16, 16))
+        meta = PngInfo()
+        meta.add_itxt("XML:com.adobe.xmp", xmp.decode("latin-1"))
+        img.save(p, pnginfo=meta)
+        return p
+
+    def test_detects_adobe_cloud_manifest(self, tmp_path: Path):
+        from remove_ai_watermarks.metadata import c2pa_cloud_manifest
+
+        assert c2pa_cloud_manifest(self._cloud_png(tmp_path)) == "Adobe Content Authenticity"
+
+    def test_no_provenance_pointer_is_none(self, tmp_clean_png: Path):
+        from remove_ai_watermarks.metadata import c2pa_cloud_manifest
+
+        assert c2pa_cloud_manifest(tmp_clean_png) is None
+
+    def test_unknown_host_is_none(self, tmp_path: Path):
+        from remove_ai_watermarks.metadata import c2pa_cloud_manifest
+
+        # A dcterms:provenance pointer to an unrecognized host is not attributed.
+        assert c2pa_cloud_manifest(self._cloud_png(tmp_path, host=b"manifests.example.com")) is None
+
+    def test_cloud_manifest_does_not_assert_ai(self, tmp_path: Path):
+        # Provenance only -- a cloud manifest can describe a human edit, so the
+        # verdict must stay 'unknown', not 'AI-generated'.
+        from remove_ai_watermarks.identify import identify
+
+        r = identify(self._cloud_png(tmp_path), check_visible=False, check_invisible=False)
+        assert r.is_ai_generated is None
+        assert any("Durable Content Credentials" in w for w in r.watermarks)
+        assert any(s.name == "c2pa_cloud" for s in r.signals)

tests/test_optional_deps.py

@@ -0,0 +1,58 @@
+"""Tests for the shared optional-dependency availability guard."""
+
+from __future__ import annotations
+
+import importlib.machinery
+import importlib.util
+
+from remove_ai_watermarks import optional_deps
+
+
+def _fake_find_spec(specs: dict[str, importlib.machinery.ModuleSpec | None]):
+    def find_spec(name: str) -> importlib.machinery.ModuleSpec | None:
+        return specs[name]
+
+    return find_spec
+
+
+def _real_spec(name: str) -> importlib.machinery.ModuleSpec:
+    spec = importlib.util.find_spec(name)
+    assert spec is not None
+    assert spec.loader is not None
+    return spec
+
+
+class TestModuleAvailable:
+    def test_installed_module_is_available(self):
+        assert optional_deps.module_available("json") is True
+
+    def test_missing_module_is_not_available(self, monkeypatch):
+        monkeypatch.setattr(importlib.util, "find_spec", _fake_find_spec({"ghost": None}))
+        assert optional_deps.module_available("ghost") is False
+
+    def test_namespace_package_remnant_is_not_available(self, monkeypatch):
+        # A leftover data dir in site-packages (e.g. trustmark/models/ surviving
+        # an uninstall) resolves to a namespace-package spec with loader=None;
+        # the guard must not report it as installed.
+        ns_spec = importlib.machinery.ModuleSpec("trustmark", loader=None, is_package=True)
+        assert ns_spec.loader is None
+        monkeypatch.setattr(importlib.util, "find_spec", _fake_find_spec({"trustmark": ns_spec}))
+        assert optional_deps.module_available("trustmark") is False
+
+    def test_any_namespace_member_fails_the_conjunction(self, monkeypatch):
+        ns_spec = importlib.machinery.ModuleSpec("spandrel", loader=None, is_package=True)
+        specs = {"spandrel": ns_spec, "torch": _real_spec("json")}
+        monkeypatch.setattr(importlib.util, "find_spec", _fake_find_spec(specs))
+        assert optional_deps.module_available("torch", "spandrel") is False
+
+    def test_all_real_members_are_available(self):
+        assert optional_deps.module_available("json", "logging") is True
+
+
+class TestGuardsUseSharedHelper:
+    def test_trustmark_is_available_rejects_namespace_remnant(self, monkeypatch):
+        from remove_ai_watermarks import trustmark_detector
+
+        ns_spec = importlib.machinery.ModuleSpec("trustmark", loader=None, is_package=True)
+        monkeypatch.setattr(importlib.util, "find_spec", _fake_find_spec({"trustmark": ns_spec}))
+        assert trustmark_detector.is_available() is False

tests/test_platform.py

@@ -20,8 +20,9 @@ from remove_ai_watermarks.noai.watermark_profiles import (
     GEMINI_STRENGTH,
     OPENAI_STRENGTH,
     UNKNOWN_STRENGTH,
-    get_model_id_for_profile,
+    normalize_profile,
     resolve_strength,
+    strength_default_help,
 )
 from remove_ai_watermarks.noai.watermark_remover import get_device, is_watermark_removal_available
 
@@ -109,27 +110,28 @@ class TestMpsErrorDetection:
 
 
 class TestModelProfiles:
-    """Tests for watermark_profiles.py."""
+    """Tests for watermark_profiles.py profile-name normalization."""
 
-    def test_default_profile(self):
-        assert get_model_id_for_profile("default") == "stabilityai/stable-diffusion-xl-base-1.0"
+    def test_canonical_profiles_unchanged(self):
+        assert normalize_profile("sdxl") == "sdxl"
+        assert normalize_profile("controlnet") == "controlnet"
 
-    def test_controlnet_profile(self):
-        # controlnet shares the SDXL base checkpoint (the ControlNet is an add-on).
-        assert get_model_id_for_profile("controlnet") == "stabilityai/stable-diffusion-xl-base-1.0"
+    def test_default_alias_resolves_to_sdxl(self):
+        # "default" is the legacy alias for "sdxl" (back-compat for existing scripts).
+        assert normalize_profile("default") == "sdxl"
 
-    def test_unknown_profile_raises(self):
-        with pytest.raises(ValueError, match="Unknown model profile"):
-            get_model_id_for_profile("nonexistent")
+    def test_normalize_is_case_and_whitespace_insensitive(self):
+        assert normalize_profile("  Default ") == "sdxl"
+        assert normalize_profile("CONTROLNET") == "controlnet"
 
 
 class TestResolveStrength:
     """resolve_strength applies the vendor default only when strength is unset."""
 
     def test_none_is_vendor_adaptive(self):
-        # No vendor -> unknown default; OpenAI lower, Google == unknown. The default
-        # is vendor-adaptive and does NOT depend on the pipeline profile (default and
-        # controlnet share the same SDXL base).
+        # No vendor -> unknown default; OpenAI lower, Google == unknown. The SAME ladder
+        # applies to both pipelines (the certified controlnet floors), so there is no
+        # pipeline argument.
         assert resolve_strength(None) == UNKNOWN_STRENGTH
         assert resolve_strength(None, "openai") == OPENAI_STRENGTH
         assert resolve_strength(None, "google") == GEMINI_STRENGTH
@@ -137,10 +139,25 @@ class TestResolveStrength:
         # An unrecognized vendor string falls through to the unknown default.
         assert resolve_strength(None, "adobe") == UNKNOWN_STRENGTH
 
+    def test_ladder_is_the_certified_controlnet_floors(self):
+        # The unified ladder == the oracle-certified controlnet floors (OpenAI 0.20,
+        # Google/unknown 0.30); Google is the more-robust watermark, so it is higher.
+        assert OPENAI_STRENGTH == 0.20
+        assert GEMINI_STRENGTH == 0.30
+        assert UNKNOWN_STRENGTH == 0.30
+        assert OPENAI_STRENGTH < GEMINI_STRENGTH
+
     def test_default_strength_alias_is_unknown_vendor_value(self):
         assert DEFAULT_STRENGTH == UNKNOWN_STRENGTH
         assert OPENAI_STRENGTH < UNKNOWN_STRENGTH
 
+    def test_strength_default_help_derives_from_constants(self):
+        # The CLI --strength help is built from this, so it can never drift from the ladder.
+        h = strength_default_help()
+        assert str(OPENAI_STRENGTH) in h
+        assert str(GEMINI_STRENGTH) in h
+        assert str(UNKNOWN_STRENGTH) in h
+
     def test_explicit_value_overrides_vendor(self):
         assert resolve_strength(0.3) == 0.3
         assert resolve_strength(0.3, "openai") == 0.3