dorado-hd/docs/ui-parity-audit.md

UI parity audit — Phase 1 (Dorado-HD)

Date: 2026-09-11 · Scope: all 63 registry apps + the shared UI harness Companion register: ui-parity-gaps.json (machine-readable) Program: UI Parity Test, Audit & Remediation (goal: usable + spec-faithful)

1. Method & evidence

Evidence	What it covers	Result
AppSmokeSuite (Robolectric Compose)	every registry app renders through the real host path at DEVICE 480×272, adaptive PORTRAIT 400×800, adaptive LANDSCAPE 800×360	63/63 green
tools/emulator_crawl.py (Android 16 x86_64)	deep-link launch + screenshot + package-filtered crash scan per app	63/63 launch, 0 crashes, 0 blank
Static audit passes (3 parallel)	W1/W2/W7 apps + harness; W3/W4 casual; W5/W6 engines — flow, scaling, input keys, loops, persistence, concrete file:line defects	63 open findings
Screenshot triage	all 63 entry screens read for clipping, overlap, overflow, empty layout	15 ranked visual failures + cross-app patterns

Baseline artifacts: reports/emulator/crawl.json, crawl-summary.json, shots/<slug>.png (git-ignored; regenerate with the tool).

2. Severity & acceptance bar

• P0 crash, softlock, dead-end, lost save, or input that breaks the run.
• P1 systemic/visible defect: unreachable or off-screen controls, dropped input, stuck overlay, IME-obscured fields, silent SFX, layout overflow.
• P2 fidelity/polish gap: empty-state copy, duplicated headings, inconsistent button rhythm, two-line row clashes.
• Acceptance: zero open P0/P1; every P2 closed or documented N/A; every app has a smoke test and crawl evidence; back/IME/layout contracts pass at all three configurations.

Canon clarification. Cropped typography (alarm cloc, run and jun) is the Zune HD design language (canon §7) and is not a defect. The audit distinguishes it from functional overflow: controls clipped off-screen, words wrapped inside a button, or rows hidden under system bars.

3. Systemic classes (fix once, benefits everything)

#	Class	Register	Notes
H-01	Back always exits the mini-app	DoradoRoot.kt:122; no per-screen BackHandler	Every multi-screen app and overlay loses state on system back
H-02/03	Context menu top-left + prompt text leak	Common.kt:131-195	Menus render over the header; nested prompts inherit text
H-04	No IME insets	MainActivity.kt:28, DoradoRoot.kt:102	Compose/search fields covered by the keyboard
H-05	Adaptive width ~227 units vs 480-authored rows	DeviceCanvas.kt:42-57	Root of the off-screen-control class (msnmoney, alarm, fan-prediction, shell game, solitaire, messenger)
H-06	Bottom content under the system nav bar	weather/calendar	Reserve insets inside apps, not just at the root
H-07	Wake shade raised on any onPause	DoradoRoot.kt:83-92	Crawl-confirmed: shade over the next app after a deep-link relaunch
H-08	Room writes keyed on ticking state	stopwatch 30 Hz, drum per frame, alarm 1 Hz, messenger per keystroke	Jank/battery; debounce helper
H-09	Composition side effects / double records	Sudoku, Reversi, Hearts, Spades, Solitaire	Move to effects with once-guards
H-10	Silent SFX	Checkers, Chess, Hexic (synth.start() missing)	One-line each
H-11	Bars/toasts overlay content	Facebook/Twitter shells, MiniPlayer	Reserve padding
H-12/13/14	Menu rhythm, duplicate headings, empty states	across apps	P2 polish

4. P0 game-breakers (per-app)

Run-and-jump death softlock · Hairball + Splatter Bug frozen retry · Vine Climb tap rewind · BBQ + Bees per-frame gesture churn · Slider Puzzle pause/autosave · WordMonger save-on-exit · Castles stale camera · Texas Hold'em buy-in lock · Facebook About trap · Twitter orphan DMs · Piano octave snap · Hearts PassPicker duplicates · Metronome dial drag · Calendar month grid + nested prompt · Shell Game/Snowball/Tug-O-War no-sensor dead input · AlarmManager exact-alarm crash + lost sleep timer · 3D Picture Puzzle GL rebuild leak · PGR per-frame mesh leak + background audio · Echoes countdown input · plus the cold-start state-clobber races (Supernova, Snowball, RunAndJump, SpaceBattle, Penalty, VineClimb, DecoderRing).

5. Visual failures from the emulator baseline

Ranked in the register (V-01…V-15): msnmoney tab bar, solitaire action column, fan-prediction overflow, shell-game shop column, shuffle track rows, zunesocial/zunereader truncation, audiosurf row clash, drummachine dead panel, calculator scientific default + wrapped key, alarm tab clip, messenger presence clip, 3D puzzle double title, weather nav-bar collision, twitter banner crop.

6. Remediation waves

1. W-H (harness): H-01…H-11 + the adaptive overflow contract.
2. W-P0: every P0 row, each with a regression test (UI test where applicable, engine test otherwise).
3. W-P2: fidelity rows + spec-checklist closure, then record goldens.
4. W-V: full unit + UI suites, lint, emulator re-crawl, closeout docs.

Every fix updates its register row to fixed with the commit SHA; the register is the falsifiable progress tracker for the program.

---

7. Remediation results (Phase 2/4 closeout)

Register: all P0/P1 rows are fixed; the two remaining P2 rows are closed (H-13 duplicate headings) or documented as accepted variation (H-12 menu rhythm, matching both rhythms present in the device-era UI).

Harness (W-H): hardware back follows the in-app header contract on every sub-screen (DetailScaffold(onBack) → BackHandler); the context menu/prompt anchors bottom-center and resets per request; the root applies IME insets with adjustResize; the wake shade triggers on ON_STOP only; MiniSynth.start() added where missing; Room writes throttled.

Per-app (W-P0): the 24 game-breakers (softlocks, frozen retries, dropped inputs, stale captures, lost saves, buy-in loss, GL rebuild storms, sensorless dead ends, exact-alarm crashes, cold-start clobber races) and the layout overflow class are fixed, each with a regression test where the defect is engine-expressible.

Verification layers now in CI (testDebugUnitTest):

Layer	Coverage	Result
Unit/engine suites	1,406 tests	green
AppSmokeSuite	63 apps × 3 parity configs	green
LayoutBoundsTest	63 apps × portrait/landscape: no unreachable clickables	126 green
BackContractTest	system back on game sub-screens returns in-app	green
GoldenCaptureTest	59 apps' device-mode entry frames, pixel tolerance	green
DesignInvariantTest	token/corner/motion invariants + silent-synth, unkeyed-pointer-input, onBack-forwarding and IME structure guards	0 violations
Emulator crawl	63 apps deep-link launch, crash + blank scan	63/63 ok

Coverage checklist: docs/ui-parity-checklists.md (63 apps × spec/smoke/bounds/golden/crawl).

Residual, documented: four clock/date screens (alarm, calendar, weather, notes) are excluded from pixel goldens because their entry frame renders the wall clock/date — they stay covered by smoke, layout, back and crawl layers; GL resource behaviour is guarded by pure cache-policy tests rather than GL instrumentation; IME correctness is structural (root insets + adjustResize) and visually spot-checked on the emulator rather than simulated in Robolectric; canvas-drawn text is not exposed to the accessibility tree (a standing fidelity/accessibility opportunity, not a parity regression).

---

8. Track A hardening (post-program)

Item	Result
A1 CI guards	lintDebug, tools/ui_lint.py and a py_compile check now run in the HD CI workflow alongside the unit/UI suites
A2 Interactive flow crawl	tools/emulator_flow_crawl.py drives each app's primary flow, then backgrounds/relaunches and cold-restarts it, scanning logcat per step: 63/63 apps, 0 crashes (evidence: reports/emulator/flows/)
A3 Accessibility	AppTouch.kt (appTap / appHold / appDescription) applied across the catalog: every button/row/tab exposes a TalkBack click action, boards and readouts carry state descriptions, press-and-hold controls expose a click. The flow crawl had to tap text bounds because pointerInput controls previously exposed no click action — that gap is closed
A4 Golden expansion	Wall-clock seam AppClock (production = system clock; tests frozen at 2024-06-15T12:34Z) enables deterministic goldens for the alarm/calendar/weather/notes entry frames; the suite now records 126 goldens (device 480x272 + adaptive landscape for all 63 apps) and verifies within tolerance. Suite total: 1,477 tests

The four clock/date exclusions from the original golden set are gone: the seam makes those entry frames deterministic. Second-screen goldens remain the one deferred item — mid-flow visuals are covered by the interactive flow crawl's per-step screenshots.

---

9. Next-steps program results (Tracks B/C/D)

Verified on-device: entry crawl 63/63 (0 crashes, 0 blank) and interactive flow crawl 63/63 (primary flow → pause → background/relaunch → cold restart), latest run 2026-09-12. Accessibility semantics from Track A also made the UI tree readable to the crawl (text nodes now present).

Item	Evidence
Fade-through crossfade + sleep timer	media/FadeRamp.kt + controller tests; settings ▸ playback
Live FFT visualizer (C5)	TapRenderersFactory/VisualizerBus/SpectrumBands; PCM-tap integration test
Richer lock-screen (M10)	DoradoMediaNotificationProvider + Robolectric provider test
Smart DJ, podcast search, Zune-Card export (M5)	music crossbar menu; PodcastSearch/CloudPodcastDirectory; CardRenderer/CardExporter
Radio + picture Now Playing, photo grid (M13)	RadioNowPlaying, PicturePresentation, ArtistPhotos
Inbox/user card (D2)	CloudSocialClient + local-first inbox_messages (DB v8)
Audiobooks (D4)	model/scanner/grouping, DB v7, parts player with speed ladder
Queue engine, built-in playlists, PIN lock	QueueEngine + showlist move/next/clear; BuiltInPlaylists; PinLock + shade keypad
Roster uplift	PGR 12 cars/6 tracks/18 events; Echoes 24 arenas; bowling 8 lanes; Labyrinth at parity

Regression the crawl caught: the audiobook speed restore in PlaybackController.connect() ran off the application thread, crashing every launch (63/63 crawl failures); fixed by resuming controller calls on Dispatchers.Main. Unit/UI suites did not catch it because tests disable the service connection — the on-device gate is the reason this shipped correctly.

Documented N/A / deferred: live-radio ±5-min rewind (needs a time-shifting server); the four remaining emulator titles (two corpus gaps, two dead services); desktop i18n remaining locales (deferred registry, 20 shipped); organization repository pinning (profile-level manual step).