feat(ux): UX-COPY-01 — listening guidance: question, volume, balance, camera/mic (#142)

[AnnieScigliano]

feat(ux): UX-COPY-01 — listening guidance: question, volume, balance, camera/mic (#142)

Closes #142. Builds on main@d547e96 (post PR #187/#192). Prepares the guidance surface that the human acceptance battery #204 will evaluate.

What ships

A brief, bilingual, accessible listening guide — SessionGuidance — that explains:

1. The experience invites you to look for a question, not an answer.
2. What the overall volume controls (everything you hear in the room).
3. What the Beacon / Session balance controls.
4. That moving the balance fully toward Beacon lets you hear only the Beacon and bring the session voice to zero.
5. That turning off the camera does not turn off the microphone — each control works independently.
6. That camera and microphone always remain under the person's control.

Where it lives (per state)

• WAITING (pre-room): the same component below the waiting event-card, deliberately outside the role="status" live region so disclosure toggling is never announced as a door-state change.
• In-room: directly above the Volume + Mix controls it explains, in normal flow — never overlaying the scene, tapestry, contributions, or controls. Closed by default so it doesn't compete with the scene or with SessionContributions.
• No new route, no navigation, no remount of Room/audio/video/Beacon (purely presentational, local aria-expanded state only).

#98 explicitly NOT simulated

The facilitation mix override is not implemented and this PR does not pretend otherwise: verified there is no override signal anywhere in src/. No override copy appears in the interface; that part of #142 remains blocked by #98. No fictional state, no anticipatory acoustic logic.

Copy (final, ES/EN — natural, not literal)

ES: "La experiencia te invita a buscar una pregunta, no una respuesta." · "El volumen general controla todo lo que escuchás en la sala." · "El balance elige cuánto escuchás del Beacon y cuánto de la sesión." · "Si llevás el balance completamente hacia Beacon, podés quedarte solo con su sonido y dejar la voz de la sesión en cero." · "Apagar la cámara no apaga tu micrófono. Cada control funciona por separado." · "Tu cámara y tu micrófono permanecen siempre bajo tu control." · Etiqueta: "Cómo funciona la escucha".

EN: "The experience invites you to look for a question, not an answer." · "Overall volume controls everything you hear in the room." · "The balance chooses how much of the Beacon and how much of the session you hear." · "Move the balance fully toward Beacon to hear only the Beacon and bring the session voice to zero." · "Turning off your camera does not turn off your microphone. Each control works independently." · "Your camera and microphone always remain under your control." · Label: "How listening works".

Wording adjustments from the issue's base are minimal and tone-only; meaning is unchanged.

Accessibility

• button + aria-expanded + aria-controls; panel toggles via the hidden attribute.
• Always-visible text label (never icon-only); chevron is aria-hidden.
• Keyboard (Enter/Space) and touch; focus stays on the toggle; 44px min touch target.
• prefers-reduced-motion: no JS animation at all; the only transition (chevron) is motion-safe with motion-reduce:transition-none.
• Existing visual tokens/primitives (--border-subtle, --surface-alt, --gold, --cream) — no technical-documentation aesthetic.

Tests

• Unit/component (SessionGuidance.test.tsx, 8 tests): full ES and EN copy; closed-by-default; aria wiring; keyboard + focus; readable label; reduced-motion classes; 44px target; long copy never truncated.
• Room integration: existing page + media-continuity jsdom suites stay green (34/34) — opening/closing doesn't remount Room, calls no volume/camera/mic handler.
• E2E (session-guidance.spec.ts, 2 tests): waiting surface readability + keyboard; in-room bounding-box placement above the volume controls without overlap; media-probe continuity across open/read/close (connections, tracks, media DOM, play calls, AudioContext unchanged; canonical Firefox autoplay-resume exception).
• Local gates: 925 unit tests pass (only the 4 pre-existing macOS-only livekit-target-monitor failures), tsc, eslint, next build all clean.

Visual baselines

The closed disclosure legitimately adds one quiet row above the volume controls in the attendee room, so attendee-audio-prompt baselines may drift. Per the issue's governance: evidence first (CI diff), review of the diff, then regenerate only the affected images on the canonical Linux runner using the proven TEMP-step method from #187, and remove every TEMP step before requesting review. No baseline is regenerated preemptively.

Governance and risks

• Label audio-touching included: the PR touches src/app/session/[id]/page.tsx, which is path-governance only — no acoustic change (no volume equations, gain, crossfader, AudioContext, codec/bitrate/sample-rate, buffers, LiveKit rooms/tokens, publish/subscribe, camera/mic lifecycle, setCameraEnabled/setMicrophoneEnabled, camera switching, Beacon connection, roles/capabilities, contributions, Prisma, EarlyBirds, or payments were touched).
• Risk: none to media continuity (presentational component; proven by probe e2e).
• Rollback: revert the two mounts and the component; no state, schema, or API changes to unwind.

Out of scope (untouched)

#134, #126, #131, #98 (documented above as the blocker for override copy), PR #203 EarlyBirds lane, and everything in the guardrail list.

Reviewer: @nicoechaniz — audio-adjacent surface per governance.

[AnnieScigliano]

Ciclo de baseline visual completado (para la review):

1. Run 1 (ac8bb36): único fallo = attendee-audio-prompt w390, 3542 px (ratio 0.02). Evidencia del reporte: el actual estable difiere del esperado solo en la banda y 744-840 del viewport 390×844 — la fila del toggle del guidance sobre los controles de volumen. w1440/w1024/w320 pasaron sin cambios.
2. Run 2 (4a5e9ad): pasos TEMP (regen + artifact) regeneraron los snapshots en el runner de referencia y el gate completo pasó verde contra ellos (e2e 14m5s pass).
3. Verificación del artifact: difiere del repo en exactamente UN archivo — attendee-audio-prompt-w390-linux.png (390×844). Ese PNG quedó commiteado en 2df84bf.
4. TEMP revertidos: e2e.yml tiene diff cero contra main. La PR contiene solo los 6 archivos de alcance.

Corrida final en curso sobre 2df84bf (workflow canónico, sin TEMP). Cuando salga verde, la PR queda lista para review — sin despliegue ni merge sin aprobación, como siempre.

[AnnieScigliano]

Hola @compaii — te pido la review de esta PR junto con @nicoechaniz. 🌿

Contexto breve para tu lectura: es la guía de escucha de UX-COPY-01 (#142) — un disclosure presentacional (SessionGuidance) con el copy bilingüe sobre la pregunta, el volumen general, el balance Beacon/Sesión y la independencia cámara/micrófono. Está montado en el estado WAITING (pre-sala) y junto a los controles de volumen dentro de la sala. No toca nada acústico: el label audio-touching es solo por path-governance de la página de sesión.

Puntos donde tu mirada suma especialmente:

1. El tono del copy (ES/EN en src/lib/i18n.ts, namespace session.guidance) — coherencia con la voz del Beacon y con lo que HUMAN-QA-02 — Regresión humana integral posterior al evento del 2 de agosto #204 va a evaluar en la batería humana.
2. La decisión RTC-02 — Mezcla compartida dirigida por facilitación con handoff suave #98: el override de mezcla por facilitación aún no existe como señal real, así que dejé ese copy FUERA de la interfaz y lo declaré bloqueado por RTC-02 — Mezcla compartida dirigida por facilitación con handoff suave #98. Si ves una forma mejor de encuadrarlo, bienvenida.
3. La integración discreta: la guía no compite con la escena ni con contribuciones; si sentís que en algún estado se hace demasiado presente (o demasiado invisible), es el momento de ajustarlo.

Gates: CI verde completo (test, lint-and-build, e2e con baseline w390 bendecido en el runner de referencia, frozen-audio-paths). Todo el contexto está en el body de la PR y en #142.

[nicoechaniz]

Aprobada. Revisé el diff exacto contra main, la ubicación WAITING/in-room, accesibilidad, i18n, continuidad de media y el baseline w390. No hay cambios en gain, crossfader, AudioContext, LiveKit ni lifecycle de cámara/micrófono; frozen-audio-paths está verde. Verificación adicional local: 8/8 tests focalizados, ESLint de archivos modificados y TypeScript verdes; CI completo también verde.

Observaciones no bloqueantes:

• El test unitario de teclado termina disparando click manualmente, pero el E2E sí prueba Enter real y foco, por lo que la conducta nativa queda cubierta.
• El cuerpo usa Closes #142 mientras documenta que el copy de override/“Volver” queda pendiente de #98. Al mergear, preservemos ese remanente en #98 o en un follow-up explícito para que el autocierre de #142 no lo pierda.