squeezelite-esp32/documentation/agents/frontend_requirements_context.md

Frontend Requirements Context (Living)

Status: Active
Last reviewed: 2026-02-12
Review scope: components/wifi-manager/webapp, components/wifi-manager/http_server_handlers.c, components/wifi-manager/wifi_manager_http_server.c, spiffs_src/CMakeLists.txt

Purpose

This document captures reverse-engineered product requirements for the embedded web UI, with measurable constraints.
It is intentionally not an implementation walkthrough.

Use this as session handoff context for UI refactoring and footprint control.

Snapshot Findings (Current State)

1. What actually ships to firmware

SPIFFS packaging currently copies only:

• components/wifi-manager/webapp/dist/*.gz
• components/wifi-manager/webapp/dist/*.png

Evidence: spiffs_src/CMakeLists.txt.

Current shipped web payload:

• Total shipped bytes: 219741 (~214.6 KiB, ~0.21 MiB)
• Largest asset: dist/js/node_vendors.bundle.js.gz (166729 bytes)

2. What looks large but is not currently shipped

• dist/ total is about 4.5M, dominated by source maps (*.map).
• Source maps are large in repo artifacts, but not copied to SPIFFS by current packaging.

3. Major technical debt signal

• UI source references many legacy endpoints (/status.zzz, /messages.zzz, /commands.zzz, etc.).
• Active server registration in wifi_manager_http_server.c is centered on /data.bin + static handlers; many legacy handlers are commented out.

This indicates API/contract drift and unclear migration state.

4. Modularity and proto usage signal

• Main UI logic is largely monolithic in src/js/custom.ts (~2.5k LOC).
• index.ts imports generated protobuf bundle (configuration_pb.js) up front.
• dist/js/index.bundle.js includes many generated proto message definitions, not only request/response minimum set.

Implication: upfront JS parse/execute and bundle weight are likely higher than needed.

Reverse-Engineered Product Requirements

These are the requirements we should preserve while refactoring.

RQ-UI-001 Captive Portal Bootstrap

The UI must reliably open and render from AP/captive-portal entry points with no manual URL knowledge.

Acceptance:

• Landing page reachable from captive portal probes.
• First meaningful controls visible without requiring cloud services.

RQ-UI-002 Network Onboarding and Recovery

Users must be able to scan APs, join/disconnect Wi-Fi, and understand current link mode (Wi-Fi vs Ethernet) with clear status.

Acceptance:

• Scan, connect, disconnect workflows remain available and understandable.
• Connection state transitions are visible and unambiguous.

RQ-UI-003 Runtime Observability

Users must see operational status and logs needed for diagnosis (network, playback, OTA progress, errors).

Acceptance:

• Status view remains available in normal and recovery mode.
• Error and warning paths are visible in UI without dev tools.

RQ-UI-004 Safe Configuration Editing

Users must be able to view/edit/apply configuration with guardrails (validation feedback, clear commit/apply behavior).

Acceptance:

• Config edit path supports both selective and global update actions.
• Validation errors are explicit before/after submit.

RQ-UI-005 OTA Operations

Users must be able to trigger firmware update by URL or upload, with progress and failure feedback.

Acceptance:

• OTA action always yields deterministic status progression or explicit terminal error.
• Recovery path remains accessible if normal OTA path fails.

RQ-UI-006 Advanced Control Access

Power-user controls (commands/NVS/diagnostics) must exist but should not degrade common-task UX.

Acceptance:

• Advanced functions remain accessible.
• Main tasks are not blocked by advanced UI complexity.

RQ-UI-007 Backward Compatibility Envelope

The UI must support currently deployed firmware API variants during migration (legacy and protobuf-era endpoints), with explicit deprecation strategy.

Acceptance:

• Contract compatibility matrix is documented and tested.
• Legacy paths have clear sunset criteria.

RQ-UI-008 Embedded Footprint Discipline

Web assets must stay within explicit firmware budget and be measurable in CI.

Acceptance:

• Shipping budget exists and is enforced.
• Size regressions fail checks unless explicitly approved.

Non-Functional Budgets (Proposed)

These are targets, not yet enforced:

• NB-001 Shipped web payload (*.gz + *.png in dist/) <= 180 KiB target, 220 KiB hard cap.
• NB-002 Main JS gzip <= 120 KiB target.
• NB-003 Vendor JS gzip <= 120 KiB target.
• NB-004 No runtime dependency on external CDNs for critical UI function.
• NB-005 One canonical API transport for new features (/data.bin protobuf), with compatibility shim for legacy endpoints during migration only.

UX + Footprint Improvement Directions

Prioritized by impact/risk.

P1 Contract Unification (High impact, medium risk)

• Define one frontend API client contract around protobuf request/response.
• Treat legacy .zzz paths as compatibility layer, not primary path.
• Add explicit compatibility table (firmware version -> supported endpoints).

P2 Modularization by Capability (High impact, medium risk)

• Split monolithic UI logic into capability modules:
  • onboarding
  • status/logs
  • config editor
  • OTA
  • advanced
• Lazy-load non-critical modules (advanced, release browser, heavy editors).

Expected result: lower startup JS cost and clearer ownership boundaries.

P3 Proto Surface Minimization (High impact, medium risk)

• Stop importing broad generated config surface on initial load.
• Create thin protobuf DTO layer for startup-critical flows.
• Load heavy schema modules only when entering related screens.

P4 UI Responsiveness and Clarity (Medium impact, low risk)

• Replace mixed polling patterns with a single scheduler and explicit backoff policy.
• Standardize in-progress/error/success state rendering across all actions.
• Reduce ambiguous icon-only cues with text fallback in constrained/offline contexts.

P5 Build Output Hygiene (Medium impact, low risk)

• Keep generating sourcemaps for dev/debug if needed, but separate from shipping artifact workflow.
• Enforce shipped-size budget on what SPIFFS actually receives, not raw dist/.

Living Maintenance Protocol

This file must be updated when any of the following changes:

• web routes/endpoints
• protobuf request/response schema used by UI
• shipped asset packaging rules
• significant UI feature flow

Required update steps:

1. Run build-scripts/ui_footprint_snapshot.sh.
2. Update Snapshot Findings and budget deltas in this file.
3. Update compatibility notes if API contract changed.
4. Add an entry to Decision Log.

Decision Log

Date	Decision	Why	Follow-up
2026-02-12	Treat this file as requirements-first context, not implementation notes	Reduce drift and speed up session handoffs	Add CI size gate and API contract checks

Open Questions

• Are legacy .zzz endpoints still required for deployed firmware versions, and for which versions exactly?
• Is the intended long-term model pure protobuf over /data.bin for all dynamic data?
• What startup latency target is acceptable on AP-mode captive portal connections?