UX-COPY-01 — Pregunta, retorno y guía de mezcla

[AnnieScigliano]

Parent

#71. Este child extrae únicamente el onboarding/copy post-sesión para no solaparse con cámara, preflight ni lifecycle ya reclamados por Nico.

Resultado

Agregar una guía breve y persistente que explique la intención de la experiencia y los controles de volumen sin modificar comportamiento acústico.

Copy/experiencia

• “La experiencia invita a buscar una pregunta, no una respuesta.”
• Explicar volumen general y balance Beacon/Sesión.
• Ejemplo: cuando el control personal está habilitado, se puede llevar la voz a cero y escuchar sólo Beacon.
• Explicar que facilitación puede dirigir temporalmente el balance y qué ocurrirá al pulsar “Volver” (RTC-02 — Mezcla compartida dirigida por facilitación con handoff suave #98).
• Con micrófono activo, aclarar que apagar cámara mantiene el audio.
• Ayuda ES/EN accesible antes de entrar y desde la sala, sin convertirla en panel técnico.

Fuera de alcance

• Gain, crossfader, AudioContext, LiveKit, mic/camera lifecycle.
• Selector/mic checker RTC-04 — Preflight de micrófono y selección de dispositivos #126.
• Implementación del override RTC-02 — Mezcla compartida dirigida por facilitación con handoff suave #98.
• Cambios de roles o capabilities ya cubiertos por PR feat(roles): explain event-scoped capabilities #139.

Reserva de archivos y secuencia

• Implementar después del merge/rebase del slice de chat UI.
• Crear preferentemente un componente aislado SessionGuidance con tests.
• Compartirá src/lib/i18n.ts; por eso no debe correr en paralelo con chat UI.
• Integración mínima en la página de sesión; no refactorizar media controls.

Aceptación

• Copy revisado ES/EN y comprensible sin explicación del equipo.
• 320/390/1024/1440, teclado y lector de pantalla pasan.
• Tests prueban cámara-off con copy de audio continuo sin cambiar tracks.
• Diff no toca ecuaciones, dispositivos, rooms ni lifecycle de audio.

[AnnieScigliano]

FASE 0 — diagnóstico y coordinación (Oliva)

Diagnóstico

Superficies reales auditadas sobre main@d547e96:

1. Pre-room / waiting: SessionEntryGate en src/app/session/[id]/page.tsx renderiza el estado WAITING como una event-card centrada (role="status", ticket confirmado, fecha). Hay espacio natural debajo de la card para una guía discreta sin tocar el live region.
2. Dentro de la sala: los controles de volumen general (room-master-volume) y balance Beacon/Sesión (room-audio-balance) viven en el bloque "Volume + Mix controls" (columna de escena, sobre el panel SessionContributions). Los toggles de micrófono y cámara viven en la barra inferior. La explicación de volumen/balance/cámara va junto al bloque de controles de audio, en flujo normal (nunca overlay).
3. RTC-02 — Mezcla compartida dirigida por facilitación con handoff suave #98 (override de mezcla por facilitación): verificado — no existe ninguna señal de override en src/ (grep de mixOverride/balanceOverride/facilitatorMix vacío). El copy de override queda FUERA de la interfaz; esa parte del issue queda bloqueada por RTC-02 — Mezcla compartida dirigida por facilitación con handoff suave #98. No se crea estado ficticio ni lógica acústica anticipada.
4. Solapamientos: PR draft: build isolated Founding Listener candidate #203 (early-birds) toca Prisma/contratos propios — fuera de mi camino. PR test(rtc): capturar diagnóstico de audio sanitizado #153 toca e2e/helpers/media-probe.ts y e2e/tests/media-continuity.spec.ts — mi spec e2e será un archivo NUEVO que solo importa el helper, sin modificarlo. PR fix(playlist): reconcile fallback lifecycle exactly once #150 toca solo services/playlist-bot/. Ninguna rama activa reserva src/lib/i18n.ts, src/app/session/[id]/page.tsx ni el componente nuevo.

Copy propuesto (base canónica, tono producto)

ES:

• Intención: "La experiencia te invita a buscar una pregunta, no una respuesta."
• Volumen: "El volumen general controla todo lo que escuchás en la sala."
• Balance: "El balance elige cuánto escuchás del Beacon y cuánto de la sesión."
• Balance a fondo: "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."
• Cámara/mic: "Apagar la cámara no apaga tu micrófono. Cada control funciona por separado."
• Control: "Tu cámara y tu micrófono permanecen siempre bajo tu control."
• Etiqueta visible del disclosure: "Cómo funciona la escucha"

EN:

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

Ubicación exacta por estado

• WAITING (pre-room): SessionGuidance como sibling debajo de la event-card de espera (NO dentro del role="status" — el disclosure no debe anunciarse como cambio de estado). Mismo componente, contenido completo (intención + controles).
• In-room: SessionGuidance inmediatamente sobre el bloque "Volume + Mix controls", en flujo normal, cerrado por defecto. Al abrirse despliega la guía completa junto a los controles que explica. No compite con SessionContributions (columna distinta en desktop, encima en flujo mobile), nunca overlay.
• Sin nueva ruta, sin navegación, sin remontar Room/audio/video/Beacon (componente presentacional puro, estado local de aria-expanded).

Archivos reservados

• src/lib/i18n.ts (namespace session.guidance, ES/EN)
• src/app/session/[id]/page.tsx (2 montajes puntuales)
• NUEVO src/components/session/SessionGuidance.tsx
• NUEVO src/components/session/__tests__/SessionGuidance.test.tsx
• NUEVO e2e/tests/session-guidance.spec.ts (importa media-probe.ts, no lo modifica)
• Tests de página existentes: solo se ajustan si el montaje nuevo los rompe; no se silencia nada.

Riesgos de continuidad

• El componente es presentacional: no fetch, no effects sobre Room/AudioContext, no handlers de volumen/cámara/micrófono. Abrir/cerrar no puede crear sockets, tracks, media elements ni AudioContext.
• Baselines visuales: el disclosure cerrado aparecerá en attendee-audio-prompt (única superficie visual que captura la sala). Si el diff es ese y solo ese, se regeneran ÚNICAMENTE las imágenes afectadas en el runner canónico Linux con el método TEMP ya probado en feat(chat): CHAT-01 UI — session contributions panel and staff drawer (#141, PR B) #187 (regen → descargar artifact → commitear PNG → revertir pasos TEMP antes de review). El estado WAITING no tiene baseline visual.
• No se tocan ecuaciones de volumen, crossfader, gain, AudioContext, LiveKit, lifecycle de cámara/mic ni contributions.

Plan de pruebas

1. Unit/component (SessionGuidance.test.tsx): render ES/EN completo; disclosure cerrado por defecto; aria-expanded/aria-controls; apertura por click y por teclado; foco conservado; todas las líneas de copy presentes (volumen, balance, balance-a-fondo, cámara/mic, control); reduced-motion (sin animación JS, transiciones solo bajo motion-safe); texto largo sin truncación.
2. Integración de sala (tests de página existentes + focalizados): abrir/cerrar la guía no remonta Room; no se invocan handlers de volumen/cámara/mic; los tests de media-continuity jsdom existentes siguen verdes.
3. Responsive: 320/390/1024/1440 sin overlay ni scroll horizontal; touch target ≥44px.
4. E2E (session-guidance.spec.ts, spec nuevo): attendee con ticket en sala LIVE, media probe instalado; abrir/cerrar la guía y verificar que conexiones, tracks, media DOM, play calls y AudioContext no cambian.

Gobernanza

• Label audio-touching por tocar src/app/session/[id]/page.tsx — se deja explícito en la PR que es path-governance, no un cambio acústico.
• Review solicitada a Nico (superficie adyacente al audio).
• UX-COPY-01 — Pregunta, retorno y guía de mezcla #142 se mueve a In Progress ahora (board: pendiente por bloqueo CLI conocido; se actualiza por web si es posible).