# ETAPA 4D — Frontend renderer: wizard pregunta-por-pantalla

## 1. Objetivo
Reemplazar el formulario de una sola página (v2) por un wizard que consume el motor
de flujo (4C) y muestra una pregunta por pantalla, con layout de altura estable.
El componente es un RENDERER: dibuja la pantalla que el motor resuelve; no contiene
lógica de flujo (ADR-005).

## 2. Contexto previo
- Motor de flujo listo y testeado: `lib/form-engine.ts` (resolveScreens, next, back,
  resolveVisibility) + `lib/form-engine.types.ts`. 16/16 tests.
- Widgets de input AISLADOS y reutilizables en `components/widgets/`:
  `radio-group`, `checkbox-group`, `text-short-field`, `text-area-field`
  (interfaz genérica value/onChange/error — se reutilizan tal cual).
- `question-renderer.tsx` despacha por `type` — reutilizable con 2 cambios (ver tareas).
- `survey-form.tsx` (una sola página, secciones por regex) se REESCRIBE entero.
- `app/page.tsx` query NO trae `hint`/`instance_generator`/`instance_of` (tarea 4.5 pospuesta de 4C).
- Gaps detectados: falta widget `yes_no`; hay hardcode A1/A2 en question-renderer a quitar.
- Comportamiento de referencia (NO de arquitectura): mockup `wizard_formulario_mapeo_v3.html`.

## 3. DECISIONES YA TOMADAS — no consultar de nuevo
- El componente consume el motor; NO reimplementa visibilidad/navegación/instancias.
- Una pregunta por pantalla. Secciones = pantallas propias (intro con número + descripción).
- Reutilizar los widgets de `components/widgets/` existentes.
- Identificación de pantalla por ID estable (el motor ya lo provee).
- **Layout de altura estable (UX 1+2+3), parte de esta etapa:**
  - (1) Viewport de altura estable: el enunciado se ancla en una posición consistente
    (tercio superior), NO centrado vertical. La caja no crece/encoge con el contenido.
  - (2) Header y footer FIJOS: progreso arriba, navegación (Anterior/Siguiente) abajo,
    ambos fuera del área que cambia de tamaño. No "saltan" entre pantallas.
  - (3) Área de respuesta con altura máxima y SCROLL INTERNO cuando hay muchas opciones,
    con affordance visual (degradado sutil en borde inferior) que indica "hay más abajo".
- Usar los tokens de marca existentes (el verde RE, variables CSS/Tailwind del proyecto).
  NO inventar colores nuevos.

## 4. Tareas

### 4.1 Ampliar la query y construir el FormSchema (app/page.tsx)
- Agregar `hint, instance_generator, instance_of` al `.select(...)`.
- Transformar las filas de `questions` (incluidas las `type='section'`) en el `FormSchema`
  que consume el motor.
- Pasar el schema al nuevo componente wizard.

### 4.2 Nuevo componente wizard (reemplaza survey-form.tsx)
- Mantiene el `WizardState` del motor (respuestas con instancias, pantalla actual).
- En cada render: pide al motor la pantalla actual y la dibuja.
- Navegación: botones Anterior/Siguiente llaman `next`/`back` del motor.
- Maneja los tipos de pantalla: sección-intro, pregunta, pregunta-de-instancia, fin.
- Para pantallas de instancia: muestra el badge de contexto ("Familiar X de N").

### 4.3 Layout de altura estable (UX 1+2+3)
Implementar el layout descrito en las decisiones. Estructura sugerida:
```
[header fijo: logo + progreso]          ← no scrollea
[viewport estable]
  [sección-header (si aplica)]
  [enunciado anclado: código + pregunta + hint]   ← posición consistente
  [área de respuesta: max-height + scroll interno + fade inferior]
[footer fijo: Anterior | indicador | Siguiente]    ← no scrollea
```
- El enunciado aparece en el mismo lugar pantalla tras pantalla.
- El área de respuesta scrollea internamente; header/footer nunca se mueven.

### 4.4 question-renderer: ajustes
- Quitar el hardcode A1/A2 (no aplica a v3; 2.1/2.2 son single_choice genéricos).
- Agregar el caso `yes_no` (lo usan 1.1/1.2). Crear `widgets/yes-no-field.tsx` si no existe,
  o resolver yes_no con el RadioGroup existente si es lo más simple — proponé cuál.
- Migrar las shapes de `lib/types.ts` (v2) a `lib/form-engine.types.ts` (v3) donde el
  renderer reciba datos del motor.

### 4.5 Progreso
- La barra/indicador de progreso se calcula desde el motor (pantalla actual / total visible),
  no desde "preguntas respondidas". Reutilizar `progress-bar.tsx` si encaja.

### 4.6 Consentimiento
- Reutilizar `consent-screen.tsx` como pantalla 1 (Sección 1), o integrarlo como la primera
  pantalla del wizard — proponé cuál es más limpio dado que ahora todo es wizard.

## 5. Entregables (DoD)
- [ ] Wizard funcional una-pregunta-por-pantalla consumiendo el motor.
- [ ] Layout de altura estable: header/footer fijos, enunciado anclado, scroll interno + fade.
- [ ] Query ampliada con las 3 columnas; FormSchema construido y pasado al componente.
- [ ] yes_no renderiza; hardcode A1/A2 removido.
- [ ] Progreso calculado desde el motor.
- [ ] Widgets de v2 reutilizados (no reescritos).
- [ ] **Validación visual del director** contra el mockup + criterios de UX estable.
- [ ] Build sin errores; sin lógica de flujo en el componente (solo consume el motor).

## 6. Qué reportar
```
Verificado:
- Wizard consume el motor (resolveScreens/next/back) ✓ — sin lógica de flujo propia
- Layout estable: header/footer fijos ✓, enunciado anclado ✓, scroll interno + fade ✓
- Query ampliada (hint/instance_generator/instance_of) ✓
- yes_no resuelto vía [RadioGroup | widget nuevo] ✓
- Hardcode A1/A2 removido ✓
- Widgets reutilizados: [lista]
- Build: [resultado]
- Capturas/descripción visual de 3 pantallas: pregunta corta, pregunta con muchas opciones
  (scroll interno), sección-intro

Asumido / Decisiones de diseño:
- [consentimiento como pantalla / yes_no / etc.]

Hallazgos no esperados:
- [lo que aparezca]
```
Reporte con datos concretos, no "se ve bien" (Patrón C.4). Describí el comportamiento del
layout estable: ¿el enunciado queda en el mismo lugar entre una pregunta de 3 opciones y
una de 15? ¿El footer se mantiene fijo?

## 7. Qué NO hacer
- ❌ No poner lógica de flujo/visibilidad/instancias en el componente (vive en el motor).
- ❌ No reescribir los widgets de input (reutilizarlos).
- ❌ No implementar el submit todavía (es 4G) ni la validación server-side.
- ❌ No implementar el autocomplete de barrios (es 4F) — barrio queda como text_short por ahora.
- ❌ No inventar colores fuera de los tokens de marca.
- ❌ No tocar v2.1.0-stable, el motor (4C), ni el seed.

## 8. Versionado
Commit sugerido:
```
feat(wizard): renderer pregunta-por-pantalla con layout estable [4D]

Reemplaza el formulario de una página por wizard que consume el motor (4C).
Layout de altura estable: header/footer fijos, enunciado anclado, scroll
interno con affordance. Reutiliza widgets de input. Agrega yes_no, quita
hardcode A1/A2. Query ampliada con columnas declarativas de v3.
```