# 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` 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.