Redesign Android + iOS operator app UI — Control tab needs quick-access feature surfaces (design doc first)

[SlyWombat]

Goal

Redesign the operator-mobile UI (Android today, iOS to be added) into an award-winning, smart, clean experience. The current Stage / Control / Status three-tab shape is the starting point — Stage and Status are largely retained; Control is the focus of the rework.

Per feedback_critical_path_spec_first: write/update an authoritative design doc first before any code lands. Operator vetoes piecemeal patches in critical-path subsystems, and the operator UI is exactly that.

Tab requirements

Stage — unchanged

Same functionality as v1.7.126. Layout view, fixture placement read-out, gyro/puck claim. Cosmetic refresh OK; behaviour identical.

Control — major rework

Today's Control tab is a fixed strip of widgets. The new design must expose quick access to any number of operator surfaces from a single screen, without nested menu diving:

• Grab an individual DMX fixture and control it directly (e.g. trigger bubbles on the Chauvet Hurricane Bubble Haze X2 Q6 — bubble on/off, haze level, fan speed, LED colour, strobe). Should work for any fixture in the layout, profile-driven.
• Grab a moving head and start aiming it (claim → live pan/tilt + colour, hands-on takeover).
• Auto Brightness — one-tap enable/disable + master multiplier.
• Pick and run a show — show selector + transport (play / stop / loop) without leaving Control.

Constraints:

• Operator-only — no editing of layout, actions, timelines, profiles (per feedback_android_operator_not_editor).
• Must work one-handed on a phone in a dim room (large tap targets, high contrast, no reliance on hover).
• Must scale to many fixtures (12+) without becoming a search problem — favourites, recent, grouping.
• Visual language follows the Kinetic Prism design manifesto: dark-first, bloom, Space Grotesk, shared tokens with desktop SPA.
• UI parity rule still applies (feedback_ui_parity): any control surface that exists in the mobile Control tab must also exist on the desktop SPA.

Status — unchanged shape

Performer health, RSSI, uptime, last PONG. Cosmetic refresh OK.

Cross-platform

The same design must carry into a native iOS app. Implementation strategy is open (Kotlin Multiplatform / native SwiftUI mirror / React Native / Compose Multiplatform) — the design doc decides based on:

• ability to reuse the existing UDP binary protocol + REST client code,
• visual fidelity to Kinetic Prism,
• App Store + Play Store distribution friction (operator currently sideloads APK — that won't fly on iOS).

Deliverables (in order)

1. Design doc in docs/design/mobile_ui_redesign.md covering:
   • Information architecture for Control (how the quick-access surfaces compose without nesting).
   • Wireframes for each surface (fixture-direct, moving-head grab, Auto Brightness, show picker/transport).
   • Component inventory + Kinetic Prism token map.
   • iOS strategy decision + rationale.
   • Migration path from current Android app (incremental vs. greenfield).
   • Test strategy (Playwright is desktop-only; what's the mobile equivalent?).
2. Operator review + sign-off on the doc before any code.
3. Implementation broken into staged PRs per the doc.

Out of scope for this issue

• Desktop SPA redesign (separate effort if needed).
• Editing surfaces — operator app stays operator-only.

Acceptance

• Doc merged and approved before any UI code.
• Control tab demonstrably reaches each of {direct DMX fixture, moving head, Auto Brightness, run a show} in ≤2 taps from app open.
• Android + iOS share a single design language and the same operator mental model.

[SlyWombat]

Design doc v2 — Gemini 2.5 Pro review folded in

Draft at docs/design/mobile_ui_redesign.md. v1 went through a Gemini 2.5 Pro adversarial review; verdict was ship-with-named-changes. All four mandatory changes are now in v2.

Gemini's findings

1. Two-tap goal failed the v1 IA. The vertical card stream meant "Trigger a bubble" and "Start a show" landed off-screen below the fold — scroll-to-find broke the operator promise. Quoted finding: "This is the antithesis of a 'quick-access' command surface and is worse than the current UI's '1 tab + scroll.'"

2. iOS strategy was misframed. v1 hand-waved TestFlight as "sideload-equivalent" — it isn't (90-day expiry, constant rebuild dance). The real question was App Store vs. no iOS app. Quoted: "Do not proceed under the illusion that a simple 'sideload-equivalent' exists."

3. Missing entirely: network-loss states, conflict states (another operator already claimed a mover), haptics (the "performance instrument" sense), per-card error states, panic surface (kill strobes / send movers home), Dynamic Type accessibility. Quoted: "The document is strong on the 'happy path' but weak on the 'show is on fire' path."

4. §5.4 channel-name match strategy was brittle. The §10.5 hybrid (opt-in "shortcut" field + name fallback) should be promoted from open question to main spec.

5. Kinetic Prism mostly serves the operator — not cargo-culted. But the glass effect needs an explicit "legibility takes precedence" clause.

6. Ambition reframe: "award-winning UI" is the wrong target for a live-control app. The right target is "ultimate performance instrument" — and that requires haptics as a first-class citizen, not polish.

What changed in v2

Area	v1	v2
Control IA	Vertical LazyColumn of 5 cards	Persistent Now Playing anchor + segmented HorizontalPager (Master / Grab / Fixtures / Shows)
Two-tap goal	Not structurally guaranteed	Structurally guaranteed (1 segment tap + 1 action tap)
Shortcut renderer	Name-match w/ hybrid as §10.5 open Q	Hybrid promoted to §5.3.1: explicit shortcut field → capability heuristic → name-match fallback. Schema gets optional shortcut per channel
iOS distribution	"TestFlight or sideload-equivalent" hand-wave	Ad-hoc via paid Apple Developer account (operator-confirmed); Stage 0.5 pre-work block defined; TestFlight explicitly rejected for 90-day expiry
iOS framework	Compose Multiplatform recommended	Stands; the v1 caveat ("distribution unclear") is resolved
Resilience	Not addressed	New §6 Resilience & Feedback: connection state machine (Connected → Degraded → Disconnected) with UI patterns, claim-conflict takeover sheet, full haptics catalogue, per-card error states, panic sheet, Dynamic Type / reduce-motion / colour-blind a11y
Panic	Long-press logo for blackout	Long-press logo plus a 🛟 Panic sheet (Blackout / All Movers Home / Stop Show / Kill Strobes / Stop Bubbles+Haze) — needs 4 new server endpoints
Principles	10 unordered	10 ordered — "Confirm with feel, not just sight" is principle #1; "Operator-only" explicitly states what we give up to be award-winning
Open questions	7	5 (iOS / card order / shortcut strategy resolved)

iOS sideload — confirmed direction

Operator has confirmed paid Apple Developer Program ($99/yr) + ad-hoc provisioning is the testing path. Stage 0.5 must run in parallel with Stage 1 (no iOS code yet, but enrolment, Bundle ID ca.electricrv.slyled, certs/profiles, and test-device UDIDs need to be in place before any iOS commit can be signed).

Remaining open questions for operator (§11)

1. Need POST /api/show/next for the Now Playing anchor's Next button — priority?
2. Grab tile preview: pan/tilt arrow on 56dp tile readable in dim room, or just colour?
3. Blackout: long-press logo (hidden) vs. always-visible top-bar button?
4. Settings tab stays in bottom nav — confirm?
5. Default page on cold start: Master (current spec) or Shows?

🤖 Generated with Claude Code

[SlyWombat]

v1.8.1 — Command Surface redesign shipped

Released as android-v1.8.1.

What landed

Android Control tab — full v3 design from docs/design/mobile_ui_redesign.md:

• Persistent NowPlayingAnchor (STOP + Next, cyan pulse when playing)
• 4-page HorizontalPager — Master (default) / Grab / Fixtures / Shows
• Master: brightness + ±5% steppers + Auto Brightness toggle (moved from Settings) + source picker + live envelope meter
• Grab: mover tiles with current colour + pan/tilt arrow, favourites row, "Send all home" safety button
• Fixtures: profile-driven shortcut renderer (🫧 / 💨 / 🌀 / 💡 / 🟣 / ⚡ / 🧼), "More controls →" sheet with capability sliders, "Stop all effects" safety button
• Shows: starred → recent → all sections with one-tap launch + last-played persistence

Top bar: long-press SlyLED logo → blackout. Connection pill (Connected / Reconnecting / Offline) replaces the static server-info text. Settings stays at the top-right gear (operator confirmed).

Resilience (§6): connection state machine, haptics catalogue (Haptics.kt), per-card error handling, page-level safety buttons replacing the v2 panic sheet (operator decision §10.3).

Backend: 5 new endpoints — /api/show/next, /api/mover-control/all-home, /api/fixtures/kill-strobes, /api/fixtures/kill-effects, /api/fixtures/<fid>/channel-write.

Profile schema: optional shortcut per channel; Hurricane Bubble Haze X2 Q6 community profile annotated. Resolver shared between SPA (fixture_shortcuts.js) and Android (FixtureShortcuts.kt) via the same 3-pass algorithm.

iOS: prep-only — see docs/design/apple_developer_setup.md for the operator-side Apple Developer enrolment + ad-hoc provisioning steps that unblock the Compose Multiplatform iOS build. Once those steps are done, the iOS port is mostly mechanical from the existing Kotlin codebase.

Known follow-ups (deferred, not blockers)

• Bundle Space Grotesk + Inter font assets in res/font/ — type ramp size/weight is correct, families default to system sans-serif until then.
• TakeoverSheet implemented but not auto-shown on real claim conflicts — needs a poll diff in ControlViewModel (v2).
• Screenshot regen via tests/screenshot_capture.py once the rig is running v1.8.1.
• iOS Compose Multiplatform scaffold — blocked on operator-side Apple Developer setup.

Tests

• test_parent: 755 passed / 2 pre-existing failures unchanged.
• Manual: assembleRelease green, APK 51.3 MB, aapt confirms versionCode=1081 versionName=1.8.1.

Closing this issue once the operator validates on the rig.

🤖 Generated with Claude Code

[SlyWombat]

iOS parity spec up for review

Drafted docs/design/ios_parity_spec.md (v1) — a port spec, not a UX redesign. IA / shortcut catalogue / haptics map / resilience model stay canonical in mobile_ui_redesign.md; this spec only covers how the Android v1.8.2 surfaces land in native SwiftUI.

TL;DR of the proposal

• Native SwiftUI, not Compose Multiplatform. The v0.1.0 shell + TestFlight CI already work; rebuilding the install path for CMP is rejected. Trade-off (dual codebase + Swift twin of FixtureShortcuts.kt) accepted, mitigated by a shared snapshot-test corpus across Pytest / JUnit / XCTest.
• iOS file layout mirrors android/app/src/main/java/.../ package-for-package, so a contributor can translate between the two by package name.
• REST client extended from 4 endpoints to the full Android catalogue (§7 has the table).
• Network.framework UDP client sends only AUTOBRI_PUSH (cmd 0x6D, port 4211, 11 bytes) — the only UDP message the operator app uses.
• AVAudioEngine mic capture runs the same envelope / beat math as Android (constants are contract — no retuning). System-playback capture is dropped on iOS (no API equivalent) — operator decision noted as open question 1.
• 6-stage TestFlight build sequence v0.2 (pager + Master + Grab read-only) → v0.7 (parity sign-off), one tag per stage, no bundling, no skipping.

Critical decisions awaiting operator

1. Playback-capture source on iOS — drop from picker, or pursue AirPlay-receiver mode later?
2. OK to land a doc-only commit fixing mobile_ui_redesign.md §7.1 (still says Compose Multiplatform + ad-hoc) before any iOS code?
3. Bundle v0.2 = pager + Master + Grab, or split into v0.2 (pager + Master) + v0.2.1 (Grab)?
4. Bonjour-discovered host picker in v0.2 SettingsScreen, or keep manual host entry?
5. AppIcon + AccentColor — v0.2 launch or v0.7 polish?
6. iPhone-only through v0.7 — confirm?

Full list in §16. No iOS code lands until this spec is signed off and the §7.1 doc-fix merges.

🤖 Generated with Claude Code