Capas independientes, projectM en el mapping y catalogo de la galeria

Mapping
- Los clips salian del reves: mapper.js activaba UNPACK_FLIP_Y_WEBGL, pero el
  modelo va con origen arriba-izquierda y texImage2D ya sube la primera fila
  en t=0, asi que el flip la mandaba al final. Comprobado renderizando el
  mapper real en Chromium headless con una fuente mitad roja / mitad azul.
- projectM se puede usar YA en una capa: los .milk de data/presets-projectm se
  traducen a Butterchurn en el navegador al elegirlos (milkdrop-preset-
  converter). La capa MilkDrop gana 'biblioteca' (butter | projectm) sin
  cambiar su firma, para no recrear el contexto WebGL al cambiar de una a otra.
  Medido: 100/100 presets de una muestra convierten, 84/84 de los que llevan
  shaders warp/comp; ~7 ms por preset.
- Cada capa tiene su pestana arriba y su propia vista, y '+ CAPA' crea una y
  entra en ella: con varias capas, ir y volver a MAPPING no era viable.
- Dos capas MilkDrop sin preset ya no salen identicas (cogian el indice 0):
  cada instancia elige uno al azar y lo escribe en el estado.
- Una capa nueva ya no nace en la fuente "motor", que es el lienzo del motor
  activo y hacia que dos capas ensenaran lo mismo.

Galeria de visuales
- scripts/catalogar-visuales.py: ficha de cada clip (pelicula, personajes,
  duracion) y, sobre todo, si es una silueta de verdad y cuanta figura tiene.
  Distingue silueta de corte crudo por el negro puro del fondo: 0,63-0,90
  frente a 0,04-0,06, sin zona gris.
- El panel lista los clips agrupados por pelicula, con nombre legible y aviso
  de los que casi no tienen figura, en vez del nombre del archivo.
- Soporte de siluetas con canal alfa (.webm VP9): transparencia de verdad, sin
  recorte por luminancia. El shader del mapper ya la respeta.

Documentacion
- docs/visuales.md nuevo; pendiente.md al dia con lo hecho y lo que queda.

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

docs/mapping.md

@@ -1,50 +1,164 @@
 # Projection mapping
 
+> **Pestañas de capa.** Cada capa tiene su propia pestaña arriba, junto a
+> MOTORES y MAPPING, y el botón **+ CAPA** crea una y te deja ya dentro de
+> ella. Esa vista enseña solo la previsualización y los ajustes de *esa* capa:
+> es la forma de trabajar cuando hay varias, sin ir y volver a la lista.
+>
+> **Visuales de projectM en una capa.** La fuente "Visuales MilkDrop" tiene
+> ahora un selector de **biblioteca**: los ~100 presets de Butterchurn, o los
+> **9795 `.milk` de projectM** (categoría / visual / variante, o "uno al
+> azar"). Los `.milk` se traducen a Butterchurn en el propio navegador al
+> elegirlos. Ver `pendiente.md` punto 2 para el detalle y sus límites.
+
+
 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**.
 
+Y no es una sola imagen troceada: **cada zona es una capa con su propio
+visual**. MilkDrop a la derecha, otro preset distinto a la izquierda y un vídeo
+en el centro, cada uno en su sitio y a la vez. Eso está en
+[Capas: un visual distinto en cada zona](#capas-un-visual-distinto-en-cada-zona).
+
 Se aplica a los motores que corren en el navegador: **Butterchurn, Hydra,
 Shaders y Mezclador**. (projectM nativo aún no; ver [Limitaciones](#limitaciones).)
 
+## Dónde está: la pestaña MAPPING
+
+El mapping tiene **su propia pestaña**, a la derecha del título **FOSFENO**, al
+lado de **MOTORES**. Están separados a propósito: MOTORES es el directo
+(encendido, audio, motores) y MAPPING es el montaje. Así ni se estorban ni se
+confunden.
+
+En la pestaña MAPPING la tarjeta ocupa el ancho entero, para que la
+previsualización sea grande y se puedan arrastrar los puntos con comodidad —
+también con el dedo, desde el móvil.
+
+Mientras el mapping esté activado, la pestaña lleva un **punto verde**: desde
+MOTORES se ve de un vistazo que la salida se está deformando.
+
+<div align="center">
+  <img src="assets/mapping.png" alt="La pestaña MAPPING del panel" width="720">
+</div>
+
 ## 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.
+1. Entra en la pestaña **MAPPING** y marca **Activar mapping**.
+2. Pulsa **+ Capa**. Aparece un recuadro en la previsualización del panel (y en
+   el proyector).
+3. **Arrastra los puntos** para encajar la forma sobre tu superficie real. Se ve
+   en el proyector al instante.
+4. Con la capa seleccionada, en **Propiedades** eliges **qué se proyecta ahí**.
 
-## La sección Mapping del panel
+## La pestaña MAPPING por dentro
+
+Tiene tres bloques, de arriba abajo: la **salida**, las **capas** y las
+**propiedades** de la capa que tengas seleccionada.
+
+**Salida**
 
 - **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).
+- **Editar en el escenario** — saca los tiradores y la malla de colores
+  también sobre las propias visuales (por si prefieres ajustar ahí con un
+  ratón). Para el uso normal **no hace falta**: con la previsualización del
+  panel basta, y así el proyector sale limpio. Es un modo de montaje, no un
+  ajuste: **arranca siempre apagado**, aunque lo dejaras puesto.
+- **Previsualización** — el recuadro donde arrastras los puntos (ratón o dedo).
+  Cada capa lleva escrito su nombre y qué visual tiene dentro.
+
+**Capas**
+
+- **+ Capa** — añade una zona nueva. Sale escalonada, para que no tape a la
+  anterior, y queda seleccionada.
 - **+ 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.
+
+> **Capa ≠ máscara.** Una **capa** proyecta algo (eliges qué en Propiedades);
+> una **máscara** solo tapa y no lleva visual. Es la confusión más fácil: si
+> creaste una máscara buscando dónde poner el visual, selecciónala y pulsa
+> **Convertirla en capa** — se sustituye por una capa en el mismo sitio y con
+> la misma forma.
+- **Reset** — borra todas las capas y máscaras.
+- La **lista** se lee como en cualquier mesa de VJ: **la de arriba es la que
+  queda delante** en el proyector. Cada fila tiene:
+
+  | Botón | Qué hace |
+  |-------|----------|
+  | ◉ / ○ | Enciende o apaga la capa sin borrarla |
+  | ▲ ▼ | La sube o la baja en el orden de pintado |
+  | ✕ | La borra |
+
+**Propiedades** — nombre, qué se proyecta, opacidad, mezcla y malla. Se explican
+abajo.
+
+## Capas: un visual distinto en cada zona
+
+Esto es lo que separa el mapping de FOSFENO de un simple recorte: **cada capa
+elige su propia fuente**, así que la proyección puede llevar cosas distintas a
+la vez.
+
+| Fuente | Qué es | Coste |
+|--------|--------|-------|
+| **El motor de MOTORES** | Lo que esté puesto en la otra pestaña. En varias capas a la vez, todas enseñan lo mismo | ninguno |
+| **Visuales MilkDrop propias** | Un Butterchurn **solo para esa capa**, con su preset. Es lo que permite dos looks de MilkDrop distintos a la vez | alto |
+| **Shader GLSL** | Uno de los shaders de la librería, reaccionando al audio | medio |
+| **Clip o imagen** | Un archivo de `data/videos`. En bucle y sin sonido | bajo |
+| **Cámara** | La webcam | bajo |
+| **Negro** | Nada: tapa la zona sin usar máscara | ninguno |
+
+Las capas de MilkDrop y de shader **son motores de verdad funcionando**: cada
+una se renderiza aparte y el mapper la estira al deformarla. Los clips y la
+cámara, en cambio, **se comparten**: si dos capas usan el mismo clip, se
+reproduce una sola vez.
+
+### La receta del ejemplo
+
+Tres zonas, tres visuales distintos:
+
+1. **+ Capa** → nómbrala «Pared izquierda» → fuente **Visuales MilkDrop
+   propias** → elige un preset.
+2. **+ Capa** → «Centro» → fuente **Clip o imagen** → elige tu vídeo.
+3. **+ Capa** → «Pared derecha» → fuente **Visuales MilkDrop propias** → *otro*
+   preset, o marca **Cambiar de preset solo** para que vaya rotando.
+4. Arrastra cada una a su sitio en la previsualización.
+
+<div align="center">
+  <img src="assets/capas.png" alt="Tres capas con visuales distintos" width="820">
+</div>
+
+### Transiciones
+
+Las capas de **Visuales MilkDrop** llevan su propio deslizador de
+**transición (0–8 s)**: es lo que tarda un preset en disolverse en el
+siguiente. A 0 el cambio es un corte seco; subiéndolo, uno se funde con el
+otro sin que se note. Combinado con **Cambiar de preset solo**, la capa va
+alternando visuales sola y en suave.
+
+El fundido lo hace el propio Butterchurn mientras carga, así que no cuesta
+rendimiento aparte.
+
+### Opacidad y mezcla
+
+Cuando dos capas se solapan, mandan estos dos ajustes:
+
+- **Opacidad** — cuánto deja ver lo que hay debajo.
+- **Mezcla** — **Normal** tapa lo de debajo; **Sumar** apila luz, así que las
+  zonas oscuras de la capa dejan pasar la de abajo. Sumar es lo que da los
+  solapes bonitos entre visuales; normal es lo que quieres cuando cada capa va
+  en su pared y no se tocan.
 
 ## Superficies con malla (curvar)
 
-Una superficie nueva es un cuadrilátero de 4 esquinas (corrección de
-perspectiva / *keystone*). Para superficies **curvas**:
+Una capa 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).
+1. Selecciona la capa (toca dentro de ella en la previsualización).
+2. En Propiedades, **Malla**: cada **+** 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
@@ -60,18 +174,39 @@ 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:
+Con **Editar en el escenario** activo, los tiradores también aparecen sobre las
+propias visuales, con el nombre y la fuente de cada capa escritos encima. 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.
+- **doble clic** en un hueco: crea una capa nueva.
+- **+ / −**: subdivide/reduce la malla de la capa seleccionada.
+- **Supr**: borra la capa o máscara seleccionada.
+
+## Cuánto aguanta
+
+Cada capa de **MilkDrop** o de **shader** es un motor de verdad renderizando
+aparte, así que tienen un coste real:
+
+| Equipo | Capas de MilkDrop / shader | Capas de clip o cámara |
+|--------|---------------------------|------------------------|
+| Portátil con GPU | 3–4 sin despeinarse | muchas |
+| Raspberry Pi 5 | 2, con margen justo | varias |
+| Raspberry Pi 4 | 1 | unas pocas |
+
+Cada capa se renderiza a **640×360** y el mapper la estira al deformarla: en una
+zona de la proyección no se nota, y es lo que hace viable tener varias a la vez.
+Si va lenta, lo primero que hay que quitar son las capas de MilkDrop de más;
+clips y cámara cuestan mucho menos, y además **se comparten** entre capas.
 
 ## 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.
+- **projectM nativo no puede ir en una capa.** projectM corre en su propia
+  ventana fuera del navegador, así que el mapper no lo alcanza. Para el mismo
+  tipo de visual, usa la fuente **Visuales MilkDrop propias**: son los mismos
+  presets de MilkDrop, dentro del navegador, y además puedes tener varios
+  distintos a la vez. Meter la ventana nativa como capa (capturándola) está en
+  estudio.
+- El mapping deforma y compone; no cambia el contenido de cada motor.
+
+Cómo está montado por dentro (el compositor WebGL, las capas, el formato de las
+superficies): [Arquitectura](arquitectura.md#mapping-y-capas).