iOS harness: stop tap_xy reporting phantom successes; add pixel sampling for colour

[GenericJam]

The on-device test harness reported success for things that did not happen, and could not see colour at all. Both made agent-driven verification on iOS unreliable — an iOS renderer bug sat unverified in a downstream repo for weeks partly because of this.

1. tap_xy reported :ok when nothing happened

On a physical iPhone it returned :ok for every coordinate — including empty space — and nothing ever happened; mob_send_touch_phase returns YES for API availability, never delivery. On the simulator, tapping a Box with on_tap: returned :ok while the handler never ran, because SwiftUI gives a plain .onTapGesture no accessibility action.

Now the return value reflects whether a handler actually ran: a process-wide atomic counter is bumped by every send helper that routes a user event into the BEAM (mob_send_tap, mob_send_event, mob_send_change), sampled before injection and polled for 300 ms after.

Value	When
:ok	an event reached the BEAM within 300 ms
{:error, :no_view_at_point}	hit-test found nothing (now on both platforms)
{:error, :no_effect}	input accepted, no handler ran
{:error, :no_element_at_point}	simulator: view present, no AX element

@doc now states the real per-platform capability, including that coordinate tapping does not work on a physical device and that the counter only sees Mob's own handlers (sidecar caveat). tap_xy also moved to ERL_NIF_DIRTY_JOB_IO_BOUND — it was already sleeping on a normal scheduler.

Device-verified: a theme chip (Box + on_tap) now returns {:error, :no_effect} where it previously returned a false :ok.

2. view_tree colour: measured, then abandoned as designed

Reading UIView.backgroundColor/UILabel.textColor gave colour for 2 of 443 nodes. Also walking CALayer/CAShapeLayer/CATextLayer reached 4 of 443. The new ui_paint_debug/0 census says why:

204x SwiftUI._UIInheritedView / CALayer            all paint props 0
 64x SwiftUI._UIInheritedView / SwiftUI.SDFLayer   all paint props 0
 14x _UIInheritedView / CGDrawingLayer             all 0, contents=14

SwiftUI on iOS 26 paints via SDFLayer or rasterises into contents, exposing no readable paint property. Layer introspection is a dead end for SwiftUI content — recorded in an ADR rather than iterated on further. The colour fields stay (correct for UIKit chrome, root background, future Android) alongside a new :class field so a caller can tell which renderer drew a node and therefore why a colour is nil.

3. sample_color/2 — colour verification that works

sample_region/4 returns raw RGBA for a natively cropped region (small payload over distribution), reduced by a pure, unit-tested Elixir function to average, dominant, dominant_share and distinct — because a card with text on it is not one flat colour, and the share/distinct fields tell you whether to trust dominant.

Gated strictly #if !MOB_RELEASE, deliberately not the || defined(MOB_ENABLE_SCREENSHOT) its neighbour uses: arbitrary-rect pixel reads let a caller reconstruct the screen region by region, which would hand release builds the capability that opt-in exists to gate. Pinned by a test on the guard string.

Acceptance test, on device: two chips, background: :primary vs :surface_raised, under a glass theme.

Build	active	inactive
without the glass fix	0xFF20202E	0xFF20202E	bug reproduced
with #78	0xFF4000AF	0xFF101023	fix confirmed

The regression that previously required hand pixel-diffing is now assert a.dominant != b.dominant.

Also reported, not fixed

scroll_info, scroll_to and element_frames are behind #if !MOB_RELEASE on iOS while Android registers them unconditionally, so an iOS release build raises nif_error(not_loaded) and kills the calling screen process. None of the three touches private API — the screenshot opt-in pattern would fit.

Verification

1011 tests passing, format/credo --strict/erlfmt/clang-format clean; ObjC compiled and run on an iPhone 17 simulator; non-vacuity of new tests proven by sabotage-and-restore.

🤖 Generated with Claude Code