# On the Level — v1 Brief Audit

**Auditor:** Claude · **Date:** 2026-07-11
**Subject:** v1 product/architecture brief (Codex) + concept board (`resources/Bubble Level Concepts.dc.html`)

## Verdict

**Approve with amendments.** The framework is sound and well-proportioned: single app module, manual DI container, no backend, offline-first, and — the load-bearing decision — the three-value separation of raw sensor → stable measurement → animated display. Findings below are ranked; the first three should be resolved in the brief before code is written.

---

## Blocking findings

### 1. Default sensor: use `TYPE_GAME_ROTATION_VECTOR`, not `TYPE_ROTATION_VECTOR`

`TYPE_ROTATION_VECTOR` fuses the magnetometer, and a level is used precisely where magnetometers lie: against steel studs, appliances, metal door frames, workbenches with power tools. Heading is irrelevant to a level — only the gravity direction matters.

- **Primary:** `TYPE_GAME_ROTATION_VECTOR` (gyro + accel, no magnetometer)
- **Fallback:** `TYPE_GRAVITY`, then low-passed accelerometer (as the brief already plans)
- Declare `uses-feature android.hardware.sensor.accelerometer` (required) in the manifest.

### 2. Missing concept: flat mode vs. edge mode

A bubble level is used two ways: phone lying on a surface (bullseye/cross — what all four mockups show) and phone held on its long edge against a wall, shelf, or picture frame. The math, the meaningful readout, and the UI all differ, and credible level apps auto-switch based on the gravity vector. Edge mode is arguably the *more* common real-world use.

- Add mode detection/auto-switching to v1 scope.
- This affects the sensor-mapping design, so decide now — it does not retrofit cleanly.

### 3. Calibration: store a reference orientation per mode, not one scalar offset

Subtracting a single angle baseline is only valid near the orientation where it was captured; a flat-mode calibration silently applied in edge mode makes readings *worse*.

- Store the baseline as a reference gravity vector/quaternion, **per mode** (flat / edge).
- Strongly recommend the classic two-measurement flow: measure, flip the phone 180°, measure again — true level is the average. It cancels device bias without needing a known-level surface, mirrors how physical levels are calibrated, and is trust-building UX.
- Invariant: lock detection and the displayed degree readout must be computed from the **same** calibrated stable value. The lock must never fire while the readout shows 0.1°.

---

## Answers to the brief's audit questions

### Sensor source / orientation reliability
Yes, once findings 1–2 are addressed. One implicit decision to make explicit: sensor axes are **device-frame, not display-frame**. Cleanest approach is to lock the Activity to portrait (avoids recreation churn mid-measurement) and remap axes / rotate UI affordances yourself from the gravity vector — in which case "normalize for screen rotation" is your own remapping code, not `Display.getRotation()`. Either approach works; pick one explicitly.

### Calibration consistency
Covered by finding 3.

### Feedback/animation separated from measurement truth
The three-value separation handles this. Specify the mechanisms so it's testable:

- **Stable value:** EMA/low-pass with a defined time constant
- **Display value:** critically-damped spring
- **Readout:** 0.1° resolution with a display deadband so it doesn't flicker between 0.0° and 0.1°
- **Lock:** enter ≤0.2°, exit ≥0.35°, short dwell before feedback (as proposed — good), plus a debounce floor of a few seconds between haptic events

### Free tier completeness
Complete and fair as specced. Product concern (non-blocking): the screen ruler is a weak Pro anchor — screen rulers are commodity, ~15 cm, and mediocre by nature. **Target-angle alerts and saved angle references are the real Pro value** for anyone doing actual work (stair stringers, drainage slope, shelf pitch). Market Pro around those; treat the ruler as a bonus.

### Pro boundary containment
The narrow `ProEntitlementRepository` is right. Make it concrete:

- Entitlement exposed as a `StateFlow<Entitlement>` from the container
- Billing calls confined to `core/billing`
- Free path never blocks on billing init (billing client connects lazily/async; level screen renders immediately)
- **Cache entitlement in DataStore** — Play Billing's `queryPurchases` needs healthy Google Play services; a Pro user on an offline job site must not lose the ruler

### Accessibility / legibility / reduced motion
Two Android-specific corrections:

- There is no first-class reduced-motion preference on Android — the signal is `Settings.Global.ANIMATOR_DURATION_SCALE == 0` (user disabled animations). Honor that plus an in-app toggle.
- Haptics: use `HapticFeedbackConstants.CONFIRM` / `VibrationEffect` so system haptic settings are respected.
- Bright-light check the amber-on-graphite and lime-lock palette — outdoor use is core. Keep numeric readouts near-white (as mockup 1c does); consider a high-contrast option later.

### Over-complexity
No — architecture is right-sized. If anything, **add** two small things:

- `FLAG_KEEP_SCREEN_ON` while a tool screen is visible (levels are used hands-free; screen timeout mid-measurement is a one-star review)
- Unregister sensor listeners when backgrounded (battery)

---

## Smaller notes

- **Ruler calibration UX:** calibrate against a credit card (ISO width 85.60 mm) rather than asking the user to hold a physical ruler to the screen. Key calibration by `Display` identity, not just configuration — foldables have two displays that each need their own scale.
- **Percent grade:** define as `tan(pitch) × 100` and decide display behavior as pitch approaches 90° (cap or show ∞) — otherwise a wall reads a comedy number.
- **Testability, made concrete:** all math (axis remapping, calibration application, smoothing, hysteresis) lives in pure Kotlin behind an injected `SensorSource` fake, with recorded real-device sensor traces as golden fixtures. That makes "trustworthy" verifiable rather than aspirational.
- **Trivia:** mockups use iOS device frames for an Android target (fine — UI is fully custom; just handle edge-to-edge insets and back gesture). The concept HTML references `./support.js` and `./ios-frame.jsx` not present in the repo.

---

## Summary of amendments to the brief

1. Sensor: `TYPE_GAME_ROTATION_VECTOR` primary; gravity/accel fallback; manifest `uses-feature`.
2. Add flat-mode / edge-mode detection and switching to v1 scope.
3. Calibration = reference orientation stored per mode; offer 180°-flip calibration; lock and readout share one calibrated value.
4. Rebalance Pro pitch toward target angles / saved references over the ruler.
5. Specify smoothing (EMA + damped spring), display deadband, haptic debounce floor.
6. Entitlement cached in DataStore; billing never blocks the free path.
7. Reduced motion via `ANIMATOR_DURATION_SCALE`; system-respecting haptics.
8. `FLAG_KEEP_SCREEN_ON` on tool screens; unregister sensors when backgrounded.
