Collapse the duplicated detection path and lift the image pipeline into the library

The visible-mark path had grown three copies of one ladder sweep, four
near-identical `detect` arms, and four hand-rolled `footprint_mask` overrides;
mark knowledge sat in five hand-maintained tables across three modules; and the
flagship `all`/`batch` pipeline existed only in cli.py, written twice with
divergent behavior.

Detection is now one measurement. `_ladder_best` replaces the three sweeps,
`_scan`/`_verdict` replace the four arms, and the winning box travels to the
mask on `TextMarkDetection.match_box` instead of being swept a second time.
`detect_both` returns the strict and relaxed verdicts from one scan, which
halves the arbiter's perception cost (260 -> 130 matchTemplate calls on a 2048²
image, verdicts identical field for field). A per-mark demotion goes in the new
`_post_gate` hook, never in a `detect` override -- an override is invisible to
the single-pass path, which is how the RunningHub and Yuanbao anchor gates
briefly stopped applying.

Everything about a mark is now one registry row: product, label regime, the
platform sentence `identify` reports, the metadata signals that confirm it, and
its TC260 producer codes. `identify._VISIBLE_MARK_PLATFORM`, the signal mapping
in `api.visible_provenance`, `_PRODUCT_OF` and the pill veto are derived from
those rows.

`api.remove_all` / `api.remove_batch` are the library form of the `all` and
`batch` commands; the CLI is a wrapper that owns console text and exit codes.
Progress is a `(stage, detail)` pair of stable tokens, so the CLI keys its
wording off structure rather than parsing the library's prose back.

Two intentional behavior changes, both verified against a recorded 811-image
sample of detector verdicts, removal-mask hashes, arbiter decisions and
`identify` reports:

  * A TC260 label now relaxes the vendor its `ContentProducer` names rather than
    ByteDance's pair on every China-AIGC image. 333 of 811 samples move; on 185
    of them the previously relaxed pair was simply the wrong vendor, and the
    mark actually present never reached the relaxed gate its own
    `provenance_ncc_factor` was calibrated for.
  * A confident LibLibAI detection suppresses the Jimeng pill, like every other
    TC260 product's mark. It was registered alongside RunningHub and Baidu, both
    of which were added to the hand-written veto list, and it was not. 1 sample
    moves, and it is exactly the co-firing case.

Nothing else in that record changes: detector verdicts, mask hashes and
`identify` verdicts are byte-identical, and all 200 calibration constants are
untouched.

Also: `aigc_label` and friends plus `extract_c2pa_info` are memoized on
(path, mtime_ns, size) -- size because this package rewrites in place; the
native TC260 container readers route on magic bytes instead of the file
extension, so a mislabeled AVI or FLV is no longer invisible; `identify` shares
one pixel decode between the DWT-DCT and visible stages (TrustMark keeps its own
Pillow decode, which is not substitutable); and the six `stabilize_*` video
wrappers collapse into one policy table.

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

src/remove_ai_watermarks/__init__.py

@@ -35,9 +35,15 @@ _warnings.filterwarnings("ignore", message=r".*ImageProcessorFast.*")
 __version__ = "0.25.0"
 
 __all__ = [
+    "BatchSummary",
+    "InvisibleOptions",
+    "MetadataStripIncomplete",
+    "RemoveAllResult",
     "__version__",
     "identify_video",
     "inspect_video_metadata",
+    "remove_all",
+    "remove_batch",
     "remove_video_all",
     "remove_video_batch",
     "remove_video_invisible",
@@ -48,7 +54,16 @@ __all__ = [
 ]
 
 if TYPE_CHECKING:
-    from remove_ai_watermarks.api import remove_visible, visible_provenance
+    from remove_ai_watermarks.api import (
+        BatchSummary,
+        InvisibleOptions,
+        MetadataStripIncomplete,
+        RemoveAllResult,
+        remove_all,
+        remove_batch,
+        remove_visible,
+        visible_provenance,
+    )
     from remove_ai_watermarks.video import (
         identify_video,
         inspect_video_metadata,
@@ -63,7 +78,16 @@ if TYPE_CHECKING:
 def __getattr__(name: str) -> object:
     """Lazily resolve the high-level API (PEP 562), so the heavy imports (cv2, the
     metadata/identify stack) load only when a caller actually reaches for them."""
-    if name in ("remove_visible", "visible_provenance"):
+    if name in (
+        "BatchSummary",
+        "InvisibleOptions",
+        "MetadataStripIncomplete",
+        "RemoveAllResult",
+        "remove_all",
+        "remove_batch",
+        "remove_visible",
+        "visible_provenance",
+    ):
         from remove_ai_watermarks import api
 
         return getattr(api, name)

src/remove_ai_watermarks/_internal/c2pa.py

@@ -329,14 +329,44 @@ def _extract_c2pa_info_png(image_path: Path) -> dict[str, Any]:
     return info
 
 
-def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
-    """Return normalized C2PA evidence from the official reader or PNG fallback."""
+def _extract_c2pa_info_impl(image_path: Path) -> dict[str, Any]:
     store = read_manifest_store_json(Path(image_path))
     if store is not None:
         return c2pa_info_from_manifest_store(store)
     return _extract_c2pa_info_png(Path(image_path))
 
 
+@functools.lru_cache(maxsize=4)
+def _extract_c2pa_info_cached(path_str: str, _mtime_ns: int, _size: int, _reader: bool) -> dict[str, Any]:
+    """Cache shim: every argument after the path is key-only.
+
+    ``_reader`` is in the key because the answer genuinely depends on it -- with the
+    official reader the manifest comes back as a store, without it from the hand-rolled
+    PNG chunk parser, and the two produce different ``c2pa_manifest`` labels. Keying on
+    the file alone handed a reader-path result to a caller that had disabled the reader.
+    """
+    return _extract_c2pa_info_impl(Path(path_str))
+
+
+def extract_c2pa_info(image_path: Path) -> dict[str, Any]:
+    """Return normalized C2PA evidence from the official reader or PNG fallback.
+
+    Memoized on ``(path, mtime_ns, size)``: one ``identify`` reaches this twice (once
+    directly, once inside ``get_ai_metadata``) and each call re-runs the Rust manifest
+    reader and re-parses its JSON. Size joins mtime in the key because this package
+    rewrites files in place, and an in-place rewrite can land inside one mtime tick.
+    """
+    try:
+        stat = image_path.stat()
+    except OSError:
+        # No stat (a pipe, or a race): read uncached rather than fail.
+        return _extract_c2pa_info_impl(image_path)
+    cached = _extract_c2pa_info_cached(str(image_path), stat.st_mtime_ns, stat.st_size, _C2PA_READER_AVAILABLE)
+    # Deep-ish copy: values are scalars plus a few lists, and a caller mutating one of
+    # those lists would otherwise poison every later reader of the same file.
+    return {key: list(cast("list[Any]", value)) if isinstance(value, list) else value for key, value in cached.items()}
+
+
 def inject_c2pa_chunk(target_path: Path, output_path: Path, c2pa_chunk: bytes) -> None:
     """Replace any C2PA chunks in a PNG and insert ``c2pa_chunk`` before IDAT."""
     if target_path.suffix.casefold() != ".png" or output_path.suffix.casefold() != ".png":

src/remove_ai_watermarks/_internal/constants.py

@@ -147,3 +147,15 @@ AI_GENERATOR_TOKENS = frozenset(
 
 _C2PA_ACTION_NAMES = _tokens("created|converted|edited|filtered|cropped|resized|opened|placed")
 C2PA_ACTIONS = {f"c2pa.{action}".encode(): action for action in _C2PA_ACTION_NAMES}
+
+
+# TC260 producer identity -> the mark key whose vendor signs with it now lives on the
+# registry rows (``KnownMark.tc260_producer_codes``, read through
+# ``watermark_registry.tc260_producer_vendors``). Keeping the codes beside the mark is
+# what stops a newly registered TC260 vendor from silently falling back to ByteDance.
+#
+# What a TC260 label confirms when its producer is absent or unmapped. Historical
+# behaviour, kept as the fallback so an unrecognized producer never regresses to no
+# relaxation at all: ByteDance's two products are the ones the relaxed band was
+# calibrated on (see _text_mark_engine._DEFAULT_PROVENANCE_NCC_FACTOR).
+TC260_FALLBACK_VENDORS: frozenset[str] = frozenset({"doubao", "jimeng"})

src/remove_ai_watermarks/_internal/qwen_zimage_pipeline.py

@@ -561,11 +561,18 @@ def _clip_sam_masks_to_boxes(
     image_size: tuple[int, int],
 ) -> list[np.ndarray]:
     """Match Impact Pack by intersecting each SAM mask with its detector box."""
+    # Same rectangle primitive the shared fill uses, rather than a private zeros/fill
+    # copy. `dilate=0` because this box CLIPS a SAM mask -- growing it would admit the
+    # pixels the clip exists to exclude. The function-local import keeps region_eraser's
+    # module-scope cv2 off this module's import path.
+    from remove_ai_watermarks.region_eraser import boxes_to_mask
+
     width, height = image_size
     clipped: list[np.ndarray] = []
     for mask, (x1, y1, x2, y2) in zip(masks, boxes, strict=True):
-        box_mask = np.zeros((height, width), dtype=np.uint8)
-        box_mask[max(0, y1) : min(height, y2), max(0, x1) : min(width, x2)] = 255
+        # (x, y, w, h) with w = x2 - x1 keeps x + w == x2, so a negative origin clamps
+        # to the same span the explicit max/min pair produced.
+        box_mask = boxes_to_mask((height, width), [(x1, y1, x2 - x1, y2 - y1)], dilate=0)
         clipped.append(np.bitwise_and(mask.astype(np.uint8), box_mask))
     return clipped
 

src/remove_ai_watermarks/_internal/watermark_profiles.py

@@ -10,7 +10,6 @@ registry and every identify path still run anywhere.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
 from typing import TYPE_CHECKING, Literal
 
 if TYPE_CHECKING:
@@ -71,19 +70,12 @@ SDXL_ZIMAGE_GEMINI_STRENGTH = 0.25
 SDXL_ZIMAGE_UNKNOWN_STRENGTH = SDXL_ZIMAGE_GEMINI_STRENGTH
 
 
-@dataclass(frozen=True)
-class _StrengthPolicy:
-    unknown: float
-    by_vendor: dict[str, float]
-
-    def choose(self, vendor: str | None) -> float:
-        return self.by_vendor.get((vendor or "").casefold(), self.unknown)
-
-
-_SDXL_ZIMAGE_POLICY = _StrengthPolicy(
-    unknown=SDXL_ZIMAGE_UNKNOWN_STRENGTH,
-    by_vendor={"openai": SDXL_ZIMAGE_OPENAI_STRENGTH, "google": SDXL_ZIMAGE_GEMINI_STRENGTH},
-)
+# sdxl-zimage picks its strength from the VENDOR (unlike qwen-zimage, which derives it
+# from image area). An unlisted or unknown vendor falls back to the Gemini value.
+_SDXL_ZIMAGE_STRENGTH_BY_VENDOR: dict[str, float] = {
+    "openai": SDXL_ZIMAGE_OPENAI_STRENGTH,
+    "google": SDXL_ZIMAGE_GEMINI_STRENGTH,
+}
 _ALIASES = {
     "qwen_zimage": QWEN_ZIMAGE_PROFILE,
     "sdxl_zimage": SDXL_ZIMAGE_PROFILE,
@@ -134,7 +126,7 @@ def resolve_strength(
     if strength is not None:
         return strength
     if normalize_profile(pipeline or "") == SDXL_ZIMAGE_PROFILE:
-        return _SDXL_ZIMAGE_POLICY.choose(vendor)
+        return _SDXL_ZIMAGE_STRENGTH_BY_VENDOR.get((vendor or "").casefold(), SDXL_ZIMAGE_UNKNOWN_STRENGTH)
     if size is None:
         raise ValueError("qwen-zimage resolves strength from image area, so size is required")
     from remove_ai_watermarks._internal.qwen_zimage_pipeline import resolution_adaptive_denoise

src/remove_ai_watermarks/_text_mark_engine.py

@@ -132,7 +132,7 @@ class TextMarkConfig:
     # Which image dimension the mark's size and margins scale with. VENDOR-SPECIFIC,
     # measured, not assumed -- see TextMarkEngine.scale_base. "short" = min(h, w), "width" = w.
     scale_basis: Literal["short", "width"] = "width"
-    # Scale rungs ``_tophat_best`` sweeps (the detection comb). PER-MARK: a vendor
+    # Scale rungs ``_ladder_best`` sweeps (the detection comb). PER-MARK: a vendor
     # whose stamp sizes do not land on the shared 3-rung comb carries its own ladder
     # (measured for 千问, whose marks sit in two size modes ~1.6x apart -- one fraction
     # on 3 rungs covers only ~75% of them). Densifying the SHARED ladder for everyone
@@ -170,6 +170,33 @@ class TextMarkDetection:
     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
+    # ROI-local (x0, y0, x1, y1) of the ladder sweep's best match, in the LOCATED BOX's
+    # coordinates. None for the ``binary`` front-end (it runs no sweep) and whenever no
+    # rung matched. ``footprint_mask`` bounds the fill with it, so carrying it here is
+    # what stops the mask path re-running a sweep the detector already ran.
+    match_box: tuple[int, int, int, int] | None = None
+    # The trust level this detection was taken at, mirroring detect()'s ``provenance``.
+    # ``footprint_mask`` reuses a threaded detection only when it matches the STRICT
+    # level its own re-detect would have used -- see TextMarkEngine._strict_detection.
+    provenance: bool = False
+
+
+@dataclass(frozen=True)
+class TextMarkScan:
+    """The trust-level-BLIND half of text-mark detection, reusable across both levels.
+
+    ``loc is None`` means detection stopped before any scan (empty or too-small image).
+    ``score is None`` means the binary front-end fell below its coverage gate, which is
+    a verdict of "not detected, confidence 0.0" without consulting the rival margin.
+    """
+
+    loc: TextMarkLocation | None
+    box: NDArray[Any] | None  # box-sized binary glyph mask
+    base: int  # scale_base(image)
+    frame: tuple[int, int] = (0, 0)  # (h, w) of the scanned image
+    coverage: float = 0.0
+    score: float | None = None
+    match_box: tuple[int, int, int, int] | None = None
 
 
 # Alpha / silhouette templates, cached per asset name. This shared cache lets every
@@ -306,6 +333,28 @@ class TextMarkEngine:
 
     # ── Locate ──────────────────────────────────────────────────────────
 
+    def _roi_fields(
+        self, image: NDArray[Any], loc: TextMarkLocation
+    ) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any]]:
+        """``(luma, saturation, local_background)`` for the located box, all float32.
+
+        The ROI is normalized to 3-channel BGR first (grayscale / BGRA would break
+        ``axis=2``).
+
+        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.
+
+        The callers each keep their own ``bh < 16 or bw < 16`` guard: they return three
+        different sentinels for a degenerate ROI, so the check cannot move in here.
+        """
+        x, y, bw, bh = loc.bbox
+        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
+        luma = roi.mean(axis=2)
+        sat = roi.max(axis=2) - roi.min(axis=2)
+        sigma = max(4.0, bh * 0.4)  # 0.4 factor and 4.0 floor are calibrated; do not retune
+        return luma, sat, cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
+
     def tophat_response(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any] | None:
         """The CONTINUOUS white top-hat in the located box -- the glyph signal, unbinarized.
 
@@ -328,26 +377,48 @@ class TextMarkEngine:
         Kept per-mark (``detect_frontend``) rather than switched globally, because a
         front-end change must be measured per mark before it ships.
         """
+        return self._residual_response(image, loc, absolute=False)
+
+    def _residual_response(self, image: NDArray[Any], loc: TextMarkLocation, *, absolute: bool) -> NDArray[Any] | None:
+        """Max-normalized uint8 local-luma residual in the located box, saturation-weighted.
+
+        ``absolute=False`` keeps only the POSITIVE side -- the white top-hat, for a mark
+        always rendered brighter than its background. ``absolute=True`` takes the
+        magnitude, for a renderer that switches between light-on-dark and dark-on-light
+        while preserving one silhouette; a one-polarity top-hat misses the latter.
+        """
         c = self.config
-        x, y, bw, bh = loc.bbox
+        _x, _y, bw, bh = loc.bbox
         if bh < 16 or bw < 16:
             return None
-        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
-        luma = roi.mean(axis=2)
-        sat = roi.max(axis=2) - roi.min(axis=2)
-        sigma = max(4.0, bh * 0.4)
-        tophat = luma - cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma)
-        resp = np.clip(tophat, 0, None) * (sat < c.max_saturation)
+        luma, sat, local_bg = self._roi_fields(image, loc)
+        residual = luma - local_bg
+        resp = (np.abs(residual) if absolute else np.clip(residual, 0, None)) * (sat < c.max_saturation)
         peak = float(resp.max())
         if peak <= 1e-6:
             return None
         return (resp / peak * 255).astype(np.uint8)
 
-    def _tophat_best(
+    def _detect_response(self, image: NDArray[Any], loc: TextMarkLocation) -> NDArray[Any] | None:
+        """The uint8 image the ladder sweep correlates the silhouette against, chosen by
+        ``TextMarkConfig.detect_frontend``. ``binary`` runs no sweep and never reaches here."""
+        frontend = self.config.detect_frontend
+        if frontend == "gray":
+            x, y, bw, bh = loc.bbox
+            if bh < 16 or bw < 16:
+                return None
+            return cv2.cvtColor(image_io.to_bgr(image[y : y + bh, x : x + bw]), cv2.COLOR_BGR2GRAY)
+        if frontend == "contrast":
+            return self._residual_response(image, loc, absolute=True)
+        if frontend == "tophat":
+            return self._residual_response(image, loc, absolute=False)
+        raise ValueError(f"{frontend!r} has no ladder response (binary runs no sweep)")
+
+    def _ladder_best(
         self, image: NDArray[Any], loc: TextMarkLocation
     ) -> tuple[float, tuple[int, int, int, int] | None]:
-        """Best TM_CCOEFF_NORMED of a soft template against the continuous response, and
-        the ROI-local box (x0, y0, x1, y1) where that best match sits.
+        """Best TM_CCOEFF_NORMED of the mark's silhouette against its front-end response,
+        and the ROI-local box (x0, y0, x1, y1) where that best match sits.
 
         Sweeps the mark's scale ladder: the nominal glyph size is derived from the mark's
         geometry, but a vendor re-rasterization shifts it by a few percent and the
@@ -358,10 +429,15 @@ class TextMarkEngine:
         detection, the box bounds the fill. Sharing it is deliberate: the standing rule is
         that detection and the mask use the same front-end, and the way that rule was last
         broken was a drift between two separate implementations. One method makes the drift
-        impossible instead of merely discouraged.
+        impossible instead of merely discouraged -- which is why the three continuous
+        front-ends (tophat / contrast / gray) sweep here rather than in a copy each.
+
+        Tie-breaking is load-bearing: the ``0.0`` seed plus the STRICT ``>`` means the
+        EARLIEST ladder rung wins a tie, and a sweep whose maximum is not above 0.0
+        returns no box at all.
         """
         c = self.config
-        resp = self.tophat_response(image, loc)
+        resp = self._detect_response(image, loc)
         sil = self._glyph_silhouette()
         if resp is None or sil is None:
             return (0.0, None)
@@ -373,90 +449,12 @@ class TextMarkEngine:
             gh = max(4, int(c.alpha_height_frac * base * scale))
             if gw >= resp.shape[1] or gh >= resp.shape[0]:
                 continue
-            tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA).astype(np.float32)
-            if c.template_blur > 0:
-                tmpl = cv2.GaussianBlur(tmpl, (0, 0), sigmaX=c.template_blur, sigmaY=c.template_blur)
-            result = cv2.matchTemplate(resp, tmpl.astype(np.uint8), cv2.TM_CCOEFF_NORMED)
-            _, score, _, top_left = cv2.minMaxLoc(result)
-            if score > best_score:
-                tx, ty = int(top_left[0]), int(top_left[1])
-                best_score, best_box = float(score), (tx, ty, tx + gw - 1, ty + gh - 1)
-        return (best_score, best_box)
-
-    def _tophat_score(self, image: NDArray[Any], loc: TextMarkLocation) -> float:
-        """The detection score alone -- the box the removal mask needs is discarded here."""
-        return self._tophat_best(image, loc)[0]
-
-    def _contrast_best(
-        self, image: NDArray[Any], loc: TextMarkLocation
-    ) -> tuple[float, tuple[int, int, int, int] | None]:
-        """Best silhouette match against the absolute local-luma residual.
-
-        Unlike the white top-hat, this response is polarity-independent: the same
-        watermark can be lighter or darker than its local background. Detection and
-        removal share the returned box, preserving the front-end parity contract.
-        """
-        c = self.config
-        x, y, bw, bh = loc.bbox
-        if bh < 16 or bw < 16:
-            return (0.0, None)
-        roi = image_io.to_bgr(image[y : y + bh, x : x + bw]).astype(np.float32)
-        luma = roi.mean(axis=2)
-        sat = roi.max(axis=2) - roi.min(axis=2)
-        sigma = max(4.0, bh * 0.4)
-        response = np.abs(luma - cv2.GaussianBlur(luma, (0, 0), sigmaX=sigma, sigmaY=sigma))
-        response *= sat < c.max_saturation
-        peak = float(response.max())
-        sil = self._glyph_silhouette()
-        if peak <= 1e-6 or sil is None:
-            return (0.0, None)
-        response = (response / peak * 255).astype(np.uint8)
-        base = self.scale_base(image)
-        best_score = 0.0
-        best_box: tuple[int, int, int, int] | None = None
-        for scale in c.ladder:
-            gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
-            gh = max(4, int(c.alpha_height_frac * base * scale))
-            if gw >= response.shape[1] or gh >= response.shape[0]:
-                continue
-            template = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
-            result = cv2.matchTemplate(response, template, cv2.TM_CCOEFF_NORMED)
-            _, score, _, top_left = cv2.minMaxLoc(result)
-            if score > best_score:
-                tx, ty = int(top_left[0]), int(top_left[1])
-                best_score, best_box = float(score), (tx, ty, tx + gw - 1, ty + gh - 1)
-        return (best_score, best_box)
-
-    def _gray_best(self, image: NDArray[Any], loc: TextMarkLocation) -> tuple[float, tuple[int, int, int, int] | None]:
-        """Best TM_CCOEFF_NORMED of the silhouette against the raw GRAYSCALE ROI, and
-        the ROI-local box (x0, y0, x1, y1) of that best match.
-
-        Mirrors :meth:`_tophat_best` (same ladder sweep, same one-method contract so
-        detection and the removal mask can never drift), but skips the top-hat
-        entirely: the RunningHub mark is a faint mid-gray text the top-hat's
-        background subtraction suppresses to clean-arm levels, while raw gray NCC
-        separates (see ``TextMarkConfig.detect_frontend``). Contrast-DEPENDENT by
-        construction, so the gate must be picked against the clean arm, which is
-        what ``scripts/vendor_mark_calibrate.py`` does.
-        """
-        c = self.config
-        x, y, bw, bh = loc.bbox
-        if bh < 16 or bw < 16:
-            return (0.0, None)
-        roi = cv2.cvtColor(image_io.to_bgr(image[y : y + bh, x : x + bw]), cv2.COLOR_BGR2GRAY)
-        sil = self._glyph_silhouette()
-        if sil is None:
-            return (0.0, None)
-        base = self.scale_base(image)
-        best_score = 0.0
-        best_box: tuple[int, int, int, int] | None = None
-        for scale in c.ladder:
-            gw = max(c.min_gw, int(c.alpha_width_frac * base * scale))
-            gh = max(4, int(c.alpha_height_frac * base * scale))
-            if gw >= roi.shape[1] or gh >= roi.shape[0]:
-                continue
             tmpl = cv2.resize(sil, (gw, gh), interpolation=cv2.INTER_AREA)
-            result = cv2.matchTemplate(roi, tmpl, cv2.TM_CCOEFF_NORMED)
+            if c.detect_frontend == "tophat" and c.template_blur > 0:
+                tmpl = cv2.GaussianBlur(
+                    tmpl.astype(np.float32), (0, 0), sigmaX=c.template_blur, sigmaY=c.template_blur
+                ).astype(np.uint8)
+            result = cv2.matchTemplate(resp, tmpl, cv2.TM_CCOEFF_NORMED)
             _, score, _, top_left = cv2.minMaxLoc(result)
             if score > best_score:
                 tx, ty = int(top_left[0]), int(top_left[1])
@@ -570,10 +568,33 @@ class TextMarkEngine:
         the mark's own ``provenance_ncc_factor`` to recover a faint or slightly
         re-rendered mark (per-mark, not shared -- see _DEFAULT_PROVENANCE_NCC_FACTOR).
         """
+        scan = self._scan(image)
+        return self._verdict(scan, provenance=provenance)
+
+    def detect_both(self, image: NDArray[Any] | None) -> tuple[TextMarkDetection, TextMarkDetection]:
+        """``(strict, relaxed)`` from ONE scan of the image.
+
+        ``provenance`` scales the acceptance THRESHOLD and nothing else -- the locate
+        box, the glyph mask, the coverage and the front-end ladder score are computed
+        identically at either trust level. Two ``detect`` calls therefore ran the same
+        expensive sweep twice to reach two verdicts, which is what the arbiter's
+        perception pass did for every mark on every image.
+
+        Returns two DISTINCT objects: subclasses demote a verdict by mutating it.
+        """
+        scan = self._scan(image)
+        return self._verdict(scan, provenance=False), self._verdict(scan, provenance=True)
+
+    def _scan(self, image: NDArray[Any] | None) -> TextMarkScan:
+        """Everything in detection that does not depend on the trust level.
+
+        Per-CALL only, never memoized on ``self``: ``remove_auto_marks`` re-invokes each
+        engine on a progressively cleaned frame inside one process, so a cached scan
+        would answer for the wrong pixels.
+        """
         c = self.config
-        det = TextMarkDetection()
         if image is None or image.size == 0:
-            return det
+            return TextMarkScan(None, None, 0)
         # Guard against the small-image NCC-noise false positive (see
         # _MIN_DETECT_SHORT_SIDE): an icon/thumbnail is too small to carry a real
         # text label, and the degraded few-pixel template spuriously correlates.
@@ -584,57 +605,57 @@ class TextMarkEngine:
                 min(image.shape[:2]),
                 _MIN_DETECT_SHORT_SIDE,
             )
-            return det
+            return TextMarkScan(None, None, 0)
         loc = self.locate(image)
         box = self.extract_mask(image, loc)  # box-sized mask (== old full-frame cropped to bbox)
         _x, _y, bw, bh = loc.bbox
         coverage = float((box > 0).sum()) / float(max(1, bw * bh))
-        det.region = loc.bbox
-        det.coverage = coverage
-        if c.detect_frontend == "tophat":
-            # The continuous front-end does not depend on the binarized blob, so the
-            # coverage gate (a blob-area heuristic) does not apply to it.
-            score = self._tophat_score(image, loc)
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug("%s detect (tophat): ncc=%.2f thr=%.2f detected=%s", c.name, score, threshold, det.detected)
+        base = self.scale_base(image)
+        match_box: tuple[int, int, int, int] | None = None
+        if c.detect_frontend == "binary":
+            # The coverage gate is a blob-AREA heuristic, so it applies only to the
+            # front-end that binarizes; the continuous ones never build a blob. Below
+            # the gate the detection stays at confidence 0.0 and the rival margin is
+            # never consulted, so the score stays None here.
+            score = self._template_match_score(box, base) if coverage >= c.detect_min_coverage else None
+        else:
+            score, match_box = self._ladder_best(image, loc)
+        return TextMarkScan(loc, box, base, frame=image.shape[:2], coverage=coverage, score=score, match_box=match_box)
+
+    def _verdict(self, scan: TextMarkScan, *, provenance: bool) -> TextMarkDetection:
+        """Apply the trust-level-dependent tail to a scan, as a fresh result object."""
+        c = self.config
+        det = TextMarkDetection(provenance=provenance)
+        if scan.loc is None or scan.box is None:
             return det
-        if c.detect_frontend == "gray":
-            # Same no-coverage-gate reasoning as tophat: the gray front-end never
-            # binarizes, so a blob-area heuristic does not apply to it either.
-            score = self._gray_best(image, loc)[0]
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug("%s detect (gray): ncc=%.2f thr=%.2f detected=%s", c.name, score, threshold, det.detected)
+        det.region = scan.loc.bbox
+        det.coverage = scan.coverage
+        det.match_box = scan.match_box
+        if scan.score is None:  # binary front-end below the coverage gate
             return det
-        if c.detect_frontend == "contrast":
-            score = self._contrast_best(image, loc)[0]
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug(
-                "%s detect (contrast): ncc=%.2f thr=%.2f detected=%s",
-                c.name,
-                score,
-                threshold,
-                det.detected,
-            )
-            return det
-        if coverage >= c.detect_min_coverage:
-            score = self._template_match_score(box, self.scale_base(image))
-            threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
-            det.confidence = score
-            det.detected = score >= threshold and self._rival_margin_ok(score, box, self.scale_base(image))
-            logger.debug(
-                "%s detect: coverage=%.3f ncc=%.2f thr=%.2f detected=%s",
-                c.name,
-                coverage,
-                score,
-                threshold,
-                det.detected,
-            )
+        threshold = c.detect_ncc_threshold * (c.provenance_ncc_factor if provenance else 1.0)
+        det.confidence = scan.score
+        # Short-circuit is load-bearing: _rival_margin_ok scores every rival template
+        # and logs its own rejection line, so it must stay unevaluated below threshold.
+        det.detected = scan.score >= threshold and self._rival_margin_ok(scan.score, scan.box, scan.base)
+        logger.debug(
+            "%s detect (%s): coverage=%.3f ncc=%.2f thr=%.2f detected=%s",
+            c.name,
+            c.detect_frontend,
+            scan.coverage,
+            scan.score,
+            threshold,
+            det.detected,
+        )
+        return self._post_gate(det, scan)
+
+    def _post_gate(self, det: TextMarkDetection, scan: TextMarkScan) -> TextMarkDetection:
+        """Per-mark demotion applied after the shared threshold, for both trust levels.
+
+        OVERRIDABLE. It lives here rather than in a ``detect`` override so a mark's gate
+        cannot be silently skipped by the single-pass ``detect_both`` path -- which is
+        exactly what happened while the anchor demotions were ``detect`` overrides.
+        """
         return det
 
     # ── Inpaint footprint (for the inpaint-fallback removal path) ────────
@@ -644,8 +665,132 @@ class TextMarkEngine:
     # to mask. A real strip covers hundreds of pixels.
     _MIN_GLYPH_PIXELS = 20
 
+    def _strict_detection(self, image: NDArray[Any], detection: TextMarkDetection | None) -> TextMarkDetection:
+        """The STRICT detection the footprint is bounded by.
+
+        A threaded detection is reused only when it was taken at the same strict level
+        this method would have used itself. A provenance-RELAXED detection is NOT
+        reused: a strict re-detect can demote a mark the relaxed gate accepted, which
+        for a continuous front-end means no mask at all. That is a MEASURED difference,
+        not a refactor, so the strict semantics stay.
+
+        Reuse is safe against ``remove_auto_marks`` chaining marks on a progressively
+        cleaned frame: the registry re-detects on that same cleaned array before
+        threading (``KnownMark.localize``), so a threaded detection is never stale.
+        """
+        if detection is not None and not detection.provenance:
+            return detection
+        return self.detect(image)  # polymorphic: a subclass gate must still apply
+
+    def _geometry_rect(self, loc: TextMarkLocation, frame: tuple[int, int]) -> tuple[int, int, int, int]:
+        """The whole locate box, clamped to the frame -- the ``force`` footprint."""
+        bx, by, bw, bh = loc.bbox
+        h, w = frame
+        return (bx, by, min(w, bx + bw), min(h, by + bh))
+
+    def _extend_match_box(
+        self, box: tuple[int, int, int, int], loc: TextMarkLocation, frame: tuple[int, int]
+    ) -> tuple[int, int, int, int]:
+        """Grow an ROI-local box into the absolute fill rectangle by a symmetric pad.
+
+        OVERRIDABLE, and the override contract is specifically the DETECTOR'S MATCH BOX:
+        a mark whose removable footprint reaches beyond what the NCC localizes -- Baidu's
+        flat white tag right of the text run, LibLibAI's triangle logo left of the
+        wordmark -- supplies its own extension here and inherits the rest of the
+        footprint path. The blob-bbox branch never routes through an override.
+        """
+        gx0, gy0, gx1, gy1 = box
+        bx, by, _bw, bh = loc.bbox
+        h, w = frame
+        pad = max(4, int(0.10 * bh))
+        return (
+            max(0, bx + gx0 - pad),
+            max(0, by + gy0 - pad),
+            min(w, bx + gx1 + 1 + pad),
+            min(h, by + gy1 + 1 + pad),
+        )
+
+    def _footprint_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Default footprint policy: the binary glyph blob's bbox, else the detector's
+        own match box for the front-ends that under-segment, else the geometry box
+        under ``force``.
+
+        The gray front-end exists for marks the top-hat under-segments, so the binary
+        blob is NOT authoritative there: trusting it first bounded the fill by a PARTIAL
+        blob (the faint head glyphs dropped out) and left the leftmost "Runni" of
+        "RunningHub AI生成" unremoved (2026-07-22).
+
+        A dark-on-light Yuanbao mark has no WHITE top-hat blob at all, so the contrast
+        front-end is bounded by the polarity-independent detector's match box too.
+
+        A tophat mark found only by the CONTINUOUS front-end has no binary glyph blob to
+        bound, so the mask came back empty and removal was a silent no-op while
+        ``identify`` still reported the mark. Use the DETECTOR'S OWN best-match box: the
+        correlation already located the mark at a position and scale, and thresholding
+        the response was a strictly worse proxy for that. An earlier fix thresholded the
+        max-normalized uint8 response at 0.5 -- which selects every non-zero pixel, not
+        "half the peak" as its comment claimed -- and filled ~120% of the corner box on
+        textured frames (measured: whole corner vs 58.7% for the match box, both
+        detector-clean). Gated on an actual detection: on a clean corner the box would
+        be spurious.
+        """
+        ys, xs = np.where(self.extract_mask(image, loc) > 0)
+        blob = (
+            (int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())) if xs.size >= self._MIN_GLYPH_PIXELS else None
+        )
+        frontend = self.config.detect_frontend
+        if frontend in ("gray", "contrast"):
+            det = self._strict_detection(image, detection)
+            box = det.match_box if det.detected else blob
+        elif blob is not None:
+            box = blob
+        elif frontend == "tophat":
+            det = self._strict_detection(image, detection)
+            box = det.match_box if det.detected else None
+        else:
+            box = None
+        if box is not None:
+            return self._extend_match_box(box, loc, image.shape[:2])
+        return self._geometry_rect(loc, image.shape[:2]) if force else None
+
+    def _match_box_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Footprint policy for a mark whose fill must be bounded by the DETECTOR's match
+        box and never by the binary glyph blob.
+
+        Baidu's white tag has a flat interior a top-hat cannot answer, and LibLibAI's
+        blob bleeds up into background structure; in both cases the blob bbox is
+        measurably wrong and the NCC match box is right. ``force`` takes priority here,
+        unlike the default policy: a ``--no-detect`` caller named the mark, so the whole
+        geometry box is the honest footprint.
+        """
+        if force:
+            return self._geometry_rect(loc, image.shape[:2])
+        det = self._strict_detection(image, detection)
+        if not det.detected or det.match_box is None:
+            return None
+        return self._extend_match_box(det.match_box, loc, image.shape[:2])
+
     def footprint_mask(
-        self, image: NDArray[Any], *, force: bool = False, dilate: int | None = None
+        self,
+        image: NDArray[Any] | None,
+        *,
+        force: bool = False,
+        dilate: int | None = None,
+        detection: TextMarkDetection | None = None,
     ) -> NDArray[Any] | None:
         """Full-frame uint8 mask (255 = mark) of the mark footprint, for the shared
         fill removal path (cv2 / MI-GAN / LaMa), or None if no glyph is found.
@@ -662,6 +807,10 @@ class TextMarkEngine:
 
         With ``force`` and no glyph found, falls back to the whole geometry box (the
         ``--no-detect`` path). The caller gates on detection.
+
+        ``detection`` is the caller's already-computed detection, threaded in so the
+        footprint does not re-run a sweep the detector already ran. See
+        :meth:`_strict_detection` for when it is reused.
         """
         if image is None or image.size == 0:
             return None  # guard before to_bgr (cvtColor raises on an empty Mat); mirror detect()
@@ -670,46 +819,10 @@ class TextMarkEngine:
         if h < 32 or w < 64:
             return None
         loc = self.locate(image)
-        bx, by, bw, bh = loc.bbox
-        glyph = self.extract_mask(image, loc)  # box-sized, 255 = glyph
-        ys, xs = np.where(glyph > 0)
-        box: tuple[int, int, int, int] | None = None
-        if self.config.detect_frontend == "gray" and self.detect(image).detected:
-            # The gray front-end exists for marks the top-hat under-segments, so the
-            # binary blob is NOT authoritative here: trusting it first bounded the
-            # fill by a PARTIAL blob (the faint head glyphs dropped out) and left the
-            # leftmost "Runni" of "RunningHub AI生成" unremoved (2026-07-22). Use the
-            # detector's own best-match box, same as the tophat faint path below.
-            _, box = self._gray_best(image, loc)
-        elif self.config.detect_frontend == "contrast" and self.detect(image).detected:
-            # A dark-on-light Yuanbao mark has no WHITE top-hat blob at all. Bound
-            # the fill by the polarity-independent detector's own match box.
-            _, box = self._contrast_best(image, loc)
-        elif xs.size >= self._MIN_GLYPH_PIXELS:
-            box = (int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max()))
-        elif self.config.detect_frontend == "tophat" and self.detect(image).detected:
-            # A mark found only by the CONTINUOUS front-end has no binary glyph blob to
-            # bound, so the mask came back empty and removal was a silent no-op while
-            # `identify` still reported the mark while removal left it untouched.
-            # Use the DETECTOR'S OWN best-match box: the correlation already located the
-            # mark at a position and scale, and thresholding the response was a strictly
-            # worse proxy for that. An earlier fix thresholded the max-normalized uint8
-            # response at 0.5 -- which selects every non-zero pixel, not "half the peak" as
-            # its comment claimed -- and filled ~120% of the corner box on textured frames
-            # (measured: whole corner vs 58.7% for the match box, both detector-clean).
-            # Gated on an actual detection: on a clean corner the box would be spurious.
-            _, box = self._tophat_best(image, loc)
-        if box is not None:
-            gx0, gy0, gx1, gy1 = box
-            pad = max(4, int(0.10 * bh))
-            rx1 = max(0, bx + gx0 - pad)
-            rx2 = min(w, bx + gx1 + 1 + pad)
-            ry1 = max(0, by + gy0 - pad)
-            ry2 = min(h, by + gy1 + 1 + pad)
-        elif force:
-            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
-        else:
+        rect = self._footprint_rect(image, loc, force=force, detection=detection)
+        if rect is None:
             return None
+        rx1, ry1, rx2, ry2 = rect
         if rx1 >= rx2 or ry1 >= ry2:
             return None
         # Rectangular footprint + dilation is exactly region_eraser.boxes_to_mask (the
@@ -717,5 +830,5 @@ class TextMarkEngine:
         # zeros/fill/MORPH_ELLIPSE-dilate here.
         from remove_ai_watermarks import region_eraser
 
-        d = dilate if dilate is not None else max(3, int(0.02 * bw))
+        d = dilate if dilate is not None else max(3, int(0.02 * loc.w))
         return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)

src/remove_ai_watermarks/api.py

@@ -16,11 +16,14 @@ Imports stay lazy (inside the functions), so ``import remove_ai_watermarks`` is
 
 from __future__ import annotations
 
+from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from numpy.typing import NDArray
 
     from remove_ai_watermarks.watermark_registry import Backend, Sensitivity
@@ -40,8 +43,17 @@ def visible_provenance(source: str | Path) -> frozenset[str]:
     """Vendor keys that the file's local metadata confirms, the evidence that drives
     the ``auto`` sensitivity (relaxing a corroborated mark's detection trust gate).
 
-    Mapping: a Google/Gemini C2PA issuer -> ``"gemini"``; a China-AIGC (TC260) label
-    -> ``"doubao"``/``"jimeng"``; a ``samsung_genai`` marker -> ``"samsung"``.
+    Mapping: a Google/Gemini C2PA issuer -> ``"gemini"``; a ``samsung_genai`` marker ->
+    ``"samsung"``; a China-AIGC (TC260) label -> the vendor its ``ContentProducer``
+    names (``KnownMark.tc260_producer_codes``), falling back to ByteDance's two products
+    when the producer is absent or unmapped.
+
+    The TC260 label itself says only "this is AI", so it used to relax Doubao and
+    Jimeng on EVERY China-AIGC image -- including one carrying a Qwen or Kling mark,
+    where relaxing the wrong pair is pure false-positive risk and the mark actually
+    present never reached the relaxed gate its own ``provenance_ncc_factor`` was
+    calibrated for. The producer code identifies the signing entity, so it can.
+
     Best-effort: any read error yields an empty set (no relaxation). Metadata-only, so
     it never loads cv2/torch.
     """
@@ -52,19 +64,33 @@ def visible_provenance(source: str | Path) -> frozenset[str]:
         from remove_ai_watermarks import identify
 
         rep = identify.identify(path, check_visible=False, check_invisible=False)
-        signal_names = {signal.name for signal in rep.signals}
-        keys: set[str] = set()
-        platform = (rep.platform or "").lower()
-        if "google" in platform or "gemini" in platform:
-            keys.add("gemini")
-        if "aigc" in signal_names:
-            keys |= {"doubao", "jimeng"}
-        if "samsung_genai" in signal_names:
-            keys.add("samsung")
-        return frozenset(keys)
+        return _provenance_from_report(rep, path)
     return frozenset()
 
 
+def _tc260_vendors(path: Path) -> frozenset[str]:
+    """Vendor keys a TC260 label confirms, from its ``ContentProducer`` identity.
+
+    An absent, unreadable or unmapped producer falls back to the historical pair rather
+    than to nothing: the caller has already established that the AIGC signal fired, so
+    the image IS China-AIGC labelled, and dropping to no relaxation would lose the
+    detections the fallback recovers today. The re-read is deliberately isolated -- a
+    failure here must narrow the answer, never discard the rest of the provenance.
+    """
+    import contextlib
+
+    from remove_ai_watermarks._internal.constants import TC260_FALLBACK_VENDORS
+
+    with contextlib.suppress(Exception):
+        from remove_ai_watermarks.metadata import aigc_label, uscc_of
+        from remove_ai_watermarks.watermark_registry import tc260_producer_vendors
+
+        producer = (aigc_label(path) or {}).get("ContentProducer", "")
+        if producer and (vendor := tc260_producer_vendors().get(uscc_of(producer))):
+            return frozenset({vendor})
+    return TC260_FALLBACK_VENDORS
+
+
 def _load_visible_input(source: str | Path | NDArray[Any]) -> _VisibleInput:
     """Normalize a path/array source without making the public operation stateful."""
     if not isinstance(source, (str, Path)):
@@ -177,3 +203,458 @@ def remove_visible(
             write_noop=write_noop,
         )
     return result, removed
+
+
+# ── The three-stage image pipeline (visible -> invisible -> metadata) ──
+# This is the `all` / `batch` pipeline. It lived only in cli.py, written twice with
+# divergences, so a library caller could not run the flagship path at all. The CLI is
+# now a thin wrapper: it builds the options, prints the stage lines through
+# `progress`, and turns the outcome into console text and an exit code.
+
+
+@dataclass(frozen=True)
+class InvisibleOptions:
+    """The invisible stage's knobs, as one value instead of a dozen parameters.
+
+    Mirrors ``InvisibleEngine.remove_watermark``. Immutable so a batch can build it once
+    and reuse it across every image while the engine itself is cached separately.
+    """
+
+    strength: float | None = None
+    pipeline: str = "qwen-zimage"
+    seed: int | None = None
+    hf_token: str | None = None
+    humanize: float = 0.0
+    unsharp: float = 0.0
+    adaptive_polish: bool | None = None
+    max_resolution: int | None = None
+    controlnet_scale: float = 1.0
+    cpu_offload: bool = True
+    tile: bool = False
+    tile_size: int = 1024
+    tile_overlap: int = 128
+    # Scrub even when no invisible watermark is locally detectable.
+    force: bool = False
+
+
+# What the invisible stage did. "unavailable" is the one outcome the caller must
+# surface loudly: the file looks processed but still carries the watermark.
+InvisibleOutcome = Literal["removed", "no-signal", "unavailable"]
+
+
+@dataclass(frozen=True)
+class RemoveAllResult:
+    """Outcome of :func:`remove_all` -- what each stage actually did."""
+
+    output: Path
+    visible_label: str | None  # the removed mark(s), or None when nothing fired
+    invisible: InvisibleOutcome
+
+
+class MetadataStripIncomplete(RuntimeError):
+    """AI metadata survived the strip, so no output was produced.
+
+    Raised BEFORE the final write, deliberately: the contract is that an incomplete
+    strip leaves nothing on disk rather than an AI-readable file the caller might ship.
+    """
+
+    def __init__(self, surviving: set[str]) -> None:
+        self.surviving = surviving
+        super().__init__(f"AI metadata survived the strip: {', '.join(sorted(surviving))}")
+
+
+class _SourceEvidence:
+    """One metadata extraction per source file, serving every stage of one call.
+
+    ``remove_all`` asks the same file two provenance questions -- which vendor the
+    metadata confirms (for the visible pass) and whether an invisible target exists
+    (for the scrub gate). Both start from the same file-backed extraction, and running
+    them independently paid for it twice.
+
+    Per-CALL only, never module-level: the pipeline REWRITES its input in place on some
+    paths (``batch`` with the output directory equal to the input), so a holder that
+    outlived one call would answer from pre-write evidence. The individual metadata
+    probes are memoized on content, which is what makes that safe -- this holder only
+    removes the remaining assembly work.
+
+    Every accessor fails safe exactly as the function it replaces does: an extraction or
+    verdict error yields no provenance (no relaxation) and an invisible target of True
+    (scrub rather than skip).
+    """
+
+    __slots__ = ("_evidence", "_extracted", "_path")
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._extracted = False
+        self._evidence: Any | None = None
+
+    def _extract(self) -> Any | None:
+        if not self._extracted:
+            self._extracted = True
+            with suppress(Exception):
+                from remove_ai_watermarks.identify import extract_provenance_evidence
+
+                self._evidence = extract_provenance_evidence(self._path)
+        return self._evidence
+
+    def visible_provenance(self) -> frozenset[str]:
+        """Vendor keys the metadata confirms; empty on any failure (no relaxation)."""
+        evidence = self._extract()
+        if evidence is None:
+            return frozenset()
+        # The suppress spans the VERDICT and the mapping, not just the extraction --
+        # `visible_provenance` fails safe as a whole, and a raise here would escape as a
+        # traceback where the old code returned an empty set.
+        with suppress(Exception):
+            from remove_ai_watermarks.identify import identify_from_evidence
+
+            report = identify_from_evidence(evidence)
+            return _provenance_from_report(report, self._path)
+        return frozenset()
+
+    def has_invisible_target(self) -> bool:
+        """Whether a diffusion target exists. True on any failure -- see the fail-safe
+        note on ``identify.has_invisible_target``: leaving a watermark on a paid removal
+        is worse than over-regenerating a clean image."""
+        evidence = self._extract()
+        if evidence is None:
+            return True
+        try:
+            from remove_ai_watermarks.identify import identify_from_evidence
+
+            report = identify_from_evidence(evidence, image_path=self._path, check_invisible=True)
+        except Exception:
+            return True
+        return bool(report.ai_from_metadata)
+
+
+def _provenance_from_report(report: Any, path: Path) -> frozenset[str]:
+    """Map an already-built report to the vendor keys it confirms.
+
+    Shared by :func:`visible_provenance` and the evidence holder so the two cannot
+    drift; which evidence confirms which mark is data on the registry row.
+    """
+    from remove_ai_watermarks.watermark_registry import known_marks
+
+    signal_names = {signal.name for signal in report.signals}
+    platform = (report.platform or "").lower()
+    keys: set[str] = set()
+    aigc = False
+    for mark in known_marks():
+        if any(token in platform for token in mark.provenance_platform_tokens):
+            keys.add(mark.key)
+        if "aigc" in mark.provenance_signals and "aigc" in signal_names:
+            aigc = True
+        elif any(name in signal_names for name in mark.provenance_signals):
+            keys.add(mark.key)
+    if aigc:
+        # The TC260 label is vendor-agnostic: which of its marks it confirms comes from
+        # the producer identity, not from the signal firing.
+        keys |= _tc260_vendors(path)
+    return frozenset(keys)
+
+
+def remove_all(
+    source: str | Path,
+    output: str | Path,
+    *,
+    backend: Backend = "auto",
+    sensitivity: Sensitivity = "auto",
+    invisible: InvisibleOptions | None = None,
+    engine: Any | None = None,
+    progress: Callable[[str, str], None] | None = None,
+) -> RemoveAllResult:
+    """Remove visible marks, the invisible watermark, and AI metadata, in that order.
+
+    Stages are chained through a file in the SYSTEM temp dir, not next to ``output``:
+    the point of staging is that the user never sees a partial output file during a long
+    model download, and writing the partial next to the final defeats that.
+
+    ``engine`` accepts an already-constructed ``InvisibleEngine`` so a batch can build
+    the model once; leave it None to construct one per call.
+
+    ``progress`` receives ``(stage, detail)`` per step -- ``stage`` is one of
+    ``visible`` / ``invisible`` / ``metadata`` and ``detail`` is a stable token, not
+    prose: the caller owns the wording. The invisible stage reports its
+    :data:`InvisibleOutcome`, plus a ``strength=<value>`` line before it runs.
+
+    Raises :class:`MetadataStripIncomplete` before writing anything when AI metadata
+    survives, and ``OSError`` when the output cannot be written.
+    """
+    import os
+    import tempfile
+
+    from remove_ai_watermarks import image_io, watermark_registry
+    from remove_ai_watermarks.metadata import strip_and_verify
+
+    def say(stage: str, detail: str) -> None:
+        if progress is not None:
+            progress(stage, detail)
+
+    opts = invisible if invisible is not None else InvisibleOptions()
+    src, out = Path(source), Path(output)
+    watermark_registry.validate_sensitivity(sensitivity)
+
+    image, alpha = image_io.read_bgr_and_alpha(src)
+    if image is None:
+        raise ValueError(f"Could not read image: {src}")
+
+    # One metadata extraction for the whole pipeline: the visible pass asks which
+    # vendor is confirmed and the scrub gate asks whether a target exists, and both
+    # start from the same evidence.
+    evidence = _SourceEvidence(src)
+
+    tmp_fd, tmp_name = tempfile.mkstemp(suffix=src.suffix)
+    os.close(tmp_fd)
+    staged = Path(tmp_name)
+    try:
+        # ── 1. Visible marks ──
+        result, removed = watermark_registry.remove_auto_marks(
+            image,
+            sensitivity=sensitivity,
+            provenance=evidence.visible_provenance(),
+            backend=backend,
+        )
+        visible_label = ", ".join(removed) if removed else None
+        say("visible", visible_label or "")
+        if not image_io.write_bgr_with_alpha(staged, result, alpha):
+            raise OSError(f"failed to write the staged intermediate: {staged}")
+
+        # ── 2. Invisible watermark ──
+        outcome = _run_invisible(src, staged, staged, opts, engine, say, evidence)
+
+        # ── 3. AI metadata ──
+        # Read the pristine ORIGINAL for provenance above and the STAGED file here:
+        # the visible pass has already dropped this file's C2PA.
+        _, leftover = strip_and_verify(staged, staged)
+        if leftover:
+            # Before the write, on purpose -- see MetadataStripIncomplete.
+            raise MetadataStripIncomplete(set(leftover))
+        say("metadata", "stripped")
+
+        # The invisible stage (and the cv2.IMREAD_COLOR paths under it) drops alpha, so
+        # re-attach the ORIGINAL alpha plane unchanged for transparent formats.
+        final_bgr, _ = image_io.read_bgr_and_alpha(staged)
+        if final_bgr is None:
+            raise OSError(f"failed to read back the staged intermediate: {staged}")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if not image_io.write_bgr_with_alpha(out, final_bgr, alpha):
+            raise OSError(f"failed to write output (is the destination writable?): {out}")
+    finally:
+        if staged.exists():
+            staged.unlink()
+    return RemoveAllResult(out, visible_label, outcome)
+
+
+def _run_invisible(
+    vendor_source: Path,
+    in_path: Path,
+    out_path: Path,
+    opts: InvisibleOptions,
+    engine: Any | None,
+    say: Callable[[str, str], None],
+    evidence: _SourceEvidence,
+) -> InvisibleOutcome:
+    """Run, or deliberately skip, the diffusion scrub.
+
+    ``vendor_source`` is the PRISTINE original: the staged/output file has already lost
+    its C2PA to the visible pass, so gating or resolving the vendor from it would always
+    read as "no signal" and "unknown vendor". ``in_path``/``out_path`` are what the
+    engine reads and writes (the same staged file for ``remove_all``, input->output for
+    an invisible-only batch).
+    """
+    from remove_ai_watermarks.invisible_engine import is_available
+
+    if not is_available():
+        say("invisible", "unavailable")
+        return "unavailable"
+    if not (opts.force or evidence.has_invisible_target()):
+        say("invisible", "no-signal")
+        return "no-signal"
+
+    from remove_ai_watermarks._internal.watermark_profiles import resolve_strength, vendor_for_strength
+
+    vendor = vendor_for_strength(vendor_source)
+    # Report the strength the engine will actually execute, resolved the same way it
+    # resolves it, so the reported value cannot drift from the executed one.
+    with suppress(Exception):
+        from PIL import Image
+
+        with Image.open(vendor_source) as probe:
+            say("invisible", f"strength={resolve_strength(opts.strength, vendor, opts.pipeline, size=probe.size)}")
+
+    if engine is None:
+        from remove_ai_watermarks.invisible_engine import InvisibleEngine
+
+        engine = InvisibleEngine(
+            pipeline=opts.pipeline,
+            hf_token=opts.hf_token,
+            progress_callback=lambda message: say("invisible", message),
+            controlnet_conditioning_scale=opts.controlnet_scale,
+            cpu_offload=opts.cpu_offload,
+        )
+    engine.remove_watermark(
+        image_path=in_path,
+        output_path=out_path,
+        strength=opts.strength,
+        seed=opts.seed,
+        humanize=opts.humanize,
+        unsharp=opts.unsharp,
+        adaptive_polish=opts.adaptive_polish,
+        max_resolution=opts.max_resolution,
+        vendor=vendor,
+        tile=opts.tile,
+        tile_size=opts.tile_size,
+        tile_overlap=opts.tile_overlap,
+    )
+    say("invisible", "removed")
+    return "removed"
+
+
+BatchMode = Literal["all", "visible", "metadata", "invisible"]
+
+
+@dataclass(frozen=True)
+class BatchSummary:
+    """Per-directory outcome of :func:`remove_batch`."""
+
+    processed: int
+    failed: int
+    # Files whose invisible watermark was left in place because the GPU extra is
+    # missing. Non-empty means the outputs LOOK processed but still carry it.
+    invisible_unavailable: list[Path]
+    errors: list[tuple[Path, str]]
+
+
+def remove_batch(
+    directory: str | Path,
+    output_dir: str | Path,
+    *,
+    mode: BatchMode = "all",
+    backend: Backend = "auto",
+    sensitivity: Sensitivity = "auto",
+    invisible: InvisibleOptions | None = None,
+    engine: Any | None = None,
+    progress: Callable[[Path, str, str], None] | None = None,
+) -> BatchSummary:
+    """Run one removal ``mode`` over every supported image in ``directory``.
+
+    Never raises for a single bad image: a per-file failure is counted and recorded in
+    ``BatchSummary.errors`` so one unreadable file cannot abandon the rest of the
+    directory. ``engine`` is threaded straight through, so a caller that passes a
+    constructed ``InvisibleEngine`` loads the model once for the whole run.
+
+    ``progress`` receives ``(path, stage, detail)``. Every image ends with exactly one
+    terminal stage -- ``done`` or ``failed`` -- whatever the mode does in between, so a
+    caller driving a progress bar can advance on that alone.
+    """
+    from remove_ai_watermarks._internal.utils import is_supported_format
+
+    src_dir, out_dir = Path(directory), Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    def say(path: Path, stage: str, detail: str) -> None:
+        if progress is not None:
+            progress(path, stage, detail)
+
+    processed = failed = 0
+    unavailable: list[Path] = []
+    errors: list[tuple[Path, str]] = []
+    for img_path in sorted(p for p in src_dir.iterdir() if is_supported_format(p)):
+        out_path = out_dir / img_path.name
+        try:
+            outcome = _run_batch_one(img_path, out_path, mode, backend, sensitivity, invisible, engine, say)
+        except Exception as exc:
+            failed += 1
+            errors.append((img_path, str(exc)))
+            say(img_path, "failed", str(exc))
+            continue
+        processed += 1
+        if outcome == "unavailable":
+            unavailable.append(img_path)
+        # Exactly one terminal event per image, in every mode: a caller's progress bar
+        # advances on this and nothing else. Keying it off a mode-specific stage line
+        # left `visible` and `metadata` runs sitting at 0% for the whole batch.
+        say(img_path, "done", outcome or "")
+    return BatchSummary(processed, failed, unavailable, errors)
+
+
+def _run_batch_one(
+    img_path: Path,
+    out_path: Path,
+    mode: BatchMode,
+    backend: Backend,
+    sensitivity: Sensitivity,
+    invisible: InvisibleOptions | None,
+    engine: Any | None,
+    say: Callable[[Path, str, str], None],
+) -> InvisibleOutcome | None:
+    """One image, one mode. Returns the invisible outcome when that stage ran."""
+    from remove_ai_watermarks import image_io
+    from remove_ai_watermarks.metadata import strip_and_verify
+
+    if mode == "all":
+        result = remove_all(
+            img_path,
+            out_path,
+            backend=backend,
+            sensitivity=sensitivity,
+            invisible=invisible,
+            engine=engine,
+            progress=lambda stage, detail: say(img_path, stage, detail),
+        )
+        return result.invisible
+
+    # NOTE on holders in batch: `out_path` may EQUAL `img_path` (nothing forbids
+    # `-o <the input directory>`), and the visible stage rewrites it. So each stage that
+    # asks the file a provenance question builds its OWN holder, after any write that
+    # precedes it. One holder spanning the write would answer the invisible gate from
+    # pre-write evidence and scrub a file that today is correctly skipped.
+    if mode == "visible":
+        # Deliberately NOT `remove_visible`: its no-op branch copies the original bytes
+        # through when nothing was removed, which is right for a single lossless call
+        # and wrong here. A batch must produce every output through the one writer, so a
+        # failed write RAISES and the run is counted and exits non-zero -- a read-only
+        # output directory once produced zero files and still exited 0 (Tier E).
+        # Always read the ORIGINAL: a stale out_path from a previous run must not be
+        # re-processed as if it were the input.
+        from remove_ai_watermarks import watermark_registry
+
+        image, alpha = image_io.read_bgr_and_alpha(img_path)
+        if image is None:
+            raise ValueError(f"Could not read image: {img_path}")
+        result, _ = watermark_registry.remove_auto_marks(
+            image,
+            sensitivity=sensitivity,
+            provenance=visible_provenance(img_path),
+            backend=backend,
+        )
+        if not image_io.write_bgr_with_alpha(out_path, result, alpha):
+            raise OSError(f"failed to write output (is the destination writable?): {out_path}")
+        return None
+
+    if mode == "metadata":
+        _, leftover = strip_and_verify(img_path, out_path)
+        if leftover:
+            raise MetadataStripIncomplete(set(leftover))
+        return None
+
+    # invisible-only: no preceding visible pass, so out_path does not exist yet, and
+    # the input IS the pristine original for both the gate and the vendor probe.
+    outcome = _run_invisible(
+        img_path,
+        img_path,
+        out_path,
+        invisible if invisible is not None else InvisibleOptions(),
+        engine,
+        lambda stage, detail: say(img_path, stage, detail),
+        _SourceEvidence(img_path),
+    )
+    if not out_path.exists():
+        # Keep the output directory COMPLETE even when the pixels are deliberately
+        # left alone; a hole the caller cannot see is worse than an unchanged copy.
+        src_bgr, src_alpha = image_io.read_bgr_and_alpha(img_path)
+        if src_bgr is None or not image_io.write_bgr_with_alpha(out_path, src_bgr, src_alpha):
+            raise OSError(f"failed to copy input through to output: {out_path}")
+    return outcome

src/remove_ai_watermarks/baidu_engine.py

@@ -30,11 +30,14 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkLocation,
+)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image SHORT side (measured basis). The
@@ -100,79 +103,51 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-BaiduDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Baidu alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "百度" silhouette (255 = glyph) from the alpha map, or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Baidu glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class BaiduEngine(TextMarkEngine):
     """Detect/localize the visible Baidu "百度 AI生成" mark (bottom-right; localize -> fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
 
-    def footprint_mask(
-        self, image: NDArray[Any] | None, *, force: bool = False, dilate: int | None = None
-    ) -> NDArray[Any] | None:
-        """Full-frame mask of the WHOLE mark (text run + the pill tag to its right).
+    def _footprint_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Bound the fill by the detector's match box, never by the binary glyph blob.
 
         The base class's blob-bbox footprint UNDERCOVERS this mark: the white tag's
         flat interior gives no top-hat response (a top-hat answers edges, not flats),
         so the blob ends at the text run and the fill leaves the tag's right half as
         a ghost (measured 2026-07-22 on the 768x1024 cohort frame: blob bbox x
-        632..746 vs the tag ending ~758). The layout is measured and fixed -- the
-        text run is at the left of the locate box, the tag runs to the corner -- so
-        the footprint is the detector's match box extended RIGHT to the corner.
+        632..746 vs the tag ending ~758).
         """
-        if image is None or image.size == 0:
-            return None
+        return self._match_box_rect(image, loc, force=force, detection=detection)
 
-        from remove_ai_watermarks import image_io, region_eraser
+    def _extend_match_box(
+        self, box: tuple[int, int, int, int], loc: TextMarkLocation, frame: tuple[int, int]
+    ) -> tuple[int, int, int, int]:
+        """Extend the match box RIGHT to the corner end of the locate box.
 
-        image = image_io.to_bgr(image)
-        h, w = image.shape[:2]
-        if h < 32 or w < 64:
-            return None
-        loc = self.locate(image)
+        The layout is measured and fixed: the text run is at the left of the locate
+        box and the tag runs to the corner, so the mark's right edge is the box's.
+        """
+        gx0, gy0, _gx1, gy1 = box
         bx, by, bw, bh = loc.bbox
-        if force:
-            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
-        else:
-            if not self.detect(image).detected:
-                return None
-            _, box = self._tophat_best(image, loc)
-            if box is None:
-                return None
-            gx0, gy0, _gx1, gy1 = box
-            pad = max(4, int(0.15 * bh))
-            rx1 = max(0, bx + gx0 - pad)
-            ry1 = max(0, by + gy0 - pad)
-            rx2 = min(w, bx + bw)  # the tag runs to the corner end of the box
-            ry2 = min(h, by + gy1 + 1 + pad)
-        if rx1 >= rx2 or ry1 >= ry2:
-            return None
-        d = dilate if dilate is not None else max(3, int(0.02 * bw))
-        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img
+        h, w = frame
+        pad = max(4, int(0.15 * bh))
+        return (
+            max(0, bx + gx0 - pad),
+            max(0, by + gy0 - pad),
+            min(w, bx + bw),  # the tag runs to the corner end of the box
+            min(h, by + gy1 + 1 + pad),
+        )

src/remove_ai_watermarks/cli.py

@@ -14,7 +14,6 @@ import contextlib
 import json
 import logging
 import time
-from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, NoReturn
 
@@ -44,6 +43,8 @@ if TYPE_CHECKING:
 
     from numpy.typing import NDArray
 
+    from remove_ai_watermarks.api import InvisibleOptions
+
 
 # ── plain-text output layer (replaces rich: no colors, no markup, no boxes) ──
 
@@ -81,7 +82,10 @@ class _Progress:
     def __enter__(self) -> _Progress:
         return self
 
-    def __exit__(self, *exc: object) -> bool:
+    def __exit__(self, *exc: object) -> Literal[False]:
+        # Literal[False], not bool: a plain `bool` tells a type checker this context
+        # manager MAY suppress an exception, which makes every name bound inside a
+        # `with` block conditionally bound afterwards. It never suppresses.
         return False
 
     def add_task(self, *args: Any, **kwargs: Any) -> int:
@@ -167,6 +171,23 @@ def _resolved_strength_for_display(
         return resolve_strength(strength, vendor, pipeline, size=image.size)
 
 
+# -o/--output is the most-repeated option in this module. The image commands and the
+# video commands differ only in the default they describe, so there are two decorators
+# rather than one -- same reason as every other shared option here: define it once so
+# the help text cannot drift between commands.
+_output_option = click.option(
+    "-o", "--output", type=click.Path(path_type=Path), default=None, help="Output path (default: <source>_clean.<ext>)."
+)
+
+_video_output_option = click.option(
+    "-o",
+    "--output",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Output path (default: <source>_clean with the same container).",
+)
+
+
 # Shared option decorator for commands that run the invisible-watermark pipeline.
 # Both cmd_invisible and cmd_all expose this flag; defining it once avoids
 # copy-paste drift.
@@ -327,38 +348,6 @@ def _visible_provenance(path: Path | None) -> frozenset[str]:
     return visible_provenance(path)
 
 
-def _remove_visible_auto(
-    image: NDArray[Any],
-    *,
-    source_path: Path | None = None,
-    backend: str = "auto",
-    sensitivity: str = "auto",
-) -> tuple[NDArray[Any], str | None]:
-    """Remove every auto-detected visible mark via the registry (localize -> fill).
-
-    Routes the ``all``/``batch`` visible step through the same registry path the
-    standalone ``visible`` command uses, so every registered mark is handled rather
-    than only the Gemini sparkle.
-    Returns ``(result, label-or-None)``; when no ``in_auto`` mark fires the image is
-    returned unchanged with ``None``. ``backend`` selects the shared fill; ``sensitivity``
-    controls how hard a borderline mark is trusted (auto reads metadata provenance)."""
-    from remove_ai_watermarks import watermark_registry
-
-    bk: watermark_registry.Backend = backend  # type: ignore[assignment]
-    sens = _parse_sensitivity(sensitivity)
-    provenance = _visible_provenance(source_path)
-    try:
-        result, removed = watermark_registry.remove_auto_marks(
-            image, sensitivity=sens, provenance=provenance, backend=bk
-        )
-    except RuntimeError as e:  # e.g. a selected migan/lama backend whose extra is absent
-        console.print(f"  Error: {e}")
-        raise SystemExit(1) from e
-    if not removed:
-        return image, None
-    return result, ", ".join(removed)
-
-
 def _parse_sensitivity(value: str) -> watermark_registry.Sensitivity:
     """Map the CLI ``--sensitivity`` choice to the registry literal.
 
@@ -607,7 +596,9 @@ def _run_visible_explicit(
     t0 = time.monotonic()
     try:
         with console.status(f"Removing {chosen.label}... ({resolved_backend})"):
-            result, _ = chosen.remove(image, backend=backend, provenance=relax, force=not detect)
+            # Reuse the detection printed above instead of re-detecting inside remove():
+            # nothing has touched `image` since, and the trust level is the same one.
+            result, _ = chosen.remove(image, backend=backend, provenance=relax, force=not detect, detection=detection)
     except RuntimeError as e:  # selected migan/lama backend whose extra is absent
         console.print(f"  Error: {e}")
         raise SystemExit(1) from e
@@ -629,9 +620,7 @@ def _run_visible_explicit(
 
 @main.command("visible")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
-@click.option(
-    "-o", "--output", type=click.Path(path_type=Path), default=None, help="Output path (default: <source>_clean.<ext>)."
-)
+@_output_option
 @click.option("--detect/--no-detect", default=True, help="Detect watermark before removal.")
 @click.option(
     "--mark",
@@ -713,9 +702,7 @@ def _parse_region(spec: str) -> tuple[int, int, int, int]:
 @main.command("erase")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.option("--region", "regions", multiple=True, required=True, help="x,y,w,h box to erase (repeatable).")
-@click.option(
-    "-o", "--output", type=click.Path(path_type=Path), default=None, help="Output path (default: <source>_clean.<ext>)."
-)
+@_output_option
 @click.option(
     "--backend",
     type=click.Choice(["cv2", "migan", "lama"]),
@@ -787,9 +774,7 @@ def cmd_erase(
 # ── Invisible watermark removal ──
 @main.command("invisible")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
-@click.option(
-    "-o", "--output", type=click.Path(path_type=Path), default=None, help="Output path (default: <source>_clean.<ext>)."
-)
+@_output_option
 @_strength_option
 @_pipeline_option
 @_seed_option
@@ -1066,13 +1051,7 @@ def cmd_video_identify(source: Path, no_visible: bool, as_json: bool) -> None:
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.option("--check", is_flag=True, help="Check for AI metadata (don't modify).")
 @click.option("--remove", is_flag=True, help="Remove AI metadata.")
-@click.option(
-    "-o",
-    "--output",
-    type=click.Path(path_type=Path),
-    default=None,
-    help="Output path (default: <source>_clean with the same container).",
-)
+@_video_output_option
 @click.option("--keep-standard/--remove-all", default=True, help="Keep standard metadata.")
 def cmd_video_metadata(
     source: Path,
@@ -1110,13 +1089,7 @@ def cmd_video_metadata(
 
 @cmd_video.command("invisible")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
-@click.option(
-    "-o",
-    "--output",
-    type=click.Path(path_type=Path),
-    default=None,
-    help="Output path (default: <source>_clean with the same container).",
-)
+@_video_output_option
 @_video_invisible_options
 def cmd_video_invisible(
     source: Path,
@@ -1158,13 +1131,7 @@ def cmd_video_invisible(
 
 @cmd_video.command("visible")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
-@click.option(
-    "-o",
-    "--output",
-    type=click.Path(path_type=Path),
-    default=None,
-    help="Output path (default: <source>_clean with the same container).",
-)
+@_video_output_option
 @_video_visible_options
 @click.option("--strip-metadata/--keep-metadata", default=True, help="Strip AI metadata from the transcoded output.")
 def cmd_video_visible(
@@ -1206,13 +1173,7 @@ def cmd_video_visible(
 
 @cmd_video.command("all")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
-@click.option(
-    "-o",
-    "--output",
-    type=click.Path(path_type=Path),
-    default=None,
-    help="Output path (default: <source>_clean with the same container).",
-)
+@_video_output_option
 @_video_visible_options
 @click.option(
     "--invisible/--no-invisible",
@@ -1427,9 +1388,7 @@ def cmd_identify(ctx: click.Context, source: Path, no_visible: bool, as_json: bo
 # ── Combined "all" mode ──
 @main.command("all")
 @click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
-@click.option(
-    "-o", "--output", type=click.Path(path_type=Path), default=None, help="Output path (default: <source>_clean.<ext>)."
-)
+@_output_option
 @_visible_backend_option
 @_visible_sensitivity_option
 @_strength_option
@@ -1483,131 +1442,81 @@ def cmd_all(
 
     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
+    from remove_ai_watermarks.api import InvisibleOptions, MetadataStripIncomplete, remove_all
 
-    # Use a temp file for intermediate results so the user doesn't see
-    # a partial output file during long model downloads.
-    import tempfile
+    stage_labels = {
+        "visible": "\n  1) Visible watermark removal",
+        "invisible": "\n  2) Invisible watermark removal",
+        "metadata": "\n  3) AI metadata stripping",
+    }
+    # The library reports WHAT happened as a (stage, detail) pair of stable tokens; the
+    # console wording is the CLI's business. These two skips in particular carry guidance
+    # a library caller does not need but a user very much does.
+    stage_text = {
+        ("invisible", "no-signal"): (
+            "Skipped (no invisible AI watermark detected; pixels left intact).\n"
+            "    Not a clean-image guarantee: a pixel SynthID is undetectable once its\n"
+            "    metadata proxy is gone. Re-run with --force to scrub regardless."
+        ),
+        ("invisible", "unavailable"): (
+            f"Warning: Skipped - GPU dependencies not installed.\n    Install them with: pip install {INVISIBLE_EXTRA}"
+        ),
+        ("invisible", "removed"): "Invisible watermark removed",
+        ("metadata", "stripped"): "AI metadata stripped",
+    }
+    seen: set[str] = set()
 
-    tmp_fd, tmp_path_str = tempfile.mkstemp(suffix=source.suffix)
-    tmp_path = Path(tmp_path_str)
-    try:
-        import os
-
-        os.close(tmp_fd)
-
-        # ── Step 1: Visible watermark ──
-        console.print("\n  1) Visible watermark removal")
-        image, alpha = image_io.read_bgr_and_alpha(source)
-        if image is None:
-            console.print(f"Error: Failed to read image: {source}")
-            raise SystemExit(1)
-
-        h, w = image.shape[:2]
-        console.print(f"    Input: {source.name}  ({w}x{h})")
-
-        with console.status("Removing visible watermark..."):
-            result, removed_label = _remove_visible_auto(
-                image, source_path=source, backend=backend, sensitivity=sensitivity
-            )
-            if removed_label is not None:
-                console.print(f"    Visible watermark removed ({removed_label})")
-            else:
-                console.print("    Skipped (no visible watermark detected)")
-
-        # Save to temp file for invisible engine input (preserve alpha if present)
-        image_io.write_bgr_with_alpha(tmp_path, result, alpha)
-
-        # ── Step 2: Invisible watermark ──
-        console.print("\n  2) Invisible watermark removal")
-        from remove_ai_watermarks.invisible_engine import is_available as invisible_available
-
-        if not invisible_available():
-            synthid_skipped = True
+    def progress(stage: str, detail: str) -> None:
+        if stage in stage_labels and stage not in seen:
+            seen.add(stage)
+            console.print(stage_labels[stage])
+        if (text := stage_text.get((stage, detail))) is not None:
+            console.print(f"    {text}")
+        elif stage == "visible":
             console.print(
-                "    Warning: Skipped - GPU dependencies not installed.\n"
-                f"    Install them with: pip install {INVISIBLE_EXTRA}"
-            )
-        elif _should_skip_invisible_scrub(force, source):
-            # No locally-detectable invisible watermark -> skip the destructive
-            # regeneration (it would only degrade the image). The visible-removed
-            # pixels in tmp_path are kept and step 3 still strips metadata, so this
-            # is a SUCCESS (exit 0), unlike the GPU-missing skip above. Read the
-            # pristine `source`, not tmp_path whose C2PA the visible pass already
-            # dropped. Not a clean-image guarantee; --force overrides.
-            console.print(
-                "    Skipped (no invisible AI watermark detected; pixels left intact).\n"
-                "    Not a clean-image guarantee: a pixel SynthID is undetectable once its\n"
-                "    metadata proxy is gone. Re-run with --force to scrub regardless."
+                f"    Visible watermark removed ({detail})" if detail else "    Skipped (no visible watermark detected)"
             )
+        elif detail.startswith("strength="):
+            console.print(f"    Strength: {detail.removeprefix('strength=')}")
         else:
-            from remove_ai_watermarks.invisible_engine import InvisibleEngine
+            console.print(f"    {detail}")
 
-            def progress_cb(msg: str) -> None:
-                console.print(f"    {msg}")
-
-            inv_engine = InvisibleEngine(
-                pipeline=pipeline,
-                hf_token=hf_token,
-                progress_callback=progress_cb,
-                controlnet_conditioning_scale=controlnet_scale,
-                cpu_offload=cpu_offload,
-            )
-
-            # Detect the vendor from the pristine ORIGINAL (`source`); `tmp_path` has
-            # already lost its C2PA to the visible-removal pass, so reading it would
-            # always resolve to the unknown-vendor default.
-            vendor = vendor_for_strength(source)
-            console.print(f"    Strength: {_resolved_strength_for_display(source, strength, vendor, pipeline)}")
-            inv_engine.remove_watermark(
-                image_path=tmp_path,
-                output_path=tmp_path,
+    try:
+        outcome = remove_all(
+            source,
+            output,
+            backend=backend,  # type: ignore[arg-type]
+            sensitivity=_parse_sensitivity(sensitivity),
+            invisible=InvisibleOptions(
                 strength=strength,
+                pipeline=pipeline,
                 seed=seed,
+                hf_token=hf_token,
                 humanize=humanize,
                 unsharp=unsharp,
                 adaptive_polish=adaptive_polish,
                 max_resolution=max_resolution,
-                vendor=vendor,
+                controlnet_scale=controlnet_scale,
+                cpu_offload=cpu_offload,
                 tile=tile,
                 tile_size=tile_size,
                 tile_overlap=tile_overlap,
-            )
-            console.print("    Invisible watermark removed")
-
-        # ── Step 3: Metadata ──
-        console.print("\n  3) AI metadata stripping")
-        try:
-            from remove_ai_watermarks.metadata import strip_and_verify
-
-            _, leftover = strip_and_verify(tmp_path, tmp_path)
-        except Exception as e:
-            console.print(f"    Error: metadata strip failed: {e}")
-            raise SystemExit(1) from e
-        if leftover:
-            console.print(f"    Error: metadata stripping was incomplete; {', '.join(sorted(leftover))} survived")
-            raise SystemExit(1)
-        console.print("    AI metadata stripped")
-
-        # ── Write final result ──
-        # The invisible step (and downstream cv2.IMREAD_COLOR paths) drops alpha,
-        # so re-attach the original alpha plane unchanged when writing the final
-        # output for transparent formats.
-        final_bgr, _ = image_io.read_bgr_and_alpha(tmp_path)
-        if final_bgr is None:
-            console.print(f"Error: Failed to read intermediate file: {tmp_path}")
-            raise SystemExit(1)
-        _write_output_or_exit(output, final_bgr, alpha)
-
-    finally:
-        # Clean up temp file if it still exists
-        if tmp_path.exists():
-            tmp_path.unlink()
+                force=force,
+            ),
+            progress=progress,
+        )
+    except MetadataStripIncomplete as e:
+        console.print(f"    Error: metadata stripping was incomplete; {', '.join(sorted(e.surviving))} survived")
+        raise SystemExit(1) from e
+    except ValueError as e:
+        console.print(f"Error: {e}")
+        raise SystemExit(1) from e
+    except RuntimeError as e:  # a selected migan/lama backend whose extra is absent
+        console.print(f"  Error: {e}")
+        raise SystemExit(1) from e
+    except OSError as e:
+        console.print(f"  Error: {e}")
+        raise SystemExit(1) from e
 
     # ── Done ──
     elapsed = time.monotonic() - t0
@@ -1618,7 +1527,7 @@ def cmd_all(
     # 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:
+    if outcome.invisible == "unavailable":
         console.print(
             "\n  =====================================================================\n"
             "  WARNING: the invisible (SynthID) watermark was NOT removed.\n"
@@ -1634,172 +1543,26 @@ def cmd_all(
 
 
 # ── Batch command ──
-def _passthrough_copy(img_path: Path, out_path: Path) -> None:
-    """Copy the input's pixels through to ``out_path`` unchanged (the invisible-mode skip
-    paths), so the output dir stays complete without touching the pixels."""
-    src_bgr, src_alpha = image_io.read_bgr_and_alpha(img_path)
-    if src_bgr is not None and not image_io.write_bgr_with_alpha(out_path, src_bgr, src_alpha):
-        # The point of this copy is to keep the output dir COMPLETE. A silently-dropped
-        # copy defeats that and leaves a hole the caller cannot see (Tier E, 2026-07-20).
-        raise OSError(f"failed to copy input through to output: {out_path}")
+def _batch_engine(mode: str, options: InvisibleOptions) -> object | None:
+    """Build the ONE invisible engine this batch reuses, or None.
 
-
-@dataclass(frozen=True)
-class _BatchOptions:
-    """Validated processing options shared by every image in one batch.
-
-    Click necessarily exposes these as individual command parameters, but the
-    processing core should receive one coherent value instead of a long positional
-    call. Keeping the object immutable also makes it safe to reuse while the
-    batch caches model instances in ``ctx.obj``.
+    Called once per run, not per image: ``--pipeline`` is a single CLI value, constant
+    across the batch, so building the model here and threading it down is what keeps the
+    diffusion stack from reloading for every file. Modes that never scrub get None, so
+    nothing is loaded at all.
     """
+    if mode not in ("all", "invisible"):
+        return None
+    from remove_ai_watermarks.invisible_engine import InvisibleEngine, is_available
 
-    strength: float | None
-    pipeline: str
-    seed: int | None
-    hf_token: str | None
-    humanize: float
-    backend: str = "auto"
-    sensitivity: str = "auto"
-    unsharp: float = 0.0
-    max_resolution: int = 0
-    controlnet_scale: float = 1.0
-    # None means "the user did not choose"; the library resolves it per profile.
-    adaptive_polish: bool | None = None
-    tile: bool = False
-    tile_size: int = 1024
-    tile_overlap: int = 128
-    force: bool = False
-    cpu_offload: bool = False
-
-
-def _run_batch_invisible(
-    ctx: click.Context,
-    img_path: Path,
-    out_path: Path,
-    mode: str,
-    options: _BatchOptions,
-) -> bool:
-    """Run or safely skip the invisible pass for one batch image.
-
-    Returns ``True`` only when a detectable target could not be processed because
-    the GPU dependencies are missing. The availability probe is intentionally
-    evaluated once so branching cannot observe inconsistent optional-dependency
-    state.
-    """
-    from remove_ai_watermarks.invisible_engine import is_available as invisible_available
-
-    skip_no_signal = _should_skip_invisible_scrub(options.force, img_path)
-    available = invisible_available()
-    if available and not skip_no_signal:
-        from remove_ai_watermarks.invisible_engine import InvisibleEngine
-
-        # 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 options.pipeline not in engines:
-            engines[options.pipeline] = InvisibleEngine(
-                pipeline=options.pipeline,
-                hf_token=options.hf_token,
-                controlnet_conditioning_scale=options.controlnet_scale,
-                cpu_offload=options.cpu_offload,
-            )
-        engines[options.pipeline].remove_watermark(
-            img_path if mode == "invisible" else out_path,
-            out_path,
-            strength=options.strength,
-            seed=options.seed,
-            humanize=options.humanize,
-            unsharp=options.unsharp,
-            adaptive_polish=options.adaptive_polish,
-            max_resolution=options.max_resolution,
-            tile=options.tile,
-            tile_size=options.tile_size,
-            tile_overlap=options.tile_overlap,
-            # Detect the vendor from the pristine original (`img_path`), not the
-            # visible-processed `out_path` whose C2PA is already gone.
-            vendor=vendor_for_strength(img_path),
-        )
-        return False
-
-    # Invisible-only mode has no preceding visible pass to create ``out_path``.
-    # Preserve a complete output directory while deliberately leaving pixels intact.
-    if mode == "invisible" and not out_path.exists():
-        _passthrough_copy(img_path, out_path)
-    return not available and not skip_no_signal
-
-
-def _process_batch_image(
-    ctx: click.Context,
-    img_path: Path,
-    out_path: Path,
-    mode: str,
-    options: _BatchOptions,
-) -> bool:
-    """Process a single image for batch mode.
-
-    Applies the requested watermark removal steps (visible, invisible,
-    metadata) to *img_path* and writes the result to *out_path*.
-
-    Returns True if the invisible (SynthID) scrub was skipped because the GPU deps
-    are missing while a signal was present -- so the batch caller can warn + exit
-    non-zero, mirroring the single ``all`` command.
-
-    Raises:
-        ValueError: If the image cannot be opened.
-    """
-    saved_alpha: NDArray[Any] | None = None
-    synthid_skipped = False
-
-    if mode in ("visible", "all"):
-        # 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 = image_io.read_bgr_and_alpha(img_path)
-        if image is None:
-            raise ValueError("Failed to read image")
-
-        result, _ = _remove_visible_auto(
-            image,
-            source_path=img_path,
-            backend=options.backend,
-            sensitivity=options.sensitivity,
-        )
-
-        # RAISE, never SystemExit: the batch loop catches per-image exceptions, counts
-        # them and exits non-zero. Discarding this flag made a read-only output directory
-        # produce ZERO files and still exit 0 -- silent data loss that also contradicted
-        # the documented batch contract (Tier E, 2026-07-20).
-        if not image_io.write_bgr_with_alpha(out_path, result, alpha):
-            raise OSError(f"failed to write output (is the destination writable?): {out_path}")
-        saved_alpha = alpha
-
-    if mode in ("invisible", "all"):
-        # Skip the destructive regeneration when no invisible watermark is locally
-        # detectable (would only degrade a clean image). Read the pristine `img_path`;
-        # `out_path` may already be the visible-processed result. --force overrides.
-        synthid_skipped = _run_batch_invisible(ctx, img_path, out_path, mode, options)
-
-    if mode in ("metadata", "all"):
-        from remove_ai_watermarks.metadata import strip_and_verify
-
-        # Same verification the single-image command does: the fail-safe copy-through
-        # would otherwise leave an AI-reading output and still exit 0, contradicting the
-        # batch contract that a failed image must make the run exit non-zero.
-        _, leftover = strip_and_verify(img_path if mode == "metadata" else out_path, out_path)
-        if leftover:
-            msg = f"AI metadata survived the strip ({', '.join(sorted(leftover))}); file could not be decoded"
-            raise RuntimeError(msg)
-
-    # In "all" mode, the invisible step (color-only OpenCV paths) drops alpha,
-    # so re-attach the cached alpha when the input had transparency.
-    if mode == "all" and saved_alpha is not None:
-        final_bgr, _ = image_io.read_bgr_and_alpha(out_path)
-        if final_bgr is not None and not image_io.write_bgr_with_alpha(out_path, final_bgr, saved_alpha):
-            raise OSError(f"failed to re-attach alpha to output: {out_path}")
-
-    return synthid_skipped
+    if not is_available():
+        return None
+    return InvisibleEngine(
+        pipeline=options.pipeline,
+        hf_token=options.hf_token,
+        controlnet_conditioning_scale=options.controlnet_scale,
+        cpu_offload=options.cpu_offload,
+    )
 
 
 @main.command("batch")
@@ -1867,29 +1630,26 @@ def cmd_batch(
     console.print(f"  Found {len(images)} images in {directory}")
     console.print(f"  Output -> {output_dir}")
     console.print(f"  Mode: {mode}")
-    options = _BatchOptions(
+    from remove_ai_watermarks.api import InvisibleOptions
+    from remove_ai_watermarks.api import remove_batch as api_remove_batch
+
+    invisible_options = InvisibleOptions(
         strength=strength,
         pipeline=pipeline,
         seed=seed,
         hf_token=hf_token,
         humanize=humanize,
-        backend=backend,
-        sensitivity=sensitivity,
         unsharp=unsharp,
+        adaptive_polish=adaptive_polish,
         max_resolution=max_resolution,
         controlnet_scale=controlnet_scale,
-        adaptive_polish=adaptive_polish,
+        cpu_offload=cpu_offload,
         tile=tile,
         tile_size=tile_size,
         tile_overlap=tile_overlap,
         force=force,
-        cpu_offload=cpu_offload,
     )
 
-    processed = 0
-    errors = 0
-    synthid_skipped_count = 0
-
     with Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
@@ -1899,28 +1659,36 @@ def cmd_batch(
         console=console,
     ) as progress:
         task = progress.add_task("Processing...", total=len(images))
+        done: set[str] = set()
 
-        for img_path in images:
-            out_path = output_dir / img_path.name
-            progress.update(task, description=f"{img_path.name}")
+        def on_progress(img: Path, stage: str, detail: str) -> None:
+            # `remove_batch` emits exactly one terminal stage per image in EVERY mode,
+            # so the bar advances on that and never on a mode-specific line.
+            progress.update(task, description=img.name)
+            if stage in ("done", "failed") and img.name not in done:
+                done.add(img.name)
+                progress.advance(task)
+            if ctx.obj.get("verbose"):
+                console.print(f"  {img.name}: {stage}{f' {detail}' if detail else ''}")
 
-            try:
-                if _process_batch_image(
-                    ctx=ctx,
-                    img_path=img_path,
-                    out_path=out_path,
-                    mode=mode,
-                    options=options,
-                ):
-                    synthid_skipped_count += 1
-                processed += 1
+        summary = api_remove_batch(
+            directory,
+            output_dir,
+            mode=mode,  # type: ignore[arg-type]
+            backend=backend,  # type: ignore[arg-type]
+            sensitivity=_parse_sensitivity(sensitivity),
+            invisible=invisible_options,
+            engine=_batch_engine(mode, invisible_options),
+            progress=on_progress,
+        )
+        progress.update(task, completed=len(images))
 
-            except Exception as e:
-                errors += 1
-                if ctx.obj.get("verbose"):
-                    console.print(f"  {img_path.name}: {e}")
+    processed, errors = summary.processed, summary.failed
+    synthid_skipped_count = len(summary.invisible_unavailable)
 
-            progress.advance(task)
+    if errors and ctx.obj.get("verbose"):
+        for failed_path, message in summary.errors:
+            console.print(f"  {failed_path.name}: {message}")
 
     console.print(f"\n  {processed} processed" + (f"  {errors} errors" if errors else ""))
 

src/remove_ai_watermarks/doubao_engine.py

@@ -23,11 +23,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of image WIDTH (the mark scales with width, anchored
@@ -96,9 +94,6 @@ _CONFIG = TextMarkConfig(
     min_gw=8,
 )
 
-# Doubao-specific aliases for the shared detection result/engine.
-DoubaoDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Doubao alpha template (float [0,1]), or None."""
@@ -120,13 +115,3 @@ class DoubaoEngine(TextMarkEngine):
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/gemini_engine.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 import functools
 import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -72,6 +72,26 @@ class _Candidate:
         return self.spatial * 0.50 + self.gradient * 0.30 + self.variance * 0.20
 
 
+@dataclass(frozen=True, slots=True)
+class _SparkleScan:
+    """The provenance-BLIND half of sparkle detection, reusable across trust levels.
+
+    ``source`` is the BGR-normalized image the false-positive gate re-reads, ``best``
+    the winning candidate, and ``base`` a template result carrying everything the scan
+    already resolved (``size`` and, when a candidate won, ``region`` and the component
+    scores). ``best is None`` covers both no-candidate cases; ``base`` distinguishes
+    them, since an empty image never resolves a ``size`` and a candidate-less one does.
+
+    Per-CALL only, never cached on the engine: ``remove_auto_marks`` re-invokes each
+    engine on a progressively cleaned frame within one process, so a memo on ``self``
+    would hand back a pre-fill scan of a different image.
+    """
+
+    source: NDArray[Any] | None
+    best: _Candidate | None
+    base: DetectionResult
+
+
 def get_watermark_size(width: int, height: int) -> WatermarkSize:
     """Return the provider's large tier only when both axes exceed 1024."""
     return WatermarkSize.LARGE if width > 1024 and height > 1024 else WatermarkSize.SMALL
@@ -200,29 +220,62 @@ class GeminiEngine:
         trust_provenance: bool = False,
     ) -> DetectionResult:
         """Return the strongest sparkle-shaped bottom-right candidate."""
-        result = DetectionResult()
+        scan = self._sparkle_scan(image, force_size)
+        return self._verdict(scan, trust_provenance=trust_provenance)
+
+    def detect_watermark_both(
+        self, image: NDArray[Any], force_size: WatermarkSize | None = None
+    ) -> tuple[DetectionResult, DetectionResult]:
+        """``(strict, relaxed)`` from ONE scan of the image.
+
+        The scan -- global candidate search, corner promotion and fused scoring -- is
+        provenance-blind; ``trust_provenance`` only decides whether the false-positive
+        gate demotes the confidence afterwards. Two calls therefore repeated the whole
+        sweep to reach two verdicts.
+
+        The two results are DISTINCT objects with genuinely different confidences (the
+        gate rewrites one of them), and callers mutate them.
+        """
+        scan = self._sparkle_scan(image, force_size)
+        return (
+            self._verdict(scan, trust_provenance=False),
+            self._verdict(scan, trust_provenance=True),
+        )
+
+    def _sparkle_scan(self, image: NDArray[Any], force_size: WatermarkSize | None) -> _SparkleScan:
+        """Everything in detection that does not depend on the trust level."""
         if image is None or image.size == 0:
-            return result
+            return _SparkleScan(None, None, DetectionResult())
 
         source = image_io.to_bgr(image)
         height, width = source.shape[:2]
-        result.size = force_size or get_watermark_size(width, height)
+        size = force_size or get_watermark_size(width, height)
         candidates = self._global_candidates(source)
         promoted = self._corner_promote(source, candidates[0].spatial if candidates else -1.0)
         if promoted is not None:
             candidates.append(_Candidate(promoted[0], promoted[1], promoted[2], promoted[3]))
+        # The no-candidate result is NOT the empty-image one: `size` is already resolved
+        # here, and it is a public field the caller can force.
+        base = DetectionResult(size=size)
         if not candidates:
-            return result
+            return _SparkleScan(None, None, base)
 
         best = max((self._score_candidate(source, candidate) for candidate in candidates), key=lambda item: item.fused)
-        result.region = (best.x, best.y, best.scale, best.scale)
-        result.spatial_score = float(best.spatial)
-        result.gradient_score = float(best.gradient)
-        result.variance_score = float(best.variance)
+        base.region = (best.x, best.y, best.scale, best.scale)
+        base.spatial_score = float(best.spatial)
+        base.gradient_score = float(best.gradient)
+        base.variance_score = float(best.variance)
+        return _SparkleScan(source, best, base)
 
+    def _verdict(self, scan: _SparkleScan, *, trust_provenance: bool) -> DetectionResult:
+        """Apply the trust-level-dependent tail to a scan, as a fresh result object."""
+        result = replace(scan.base)
+        if scan.best is None or scan.source is None:
+            return result
+        best = scan.best
         confidence = best.fused
         if best.spatial >= 0.25 and confidence < self._SPARKLE_FP_CONF and not trust_provenance:
-            confidence = self._apply_false_positive_gate(source, best, confidence)
+            confidence = self._apply_false_positive_gate(scan.source, best, confidence)
         result.confidence = float(np.clip(confidence, 0.0, 1.0))
         result.detected = result.confidence >= 0.35
         return result

src/remove_ai_watermarks/identify.py

@@ -59,6 +59,7 @@ from remove_ai_watermarks.metadata import (
     xai_signature_pair,
 )
 from remove_ai_watermarks.watermark_registry import GEMINI_SPARKLE_TRUST_CONF
+from remove_ai_watermarks.watermark_registry import known_marks as _known_marks
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -446,14 +447,22 @@ _DEVICE_C2PA_PLATFORM: tuple[tuple[bytes, str], ...] = (
 )
 
 
-def _device_platform(head: bytes) -> str | None:
-    """Map a distinctive C2PA device/camera token in the manifest bytes to a platform."""
-    for token, platform in _DEVICE_C2PA_PLATFORM:
+def _first_token_match(head: bytes, table: tuple[tuple[bytes, str], ...]) -> str | None:
+    """First platform in ``table`` whose token appears in ``head``, else None.
+
+    Table order is priority: the more specific token must be listed first.
+    """
+    for token, platform in table:
         if token in head:
             return platform
     return None
 
 
+def _device_platform(head: bytes) -> str | None:
+    """Map a distinctive C2PA device/camera token in the manifest bytes to a platform."""
+    return _first_token_match(head, _DEVICE_C2PA_PLATFORM)
+
+
 # C2PA signers that are an editing app or AI-capable device rather than a
 # verified-capture camera. Unlike `_DEVICE_C2PA_PLATFORM`, these do NOT feed the
 # camera-vs-AI integrity clash (rule 2 in `_integrity_clashes`): a Galaxy phone
@@ -474,10 +483,7 @@ _SIGNER_C2PA_PLATFORM: tuple[tuple[bytes, str], ...] = (
 
 def _signer_platform(head: bytes) -> str | None:
     """Map a C2PA editing-app / AI-capable-device signer token to a platform."""
-    for token, platform in _SIGNER_C2PA_PLATFORM:
-        if token in head:
-            return platform
-    return None
+    return _first_token_match(head, _SIGNER_C2PA_PLATFORM)
 
 
 def _attribute_platform(issuers: list[str], *, is_ai: bool = True) -> str | None:
@@ -678,16 +684,18 @@ def _visible_sparkle(image_path: Path, *, image: NDArray[Any] | None = None) ->
 # Gemini-sparkle phrasing. These are the stripped-metadata visual fallback for
 # the China-served ByteDance generators (normally also caught by the TC260 AIGC
 # metadata label); the per-engine detection thresholds live in the registry.
-_VISIBLE_MARK_PLATFORM = {
-    "doubao": "ByteDance Doubao (visible 豆包AI生成 mark detected)",
-    "jimeng": "ByteDance Jimeng / Dreamina (visible 即梦AI mark detected)",
-    "qwen": "Alibaba Tongyi Qianwen (visible 千问AI生成 mark detected)",
-    "kling": "Kuaishou Kling (visible 可灵AI 3.0 mark detected)",
-    "yuanbao": "Tencent Yuanbao (visible 元宝 / AI生成 mark detected)",
-    "samsung": "Samsung Galaxy AI (visible 'Contenuti generati dall'AI' mark detected)",
-    "runninghub": "RunningHub (visible RunningHub AI生成 mark detected)",
-    "baidu": "Baidu (visible 百度 AI生成 mark detected)",
-    "liblib": "LibLibAI (visible LibLibAI mark detected)",
+# Text mark -> the platform sentence this report prints when that mark is the strongest
+# evidence, DERIVED from the registry rows so registering a mark is one edit. It was a
+# hand-maintained copy, and that class of copy is how LibLibAI ended up registered but
+# missing from the pill veto. Insertion order is the registry's, which is what fixes the
+# scan order below. The Gemini sparkle and the capture-less pill carry no platform of
+# their own (`KnownMark.platform is None`) and are excluded here: the sparkle has its
+# own higher-confidence `_visible_sparkle` path.
+#
+# Safe at module scope: `watermark_registry` is already imported above for
+# GEMINI_SPARKLE_TRUST_CONF, and it is deliberately cv2-free at import time.
+_VISIBLE_MARK_PLATFORM: dict[str, str] = {
+    mark.key: mark.platform for mark in _known_marks() if mark.platform is not None
 }
 
 
@@ -724,15 +732,20 @@ def _visible_text_marks(image_path: Path, *, image: NDArray[Any] | None = None)
     return detections
 
 
-def _invisible_watermark(image_path: Path) -> str | None:
+def _invisible_watermark(image_path: Path, decode: _SharedDecode) -> str | None:
     """Open invisible-watermark scheme name (SD/SDXL/FLUX) or None.
 
     Optional: needs the torch-free DWT-DCT decoder (extra ``detect``). Returns
     None if it is not installed or no known watermark decodes.
     """
-    from remove_ai_watermarks.invisible_watermark import detect_invisible_watermark
+    from remove_ai_watermarks.invisible_watermark import detect_invisible_watermark, is_available
 
-    return detect_invisible_watermark(image_path)
+    if not is_available():
+        return None
+    # `decode.get()` re-raises a decode failure exactly as the old unguarded
+    # `imread` inside the detector did -- `has_invisible_target` needs that to reach
+    # its fail-safe rather than silently reporting "no signal".
+    return detect_invisible_watermark(image_path, image=decode.get())
 
 
 def _trustmark(image_path: Path) -> str | None:
@@ -746,27 +759,79 @@ def _trustmark(image_path: Path) -> str | None:
     return detect_trustmark(image_path)
 
 
+class _SharedDecode:
+    """One decode of the source pixels, shared by every detector in a single report.
+
+    ``identify`` used to decode the file three times. This holder unifies TWO of
+    them -- the DWT-DCT detector and the visible-mark stage, whose own docstring
+    already promised a single shared array. TrustMark keeps its own Pillow decode
+    on purpose and is NOT served from here: cv2 and Pillow disagree on EXIF
+    orientation and on 16-bit PNG, so feeding it this array would change what it
+    decodes. An install carrying the optional ``trustmark`` extra therefore still
+    pays two decodes, not one.
+
+    Two accessors, because the two arms need OPPOSITE failure handling:
+
+    * :meth:`get_or_none` swallows a decode failure and logs it. That is the visible
+      arm's historical behavior -- no cv2, no visible marks, verdict unchanged.
+    * :meth:`get` RE-RAISES it. The invisible arm never caught a decode error, and
+      ``has_invisible_target`` converts that exception into its documented fail-safe
+      ``True``. Swallowing it here would silently skip a diffusion scrub on a file
+      that used to get one -- leaving a watermark on a paid removal.
+
+    Per-CALL only: constructed inside ``_identify_from_evidence`` and discarded with
+    it, so an in-place rewrite between calls can never be answered from a stale array.
+    """
+
+    __slots__ = ("_done", "_error", "_image", "_path")
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._done = False
+        self._image: NDArray[Any] | None = None
+        self._error: Exception | None = None
+
+    def _decode(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        try:
+            from remove_ai_watermarks.image_io import imread
+
+            self._image = imread(self._path)
+        except Exception as exc:  # cv2 missing / unreadable container
+            self._error = exc
+
+    def get(self) -> NDArray[Any] | None:
+        """The decoded array; re-raises a decode failure, None only on a clean miss."""
+        self._decode()
+        if self._error is not None:
+            raise self._error
+        return self._image
+
+    def get_or_none(self) -> NDArray[Any] | None:
+        """The decoded array, or None when it could not be decoded at all."""
+        self._decode()
+        if self._error is not None:
+            logger.debug("visible-mark decode unavailable: %s", self._error)
+            return None
+        return self._image
+
+
 def _collect_visible_signals(
     image_path: Path,
     signals: list[Signal],
     watermarks: list[str],
     platform: str | None,
+    decode: _SharedDecode,
 ) -> str | None:
-    """Decode once, append every trusted visible-mark signal, and return platform.
+    """Append every trusted visible-mark signal and return platform.
 
-    Keeping this stage separate from metadata aggregation makes the optional cv2
-    boundary explicit and guarantees that all visible detectors share one decoded
-    BGR array. A decode failure preserves the detectors' historical fallback/no-op
-    behavior.
+    All visible detectors share the one decoded BGR array held by ``decode`` (which
+    the invisible detectors have usually already paid for). A decode failure
+    preserves the detectors' historical fallback/no-op behavior.
     """
-    image: NDArray[Any] | None = None
-    try:
-        from remove_ai_watermarks.image_io import imread
-
-        image = imread(image_path)
-    except Exception as exc:  # cv2 missing - detectors fall back / no-op
-        logger.debug("visible-mark decode unavailable: %s", exc)
-        return platform
+    image = decode.get_or_none()
     if image is None:
         return platform
 
@@ -800,6 +865,10 @@ def _identify_from_evidence(
     if (check_visible or check_invisible) and image_path is None:
         raise ValueError("Pixel-backed checks require image_path")
     pixel_path = image_path
+    # One decode for every pixel detector in this report. Built here, per call, so it
+    # dies with the report -- an in-place rewrite between two calls cannot be answered
+    # from a stale array. Lazy inside, so a metadata-only report never decodes at all.
+    decode = _SharedDecode(pixel_path) if pixel_path is not None else _SharedDecode(evidence.path)
 
     info = evidence.c2pa_info
     meta = evidence.ai_metadata
@@ -1006,7 +1075,7 @@ def _identify_from_evidence(
 
     # ── Open invisible watermark (SD / SDXL / FLUX, dwtDct) ──────────
     # Public decoder, no key -- a definitive embedded signal on pristine files.
-    if check_invisible and pixel_path is not None and (scheme := _invisible_watermark(pixel_path)) is not None:
+    if check_invisible and pixel_path is not None and (scheme := _invisible_watermark(pixel_path, decode)) is not None:
         signals.append(Signal("invisible_watermark", scheme, "high"))
         watermarks.append(f"Open invisible watermark: {scheme}")
         caveats.append(_INVISIBLE_WM_CAVEAT)
@@ -1039,7 +1108,7 @@ def _identify_from_evidence(
     )
 
     if check_visible and pixel_path is not None:
-        platform = _collect_visible_signals(pixel_path, signals, watermarks, platform)
+        platform = _collect_visible_signals(pixel_path, signals, watermarks, platform, decode)
 
     visible_only = any(s.name.startswith("visible_") for s in signals) and not ai_from_metadata
     hf_only = bool(hf_job) and not ai_from_metadata
@@ -1078,9 +1147,27 @@ def _identify_from_evidence(
     )
 
 
-def identify_from_evidence(evidence: ProvenanceEvidence) -> ProvenanceReport:
-    """Build a metadata-only provenance verdict without reopening the source."""
-    return _identify_from_evidence(evidence)
+def identify_from_evidence(
+    evidence: ProvenanceEvidence,
+    *,
+    image_path: Path | None = None,
+    check_visible: bool = False,
+    check_invisible: bool = False,
+) -> ProvenanceReport:
+    """Build a provenance verdict from already-extracted evidence.
+
+    Metadata-only by default -- the source is never reopened. Pass ``image_path`` with
+    ``check_visible`` / ``check_invisible`` to add the pixel-backed detectors on top of
+    the SAME evidence, which is how a caller that asks the file two provenance questions
+    (which vendor is confirmed, and is there an invisible target) pays for the metadata
+    extraction once.
+    """
+    return _identify_from_evidence(
+        evidence,
+        image_path=image_path,
+        check_visible=check_visible,
+        check_invisible=check_invisible,
+    )
 
 
 def identify(

src/remove_ai_watermarks/image_io.py

@@ -89,6 +89,19 @@ def _pil_read(path: str | Path, flags: int) -> NDArray[Any] | None:
         return None
 
 
+def load_image_bgr(path: str | Path) -> NDArray[Any]:
+    """Read ``path`` as a BGR ndarray, raising instead of returning ``None``.
+
+    :func:`imread` keeps cv2's ``None``-on-failure contract because the removal paths
+    branch on it. Scripts and tests want the opposite -- fail loudly at the read -- so
+    they call this. Each vendor engine used to carry its own verbatim copy.
+    """
+    image = imread(path)
+    if image is None:
+        raise FileNotFoundError(f"Failed to read image: {path}")
+    return image
+
+
 def to_bgr(image: NDArray[Any]) -> NDArray[Any]:
     """Return a 3-channel BGR view of ``image``, promoting grayscale and BGRA.
 

src/remove_ai_watermarks/invisible_watermark.py

@@ -29,6 +29,9 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Iterable
     from pathlib import Path
+    from typing import Any
+
+    from numpy.typing import NDArray
 
 logger = logging.getLogger(__name__)
 
@@ -81,7 +84,7 @@ def _bits_to_bytes(bits: Iterable[object], nbytes: int) -> bytes:
     return bytes(int(value) for value in packed[:nbytes])
 
 
-def detect_invisible_watermark(image_path: Path) -> str | None:
+def detect_invisible_watermark(image_path: Path, *, image: NDArray[Any] | None = None) -> str | None:
     """Return the embedding scheme name if a known open watermark is decoded.
 
     Returns e.g. ``"Stable Diffusion XL"`` / ``"FLUX.2 (Black Forest Labs)"`` /
@@ -94,7 +97,10 @@ def detect_invisible_watermark(image_path: Path) -> str | None:
     from remove_ai_watermarks import image_io
     from remove_ai_watermarks.dwt_dct import decode_dwt_dct_lengths
 
-    img = image_io.imread(image_path)
+    # ``image`` lets a caller that has already decoded these pixels hand them in
+    # (mirrors gemini_engine.detect_sparkle_confidence). The decoder only reads the
+    # array -- it converts colour spaces into fresh buffers -- so no copy is needed.
+    img = image if image is not None else image_io.imread(image_path)
     if img is None:
         return None
 

src/remove_ai_watermarks/jimeng_engine.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
@@ -85,8 +85,6 @@ _CONFIG = TextMarkConfig(
     min_gw=8,
 )
 
-JimengDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Jimeng alpha template (float [0,1]), or None."""

src/remove_ai_watermarks/kling_engine.py

@@ -52,11 +52,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image SHORT side (measured basis -- see
@@ -114,8 +112,6 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-KlingDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Kling alpha template (float [0,1]), or None."""
@@ -127,23 +123,8 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Kling glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class KlingEngine(TextMarkEngine):
     """Detect/localize the visible Kling "可灵AI 3.0" watermark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/liblib_engine.py

@@ -25,11 +25,15 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkLocation,
+    TextMarkScan,
+)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image WIDTH (measured basis). The box is
@@ -84,24 +88,12 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-LibLibDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled LibLibAI alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "LibLibAI" silhouette (255 = glyph) from the alpha map, or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the LibLibAI glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class LibLibEngine(TextMarkEngine):
     """Detect/localize the visible LibLibAI wordmark (bottom-center; localize -> fill)."""
 
@@ -111,60 +103,51 @@ class LibLibEngine(TextMarkEngine):
     def __init__(self) -> None:
         super().__init__(_CONFIG)
 
-    def detect(self, image: NDArray[Any] | None, *, provenance: bool = False) -> TextMarkDetection:
-        if image is None or not image.size or min(image.shape[:2]) < self._MIN_SHORT_SIDE:
-            return TextMarkDetection()
-        return super().detect(image, provenance=provenance)
+    def _scan(self, image: NDArray[Any] | None) -> TextMarkScan:
+        """Skip the scan entirely below the size floor.
 
-    def footprint_mask(
-        self, image: NDArray[Any] | None, *, force: bool = False, dilate: int | None = None
-    ) -> NDArray[Any] | None:
-        """Full-frame mask of the logo + wordmark, bounded by the detector's match box.
+        Gating the SCAN rather than overriding ``detect`` is what keeps the floor on the
+        single-pass perception path too, and it means a small image costs nothing.
+        """
+        if image is None or not image.size or min(image.shape[:2]) < self._MIN_SHORT_SIDE:
+            return TextMarkScan(None, None, 0)
+        return super()._scan(image)
+
+    def _footprint_rect(
+        self,
+        image: NDArray[Any],
+        loc: TextMarkLocation,
+        *,
+        force: bool,
+        detection: TextMarkDetection | None,
+    ) -> tuple[int, int, int, int] | None:
+        """Bound the fill by the detector's match box, never by the binary glyph blob.
 
         The base class's blob-bbox footprint is wrong in both directions here: the
         blob bleeds UP into bright background structure (on the 768x1024 cohort
         frame it reached y 931 and the fill ate the shirt's own print) and it does
-        not own the triangle logo anyway. The match box bounds the wordmark exactly
-        (that is what the NCC localized); the logo sits its own height to the LEFT
-        of the text (measured on the cohort zoom: logo ~1.0x the glyph height, gap
-        ~0.3x), so the footprint is the match box extended left by ~1.3 heights.
+        not own the triangle logo anyway.
         """
-        if image is None or image.size == 0:
-            return None
-        from remove_ai_watermarks import image_io, region_eraser
+        return self._match_box_rect(image, loc, force=force, detection=detection)
 
-        image = image_io.to_bgr(image)
-        h, w = image.shape[:2]
-        if h < 32 or w < 64:
-            return None
-        loc = self.locate(image)
-        bx, by, bw, bh = loc.bbox
-        if force:
-            rx1, ry1, rx2, ry2 = bx, by, min(w, bx + bw), min(h, by + bh)
-        else:
-            if not self.detect(image).detected:
-                return None
-            _, box = self._tophat_best(image, loc)
-            if box is None:
-                return None
-            gx0, gy0, gx1, gy1 = box
-            gh = gy1 - gy0 + 1
-            pad = max(3, int(0.25 * gh))
-            rx1 = max(0, bx + gx0 - int(1.3 * gh))  # the triangle logo, left of the text
-            ry1 = max(0, by + gy0 - pad)
-            rx2 = min(w, bx + gx1 + 1 + pad)
-            ry2 = min(h, by + gy1 + 1 + pad)
-        if rx1 >= rx2 or ry1 >= ry2:
-            return None
-        d = dilate if dilate is not None else max(3, int(0.02 * bw))
-        return region_eraser.boxes_to_mask((h, w), [(rx1, ry1, rx2 - rx1, ry2 - ry1)], dilate=d)
+    def _extend_match_box(
+        self, box: tuple[int, int, int, int], loc: TextMarkLocation, frame: tuple[int, int]
+    ) -> tuple[int, int, int, int]:
+        """Extend the match box LEFT to take in the triangle logo.
 
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img
+        The match box bounds the wordmark exactly (that is what the NCC localized);
+        the logo sits its own height to the LEFT of the text (measured on the cohort
+        zoom: logo ~1.0x the glyph height, gap ~0.3x), so the footprint is the match
+        box extended left by ~1.3 heights.
+        """
+        gx0, gy0, gx1, gy1 = box
+        bx, by, _bw, _bh = loc.bbox
+        h, w = frame
+        gh = gy1 - gy0 + 1
+        pad = max(3, int(0.25 * gh))
+        return (
+            max(0, bx + gx0 - int(1.3 * gh)),  # the triangle logo, left of the text
+            max(0, by + gy0 - pad),
+            min(w, bx + gx1 + 1 + pad),
+            min(h, by + gy1 + 1 + pad),
+        )

src/remove_ai_watermarks/metadata.py

@@ -15,7 +15,7 @@ import struct
 from typing import TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Callable, Iterable
     from pathlib import Path
 
 logger = logging.getLogger(__name__)
@@ -165,6 +165,21 @@ TC260_AIGC_FIELDS: frozenset[str] = frozenset(
 MAX_TC260_VALUE_BYTES = 1024 * 1024
 
 
+# A TC260 producer code is ``001`` + ``1`` + USCC(18) + a 5-digit app/product suffix,
+# so two codes sharing the USCC are the same legal entity registering different
+# products. Slicing is defensive: anything not matching the layout is returned as-is,
+# which also passes through the bare-name forms some generators write ("doubao",
+# "picwish").
+_USCC_START, _USCC_END = 4, 22
+
+
+def uscc_of(code: str) -> str:
+    """The 18-char Unified Social Credit Code embedded in a TC260 producer code."""
+    if len(code) >= _USCC_END and code[:3] == "001":
+        return code[_USCC_START:_USCC_END]
+    return code
+
+
 def parse_tc260_aigc_json(value: bytes) -> dict[str, str] | None:
     """Parse a bounded JSON object carrying at least one normative TC260 field."""
     if len(value) > MAX_TC260_VALUE_BYTES:
@@ -270,6 +285,21 @@ def _png_late_metadata(image_path: Path, window: int) -> bytes:
     return bytes(out)
 
 
+def _stat_key(image_path: Path) -> tuple[str, int, int] | None:
+    """Cache key identifying this file's exact CONTENT, or None when it cannot stat.
+
+    ``(path, mtime_ns, size)`` -- size as well as mtime because an in-place rewrite
+    can land inside the same mtime tick on a coarse filesystem, and this package does
+    rewrite in place (``remove_ai_metadata(p, p)``, the batch output-equals-input
+    case). A file it cannot stat is read uncached rather than failing.
+    """
+    try:
+        st = image_path.stat()
+    except OSError:
+        return None
+    return (str(image_path), st.st_mtime_ns, st.st_size)
+
+
 def scan_head(image_path: Path, size: int = 1024 * 1024) -> bytes:
     """First ``size`` bytes of the file, plus the payloads of any provenance
     metadata found beyond that window: ISOBMFF ``uuid`` / ``jumb`` boxes (seeking
@@ -420,7 +450,7 @@ def aigc_label_from_metadata(data: bytes, candidates: tuple[str, ...] = ()) -> d
     return None
 
 
-def aigc_label(image_path: Path) -> dict[str, str] | None:
+def _aigc_label_impl(image_path: Path) -> dict[str, str] | None:
     """Parse a China TC260 AI-labeling block, if present.
 
     Supported serializations are:
@@ -459,45 +489,44 @@ def aigc_label(image_path: Path) -> dict[str, str] | None:
     if isinstance(value, str) and (result := aigc_label_from_metadata(b"", (value,))):
         return result
 
-    # Native MP4/MOV TC260 metadata (TC260-PG-20257A): the ``AIGC`` key lives
-    # in ``moov.udta.meta.keys`` and points to a raw JSON value in ``ilst``.
-    # Read it through the bounded box walker so a tail ``moov`` after a large
-    # ``mdat`` is found without loading or scanning the media payload.
-    from remove_ai_watermarks._internal.isobmff import tc260_aigc_payloads
-
-    isobmff_candidates = tuple(payload.decode("utf-8", "replace") for payload in tc260_aigc_payloads(image_path))
-    if result := aigc_label_from_metadata(b"", isobmff_candidates):
-        return result
-
-    # Native MKV/WebM TC260 metadata: ``Segment.Tags.Tag.SimpleTag`` carries
-    # ``TagName=AIGC`` and the raw JSON in ``TagString``. The EBML walker seeks
-    # over clusters and reads only bounded metadata values.
-    from remove_ai_watermarks._internal.ebml import tc260_aigc_payloads as ebml_tc260_aigc_payloads
-
-    ebml_candidates = tuple(payload.decode("utf-8", "replace") for payload in ebml_tc260_aigc_payloads(image_path))
-    if result := aigc_label_from_metadata(b"", ebml_candidates):
-        return result
-
-    # Native AVI and FLV TC260 metadata. Both readers walk their container
-    # structures and skip media payloads instead of relying on a raw substring
-    # that could collide inside compressed video.
-    legacy_payloads: tuple[bytes, ...] = ()
-    if image_path.suffix.lower() == ".avi":
-        from remove_ai_watermarks._internal.riff import tc260_aigc_payloads as riff_tc260_aigc_payloads
-
-        legacy_payloads = riff_tc260_aigc_payloads(image_path)
-    elif image_path.suffix.lower() == ".flv":
-        from remove_ai_watermarks._internal.flv import tc260_aigc_payloads as flv_tc260_aigc_payloads
-
-        legacy_payloads = flv_tc260_aigc_payloads(image_path)
-    legacy_candidates = tuple(payload.decode("utf-8", "replace") for payload in legacy_payloads)
-    if result := aigc_label_from_metadata(b"", legacy_candidates):
-        return result
+    # Native container TC260 metadata. Every reader walks its own container structure
+    # and skips media payloads instead of relying on a raw substring that could collide
+    # inside compressed video, and every one of them SELF-GATES on its magic bytes --
+    # returning () after a 4-12 byte read on anything else. So the route is content, not
+    # extension: a correctly formatted AVI or FLV served under the wrong suffix used to
+    # be missed, which contradicts this module's own rule elsewhere ("route on the
+    # actual content format, not the extension").
+    for reader in _tc260_container_readers():
+        candidates = tuple(payload.decode("utf-8", "replace") for payload in reader(image_path))
+        if result := aigc_label_from_metadata(b"", candidates):
+            return result
 
     data = scan_head(image_path)
     return aigc_label_from_metadata(data)
 
 
+def _tc260_container_readers() -> tuple[Callable[[Path], tuple[bytes, ...]], ...]:
+    """The native-container TC260 readers, most common first.
+
+    Static imports rather than ``importlib``: this module carries no pyright pragma, so
+    a dynamically resolved callable would be ``Any`` and fail the strict gate. They stay
+    function-local because ``isobmff`` imports this module's constants at import time.
+
+    * MP4/MOV -- the ``AIGC`` key in ``moov.udta.meta.keys`` points at raw JSON in
+      ``ilst``; the bounded box walker finds a tail ``moov`` after a large ``mdat``
+      without loading the media payload.
+    * MKV/WebM -- ``Segment.Tags.Tag.SimpleTag`` carries ``TagName=AIGC``.
+    * AVI -- a ``LIST/INFO/AIGC`` chunk.
+    * FLV -- ``script.onMetaData.AIGC``.
+    """
+    from remove_ai_watermarks._internal.ebml import tc260_aigc_payloads as ebml_payloads
+    from remove_ai_watermarks._internal.flv import tc260_aigc_payloads as flv_payloads
+    from remove_ai_watermarks._internal.isobmff import tc260_aigc_payloads as isobmff_payloads
+    from remove_ai_watermarks._internal.riff import tc260_aigc_payloads as riff_payloads
+
+    return (isobmff_payloads, ebml_payloads, riff_payloads, flv_payloads)
+
+
 # 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
@@ -538,7 +567,7 @@ def c2pa_cloud_manifest(image_path: Path) -> str | None:
     return c2pa_cloud_manifest_in(scan_head(image_path, _QUICK_SCAN_BYTES))
 
 
-def huggingface_job(image_path: Path) -> str | None:
+def _huggingface_job_impl(image_path: Path) -> str | None:
     """Return the HuggingFace job id if the image carries an ``hf-job-id`` PNG
     text chunk, else None.
 
@@ -599,7 +628,7 @@ def samsung_genai_in(data: bytes) -> int | None:
     return int(match.group(1)) or None
 
 
-def samsung_genai(image_path: Path) -> int | None:
+def _samsung_genai_impl(image_path: Path) -> int | None:
     """Return Samsung's non-zero ``genAIType`` value if the image carries the
     Galaxy AI editing marker, else None.
 
@@ -636,7 +665,7 @@ def iptc_ai_system_in(data: bytes) -> str | None:
     return "fields present"
 
 
-def iptc_ai_system(image_path: Path) -> str | None:
+def _iptc_ai_system_impl(image_path: Path) -> str | None:
     """Return an IPTC 2025.1 AI-disclosure note if the file carries those XMP
     properties, else None.
 
@@ -775,7 +804,7 @@ def _exif_text(ifd: dict[int, Any], tag: int) -> str:
     return value.decode("latin1", "replace").strip() if isinstance(value, bytes) else ""
 
 
-def xai_signature(image_path: Path) -> bool:
+def _xai_signature_impl(image_path: Path) -> bool:
     """Detect xAI / Grok's EXIF provenance signature scheme.
 
     Grok image downloads (Aurora model) carry no C2PA, XMP, SynthID, or IPTC --
@@ -1372,3 +1401,87 @@ def remove_ai_metadata(
 
     logger.info("Stripped AI metadata → %s", output_path)
     return output_path
+
+
+# ── Per-file probe memoization ──────────────────────────────────────────────
+# One ``identify`` reaches each of these twice (``get_ai_metadata`` internally, then
+# ``extract_provenance_evidence``), and each call re-walks the container -- the
+# ISOBMFF/EBML walks in ``aigc_label`` and the file-tail read in ``samsung_genai``
+# are the expensive ones. Keyed on (path, mtime_ns, size) so an in-place rewrite
+# invalidates; ``maxsize`` bounds memory to a handful of entries.
+
+
+@functools.lru_cache(maxsize=4)
+def _aigc_label_cached(path_str: str, _mtime_ns: int, _size: int) -> dict[str, str] | None:
+    from pathlib import Path as _Path
+
+    return _aigc_label_impl(_Path(path_str))
+
+
+def aigc_label(image_path: Path) -> dict[str, str] | None:
+    """See :func:`_aigc_label_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _aigc_label_impl(image_path)
+    result = _aigc_label_cached(*key)
+    return dict(result) if result is not None else None
+
+
+@functools.lru_cache(maxsize=4)
+def _huggingface_job_cached(path_str: str, _mtime_ns: int, _size: int) -> str | None:
+    from pathlib import Path as _Path
+
+    return _huggingface_job_impl(_Path(path_str))
+
+
+def huggingface_job(image_path: Path) -> str | None:
+    """See :func:`_huggingface_job_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _huggingface_job_impl(image_path)
+    return _huggingface_job_cached(*key)
+
+
+@functools.lru_cache(maxsize=4)
+def _samsung_genai_cached(path_str: str, _mtime_ns: int, _size: int) -> int | None:
+    from pathlib import Path as _Path
+
+    return _samsung_genai_impl(_Path(path_str))
+
+
+def samsung_genai(image_path: Path) -> int | None:
+    """See :func:`_samsung_genai_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _samsung_genai_impl(image_path)
+    return _samsung_genai_cached(*key)
+
+
+@functools.lru_cache(maxsize=4)
+def _iptc_ai_system_cached(path_str: str, _mtime_ns: int, _size: int) -> str | None:
+    from pathlib import Path as _Path
+
+    return _iptc_ai_system_impl(_Path(path_str))
+
+
+def iptc_ai_system(image_path: Path) -> str | None:
+    """See :func:`_iptc_ai_system_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _iptc_ai_system_impl(image_path)
+    return _iptc_ai_system_cached(*key)
+
+
+@functools.lru_cache(maxsize=4)
+def _xai_signature_cached(path_str: str, _mtime_ns: int, _size: int) -> bool:
+    from pathlib import Path as _Path
+
+    return _xai_signature_impl(_Path(path_str))
+
+
+def xai_signature(image_path: Path) -> bool:
+    """See :func:`_xai_signature_impl`; memoized per file content."""
+    key = _stat_key(image_path)
+    if key is None:
+        return _xai_signature_impl(image_path)
+    return _xai_signature_cached(*key)

src/remove_ai_watermarks/pill_engine.py

@@ -61,6 +61,10 @@ _MASK_W, _MASK_H = 0.205, 0.115  # width of W, height of W
 # invisible inpaint. Threshold = median Sobel magnitude over the footprint box at a
 # normalized width. The reliable bottom-right wordmark arm is NOT texture-gated:
 # a wordmark-confirmed pill is removed regardless.
+#
+# Measured through the PRODUCT path (the `_keep_pill` gate), not the raw detector, by
+# ``scripts/pill_gate_audit.py`` -- the raw path bypasses the gate and reads as a
+# disaster that the shipped behaviour does not have. Re-run it when the gate changes.
 _FLAT_TEXTURE_MAX = 6.0
 
 _silhouette: NDArray[Any] | None = None
@@ -163,8 +167,11 @@ class PillEngine:
         box = self._footprint_box(image)
         if box is None:
             return None
+        # Same primitive the shared fill uses, rather than a private zeros/fill copy.
+        # `dilate=0` because this footprint is already generous by construction; the
+        # box is clamped to the frame in _footprint_box and both origins are positive
+        # fractions, so boxes_to_mask's own clamping is a no-op here.
+        from remove_ai_watermarks import region_eraser
+
         x0, y0, x1, y1 = box
-        h, w = image.shape[:2]
-        mask = np.zeros((h, w), np.uint8)
-        mask[y0:y1, x0:x1] = 255
-        return mask
+        return region_eraser.boxes_to_mask(image.shape[:2], [(x0, y0, x1 - x0, y1 - y0)], dilate=0)

src/remove_ai_watermarks/qwen_engine.py

@@ -52,11 +52,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image SHORT side (measured basis -- see
@@ -122,8 +120,6 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-QwenDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Qwen alpha template (float [0,1]), or None."""
@@ -135,23 +131,8 @@ def _glyph_silhouette() -> NDArray[Any] | None:
     return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
 
 
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Qwen glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class QwenEngine(TextMarkEngine):
     """Detect/localize the visible Qwen "千问AI生成" watermark (locate -> mask; mask feeds the fill)."""
 
     def __init__(self) -> None:
         super().__init__(_CONFIG)
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/region_eraser.py

@@ -21,6 +21,10 @@ Backends:
     texture but ~200 MB model and ~4.7 GB peak RAM (too heavy for a small host).
     The model is downloaded on first use and cached by huggingface_hub; it is
     never bundled in this repo.
+
+The per-backend RAM and wall-time figures above are reproduced by
+``scripts/resource_ceilings.py`` (fresh subprocess per measurement, synthetic inputs).
+Re-run it before changing any of them.
 """
 
 # cv2/numpy boundary: cv2 ships no usable type info, so strict pyright cannot know
@@ -30,6 +34,7 @@ Backends:
 from __future__ import annotations
 
 import logging
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
 import cv2
@@ -48,9 +53,38 @@ _LAMA_FILE = "lama_fp32.onnx"
 _MIGAN_REPO = "andraniksargsyan/migan"
 _MIGAN_FILE = "migan.onnx"
 
-# Cached onnxruntime sessions (loading is expensive; reuse across calls).
-_lama_session: object | None = None
-_migan_session: object | None = None
+# Cached onnxruntime sessions, keyed by backend name (loading is expensive; reuse
+# across calls).
+_sessions: dict[str, object] = {}
+
+
+@dataclass(frozen=True)
+class _LearnedBackend:
+    """One optional model-backed fill: its human label and the module-level names of
+    its availability probe and erase function.
+
+    NAMES, not function objects: the fallback tests monkeypatch these by attribute on
+    the module, and a table holding bound references would not see the patch.
+    """
+
+    label: str
+    available: str
+    erase: str
+
+
+# The learned tier, best-quality first. `resolve_backend`'s preference order and the
+# CLI's choices are separate literals by design (see FILL_BACKENDS below), but the
+# availability probe, install hint and dispatch all read this one table.
+_LEARNED_BACKENDS: dict[str, _LearnedBackend] = {
+    "lama": _LearnedBackend("LaMa", "lama_available", "erase_lama"),
+    "migan": _LearnedBackend("MI-GAN", "migan_available", "erase_migan"),
+}
+
+# Every fill backend this module can execute, plus the caller-facing `auto`. Kept as a
+# literal tuple (not derived through an import) so `watermark_registry` and the CLI can
+# state their choices without importing this cv2-loading module at their import time --
+# a test pins the two in sync.
+FILL_BACKENDS: tuple[str, ...] = ("auto", "cv2", "migan", "lama")
 
 
 def boxes_to_mask(
@@ -119,19 +153,25 @@ def lama_available() -> bool:
     return module_available("onnxruntime")
 
 
-def _get_lama_session() -> object:
-    """Load (once) the big-LaMa ONNX session, downloading the model on first use."""
-    global _lama_session
-    if _lama_session is not None:
-        return _lama_session
+def _get_session(name: str, repo_id: str, filename: str, label: str) -> object:
+    """Load (once) an ONNX session, downloading the model on first use."""
+    cached = _sessions.get(name)
+    if cached is not None:
+        return cached
 
     import onnxruntime as ort
     from huggingface_hub import hf_hub_download
 
-    model_path = hf_hub_download(repo_id=_LAMA_REPO, filename=_LAMA_FILE)
-    logger.info("Loading LaMa-ONNX model: %s", model_path)
-    _lama_session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
-    return _lama_session
+    model_path = hf_hub_download(repo_id=repo_id, filename=filename)
+    logger.info("Loading %s model: %s", label, model_path)
+    session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
+    _sessions[name] = session
+    return session
+
+
+def _get_lama_session() -> object:
+    """The big-LaMa ONNX session (kept as a named seam the tests monkeypatch)."""
+    return _get_session("lama", _LAMA_REPO, _LAMA_FILE, "LaMa-ONNX")
 
 
 def erase_lama(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
@@ -196,25 +236,21 @@ def erase_lama(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
 
 
 def migan_available() -> bool:
-    """True when the optional MI-GAN backend can run (onnxruntime installed)."""
+    """True when the optional MI-GAN backend can run (onnxruntime installed).
+
+    Deliberately a separate function from :func:`lama_available` even though both
+    currently reduce to the same onnxruntime probe: they are independent capability
+    questions and `auto` resolves them separately (see
+    ``watermark_registry.preferred_inpaint_backend``).
+    """
     from .optional_deps import module_available
 
     return module_available("onnxruntime")
 
 
 def _get_migan_session() -> object:
-    """Load (once) the MI-GAN ONNX session, downloading the model on first use."""
-    global _migan_session
-    if _migan_session is not None:
-        return _migan_session
-
-    import onnxruntime as ort
-    from huggingface_hub import hf_hub_download
-
-    model_path = hf_hub_download(repo_id=_MIGAN_REPO, filename=_MIGAN_FILE)
-    logger.info("Loading MI-GAN ONNX model: %s", model_path)
-    _migan_session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
-    return _migan_session
+    """The MI-GAN ONNX session (kept as a named seam the tests monkeypatch)."""
+    return _get_session("migan", _MIGAN_REPO, _MIGAN_FILE, "MI-GAN ONNX")
 
 
 def erase_migan(image_bgr: NDArray[Any], mask: NDArray[Any]) -> NDArray[Any]:
@@ -308,16 +344,17 @@ def erase(
     if not mask.any():
         return image_bgr.copy()
 
-    if backend == "migan":
-        if not migan_available():
+    learned = _LEARNED_BACKENDS.get(backend)
+    if learned is not None:
+        # Probe and erase by MODULE NAME, not by the captured function object: the
+        # availability probes and the erase functions are monkeypatched by name in the
+        # fallback tests, and a table of bound references would not see those patches.
+        if not globals()[learned.available]():
             raise RuntimeError(
-                "MI-GAN backend requires onnxruntime. Install the extra: pip install 'remove-ai-watermarks[migan]'"
+                f"{learned.label} backend requires onnxruntime. "
+                f"Install the extra: pip install 'remove-ai-watermarks[{backend}]'"
             )
-        return erase_migan(image_bgr, mask)
-    if backend == "lama":
-        if not lama_available():
-            raise RuntimeError(
-                "LaMa backend requires onnxruntime. Install the extra: pip install 'remove-ai-watermarks[lama]'"
-            )
-        return erase_lama(image_bgr, mask)
+        return globals()[learned.erase](image_bgr, mask)
+    # cv2 and anything unrecognized (including "auto", which a library caller may pass
+    # straight through) degrade to the classical fill rather than raising.
     return erase_cv2(image_bgr, mask, method=cv2_method, radius=cv2_radius)

src/remove_ai_watermarks/runninghub_engine.py

@@ -48,13 +48,16 @@ import logging
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkScan,
+)
 
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 # Locate geometry as a fraction of the image WIDTH (the measured basis: every
@@ -111,24 +114,12 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-RunningHubDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled RunningHub alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary "RunningHub AI生成" silhouette (255 = glyph) from the alpha map, or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the RunningHub glyph silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class RunningHubEngine(TextMarkEngine):
     """Detect/localize the visible RunningHub "RunningHub AI生成" mark (top-left; localize -> fill)."""
 
@@ -140,18 +131,21 @@ class RunningHubEngine(TextMarkEngine):
     _ANCHOR_MAX_X = 0.025
     _ANCHOR_MAX_Y = 0.015
 
-    def detect(self, image: NDArray[Any], *, provenance: bool = False) -> TextMarkDetection:
-        det = super().detect(image, provenance=provenance)
-        if not det.detected:
+    def _post_gate(self, det: TextMarkDetection, scan: TextMarkScan) -> TextMarkDetection:
+        """Demote a match that does not hug the top-left corner.
+
+        A shared post-gate rather than a ``detect`` override, so the single-pass
+        perception path (``detect_both``) cannot skip it.
+        """
+        if not det.detected or scan.loc is None:
             return det
-        loc = self.locate(image)
-        _, box = self._gray_best(image, loc)
+        box = det.match_box  # the sweep the scan already ran on this same loc
         if box is None:
             det.detected = False
             return det
-        h, w = image.shape[:2]
-        ax = (loc.x + box[0]) / w
-        ay = (loc.y + box[1]) / h
+        h, w = scan.frame
+        ax = (scan.loc.x + box[0]) / w
+        ay = (scan.loc.y + box[1]) / h
         if ax > self._ANCHOR_MAX_X or ay > self._ANCHOR_MAX_Y:
             logger.debug(
                 "RunningHub detect: score %.3f but match off-anchor (x=%.3f y=%.3f); demoting.",
@@ -161,13 +155,3 @@ class RunningHubEngine(TextMarkEngine):
             )
             det.detected = False
         return det
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as BGR ndarray (helper for scripts/tests)."""
-    from remove_ai_watermarks import image_io
-
-    img = image_io.imread(path)
-    if img is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return img

src/remove_ai_watermarks/samsung_engine.py

@@ -28,7 +28,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkEngine
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
@@ -79,8 +79,6 @@ _CONFIG = TextMarkConfig(
     min_gw=16,
 )
 
-SamsungDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Samsung alpha template (float [0,1]), or None."""

src/remove_ai_watermarks/video.py

@@ -229,58 +229,34 @@ def _visible_removal_plan(
     selected_scan: VideoScan,
     markers: dict[str, str],
 ) -> tuple[list[tuple[int, int, int, int] | None], float, Literal["box", "veo"]]:
-    """Resolve one provider's stable frame regions and fill geometry."""
+    """Resolve one provider's stable frame regions and fill geometry.
+
+    Everything provider-specific -- the confidence floors, the run length, the fill
+    padding and the mask style -- is data on ``VISIBLE_MARK_POLICIES``. The only thing
+    left here is WHICH metadata predicate confirms which vendor, which genuinely is a
+    mapping and not a tuning constant.
+    """
     from remove_ai_watermarks.video_visible import (
+        VISIBLE_MARK_POLICIES,
         has_bytedance_video_provenance,
         has_sora_provenance,
         has_veo_provenance,
-        stabilize_dola_localizations,
-        stabilize_hailuo_localizations,
-        stabilize_kling_localizations,
-        stabilize_seedance_localizations,
-        stabilize_sora_localizations,
-        stabilize_veo_localizations,
+        stabilize_localizations,
     )
 
-    if selected_mark == "sora":
-        return (
-            stabilize_sora_localizations(
-                selected_scan.detections,
-                provenance=has_sora_provenance(markers),
-            ),
-            0.28,
-            "box",
-        )
-    if selected_mark == "veo":
-        return (
-            stabilize_veo_localizations(
-                selected_scan.detections,
-                provenance=has_veo_provenance(markers),
-            ),
-            0.18,
-            "veo",
-        )
-    if selected_mark == "seedance":
-        return (
-            stabilize_seedance_localizations(
-                selected_scan.detections,
-                provenance=has_bytedance_video_provenance(markers),
-            ),
-            0.0,
-            "box",
-        )
-    if selected_mark == "dola":
-        return (
-            stabilize_dola_localizations(
-                selected_scan.detections,
-                provenance=has_bytedance_video_provenance(markers),
-            ),
-            0.20,
-            "box",
-        )
-    if selected_mark == "hailuo":
-        return stabilize_hailuo_localizations(selected_scan.detections), 0.12, "box"
-    return stabilize_kling_localizations(selected_scan.detections), 0.12, "box"
+    confirms = {
+        "sora": has_sora_provenance,
+        "veo": has_veo_provenance,
+        "seedance": has_bytedance_video_provenance,
+        "dola": has_bytedance_video_provenance,
+    }.get(selected_mark)
+    policy = VISIBLE_MARK_POLICIES[selected_mark]
+    regions = stabilize_localizations(
+        selected_mark,
+        selected_scan.detections,
+        provenance=bool(confirms and confirms(markers)),
+    )
+    return regions, policy.padding_fraction, policy.mask_style
 
 
 def _select_stable_visible_mark(

src/remove_ai_watermarks/video_visible.py

@@ -402,7 +402,7 @@ def detect_sora_frame(
     """Locate the strongest synthetic Sora-wordmark match in one frame.
 
     The returned candidate is intentionally untrusted. Call
-    :func:`stabilize_sora_localizations` across the full sequence before building
+    :func:`stabilize_localizations` across the full sequence before building
     any removal mask.
     """
     if image_bgr.size == 0:
@@ -883,113 +883,133 @@ def _region_iou(left: Region, right: Region) -> float:
     return intersection / union if union > 0 else 0.0
 
 
-def stabilize_sora_localizations(
-    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
-    *,
-    provenance: bool,
-) -> list[Region | None]:
-    """Accept only spatially recurring Sora candidates and bridge short dropouts.
+@dataclass(frozen=True)
+class VisibleMarkPolicy:
+    """One provider's temporal-arbiter tuning, plus the fill geometry it needs.
 
-    Metadata never creates a detection. It only allows a stable visual run whose
-    scores remain below the strict confidence floor, which covers low-contrast
-    Sora marks while clean metadata-bearing exports stay untouched.
+    Every value here is MEASURED per provider; the arbiter itself
+    (:func:`_stabilize_localizations`) is shared and knows nothing about providers.
+
+    ``accepts_provenance`` is load-bearing rather than cosmetic. Hailuo and Kling have
+    no metadata that could confirm them, so their rows force ``provenance=False``; that
+    used to be guaranteed structurally by wrappers that took no ``provenance``
+    parameter at all, and this flag is what preserves the guarantee now that one entry
+    point serves every mark.
+
+    ``padding_fraction`` and ``mask_style`` belong to the removal plan rather than the
+    arbiter, but they are per-provider constants like the rest, so they live on the same
+    row instead of in a parallel branch in ``video.py``.
     """
-    weak_floor = _SORA_PROVENANCE_WEAK_CONFIDENCE if provenance else _SORA_STRICT_WEAK_CONFIDENCE
-    return _stabilize_localizations(
-        detections,
-        provenance=provenance,
-        weak_floor=weak_floor,
+
+    weak_floor: float
+    strong_floor: float
+    transition_floor: float
+    min_stable_frames: int
+    cover_after_confirmation: bool
+    padding_fraction: float
+    mask_style: Literal["box", "veo"]
+    anchor_iou: float | None = None
+    accepts_provenance: bool = True
+    # Weak floor to use when provenance confirms the vendor. None = the mark has no
+    # relaxed band; metadata never creates a detection, it only lets a stable visual
+    # run below the strict floor through.
+    provenance_weak_floor: float | None = None
+
+
+VISIBLE_MARK_POLICIES: dict[str, VisibleMarkPolicy] = {
+    "sora": VisibleMarkPolicy(
+        weak_floor=_SORA_STRICT_WEAK_CONFIDENCE,
+        provenance_weak_floor=_SORA_PROVENANCE_WEAK_CONFIDENCE,
         strong_floor=_SORA_STRONG_CONFIDENCE,
         transition_floor=0.45,
         min_stable_frames=_MIN_STABLE_FRAMES,
         cover_after_confirmation=False,
-    )
-
-
-def stabilize_veo_localizations(
-    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
-    *,
-    provenance: bool,
-) -> list[Region | None]:
-    """Accept temporally recurring current or legacy Veo candidates."""
-    weak_floor = _VEO_PROVENANCE_WEAK_CONFIDENCE if provenance else _VEO_STRICT_WEAK_CONFIDENCE
-    return _stabilize_localizations(
-        detections,
-        provenance=provenance,
-        weak_floor=weak_floor,
+        padding_fraction=0.28,
+        mask_style="box",
+    ),
+    "veo": VisibleMarkPolicy(
+        weak_floor=_VEO_STRICT_WEAK_CONFIDENCE,
+        provenance_weak_floor=_VEO_PROVENANCE_WEAK_CONFIDENCE,
         strong_floor=_VEO_STRONG_CONFIDENCE,
         transition_floor=0.35,
         min_stable_frames=_MIN_VEO_STABLE_FRAMES,
         cover_after_confirmation=True,
-    )
-
-
-def stabilize_seedance_localizations(
-    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
-    *,
-    provenance: bool,
-) -> list[Region | None]:
-    """Accept a recurring Seedance boxed-AI mark at a fixed position."""
-    return _stabilize_localizations(
-        detections,
-        provenance=provenance,
+        padding_fraction=0.18,
+        mask_style="veo",
+    ),
+    "seedance": VisibleMarkPolicy(
+        # One floor at either trust level: provenance still gates the run acceptance
+        # inside the arbiter, but the confidence bar does not move.
         weak_floor=_SEEDANCE_WEAK_CONFIDENCE,
         strong_floor=_SEEDANCE_STRONG_CONFIDENCE,
         transition_floor=0.30,
         min_stable_frames=_MIN_FIXED_MARK_STABLE_FRAMES,
         cover_after_confirmation=True,
         anchor_iou=0.80,
-    )
-
-
-def stabilize_dola_localizations(
-    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
-    *,
-    provenance: bool,
-) -> list[Region | None]:
-    """Accept a recurring Dola AI text mark at a fixed position."""
-    weak_floor = _DOLA_PROVENANCE_WEAK_CONFIDENCE if provenance else _DOLA_STRICT_WEAK_CONFIDENCE
-    return _stabilize_localizations(
-        detections,
-        provenance=provenance,
-        weak_floor=weak_floor,
+        padding_fraction=0.0,
+        mask_style="box",
+    ),
+    "dola": VisibleMarkPolicy(
+        weak_floor=_DOLA_STRICT_WEAK_CONFIDENCE,
+        provenance_weak_floor=_DOLA_PROVENANCE_WEAK_CONFIDENCE,
         strong_floor=_DOLA_STRONG_CONFIDENCE,
         transition_floor=0.40,
         min_stable_frames=_MIN_FIXED_MARK_STABLE_FRAMES,
         cover_after_confirmation=True,
         anchor_iou=0.80,
-    )
-
-
-def stabilize_hailuo_localizations(
-    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
-) -> list[Region | None]:
-    """Accept a recurring MINIMAX/Hailuo label at a fixed position."""
-    return _stabilize_localizations(
-        detections,
-        provenance=False,
+        padding_fraction=0.20,
+        mask_style="box",
+    ),
+    "hailuo": VisibleMarkPolicy(
         weak_floor=_HAILUO_WEAK_CONFIDENCE,
         strong_floor=_HAILUO_STRONG_CONFIDENCE,
         transition_floor=0.28,
         min_stable_frames=_MIN_FIXED_MARK_STABLE_FRAMES,
         cover_after_confirmation=True,
         anchor_iou=0.80,
-    )
-
-
-def stabilize_kling_localizations(
-    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
-) -> list[Region | None]:
-    """Accept a recurring versioned Kling label at a fixed position."""
-    return _stabilize_localizations(
-        detections,
-        provenance=False,
+        padding_fraction=0.12,
+        mask_style="box",
+        accepts_provenance=False,
+    ),
+    "kling": VisibleMarkPolicy(
         weak_floor=_KLING_WEAK_CONFIDENCE,
         strong_floor=_KLING_STRONG_CONFIDENCE,
         transition_floor=0.30,
         min_stable_frames=_MIN_FIXED_MARK_STABLE_FRAMES,
         cover_after_confirmation=True,
         anchor_iou=0.80,
+        padding_fraction=0.12,
+        mask_style="box",
+        accepts_provenance=False,
+    ),
+}
+
+
+def stabilize_localizations(
+    mark: str,
+    detections: tuple[FrameLocalization, ...] | list[FrameLocalization],
+    *,
+    provenance: bool = False,
+) -> list[Region | None]:
+    """Accept only spatially/temporally recurring candidates for ``mark``.
+
+    Metadata never creates a detection. It only allows a stable visual run whose scores
+    remain below the strict confidence floor, which covers a low-contrast mark while
+    clean metadata-bearing exports stay untouched. A mark whose policy sets
+    ``accepts_provenance=False`` ignores the argument entirely.
+    """
+    policy = VISIBLE_MARK_POLICIES[mark]
+    trusted = provenance and policy.accepts_provenance
+    weak_floor = policy.provenance_weak_floor if (trusted and policy.provenance_weak_floor is not None) else None
+    return _stabilize_localizations(
+        detections,
+        provenance=trusted,
+        weak_floor=weak_floor if weak_floor is not None else policy.weak_floor,
+        strong_floor=policy.strong_floor,
+        transition_floor=policy.transition_floor,
+        min_stable_frames=policy.min_stable_frames,
+        cover_after_confirmation=policy.cover_after_confirmation,
+        **({"anchor_iou": policy.anchor_iou} if policy.anchor_iou is not None else {}),
     )
 
 
@@ -1182,8 +1202,8 @@ def _mask_for_region(
 ) -> NDArray[Any]:
     height, width = frame_bgr.shape[:2]
     x, y, region_width, region_height = region
-    mask = np.zeros((height, width), dtype=np.uint8)
     if mask_style == "veo" and 0.80 <= region_width / region_height <= 1.25:
+        mask = np.zeros((height, width), dtype=np.uint8)
         diamond_base, _ = _veo_templates()
         diamond = cv2.resize(
             diamond_base,
@@ -1207,13 +1227,16 @@ def _mask_for_region(
     # into the hole, recreating the mascot as a bright blob. The measured clean
     # floor on real Sora frames is a full box with roughly 0.28 mark-heights of
     # context on every side.
+    # Padded rectangle + no dilation is exactly region_eraser.boxes_to_mask (the same
+    # primitive the image fill uses); the padding IS the growth, so `dilate=0`.
+    from remove_ai_watermarks.region_eraser import boxes_to_mask
+
     padding = max(4, round(region_height * padding_fraction))
-    x0 = max(0, x - padding)
-    y0 = max(0, y - padding)
-    x1 = min(width, x + region_width + padding)
-    y1 = min(height, y + region_height + padding)
-    mask[y0:y1, x0:x1] = 255
-    return mask
+    return boxes_to_mask(
+        (height, width),
+        [(x - padding, y - padding, region_width + 2 * padding, region_height + 2 * padding)],
+        dilate=0,
+    )
 
 
 def _timestamp_time_base(profile_time_base: str | None) -> Fraction:

src/remove_ai_watermarks/watermark_registry.py

@@ -33,7 +33,7 @@ Entries:
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
@@ -79,24 +79,8 @@ Sensitivity = Literal["auto", "strict"]
 # A third ``assumed`` level existed for ``assume_ai`` and went with it (2026-07-19).
 Trust = Literal["strict", "confirmed"]
 
-# Product family per mark, for the ``auto`` cross-mark corroboration: a confidently
-# detected mark relaxes only OTHER marks of the SAME product (different corners, one
-# product -- the Jimeng wordmark + the Jimeng pill). Doubao and Jimeng are BOTH ByteDance
-# but distinct products in the SAME bottom-right corner, so they must NOT cross-relax
-# (relaxing Doubao on a Jimeng wordmark would spuriously fire Doubao on it).
-_PRODUCT_OF: dict[str, str] = {
-    "gemini": "gemini",
-    "doubao": "doubao",
-    "jimeng": "jimeng",
-    "jimeng_pill": "jimeng",  # same product as the Jimeng wordmark
-    "qwen": "qwen",
-    "kling": "kling",
-    "yuanbao": "yuanbao",
-    "samsung": "samsung",
-    "runninghub": "runninghub",
-    "baidu": "baidu",
-    "liblib": "liblib",
-}
+# Product family per mark now lives on the registry row (``KnownMark.product``);
+# ``_PRODUCT_OF`` is derived from it right after ``_REGISTRY`` is built.
 
 
 # Marks whose own detection is too weak to serve as EVIDENCE for a sibling of the
@@ -134,6 +118,11 @@ class MarkDetection:
     detected: bool
     confidence: float
     region: Region
+    # The engine's OWN detection object, threaded back to this mark's mask builder so it
+    # does not re-run the detector (the text-mark footprint is bounded by the ladder
+    # sweep detection already ran). Opaque here: each mask adapter knows its engine's
+    # type. Excluded from eq/repr so the uniform result stays comparable across engines.
+    engine_detection: Any | None = field(default=None, compare=False, repr=False)
 
 
 @dataclass(frozen=True)
@@ -234,12 +223,42 @@ class KnownMark:
     label: str
     location: str  # usual place, human-readable ("bottom-right")
     in_auto: bool  # participate in `--mark auto` scanning
+    # Product family, for the `auto` cross-mark corroboration: a confidently detected
+    # mark relaxes only OTHER marks of the SAME product (different corners, one product
+    # -- the Jimeng wordmark + the Jimeng pill). Doubao and Jimeng are BOTH ByteDance but
+    # distinct products in the SAME bottom-right corner, so they must NOT cross-relax
+    # (relaxing Doubao on a Jimeng wordmark would spuriously fire Doubao on it).
+    # REQUIRED, deliberately: a defaulted empty product would let two rows that forgot
+    # the field corroborate each other and silently bypass the trust gate.
+    product: str
+    # Which provenance regime this mark's vendor labels under, or None. "tc260" means
+    # the vendor stamps the China AIGC label, so a confident detection of it names a
+    # DIFFERENT TC260 product than the Jimeng pill -- see _keep_pill.
+    label_regime: str | None
+    # The sentence `identify` reports when THIS mark is the strongest evidence. None for
+    # a mark that never names a platform on its own: `gemini` has its own higher-
+    # confidence sparkle path, and the capture-less pill is too weak to attribute.
+    platform: str | None
     _detect: Callable[..., MarkDetection]
     _mask: Callable[..., NDArray[Any] | None]
     # Optional physical-feature probe: the mark's OWN measurements its gate needs
     # (e.g. the pill's footprint flatness), so the perception pass stays uniform and
     # does not special-case any mark. None = the mark's gate needs no extra evidence.
     _features: Callable[..., dict[str, float]] | None = None
+    # Metadata signal names that confirm this mark's vendor, and platform substrings
+    # that do. Both drive `api.visible_provenance`; empty means nothing confirms it.
+    provenance_signals: tuple[str, ...] = ()
+    provenance_platform_tokens: tuple[str, ...] = ()
+    # TC260 ``ContentProducer`` identities that name THIS mark's vendor -- Unified
+    # Social Credit Codes as normalized by ``metadata.uscc_of``, plus the bare product
+    # names a few generators write instead. Here rather than in a separate table
+    # because a newly registered TC260 mark whose codes were forgotten fails SILENTLY:
+    # it falls back to relaxing ByteDance's pair on an image carrying the new mark,
+    # the exact false positive the producer code exists to prevent.
+    tc260_producer_codes: tuple[str, ...] = ()
+    # Optional single-pass dual verdict for the arbiter's perception stage (see
+    # `detect_both`). None = fall back to two `_detect` calls.
+    _detect_both: Callable[..., tuple[MarkDetection, MarkDetection]] | None = None
 
     def features(self, image: NDArray[Any]) -> dict[str, float]:
         """Physical features the mark reports for the arbiter's gate (empty if none)."""
@@ -252,11 +271,35 @@ class KnownMark:
         is trusted when provenance says the vendor is present)."""
         return self._detect(image, provenance=provenance)
 
-    def localize(self, image: NDArray[Any], *, provenance: bool = False, force: bool = False) -> Localization:
+    def detect_both(self, image: NDArray[Any]) -> tuple[MarkDetection, MarkDetection]:
+        """``(strict, relaxed)`` from ONE pass over the image.
+
+        The arbiter's perception stage needs a mark's verdict at BOTH trust levels so it
+        can pick per mark without re-detecting. ``provenance`` never changes what a
+        detector computes -- only the threshold it compares against, or (Gemini) whether
+        a false-positive gate demotes the result afterwards -- so the expensive scan is
+        shared. A mark without a ``_detect_both`` adapter falls back to two calls."""
+        if self._detect_both is not None:
+            return self._detect_both(image)
+        return self.detect(image, provenance=False), self.detect(image, provenance=True)
+
+    def localize(
+        self,
+        image: NDArray[Any],
+        *,
+        provenance: bool = False,
+        force: bool = False,
+        detection: MarkDetection | None = None,
+    ) -> Localization:
         """Detect and build the removal mask in one call. Returns a
         :class:`Localization`; ``mask`` is None unless the mark is detected (or
-        ``force`` bypasses detection for the mark's usual footprint)."""
-        det = self.detect(image, provenance=provenance)
+        ``force`` bypasses detection for the mark's usual footprint).
+
+        ``detection`` lets a caller that has ALREADY detected this mark at this trust
+        level hand the result in rather than pay for the scan twice -- the explicit
+        ``visible --mark <name>`` path detects once to report the confidence and would
+        otherwise re-detect here."""
+        det = detection if detection is not None else self.detect(image, provenance=provenance)
         if not (det.detected or force):
             return Localization(det.detected, det.confidence, det.region, None)
         # Pass the (provenance-aware) detection to the mask builder so it does NOT
@@ -272,6 +315,7 @@ class KnownMark:
         backend: Backend = "auto",
         provenance: bool = False,
         force: bool = False,
+        detection: MarkDetection | None = None,
     ) -> tuple[NDArray[Any], Region | None]:
         """Remove this mark by localize -> fill; returns ``(result, region)`` where
         ``region`` is the removed mark's bbox, or None if nothing was removed.
@@ -282,7 +326,7 @@ class KnownMark:
         usual footprint even without a positive detection (the ``--no-detect`` path).
         NB: the CLI does NOT use ``region`` to clear alpha on save -- that zeroing
         caused the issue-#30 white box."""
-        loc = self.localize(image, provenance=provenance, force=force)
+        loc = self.localize(image, provenance=provenance, force=force, detection=detection)
         if loc.mask is None or not loc.mask.any():
             return image.copy(), None
         return fill(image, loc.mask, backend=backend), (loc.region if loc.detected else None)
@@ -349,55 +393,31 @@ _GEMINI_PROVENANCE_MIN_CONF = 0.42
 
 _engines: dict[str, Any] = {}
 
+# key -> (module basename, class name). Only the NAMES live here: ``import_module``
+# runs inside :func:`_engine` on first use, so importing this module -- and with it the
+# metadata-only ``identify`` / ``visible_provenance`` path -- never pulls cv2 through
+# an engine. Same lazy-import shape as ``_text_mark_engine._rival_config`` and ``fill``.
+_ENGINE_CLASS: dict[str, tuple[str, str]] = {
+    "gemini": ("gemini_engine", "GeminiEngine"),
+    "doubao": ("doubao_engine", "DoubaoEngine"),
+    "jimeng": ("jimeng_engine", "JimengEngine"),
+    "qwen": ("qwen_engine", "QwenEngine"),
+    "kling": ("kling_engine", "KlingEngine"),
+    "yuanbao": ("yuanbao_engine", "YuanbaoEngine"),
+    "samsung": ("samsung_engine", "SamsungEngine"),
+    "jimeng_pill": ("pill_engine", "PillEngine"),
+    "runninghub": ("runninghub_engine", "RunningHubEngine"),
+    "baidu": ("baidu_engine", "BaiduEngine"),
+    "liblib": ("liblib_engine", "LibLibEngine"),
+}
+
 
 def _engine(key: str) -> Any:
     if key not in _engines:
-        if key == "gemini":
-            from remove_ai_watermarks.gemini_engine import GeminiEngine
+        from importlib import import_module
 
-            _engines[key] = GeminiEngine()
-        elif key == "doubao":
-            from remove_ai_watermarks.doubao_engine import DoubaoEngine
-
-            _engines[key] = DoubaoEngine()
-        elif key == "jimeng":
-            from remove_ai_watermarks.jimeng_engine import JimengEngine
-
-            _engines[key] = JimengEngine()
-        elif key == "qwen":
-            from remove_ai_watermarks.qwen_engine import QwenEngine
-
-            _engines[key] = QwenEngine()
-        elif key == "kling":
-            from remove_ai_watermarks.kling_engine import KlingEngine
-
-            _engines[key] = KlingEngine()
-        elif key == "yuanbao":
-            from remove_ai_watermarks.yuanbao_engine import YuanbaoEngine
-
-            _engines[key] = YuanbaoEngine()
-        elif key == "samsung":
-            from remove_ai_watermarks.samsung_engine import SamsungEngine
-
-            _engines[key] = SamsungEngine()
-        elif key == "jimeng_pill":
-            from remove_ai_watermarks.pill_engine import PillEngine
-
-            _engines[key] = PillEngine()
-        elif key == "runninghub":
-            from remove_ai_watermarks.runninghub_engine import RunningHubEngine
-
-            _engines[key] = RunningHubEngine()
-        elif key == "baidu":
-            from remove_ai_watermarks.baidu_engine import BaiduEngine
-
-            _engines[key] = BaiduEngine()
-        elif key == "liblib":
-            from remove_ai_watermarks.liblib_engine import LibLibEngine
-
-            _engines[key] = LibLibEngine()
-        else:  # pragma: no cover - guarded by the registry keys
-            raise KeyError(key)
+        module_name, class_name = _ENGINE_CLASS[key]  # KeyError(key) for an unknown key
+        _engines[key] = getattr(import_module(f"remove_ai_watermarks.{module_name}"), class_name)()
     return _engines[key]
 
 
@@ -462,13 +482,21 @@ def fill(image: NDArray[Any], mask: NDArray[Any], *, backend: Backend = "auto")
 # detector on the memory-tight identify host), so detection never builds a mask.
 
 
-def _gemini_detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
-    d = _engine("gemini").detect_watermark(image, trust_provenance=provenance)
+def _gemini_wrap(d: Any, *, provenance: bool) -> MarkDetection:
     gate = _GEMINI_PROVENANCE_MIN_CONF if provenance else _GEMINI_AUTO_MIN_CONF
     detected = bool(d.detected) and d.confidence >= gate
     return MarkDetection("gemini", "Google Gemini sparkle", "bottom-right", detected, d.confidence, d.region)
 
 
+def _gemini_detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
+    return _gemini_wrap(_engine("gemini").detect_watermark(image, trust_provenance=provenance), provenance=provenance)
+
+
+def _gemini_detect_both(image: NDArray[Any]) -> tuple[MarkDetection, MarkDetection]:
+    strict, relaxed = _engine("gemini").detect_watermark_both(image)
+    return _gemini_wrap(strict, provenance=False), _gemini_wrap(relaxed, provenance=True)
+
+
 def _gemini_mask(
     image: NDArray[Any], *, force: bool = False, detection: MarkDetection | None = None
 ) -> NDArray[Any] | None:
@@ -487,26 +515,73 @@ def _gemini_mask(
 def _text_mark_detect(key: str, label: str, location: str) -> Callable[..., MarkDetection]:
     def detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetection:
         d = _engine(key).detect(image, provenance=provenance)
-        return MarkDetection(key, label, location, d.detected, d.confidence, d.region)
+        return MarkDetection(key, label, location, d.detected, d.confidence, d.region, engine_detection=d)
 
     return detect
 
 
+def _text_mark_detect_both(key: str, label: str, location: str) -> Callable[..., tuple[MarkDetection, MarkDetection]]:
+    def detect_both(image: NDArray[Any]) -> tuple[MarkDetection, MarkDetection]:
+        strict, relaxed = _engine(key).detect_both(image)
+        return (
+            MarkDetection(
+                key, label, location, strict.detected, strict.confidence, strict.region, engine_detection=strict
+            ),
+            MarkDetection(
+                key, label, location, relaxed.detected, relaxed.confidence, relaxed.region, engine_detection=relaxed
+            ),
+        )
+
+    return detect_both
+
+
 def _text_mark_mask(key: str) -> Callable[..., NDArray[Any] | None]:
     def mask(
         image: NDArray[Any], *, force: bool = False, detection: MarkDetection | None = None
     ) -> NDArray[Any] | None:
-        # Text masks rebuild the glyph blob template-free (no trust gate to re-apply), so
-        # the detection is not needed here; accepted for the uniform _mask signature.
-        del detection
-        return _engine(key).footprint_mask(image, force=force)
+        # Thread the engine's OWN detection into the mask builder: the footprint is
+        # bounded by the ladder sweep the detector already ran, so re-detecting here
+        # repeated locate + extract_mask + an identical sweep. footprint_mask still
+        # re-detects when nothing is threaded (a direct or --no-detect caller) and when
+        # the threaded detection was taken at a relaxed trust level.
+        return _engine(key).footprint_mask(
+            image, force=force, detection=detection.engine_detection if detection is not None else None
+        )
 
     return mask
 
 
-def _text_mark(key: str, label: str, location: str) -> KnownMark:
-    """Build a text-mark registry row from its shared detector and mask adapters."""
-    return KnownMark(key, label, location, True, _text_mark_detect(key, label, location), _text_mark_mask(key))
+def _text_mark(
+    key: str,
+    label: str,
+    location: str,
+    *,
+    platform: str,
+    product: str | None = None,
+    label_regime: str | None = "tc260",
+    provenance_signals: tuple[str, ...] = ("aigc",),
+    tc260_producer_codes: tuple[str, ...] = (),
+) -> KnownMark:
+    """Build a text-mark registry row from its shared detector and mask adapters.
+
+    ``product`` defaults to the key (one mark, one product); pass it only when two
+    marks share a product. ``label_regime`` and ``provenance_signals`` default to the
+    China-AIGC label because every text mark registered so far except Samsung uses it.
+    """
+    return KnownMark(
+        key,
+        label,
+        location,
+        True,
+        product or key,
+        label_regime,
+        platform,
+        _text_mark_detect(key, label, location),
+        _text_mark_mask(key),
+        provenance_signals=provenance_signals,
+        tc260_producer_codes=tc260_producer_codes,
+        _detect_both=_text_mark_detect_both(key, label, location),
+    )
 
 
 # ── Capture-less mark: the Jimeng-basic "AI生成" pill (top-left) ──
@@ -518,6 +593,13 @@ def _pill_detect(image: NDArray[Any], *, provenance: bool = False) -> MarkDetect
     return MarkDetection("jimeng_pill", "Jimeng AI生成 pill", "top-left", d.detected, d.confidence, d.region)
 
 
+def _pill_detect_both(image: NDArray[Any]) -> tuple[MarkDetection, MarkDetection]:
+    # The pill detector is provenance-independent (`_pill_detect` discards the flag), so
+    # one call answers both levels. MarkDetection is frozen, so sharing it is safe.
+    d = _pill_detect(image)
+    return d, d
+
+
 def _pill_mask(
     image: NDArray[Any], *, force: bool = False, detection: MarkDetection | None = None
 ) -> NDArray[Any] | None:
@@ -534,19 +616,110 @@ def _pill_features(image: NDArray[Any]) -> dict[str, float]:
 
 
 _REGISTRY: tuple[KnownMark, ...] = (
-    KnownMark("gemini", "Google Gemini sparkle", "bottom-right", True, _gemini_detect, _gemini_mask),
-    _text_mark("doubao", "Doubao 豆包AI生成 text", "bottom-right"),
-    _text_mark("jimeng", "Jimeng 即梦AI wordmark", "bottom-right"),
-    _text_mark("qwen", "Qwen 千问AI生成 text", "bottom-right"),
-    _text_mark("kling", "Kling 可灵AI 3.0 text", "bottom-right"),
-    _text_mark("yuanbao", "Tencent Yuanbao 元宝 / AI生成 mark", "bottom-right"),
-    _text_mark("samsung", "Samsung Galaxy AI text", "bottom-left"),
-    _text_mark("runninghub", "RunningHub AI生成 text", "top-left"),
-    _text_mark("baidu", "Baidu 百度 AI生成 text", "bottom-right"),
-    _text_mark("liblib", "LibLibAI wordmark", "bottom-center"),
-    KnownMark("jimeng_pill", "Jimeng AI生成 pill", "top-left", True, _pill_detect, _pill_mask, _pill_features),
+    # Gemini is a Google C2PA/SynthID product, not a China-AIGC labeller: label_regime
+    # is None so it can never act as a TC260 sibling in _keep_pill.
+    KnownMark(
+        "gemini",
+        "Google Gemini sparkle",
+        "bottom-right",
+        True,
+        "gemini",
+        None,
+        # No platform sentence: the sparkle has its own higher-confidence
+        # `_visible_sparkle` path in identify, which names the platform itself.
+        None,
+        _gemini_detect,
+        _gemini_mask,
+        provenance_platform_tokens=("google", "gemini"),
+        _detect_both=_gemini_detect_both,
+    ),
+    _text_mark(
+        "doubao",
+        "Doubao 豆包AI生成 text",
+        "bottom-right",
+        platform="ByteDance Doubao (visible 豆包AI生成 mark detected)",
+        tc260_producer_codes=("91110102MACQD9K640", "doubao"),
+    ),
+    _text_mark(
+        "jimeng",
+        "Jimeng 即梦AI wordmark",
+        "bottom-right",
+        platform="ByteDance Jimeng / Dreamina (visible 即梦AI mark detected)",
+        tc260_producer_codes=("9144030008867405X2",),
+    ),
+    _text_mark(
+        "qwen",
+        "Qwen 千问AI生成 text",
+        "bottom-right",
+        platform="Alibaba Tongyi Qianwen (visible 千问AI生成 mark detected)",
+        tc260_producer_codes=("91440101MA9Y9T4H7A",),
+    ),
+    _text_mark(
+        "kling",
+        "Kling 可灵AI 3.0 text",
+        "bottom-right",
+        platform="Kuaishou Kling (visible 可灵AI 3.0 mark detected)",
+        tc260_producer_codes=("91110108335469089C",),
+    ),
+    _text_mark(
+        "yuanbao",
+        "Tencent Yuanbao 元宝 / AI生成 mark",
+        "bottom-right",
+        platform="Tencent Yuanbao (visible 元宝 / AI生成 mark detected)",
+        tc260_producer_codes=("91440300708461136T",),
+    ),
+    # Samsung Galaxy AI is a device editing marker (samsung_genai), not a TC260 label.
+    _text_mark(
+        "samsung",
+        "Samsung Galaxy AI text",
+        "bottom-left",
+        label_regime=None,
+        provenance_signals=("samsung_genai",),
+        platform="Samsung Galaxy AI (visible 'Contenuti generati dall'AI' mark detected)",
+    ),
+    _text_mark(
+        "runninghub",
+        "RunningHub AI生成 text",
+        "top-left",
+        platform="RunningHub (visible RunningHub AI生成 mark detected)",
+        tc260_producer_codes=("91340100MAEB4N8H76", "RunningHub"),
+    ),
+    _text_mark(
+        "baidu",
+        "Baidu 百度 AI生成 text",
+        "bottom-right",
+        platform="Baidu (visible 百度 AI生成 mark detected)",
+        tc260_producer_codes=("91110000802100433B",),
+    ),
+    _text_mark(
+        "liblib",
+        "LibLibAI wordmark",
+        "bottom-center",
+        platform="LibLibAI (visible LibLibAI mark detected)",
+        tc260_producer_codes=("91110105MACJ6K1C8A",),
+    ),
+    # Same product as the Jimeng wordmark -- the one pair that cross-relaxes.
+    KnownMark(
+        "jimeng_pill",
+        "Jimeng AI生成 pill",
+        "top-left",
+        True,
+        "jimeng",
+        "tc260",
+        # The capture-less pill is too weak a detector to attribute a platform on its
+        # own; the Jimeng wordmark is what names ByteDance.
+        None,
+        _pill_detect,
+        _pill_mask,
+        _pill_features,
+        _detect_both=_pill_detect_both,
+    ),
 )
 
+# Product family per mark, derived from the registry rows so registering a mark is one
+# edit. See KnownMark.product for why Doubao and Jimeng must not cross-relax.
+_PRODUCT_OF: dict[str, str] = {m.key: m.product for m in _REGISTRY}
+
 
 def known_marks() -> tuple[KnownMark, ...]:
     """All registered known visible watermarks."""
@@ -606,6 +779,30 @@ def resolve_trust(
     return "confirmed" if confirmed else "strict"
 
 
+def tc260_producer_vendors() -> dict[str, str]:
+    """TC260 ``ContentProducer`` identity -> the mark key whose vendor signs with it.
+
+    Derived from the registry rows, so registering a TC260 mark and its producer codes
+    is one edit. A mark registered without codes falls through to
+    :data:`TC260_FALLBACK_VENDORS`, which relaxes ByteDance's pair -- a silent wrong
+    answer on an image carrying the new mark, which is why the codes belong on the row
+    next to ``label_regime`` rather than in a table someone must remember to update.
+    """
+    return {code: mark.key for mark in _REGISTRY for code in mark.tc260_producer_codes}
+
+
+def _pill_suppressors() -> set[str]:
+    """Marks whose detection vetoes the capture-less pill: same label regime as the
+    pill, different product. Derived so a newly registered TC260 mark cannot be
+    forgotten here -- which is exactly how LibLibAI ended up missing."""
+    pill = get_mark("jimeng_pill")
+    return {
+        m.key
+        for m in _REGISTRY
+        if m.label_regime is not None and m.label_regime == pill.label_regime and m.product != pill.product
+    }
+
+
 def _keep_pill(keys: set[str], *, provenance: frozenset[str], footprint_flat: bool) -> bool:
     """Whether to auto-remove the capture-less 'AI生成' pill given the fired marks.
 
@@ -620,17 +817,18 @@ def _keep_pill(keys: set[str], *, provenance: frozenset[str], footprint_flat: bo
         so real flat-scene pills (and harmless flat false fires) are cleaned while the
         damaging textured false fires are left untouched.
     A Doubao image is TC260 too but is not Jimeng-basic, so the pill never rides on a
-    Doubao detection; Qwen, Kling, Yuanbao, RunningHub, and Baidu detections likewise
-    name other products and suppress the pill.
-    No confirmation at all -> never remove (blocks false fires on non-Jimeng content)."""
-    if (
-        "doubao" in keys
-        or "qwen" in keys
-        or "kling" in keys
-        or "yuanbao" in keys
-        or "runninghub" in keys
-        or "baidu" in keys
-    ):
+    Doubao detection; every other TC260 product's mark likewise names a different
+    product and suppresses the pill.
+    No confirmation at all -> never remove (blocks false fires on non-Jimeng content).
+
+    The suppressor set is DERIVED from the registry (same label regime, different
+    product), not hand-listed. The hand-written list had drifted: LibLibAI was
+    registered alongside RunningHub and Baidu but never added to it, so a confident
+    LibLibAI detection did not veto the pill the way its two siblings did. Marks
+    outside the TC260 regime (Gemini, Samsung) are deliberately NOT suppressors --
+    neither can put ``"jimeng"`` into ``provenance``, so neither can enable the arm
+    they would be vetoing."""
+    if _pill_suppressors() & keys:
         return False
     if "jimeng" in keys:
         return True
@@ -647,15 +845,17 @@ def _build_candidates(image: NDArray[Any]) -> list[Candidate]:
     Each mark is detected at the strict AND the relaxed (``provenance=True``) level so
     :func:`decide` can pick per mark without re-running detection; a relaxed gate is
     monotonically more permissive, so this reproduces the old strict-then-relax pass
-    exactly. The loop is uniform -- it knows nothing about any specific mark: each mark
-    reports its own gate features via :meth:`KnownMark.features` (computed only when the
-    mark is detected, so a clean image pays nothing extra)."""
+    exactly. Both levels come from ONE scan per mark (:meth:`KnownMark.detect_both`):
+    the trust level moves a threshold, never the measurement, so running the detector
+    twice was doing the expensive half of the work for a second time. The loop is
+    uniform -- it knows nothing about any specific mark: each mark reports its own gate
+    features via :meth:`KnownMark.features` (computed only when the mark is detected, so
+    a clean image pays nothing extra)."""
     cands: list[Candidate] = []
     for m in _REGISTRY:
         if not m.in_auto:
             continue
-        strict = m.detect(image, provenance=False)
-        relaxed = m.detect(image, provenance=True)
+        strict, relaxed = m.detect_both(image)
         feats = m.features(image) if (strict.detected or relaxed.detected) else {}
         cands.append(Candidate(m.key, m.label, strict.detected, relaxed.detected, feats))
     return cands

src/remove_ai_watermarks/yuanbao_engine.py

@@ -26,13 +26,16 @@ import logging
 from typing import TYPE_CHECKING, Any
 
 from remove_ai_watermarks import _text_mark_engine
-from remove_ai_watermarks._text_mark_engine import TextMarkConfig, TextMarkDetection, TextMarkEngine
+from remove_ai_watermarks._text_mark_engine import (
+    TextMarkConfig,
+    TextMarkDetection,
+    TextMarkEngine,
+    TextMarkScan,
+)
 
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from numpy.typing import NDArray
 
 WM_WIDTH_FRAC = 0.20
@@ -75,24 +78,12 @@ _CONFIG = TextMarkConfig(
     provenance_ncc_factor=1.0,
 )
 
-YuanbaoDetection = TextMarkDetection
-
 
 def _alpha_template() -> NDArray[Any] | None:
     """The bundled Yuanbao alpha template (float [0,1]), or None."""
     return _text_mark_engine.load_alpha_template(_CONFIG.asset_name)
 
 
-def _glyph_silhouette() -> NDArray[Any] | None:
-    """Binary two-line Yuanbao silhouette (255 = glyph), or None."""
-    return _text_mark_engine.glyph_silhouette(_CONFIG.asset_name)
-
-
-def _template_match_score(box_mask: NDArray[Any], scale_base: int) -> float:
-    """TM_CCOEFF_NORMED of the Yuanbao silhouette against ``box_mask``."""
-    return _text_mark_engine.template_match_score(box_mask, scale_base, _CONFIG)
-
-
 class YuanbaoEngine(TextMarkEngine):
     """Detect and localize the bottom-right Yuanbao mark."""
 
@@ -102,37 +93,28 @@ class YuanbaoEngine(TextMarkEngine):
     def __init__(self) -> None:
         super().__init__(_CONFIG)
 
-    def detect(self, image: NDArray[Any] | None, *, provenance: bool = False) -> TextMarkDetection:
-        if image is None or not image.size:
-            return TextMarkDetection()
-        detection = super().detect(image, provenance=provenance)
-        if not detection.detected:
-            return detection
-        location = self.locate(image)
-        _, box = self._contrast_best(image, location)
+    def _post_gate(self, det: TextMarkDetection, scan: TextMarkScan) -> TextMarkDetection:
+        """Demote a match that does not hug the bottom-right corner.
+
+        A shared post-gate rather than a ``detect`` override, so the single-pass
+        perception path (``detect_both``) cannot skip it.
+        """
+        if not det.detected or scan.loc is None:
+            return det
+        box = det.match_box  # the sweep the scan already ran on this same loc
         if box is None:
-            detection.detected = False
-            return detection
-        h, w = image.shape[:2]
+            det.detected = False
+            return det
+        h, w = scan.frame
         base = min(h, w)
-        right = (w - (location.x + box[2] + 1)) / base
-        bottom = (h - (location.y + box[3] + 1)) / base
+        right = (w - (scan.loc.x + box[2] + 1)) / base
+        bottom = (h - (scan.loc.y + box[3] + 1)) / base
         if not (0 <= right <= self._ANCHOR_MAX_RIGHT and 0 <= bottom <= self._ANCHOR_MAX_BOTTOM):
             logger.debug(
                 "Yuanbao detect: score %.3f but match off-anchor (right=%.3f bottom=%.3f); demoting.",
-                detection.confidence,
+                det.confidence,
                 right,
                 bottom,
             )
-            detection.detected = False
-        return detection
-
-
-def load_image_bgr(path: str | Path) -> NDArray[Any]:
-    """Read an image as a BGR ndarray."""
-    from remove_ai_watermarks import image_io
-
-    image = image_io.imread(path)
-    if image is None:
-        raise FileNotFoundError(f"Failed to read image: {path}")
-    return image
+            det.detected = False
+        return det