morfeo 0.3.4 → 0.5.0

package/lib/render.mjs

@@ -213,7 +213,9 @@ export async function preparar({proyecto = process.cwd(), ids, log = console.log
  * @param {{proyecto?: string, ids?: string[], todos?: boolean, log?: (m: string) => void, alProgreso?: (id: string, p: number) => void}} o
  * @returns {Promise<{id: string, mp4: string, jpg: string | null, segundos: number}[]>}
  */
-export async function render({proyecto = process.cwd(), ids, todos = false, soloFallidos = false, log = console.log, alProgreso} = {}) {
+export async function render({proyecto = process.cwd(), ids, todos = false, soloFallidos = false, previa = null, log = console.log, alProgreso} = {}) {
+	// previa: solo el gancho (las primeras escenas, hasta `previa` segundos o ~8 s) en "<título> (previa).mp4", sin miniatura
+	if (previa && !ids?.length) throw new ErrorMorfeo('Dime qué video:  npx morfeo previa mi-video');
 	cargarEnv(proyecto);
 	const p = await cargarProyecto(proyecto);
 	const loteArchivo = path.join(p.trabajo, 'ultimo-lote.json');
@@ -266,7 +268,10 @@ export async function render({proyecto = process.cwd(), ids, todos = false, solo
 			const t = Date.now();
 			try {
 			const inputProps = {videos: {[id]: datos[id]}, marca, ...extras};
-			const mp4 = salidaDe(p, id);
+			const mp4 = previa ? salidaDe(p, id).replace(/\.mp4$/, ' (previa).mp4') : salidaDe(p, id);
+			// tramo de la previa: hasta el final de la 2.ª escena (gancho + la que sigue), entre 4 y 8 s, o lo que se pida
+			const d0 = datos[id];
+			const finPrevia = typeof previa === 'number' ? previa : Math.min(8, Math.max(4, (d0.escenas[1] ?? d0.escenas[0]).t0 + (d0.escenas[1] ?? d0.escenas[0]).dur));
 			let gl = p.render.gl;
 			let concurrencia = concurrenciaBase;
 			let composition;
@@ -289,6 +294,7 @@ export async function render({proyecto = process.cwd(), ids, todos = false, solo
 						jpegQuality: 92,
 						concurrency: concurrencia,
 						outputLocation: mp4,
+						...(previa ? {frameRange: [0, Math.min(composition.durationInFrames - 1, Math.round(finPrevia * composition.fps))]} : {}),
 						onProgress: ({progress}) => {
 							alProgreso?.(id, progress);
 							// con terminal: cada 10 % en la misma línea; sin terminal (logs, CI): cada 25 %
@@ -314,7 +320,7 @@ export async function render({proyecto = process.cwd(), ids, todos = false, solo
 				}
 			}
 			let jpg = null;
-			if (p.render.miniatura) {
+			if (p.render.miniatura && !previa) {
 				// miniatura: cuando la primera escena ya está completa (o en `miniaturaEn`), sin subtítulos
 				jpg = salidaDe(p, id, 'jpg');
 				const d = datos[id];
@@ -324,6 +330,17 @@ export async function render({proyecto = process.cwd(), ids, todos = false, solo
 				const props = {...inputProps, miniatura: true};
 				await renderStill({serveUrl, composition: {...composition, props: {...composition.props, miniatura: true}}, inputProps: props, browserExecutable, chromiumOptions: {gl}, frame, imageFormat: 'jpeg', jpegQuality: 92, output: jpg});
 			}
+			// portada: el mismo cuadro con el título grande y la marca (`portada: 'texto'` o el título sin emojis; false = sin portada)
+			const vid = p.videos[id];
+			if (!previa && p.render.portada !== false && vid.portada !== false && jpg) {
+				const textoPortada = typeof vid.portada === 'string' ? vid.portada : String(vid.title ?? id).replace(/[\p{Extended_Pictographic}\uFE0F\u200D]/gu, '').replace(/\s*[|·].*$/, '').trim();
+				const d = datos[id];
+				const e0 = d.escenas[0];
+				const seg = vid.miniaturaEn ?? Math.min(e0.dur - 0.15, Math.max(1.4, e0.habla[1] * 0.85));
+				const frame = Math.max(0, Math.min(composition.durationInFrames - 1, Math.round(seg * composition.fps)));
+				const props = {...inputProps, portada: textoPortada};
+				await renderStill({serveUrl, composition: {...composition, props: {...composition.props, portada: textoPortada}}, inputProps: props, browserExecutable, chromiumOptions: {gl}, frame, imageFormat: 'jpeg', jpegQuality: 92, output: salidaDe(p, id, 'jpg').replace(/\.jpg$/, ' (portada).jpg')});
+			}
 			const segundos = Math.round((Date.now() - t) / 1000);
 			if (process.stdout.isTTY) process.stdout.write('\r');
 			log(`[${i + 1}/${listos.length}] ${id}: listo en ${segundos} s  →  ${path.relative(p.proyecto, mp4)}      `);
@@ -337,6 +354,7 @@ export async function render({proyecto = process.cwd(), ids, todos = false, solo
 	} finally {
 		soltar();
 	}
+	if (previa) return hechos;
 	return terminarLote(p, loteArchivo, hechos, fallidos, log);
 }
 
@@ -438,7 +456,18 @@ function escribirResumen(p) {
 		const v = p.videos[f.id];
 		const tags = (v.tags ?? []).map((x) => `#${String(x).replace(/^#/, '').replace(/\s+/g, '')}`).join(' ');
 		const creditos = f.creditos?.length ? ['', 'Créditos:', ...f.creditos.map((c) => `- ${c}`)] : [];
-		const lineas = [v.title ?? f.id, '', ...(v.descripcion ? [v.descripcion, ''] : []), ...(tags ? [tags] : []), ...creditos];
+		const fuentes = (v.fuentes ?? []).map((x) => (typeof x === 'string' ? `- ${x}` : `- ${x.texto ?? ''}${x.url ? ` · ${x.url}` : ''}`));
+		const ganchos = (v.hooks ?? []).map((h, i) => `${i + 1}. ${h}`);
+		const lineas = [
+			v.title ?? f.id,
+			'',
+			...(v.descripcion ? [v.descripcion, ''] : []),
+			...(tags ? [tags] : []),
+			...(fuentes.length ? ['', 'Fuentes:', ...fuentes] : []),
+			...creditos,
+			// lo de abajo no va en el post: ganchos para probar otra versión del inicio
+			...(ganchos.length ? ['', '———', 'Ganchos de reserva (para otra versión):', ...ganchos] : []),
+		];
 		fs.writeFileSync(salidaDe(p, f.id, 'txt'), lineas.join('\n').trim() + '\n');
 	}
 	if (conCreditos.length)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "morfeo",
-	"version": "0.3.4",
+	"version": "0.5.0",
 	"description": "Genera videos verticales animados (Remotion + Three.js) con voz, música y subtítulos, desde un guion en código o escrito por IA.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",

package/plantilla/AGENTS.md

@@ -0,0 +1,54 @@
+# Instrucciones para la IA (Claude Code, Codex u otra)
+
+Este es un proyecto de **Morfeo**: videos verticales animados (Shorts, TikTok, Reels) desde código. Tú eres quien
+los hace: la persona te pide un tema y tú le devuelves el video terminado. Habla con ella en su idioma, sin jerga
+técnica. Nunca publiques nada por ella: le entregas los archivos y ella decide dónde subirlos.
+
+Comandos de referencia: `npx morfeo ayuda`. Tipos de todo lo que existe: `node_modules/morfeo/index.d.ts`.
+
+## Cuando diga «Configúrame» (o es la primera vez)
+
+1. Revisa que haya Node 20+ (`node -v`). Si falta, dile cómo instalarlo y espera.
+2. `npm install` en esta carpeta.
+3. `npx morfeo instalar --si` (Python, voces gratis, navegador; tarda unos minutos la primera vez). Si algo falla,
+   lee el mensaje, arréglalo y vuelve a correrlo. `npx morfeo doctor` dice qué falta.
+4. `npx morfeo estilo`: abre una página para que elija nombre, siglas, colores, letra, voz, ritmo y frase de cierre.
+   Espera a que diga que guardó (crea `estilo.json`).
+5. Si quiere su voz de ElevenLabs: que pegue su clave en `.env` como `ELEVENLABS_API_KEY=…` (cópialo de `.env.example`;
+   nunca escribas tú la clave ni la pongas en el chat). Para investigar con Claude desde la terminal, `ANTHROPIC_API_KEY`.
+6. Haz un video de prueba (`npx morfeo render ejemplo-2d`) y dile dónde quedó.
+
+## Cuando diga «Hazme un video sobre…»
+
+1. **Investiga.** Busca los datos en la web y quédate solo con lo que puedas respaldar con una fuente (medio,
+   institución, URL). Si no puedes buscar, usa `npx morfeo guion "tema" --investigar` (necesita `ANTHROPIC_API_KEY`).
+   Si dudas de una cifra, dila en general o quítala.
+2. **Elige la fórmula** que mejor le queda al tema: `npx morfeo formulas` (construiste, mito, misterio, serie,
+   biografía, experimento, demuéstralo, roast…). Si hay una base para esa fórmula, empieza de ahí:
+   `npx morfeo nuevo-video <id> --formula <fórmula>` (bases: serie, mito, escalada, biografia, construiste; o
+   `--look 2d` / `--look 3d`). Si no, `npx morfeo guion "tema" --formula <fórmula>` o escribe el guion a mano en
+   `guiones/<id>.mjs` (mira los ejemplos de `guiones/`).
+3. **Escribe el guion** siguiendo la fórmula y estas reglas:
+   - Gancho en los primeros 2 s, en segunda persona o con una cifra imposible. Nada de "hoy te voy a contar".
+   - Una idea por escena (2–5 s de voz). Pregunta antes de revelar. Sube la apuesta hacia el final.
+   - `say` es lo que dice la voz (cifras con letra); `show` el subtítulo con cifras.
+   - Rótulos cortos en 2–4 escenas (`rotulo`, con `rotuloEstilo` sello/paso/pixel si va), `claves` en cada escena.
+   - Cierre que pide algo: `{type: 'cta', pide: 'comenta', palabra: 'X'}` o `pide: 'comparte', a: 'tu amigo que…'`.
+   - `title`, `descripcion`, `tags`, `hooks` (3 ganchos de reserva) y `fuentes` (cada dato con su fuente).
+4. **Enséñale el guion** (texto de cada escena, en limpio) y espera su visto bueno o sus cambios.
+5. **Enséñale el gancho:** `npx morfeo previa <id>` renderiza solo los primeros segundos. Si no le convence, cámbialo
+   (tiene 3 ganchos de reserva en `hooks`).
+6. **Renderiza:** `npx morfeo render <id>`.
+7. **Revisa antes de entregar:**
+   - `npx morfeo revisar <id>`: estructura, que la voz haya dicho el guion y que nada quede bajo los botones de la app.
+   - `npx morfeo hoja <id> --zona`: mira la hoja de contacto (es una imagen); lo pintado en rojo es lo que tapan las apps.
+   - Si algo se ve mal (texto encimado, objeto cortado, cuadro vacío), arréglalo y vuelve a renderizar.
+8. **Entrega:** en `salida/` quedan `<título>.mp4`, `<título>.jpg` (miniatura), `<título> (portada).jpg` y
+   `<título>.txt` (texto del post, etiquetas, fuentes y ganchos de reserva). Dile eso y nada más.
+
+## Reglas
+
+- No inventes datos. No copies videos de otros: se toma la forma, no el contenido.
+- Emojis solo como último recurso; mejor objetos 2D/3D (`{tipo: 'recurso', buscar: 'volcán', estilo: '3d'}`).
+- Un render a la vez. Si un render falla, lee el error (Morfeo explica qué falta) y corrígelo.
+- No toques `node_modules/`. Lo de la persona vive en `guiones/`, `escenas/`, `assets/`, `estilo.json` y `morfeo.config.mjs`.

package/plantilla/CLAUDE.md

@@ -0,0 +1,5 @@
+# Instrucciones para Claude Code
+
+Las instrucciones de este proyecto están en AGENTS.md (las mismas para cualquier IA):
+
+@AGENTS.md

package/python/musica.py

@@ -179,11 +179,97 @@ def efecto(nombre, rng):
         x = 0.22 * pop(180, 90, 0.16)
         add(x, 0.1 * lp(rng.standard_normal(int(0.06 * SR)), 1200), 0)
         return x
+    if nombre in EFECTOS_EXTRA: return EFECTOS_EXTRA[nombre](rng)
     return 0.14 * pop()
 
 
+def _env(n, ataque=0.004, cola=6.0):
+    t = np.arange(n) / SR
+    return np.minimum(1, t / ataque) * np.exp(-t * cola)
+
+
+def _tono(f, d, cola=8.0, armonicos=(1,)):
+    n = int(d * SR); t = np.arange(n) / SR
+    x = sum(np.sin(2 * np.pi * f * h * t) / (i + 1) for i, h in enumerate(armonicos))
+    return x * _env(n, 0.003, cola)
+
+
+def _teclas(rng):
+    """Ráfaga de teclas de máquina: 7 clics secos con espaciado irregular."""
+    x = np.zeros(int(0.9 * SR)); t = 0.0
+    for _ in range(7):
+        c = hp(rng.standard_normal(int(0.012 * SR)), 2500) * _env(int(0.012 * SR), 0.0005, 300)
+        add(x, 0.14 * c, t); t += 0.07 + rng.random() * 0.07
+    return x
+
+
+def _radio(rng):
+    """Estática de radio con un pitido de sintonía."""
+    n = int(0.7 * SR)
+    ruido = hp(lp(rng.standard_normal(n), 3500), 400) * 0.25 * np.minimum(1, np.arange(n) / (0.03 * SR)) * np.linspace(1, 0.2, n)
+    add(ruido, 0.08 * _tono(1200, 0.25, 4), 0.2)
+    return ruido
+
+
+def _obturador(rng):
+    """Obturador de cámara: dos clics mecánicos."""
+    x = np.zeros(int(0.25 * SR))
+    for t, f in ((0.0, 1800), (0.07, 1300)):
+        c = lp(hp(rng.standard_normal(int(0.02 * SR)), 900), f * 3) * _env(int(0.02 * SR), 0.0004, 220)
+        add(x, 0.5 * c, t)
+    return x
+
+
+def _notificacion(rng):
+    """Notificación del teléfono: dos notas que suben."""
+    x = np.zeros(int(0.5 * SR))
+    add(x, 0.18 * _tono(nf(84), 0.25, 14, (1, 2)), 0)
+    add(x, 0.18 * _tono(nf(91), 0.35, 10, (1, 2)), 0.11)
+    return x
+
+
+def _latido(rng):
+    """Latido: dos golpes graves (lub-dub)."""
+    x = np.zeros(int(0.7 * SR))
+    add(x, 0.5 * _tono(55, 0.18, 22), 0)
+    add(x, 0.35 * _tono(48, 0.16, 24), 0.2)
+    return lp(x, 300)
+
+
+def _alarma(rng):
+    """Alarma: tres pitidos cuadrados."""
+    x = np.zeros(int(0.9 * SR))
+    for i in range(3):
+        n = int(0.16 * SR); t = np.arange(n) / SR
+        b = np.sign(np.sin(2 * np.pi * 1600 * t)) * 0.09 * np.minimum(1, (n - np.arange(n)) / (0.01 * SR))
+        add(x, lp(b, 5000), i * 0.27)
+    return x
+
+
+def _reloj(rng):
+    """Tic-tac de reloj: tic agudo y tac grave."""
+    x = np.zeros(int(1.0 * SR))
+    for i in range(2):
+        add(x, 0.45 * tick(0.02), i * 0.5)
+        add(x, 0.3 * lp(tick(0.025), 1500), i * 0.5 + 0.25)
+    return x
+
+
+def _caja(rng):
+    """Caja registradora: campanita y cajón que se abre."""
+    x = np.zeros(int(0.9 * SR))
+    add(x, 0.25 * bell(nf(96), 0.7), 0.0)
+    cajon = lp(rng.standard_normal(int(0.25 * SR)), 900) * _env(int(0.25 * SR), 0.01, 10) * 0.25
+    add(x, cajon, 0.12)
+    return x
+
+
+EFECTOS_EXTRA = {"teclas": _teclas, "radio": _radio, "obturador": _obturador, "notificacion": _notificacion, "latido": _latido, "alarma": _alarma, "reloj": _reloj, "caja": _caja}
+
+
 # sonido por defecto según cómo entra o qué es la capa (sonido: false lo apaga; sonido: "x" lo cambia)
-SONIDO_TIPO = {"sello": "golpe", "dato": "tick", "contador": "tick", "nombre": "pop", "accion": "pop", "chip": "pop", "insignia": "pop"}
+SONIDO_TIPO = {"sello": "golpe", "dato": "tick", "contador": "tick", "nombre": "pop", "accion": "pop", "chip": "pop", "insignia": "pop",
+               "bloqueo": "notificacion", "llamada": "notificacion", "vigilancia": "radio", "terminal": "teclas", "calendario": "reloj", "fecha": "golpe", "noticia": "radio", "recuento": "tick", "cronometro": "reloj"}
 SONIDO_ENTRADA = {"rebote": "pop", "caer": "golpe", "deslizar-izq": "whoosh", "deslizar-der": "whoosh", "deslizar-arriba": "whoosh", "deslizar-abajo": "whoosh", "girar": "whoosh"}
 
 

package/python/preparar.py

@@ -264,7 +264,7 @@ def preparar(job):
     subs = [dict(a=round(c[0][1], 3), b=round(c[-1][2], 3), w=[[x[0].upper(), round(x[1], 3), round(x[2], 3)] for x in c])
             for ws in WORDS for c in trozos(ws)]
     datos = dict(id=vid, titulo=v.get("title", vid), indice=job.get("indice", 0), duracion=round(sum(durs), 3),
-                 estilo=v.get("estilo", "datos-curiosos"), tema=v.get("tema") or {}, hud=v.get("hud") or [], mundo=v.get("mundo") or [], serie=v.get("serie"),
+                 estilo=v.get("estilo", "datos-curiosos"), tema=v.get("tema") or {}, hud=v.get("hud") or [], mundo=v.get("mundo") or [], lugares=v.get("lugares") or {}, serie=v.get("serie"),
                  audio=f"v/{vid}/mix.wav", whisper=reales, escenas=escenas, subtitulos=subs)
     json.dump(datos, open(os.path.join(outdir, "datos.json"), "w", encoding="utf-8"), ensure_ascii=False, indent=1)
     print(f"    tiempos por palabra: {'Whisper' if reales else 'reparto por frase'} ({reales}/{len(TIM)} escenas)", flush=True)

package/remotion/Short.tsx

@@ -27,10 +27,11 @@ import {MARCA_VACIA, type Datos, type Escena, type Marca as TipoMarca} from './t
 import {Capas} from './motor/capas';
 import {capasDe} from './motor/plantillas';
 import {temaDe} from './motor/tema';
+import {Portada} from './motor/portada';
 import {VideoConAudio} from './motor/Video';
 import {loadFont} from '@remotion/fonts';
 
-export type PropsShort = {id: string; videos?: Record<string, Datos>; marca?: TipoMarca; guias?: boolean; miniatura?: boolean; fuentes?: {familia: string; url: string}[]; estilos?: Record<string, any>};
+export type PropsShort = {id: string; videos?: Record<string, Datos>; marca?: TipoMarca; guias?: boolean; miniatura?: boolean; portada?: string; fuentes?: {familia: string; url: string}[]; estilos?: Record<string, any>};
 
 const ADELANTO_GANCHO = 0.4; // el gancho arranca ya animado: el fotograma 0 nunca está vacío
 const CIERRE_BUCLE = 0.5; // al final se funde con el fotograma 0 para que el video se repita sin corte
@@ -246,7 +247,7 @@ export const Fotograma: React.FC<{d: Datos; T: number; guias?: boolean; miniatur
 	);
 };
 
-export const Short: React.FC<PropsShort> = ({id, videos, marca, guias, miniatura, fuentes, estilos}) => {
+export const Short: React.FC<PropsShort> = ({id, videos, marca, guias, miniatura, portada, fuentes, estilos}) => {
 	const frame = useCurrentFrame();
 	const [listo, setListo] = useState(false);
 	const [handle] = useState(() => delayRender('Cargando fuentes'));
@@ -259,6 +260,13 @@ export const Short: React.FC<PropsShort> = ({id, videos, marca, guias, miniatura
 	const d = videos?.[id];
 	if (!d) throw new Error(`El video "${id}" no está preparado. Corre: npx morfeo render ${id}`);
 	if (!listo) return null;
+	if (portada)
+		return (
+			<AbsoluteFill>
+				{d.estilo && d.estilo !== 'datos-curiosos' ? <VideoConAudio d={d} frame={frame} marca={{...MARCA_VACIA, ...marca}} estilos={estilos} miniatura sinMarca /> : <Fotograma d={d} T={frame / FPS} miniatura />}
+				<Portada texto={portada} marca={{...MARCA_VACIA, ...marca}} />
+			</AbsoluteFill>
+		);
 	if (d.estilo && d.estilo !== 'datos-curiosos') return <VideoConAudio d={d} frame={frame} marca={{...MARCA_VACIA, ...marca}} estilos={estilos} miniatura={miniatura} />;
 	const T = frame / FPS;
 	const kb = clamp((T - (d.duracion - CIERRE_BUCLE)) / CIERRE_BUCLE);

package/remotion/kit/armar.tsx

@@ -0,0 +1,245 @@
+// Piezas 3D para los formatos "construiste un X" y "escalada absurda" (un objeto que suma partes escena por escena),
+// para multitudes ("30 000 hombres") y para la mano en primera persona que aprieta un control o sostiene algo.
+// Todo depende de `t` (segundos) y de props; nada de useFrame.
+//
+//   <Aparece t={t} en={cuando('ruedas')} desde="arriba"><Ruedas /></Aparece>      (cae, rebota y suena por su cuenta)
+//   <Multitud3D t={t} n={400} ancho={16} fondo={10} colores={['#2F6FE0', '#F2B632']} destacar={[0, 7]} />
+//   <Mano3D t={t} pos={[0.5, -1.2, 3]} sostiene="control" aprieta={cuando('botón')} />
+import React, {useMemo} from 'react';
+import * as THREE from 'three';
+import {azarN} from './ilustrado';
+import {grupo, type Pieza, type V3} from './tres';
+
+const clamp01 = (x: number) => Math.max(0, Math.min(1, x));
+const suave = (x: number) => {
+	const c = clamp01(x);
+	return c * c * (3 - 2 * c);
+};
+/** Rebote al caer: llega en 0.55 del tramo, rebota dos veces y se queda. */
+const caida = (k: number) => {
+	if (k >= 1) return 1;
+	if (k < 0.55) return (k / 0.55) ** 2;
+	const r = (k - 0.55) / 0.45;
+	return 1 - Math.abs(Math.sin(r * Math.PI * 2)) * (1 - r) * 0.12;
+};
+
+const Mate: React.FC<{c: string; r?: number}> = ({c, r = 0.75}) => <meshStandardMaterial color={c} roughness={r} flatShading />;
+
+/**
+ * Una parte que llega en su momento: cae desde arriba con rebote (`desde: 'arriba'`), crece desde cero (`'crece'`),
+ * entra de lado (`'izq'`/`'der'`) o sube del suelo (`'abajo'`). Antes de `en` no se ve. `dur` en segundos, `altura` de caída.
+ */
+export const Aparece: React.FC<Pieza & {t: number; en: number; desde?: 'arriba' | 'crece' | 'izq' | 'der' | 'abajo'; dur?: number; altura?: number; hasta?: number; children: React.ReactNode}> = ({t, en, desde = 'arriba', dur = 0.55, altura = 4, hasta, children, ...p}) => {
+	if (t < en) return null;
+	const k = clamp01((t - en) / dur);
+	const fuera = hasta != null ? suave((t - hasta) / 0.35) : 0;
+	if (fuera >= 1) return null;
+	const g = grupo(p);
+	let [x, y, z] = g.position;
+	let esc = g.scale * (1 - fuera);
+	if (desde === 'arriba') y += (1 - caida(k)) * altura;
+	else if (desde === 'abajo') y -= (1 - suave(k)) * altura;
+	else if (desde === 'izq') x -= (1 - suave(k)) * altura;
+	else if (desde === 'der') x += (1 - suave(k)) * altura;
+	else esc *= k < 1 ? Math.sin(suave(k) * Math.PI * 0.62) / Math.sin(Math.PI * 0.62) : 1;
+	// pequeño aplastamiento al tocar el suelo
+	const apl = desde === 'arriba' && k > 0.5 && k < 0.8 ? Math.sin(((k - 0.5) / 0.3) * Math.PI) * 0.12 : 0;
+	return (
+		<group position={[x, y, z]} rotation={g.rotation} scale={[esc * (1 + apl * 0.5), esc * (1 - apl), esc * (1 + apl * 0.5)]}>
+			{children}
+		</group>
+	);
+};
+
+/**
+ * Multitud de figuras simples (cuerpo + cabeza) en una rejilla con algo de desorden, en un solo `instancedMesh` (miles
+ * sin costo). `n`, `ancho`×`fondo` (unidades), `colores` del cuerpo, `destacar: [índices]` en `colorDestacado`, `brinca`
+ * para que salten. Aparece de adelante hacia atrás desde `en`.
+ */
+export const Multitud3D: React.FC<Pieza & {t: number; n?: number; ancho?: number; fondo?: number; colores?: string[]; colorDestacado?: string; destacar?: number[]; brinca?: boolean; en?: number; altura?: number}> = ({t, n = 300, ancho = 14, fondo = 10, colores = ['#2F6FE0', '#3D7DF0', '#2A5FC8'], colorDestacado = '#F2B632', destacar = [], brinca = false, en = 0, altura = 1.1, ...p}) => {
+	const cols = Math.max(1, Math.round(Math.sqrt((n * ancho) / fondo)));
+	const filas = Math.ceil(n / cols);
+	const datos = useMemo(() => {
+		let semilla = n * 3 + 7;
+		const r = () => azarN(semilla++);
+		return Array.from({length: n}, (_, i) => {
+			const c = i % cols;
+			const f = Math.floor(i / cols);
+			const x = (c / Math.max(1, cols - 1) - 0.5) * ancho + (r() - 0.5) * (ancho / cols) * 0.5;
+			const z = (f / Math.max(1, filas - 1) - 0.5) * fondo + (r() - 0.5) * (fondo / filas) * 0.5;
+			return {x, z, fase: r() * 6.28, escala: 0.9 + r() * 0.2, color: destacar.includes(i) ? colorDestacado : colores[Math.floor(r() * colores.length)], fila: f};
+		});
+	}, [n, cols, filas, ancho, fondo, colores.join(), colorDestacado, destacar.join()]);
+	const cuerpo = useMemo(() => new THREE.CapsuleGeometry(0.22 * altura, 0.5 * altura, 3, 6), [altura]);
+	const cabeza = useMemo(() => new THREE.IcosahedronGeometry(0.2 * altura, 0), [altura]);
+	const m = useMemo(() => new THREE.Matrix4(), []);
+	const color = useMemo(() => new THREE.Color(), []);
+	const refC = React.useRef<THREE.InstancedMesh>(null);
+	const refH = React.useRef<THREE.InstancedMesh>(null);
+	// las matrices se escriben en cada render (depende de t), no en un efecto
+	const aplicar = () => {
+		if (!refC.current || !refH.current) return;
+		datos.forEach((d, i) => {
+			const k = clamp01((t - en - d.fila * 0.04) / 0.35);
+			const s = d.escala * (k < 1 ? caida(k) : 1);
+			const salto = brinca ? Math.max(0, Math.sin(t * 6 + d.fase)) * 0.25 : 0;
+			m.compose(new THREE.Vector3(d.x, (0.47 * altura + salto) * s, d.z), new THREE.Quaternion(), new THREE.Vector3(s, s, s));
+			refC.current!.setMatrixAt(i, m);
+			refC.current!.setColorAt(i, color.set(d.color));
+			m.compose(new THREE.Vector3(d.x, (1.05 * altura + salto) * s, d.z), new THREE.Quaternion(), new THREE.Vector3(s, s, s));
+			refH.current!.setMatrixAt(i, m);
+			refH.current!.setColorAt(i, color.set('#F2C9A4'));
+		});
+		refC.current.instanceMatrix.needsUpdate = true;
+		refH.current.instanceMatrix.needsUpdate = true;
+		if (refC.current.instanceColor) refC.current.instanceColor.needsUpdate = true;
+		if (refH.current.instanceColor) refH.current.instanceColor.needsUpdate = true;
+	};
+	React.useLayoutEffect(aplicar);
+	return (
+		<group {...grupo(p)}>
+			<instancedMesh ref={refC} args={[cuerpo, undefined, n]} castShadow>
+				<meshStandardMaterial roughness={0.7} flatShading />
+			</instancedMesh>
+			<instancedMesh ref={refH} args={[cabeza, undefined, n]} castShadow>
+				<meshStandardMaterial roughness={0.7} flatShading />
+			</instancedMesh>
+		</group>
+	);
+};
+
+/** Control remoto o de portón: caja oscura con botones. */
+const Control: React.FC<{apretado: number}> = ({apretado}) => (
+	<group>
+		<mesh castShadow>
+			<boxGeometry args={[0.55, 0.95, 0.16]} />
+			<Mate c="#26282E" />
+		</mesh>
+		<mesh position={[0, 0.2, 0.09 - apretado * 0.03]}>
+			<cylinderGeometry args={[0.13, 0.13, 0.06, 16]} />
+			<meshStandardMaterial color="#E5484D" roughness={0.4} emissive="#E5484D" emissiveIntensity={apretado * 0.8} />
+		</mesh>
+		{[-0.13, 0.13].map((x) => (
+			<mesh key={x} position={[x, -0.15, 0.09]} rotation={[Math.PI / 2, 0, 0]}>
+				<cylinderGeometry args={[0.07, 0.07, 0.04, 12]} />
+				<Mate c="#D7D9DE" />
+			</mesh>
+		))}
+	</group>
+);
+
+/** Teléfono: losa negra con pantalla encendida. */
+const Movil: React.FC<{pantalla?: string}> = ({pantalla = '#3A6FF2'}) => (
+	<group>
+		<mesh castShadow>
+			<boxGeometry args={[0.55, 1.1, 0.08]} />
+			<Mate c="#111214" r={0.4} />
+		</mesh>
+		<mesh position={[0, 0, 0.045]}>
+			<planeGeometry args={[0.48, 1.0]} />
+			<meshStandardMaterial color={pantalla} emissive={pantalla} emissiveIntensity={0.7} />
+		</mesh>
+	</group>
+);
+
+/**
+ * Mano en primera persona (entra desde abajo del cuadro): palma, cuatro dedos que rodean lo que sostiene y pulgar que
+ * aprieta en `aprieta` (segundos). `sostiene: 'control' | 'movil' | 'nada'`, `piel`, `manga` (color de la manga).
+ * Ponla cerca de la cámara (2–4 u) y abajo del centro.
+ */
+export const Mano3D: React.FC<Pieza & {t: number; sostiene?: 'control' | 'movil' | 'nada'; aprieta?: number; piel?: string; manga?: string; en?: number; pantalla?: string}> = ({t, sostiene = 'control', aprieta, piel = '#E8B48F', manga = '#2F6FE0', en = 0, pantalla, ...p}) => {
+	const entra = suave((t - en) / 0.45);
+	const dt = aprieta != null ? t - aprieta : -1;
+	const apretado = dt >= 0 && dt < 0.5 ? Math.sin((dt / 0.5) * Math.PI) : 0;
+	const g = grupo(p);
+	const [x, y, z] = g.position;
+	const tiembla = Math.sin(t * 2.1) * 0.01;
+	return (
+		<group position={[x, y - (1 - entra) * 1.6 + tiembla, z]} rotation={g.rotation} scale={g.scale}>
+			{/* manga y muñeca */}
+			<mesh position={[0, -0.95, -0.05]} rotation={[0.25, 0, 0]} castShadow>
+				<cylinderGeometry args={[0.24, 0.3, 0.9, 8]} />
+				<Mate c={manga} />
+			</mesh>
+			<mesh position={[0, -0.45, 0]} castShadow>
+				<cylinderGeometry args={[0.17, 0.2, 0.3, 8]} />
+				<Mate c={piel} />
+			</mesh>
+			{/* palma detrás del objeto */}
+			<mesh position={[0, -0.05, -0.14]} castShadow>
+				<boxGeometry args={[0.6, 0.62, 0.2]} />
+				<Mate c={piel} />
+			</mesh>
+			{/* lo que sostiene */}
+			<group position={[0, 0.15, 0]}>{sostiene === 'control' ? <Control apretado={apretado} /> : sostiene === 'movil' ? <Movil pantalla={pantalla} /> : null}</group>
+			{/* dedos que rodean por la derecha */}
+			{[0.22, 0.02, -0.18, -0.36].map((yy, i) => (
+				<mesh key={i} position={[0.33, yy + 0.1, 0.02]} rotation={[0, 0, 0.1]} castShadow>
+					<boxGeometry args={[0.14, 0.15, 0.24]} />
+					<Mate c={piel} />
+				</mesh>
+			))}
+			{/* pulgar: baja sobre el botón al apretar */}
+			<group position={[-0.32, -0.05, 0.05]} rotation={[0, 0, -0.9 + apretado * 0.35]}>
+				<mesh position={[0, 0.25, 0.1 - apretado * 0.04]} castShadow>
+					<boxGeometry args={[0.16, 0.42, 0.16]} />
+					<Mate c={piel} />
+				</mesh>
+			</group>
+		</group>
+	);
+};
+
+/** Partes listas para armar objetos que crecen: rueda, motor y asiento (low-poly, se combinan con Aparece). */
+export const Rueda: React.FC<Pieza & {radio?: number; t?: number; gira?: number; color?: string}> = ({radio = 0.35, t = 0, gira = 0, color = '#1E1F24', ...p}) => (
+	<group {...grupo(p)}>
+		<group rotation={[0, 0, -t * gira]}>
+			<mesh rotation={[Math.PI / 2, 0, 0]} castShadow>
+				<cylinderGeometry args={[radio, radio, radio * 0.6, 14]} />
+				<Mate c={color} r={0.9} />
+			</mesh>
+			<mesh rotation={[Math.PI / 2, 0, 0]} position={[0, 0, 0.01]}>
+				<cylinderGeometry args={[radio * 0.5, radio * 0.5, radio * 0.62, 8]} />
+				<Mate c="#B9BEC8" r={0.5} />
+			</mesh>
+		</group>
+	</group>
+);
+
+export const Motor: React.FC<Pieza & {t?: number; color?: string}> = ({t = 0, color = '#F2B632', ...p}) => {
+	const vibra = Math.sin(t * 60) * 0.01;
+	return (
+		<group {...grupo(p)} position={[(p.pos?.[0] ?? 0) + vibra, p.pos?.[1] ?? 0, p.pos?.[2] ?? 0]}>
+			<mesh castShadow>
+				<boxGeometry args={[0.7, 0.5, 0.5]} />
+				<Mate c={color} />
+			</mesh>
+			<mesh position={[0, 0.32, 0]} castShadow>
+				<boxGeometry args={[0.4, 0.14, 0.34]} />
+				<Mate c="#2A2C33" />
+			</mesh>
+			<mesh position={[0.42, 0.1, 0]} rotation={[0, 0, Math.PI / 2]} castShadow>
+				<cylinderGeometry args={[0.06, 0.06, 0.2, 8]} />
+				<Mate c="#6B7080" />
+			</mesh>
+		</group>
+	);
+};
+
+export const Asiento: React.FC<Pieza & {color?: string}> = ({color = '#E5484D', ...p}) => (
+	<group {...grupo(p)}>
+		<mesh position={[0, 0, 0]} castShadow>
+			<boxGeometry args={[0.6, 0.14, 0.55]} />
+			<Mate c={color} />
+		</mesh>
+		<mesh position={[0, 0.32, -0.24]} castShadow>
+			<boxGeometry args={[0.6, 0.6, 0.12]} />
+			<Mate c={color} />
+		</mesh>
+		<mesh position={[0, -0.25, 0]} castShadow>
+			<cylinderGeometry args={[0.05, 0.05, 0.4, 6]} />
+			<Mate c="#6B7080" />
+		</mesh>
+	</group>
+);
+

package/remotion/kit/index.ts

@@ -12,3 +12,4 @@ export * from './mundo3d';
 export * from './datos';
 export * from './diorama';
 export {clamp, easeIO, easeOut, easeOutExpo, backOut, resorte, ruido, lerp, mezclaColor} from '../estilo';
+export * from './armar';