fix(runners): normalize painted inpainting masks for each provider (fixes #106)

[BerryUIKI]

Summary

Fixes #106 by normalizing Berry-painted masks to each provider's specific mask semantics. The canonical Berry convention (painted white = edit, transparent = protect) is now correctly converted for ComfyUI, WebUI, OpenAI, and Fal.ai.

Problem

Different providers interpret mask alpha channels differently:

• ComfyUI: LoadImage MASK output = 1 - alpha, so painted regions (alpha=255) became 0 (protect) instead of 1 (edit)
• WebUI: Expects grayscale where white=edit, black=protect
• OpenAI: Expects transparent=edit, opaque=protect (inverted from Berry)
• Fal.ai: Expects opaque=edit, transparent=protect (matches Berry)

The original implementation passed Berry masks directly without conversion, causing painted regions to be protected instead of edited in ComfyUI and OpenAI.

Implementation

Canonical Berry Convention

Documented in mask_converter.py:

• Painted regions (opaque white, alpha=255) = areas TO BE EDITED
• Unpainted regions (transparent, alpha=0) = areas TO BE PROTECTED

Provider-Specific Conversions

1. ComfyUI (normalize_mask_for_comfyui):

   • Inverts alpha channel before upload
   • Creates temporary converted mask
   • Cleans up after upload completes

2. WebUI (normalize_mask_for_webui):

   • Converts RGBA alpha to grayscale L mode
   • White (255) = edit, Black (0) = protect

3. OpenAI (normalize_mask_for_openai):

   • Inverts alpha channel
   • Transparent (0) = edit for API

4. Fal.ai (normalize_mask_for_fal_ai):

   • Validates format only
   • Already matches Berry convention

Integration Points

• creative_runner._run_comfy(): Converts and uploads mask, validates dimensions
• webui_runner._run_inpaint(): Converts mask before base64 encoding
• creative_runner._run_cloud(): Converts based on provider_id
• All paths validate source/mask dimension alignment

Cache Invalidation

Runner version bumped from 0.1.0 to 0.2.0 in compute_creative_cache_hash() to prevent reuse of results generated with incorrect mask semantics.

Tests

New Test Suite (test_mask_converter.py - 13 tests, all passing)

• ✅ Berry mask convention documentation
• ✅ ComfyUI alpha inversion
• ✅ WebUI grayscale conversion
• ✅ OpenAI alpha inversion
• ✅ Fal.ai passthrough validation
• ✅ Dimension validation (success, mismatch, file not found)
• ✅ Dimension preservation during conversion
• ✅ Partial alpha (anti-aliased edges)
• ✅ Fully painted mask
• ✅ Fully transparent mask

Existing Tests

• ✅ 22 ComfyUI bridge and upload tests passing
• ✅ No regressions in existing functionality

Verification

What Was Tested

• Unit tests verify correct alpha inversion for each provider
• Dimension validation prevents misaligned masks
• File handle management (Windows lock issues resolved)
• Edge cases: partial transparency, fully painted, fully transparent

What Remains Unverified

⚠️ Real GPU inference with actual ComfyUI/WebUI/cloud providers

Contract tests verify payload construction and mask conversion logic. Live inference testing requires:

• Running ComfyUI instance with real models
• WebUI instance with real models
• Paid cloud provider API access
• Manual visual verification of edited regions

Architecture Preservation

• ✅ Original Berry assets remain unchanged
• ✅ Source/mask dimensions strictly validated
• ✅ Deterministic caching preserved (version bump)
• ✅ API-first, local-optional architecture maintained
• ✅ No GUI or engine lifecycle changes

Documentation

Added MASK_NORMALIZATION.md documenting:

• Canonical Berry mask convention
• Provider-specific contracts
• Integration points
• Cache invalidation strategy

Related Issues

Fixes #106

🤖 Generated with Claude Code