Add concept board, v1 brief audit, and .gitignore
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user