Eye-zone model with reflected-glare constraints

[vfilby]

What

Replaces the floor-strip protect_depth model with an optional eye zone — a height range × depth range to keep sun out of — plus reflectors (floor, countertops) that catch sun bouncing up into it. protect_depth is unchanged and remains the default; nothing changes for existing configs until a zone opts in.

How it works

All geometry stays in the profile-angle plane, so each reflector is just {height, from, to} — no 3D. Reflections are handled by unfolding the mirror: a bounce off a plane at height r into the eye zone is a straight ray into the zone's mirror image below that plane, so every reflector is one more linear constraint in the same min(). Constraints are clipped to the strip of surface that can actually bounce into the zone and to the patch the sun actually lights, which yields the escape case (bounce lands beyond the hazard, rises past the eyes) for free.

The result is deliberately non-monotonic over a day — glare when high (floor bounce), open mid-descent, closing again as the sun reaches eye level — matching the observed kitchen behavior.

Changes

• calculator.py: EyeZone, Reflector, sill_height; glare() takes the min over direct + per-reflector constraints and reports which one bound via a new constraint field
• __init__.py: YAML schema (eye_zone, reflectors, sill_height), cross-field validation, protect_depth now optional-but-one-required
• sensor.py: constraint attribute on the glare sensor (direct/reflected/none) for shadow-mode tuning
• README section, manifest → 0.3.0
• 8 new calculator tests (28 total pass): protect_depth equivalence, mirror-formula exactness, counter extent clipping, sill escape branch, non-monotonic daily pattern, above-zone reflector ignored

Verification

• pytest tests/ -q → 28 passed
• YAML schema smoke-tested end-to-end with HA stubbed (valid configs map to geometry; 5 invalid shapes rejected)

Suggested rollout: add an eye_zone + floor/counter reflectors to the kitchen zone only, shadow the constraint attribute for a few sunny days, and narrow reflector spans if reflected binds at glare-free hours.

🤖 Generated with Claude Code