Docs del mapping (Fase 1+2) + gitignore de runtime

- docs/mapping.md: guia del projection mapping (activar, superficies con malla
  para curvar, mascaras, editar arrastrando desde el panel, dónde se guarda,
  limitaciones). Enlazada desde docs/README.md y el README principal.
- .gitignore: ignora data/pm-fijado/ (runtime de projectM).

El mapper funcional (esquinas + malla + mascaras, para Butterchurn/Hydra/
Shaders/Mezclador) ya estaba en main (Fase 1 y 2). La via de captura para
projectM nativo se retira por ahora; se retoma mas adelante.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -18,6 +18,7 @@ data/videos/*
 # Config de runtime (por instalacion): no va al repo
 data/mapping.json
 data/pm-favoritos.json
+data/pm-fijado/
 
 # Temporales
 *.log

README.md

@@ -40,6 +40,8 @@ La carpeta [`docs/`](docs/) tiene la guía completa:
 - [Conectarse al panel](docs/conexion.md) — el código QR, `fosfeno.local` y
   el router.
 - [Uso del panel](docs/uso.md) — cómo se maneja y qué hace cada motor.
+- [Projection mapping](docs/mapping.md) — deformar las visuales para encajarlas
+  en superficies físicas (malla, máscaras) desde el panel.
 - [Solución de problemas](docs/problemas.md) — qué hacer cuando algo falla.
 
 El panel además lleva un botón de información en cada apartado: explica qué
@@ -63,6 +65,13 @@ Visuales de ejemplo — el motor Hydra con su editor de código en vivo:
   <img src="docs/assets/hydra.png" alt="Hydra" width="940">
 </div>
 
+## Projection mapping
+
+Las visuales web (Butterchurn, Hydra, Shaders y Mezclador) se pueden **deformar
+para encajarlas en superficies físicas** desde el panel: superficies con malla
+(curvas), varias a la vez y máscaras para tapar zonas, arrastrando con el ratón
+o el dedo. Se guarda solo en `data/mapping.json`. Guía: [docs/mapping.md](docs/mapping.md).
+
 ## Hardware necesario
 
 - Raspberry Pi 5 o Pi 4 + fuente oficial + microSD/SSD

docs/README.md

@@ -23,6 +23,10 @@ para consultarse a saltos después.
   Cómo se maneja desde el móvil, qué hace cada motor de visuales y cómo se
   configura cada opción.
 
+- [Projection mapping](mapping.md)
+  Cómo deformar las visuales para encajarlas en superficies físicas: malla,
+  máscaras y edición desde el panel arrastrando con el ratón o el dedo.
+
 - [Solución de problemas](problemas.md)
   Qué hacer cuando algo no arranca, no se ve o no suena. Incluye cómo leer
   los mensajes de error que aparecen en el propio panel.

docs/mapping.md

@@ -0,0 +1,77 @@
+# Projection mapping
+
+FOSFENO puede **deformar las visuales** para encajarlas en superficies físicas
+(una pared en ángulo, cajas, un objeto, varias zonas de una fachada) en vez de
+proyectar un simple rectángulo. Todo se hace **desde el panel**, arrastrando con
+el ratón o el dedo, y se **guarda solo**.
+
+Se aplica a los motores que corren en el navegador: **Butterchurn, Hydra,
+Shaders y Mezclador**. (projectM nativo aún no; ver [Limitaciones](#limitaciones).)
+
+## En 4 pasos
+
+1. Elige un motor que **no** sea projectM (Butterchurn, Hydra, Shaders o Mezcla).
+2. En el panel, sección **Mapping**, marca **Activar mapping**.
+3. Pulsa **+ Superficie**. Aparece un recuadro con las visuales en la
+   previsualización del panel (y en el proyector).
+4. En la **previsualización** del panel, **arrastra los puntos** para encajar la
+   forma sobre tu superficie real. Se ve en el proyector al instante.
+
+## La sección Mapping del panel
+
+- **Activar mapping** — enciende/apaga la deformación.
+- **Modo edición** — muestra u oculta los tiradores en la **ventana de las
+  visuales** (por si prefieres ajustar ahí con un ratón). Para el uso normal no
+  hace falta: con la previsualización del panel basta.
+- **+ Superficie** — añade una superficie nueva (un cuadrilátero).
+- **+ Máscara** — añade una **máscara**: un recuadro **negro** que tapa una zona
+  (útil para recortar el derrame de luz fuera de la superficie física).
+- **Reset** — borra todas las superficies y máscaras.
+- **Previsualización** — el recuadro donde arrastras los puntos (ratón o dedo).
+  Muestra una rejilla dentro de cada superficie para que veas cómo se deforma.
+- **Lista** — cada superficie y máscara con su tamaño de malla y un botón **✕**
+  para borrarla.
+
+## Superficies con malla (curvar)
+
+Una superficie nueva es un cuadrilátero de 4 esquinas (corrección de
+perspectiva / *keystone*). Para superficies **curvas**:
+
+1. Selecciona la superficie (toca dentro de ella en la previsualización).
+2. Aparece **− malla / + malla**: cada **+ malla** la subdivide (2×2, 3×3…
+   hasta 6×6).
+3. Ahora puedes arrastrar **cualquier punto** de la rejilla (no solo las
+   esquinas) para curvarla y adaptarla a superficies no planas.
+
+Puedes crear **varias superficies** y mapear la misma imagen en distintas zonas.
+
+## Máscaras
+
+Una máscara es un cuadrilátero **negro** que se pinta encima de todo. Sirve para
+**tapar** lo que no quieres que se vea (bordes, derrames de luz, huecos entre
+superficies). Añádelas con **+ Máscara** y arrastra sus esquinas igual que una
+superficie.
+
+## Dónde se guarda
+
+La configuración se guarda sola en `data/mapping.json` y se mantiene al
+reiniciar. Es **por instalación** (no se sube al repositorio). Para empezar de
+cero, usa **Reset** o borra ese archivo.
+
+## Editar en la ventana de las visuales (opcional)
+
+Con **Modo edición** activo, los tiradores también aparecen sobre las propias
+visuales. Ahí, además, funcionan atajos de teclado:
+
+- **doble clic** en un hueco: crea una superficie nueva.
+- **+ / −**: subdivide/reduce la malla de la superficie seleccionada.
+- **Supr**: borra la superficie o máscara seleccionada.
+
+## Limitaciones
+
+- **projectM nativo no se mapea todavía.** projectM corre en su propia ventana
+  fuera del navegador, así que el mapper (que trabaja sobre las visuales web) no
+  lo alcanza. Para mapear el mismo tipo de gráficos, usa **Butterchurn**
+  (MilkDrop en el navegador). El soporte de projectM está en estudio.
+- El mapping es una capa de deformación sobre la imagen final; no cambia el
+  contenido de cada motor.