DozenTwelve/papermorph

¿Qué hace papermorph?

Papermorph crea tres niveles de libro en un solo motor:

• Lecciones, a partir de un PDF de libro de texto: cada capítulo es una breve película animada de lección donde la imagen lleva la explicación, la narración la dice, y los controles rápidos y la práctica ocurren dentro de la imagen.
• Libros ilustrados, a partir de un cuento, un chiste o un cuento de hadas: cortometrajes de marionetas de papel frente a decorados, dibujados en código o pintados por un modelo de imagen, con voces, efectos y música.
• Películas, a partir de un libro, una idea o el argumento del usuario: documentales narrados con imágenes de dominio público encontradas, palabras y mapas movidos al compás de la voz, y cortos verticales para el feed del teléfono que exponen un punto en menos de tres minutos.

Todos son un escenario SVG (1600×900, o 900×1600 para un corto) más un reproductor; los beats emparejan clips de narración con acciones temporizadas. Bueno significa vivo (las cosas actúan y cambian con peso y ritmo), compuesto (cada momento se lee como una imagen, texto junto a lo que nombra), verdadero (el movimiento, las etiquetas y los números concuerdan en cada momento) y suave (se reproduce sin tirones, incluido Firefox).

Qué debe ser la imagen depende del libro y del usuario, así que el trabajo comienza con una conversación que termina en style.json: las palabras del usuario, el aspecto que eligieron, las voces, qué modelo hace cada paso, y más tarde los capítulos aprobados. Cada capítulo se hace contra eso; cómo se dispone y coreografía cada beat depende de tu criterio comparándolo con eso y los capítulos aprobados. Las solicitudes del usuario anulan los valores predeterminados. Vuelve a crear explicaciones, ejemplos y dibujos; mantén los PDFs fuente, las imágenes de página y el texto extraído fuera de la carpeta de salida estática y fuera del control de versiones (.gitignore: *.pdf, books/*/pages/). Un capítulo hecho por el Skill es un primer corte: las rondas de revisión y la visualización del usuario ocurren antes de que se publique.

Qué nivel

Lee el primer archivo del nivel, luego solo lo que necesita el paso actual. Cada archivo a continuación está enlazado desde aquí; ninguno necesita otro para ser encontrado.

El usuario trae	Nivel	Comienza con	Luego, según lo que necesite el paso
Un PDF de libro de texto (también un libro de curso)	Lecciones	lessons.md	intake.md · authoring.md · diagrams.md (nivel 1) · scenes.md (nivel 2) · assets.md · maths.md (math.js, partes matemáticas, LaTeX) · questions.md · figures.md (figuras que el lector mueve) · checks.md · cover.md · courses.md (citas, banco de ítems, SCORM: solo cuando el libro lo requiera)
Un cuento, un chiste, un cuento de hadas, o el PDF de un libro ilustrado (sus propias imágenes escaneadas: stories.md)	Libros ilustrados	stories.md	puppets.md · painting.md (un aspecto pintado) · listen-and-find.md (un juego de encontrar para niños pequeños)
Un libro, una idea o un tramo de historia para explicar como película narrada	Películas: documental	films.md	documentary.md
Un punto que exponer en menos de tres minutos, vertical, para el feed del teléfono (YouTube Shorts, TikTok, Reels), o una película larga para re-cortar	Películas: cortos	films.md	shorts.md
El material de una película, o una idea que es principalmente mapas y números, para leer al propio ritmo del lector en una página cuya imagen cambia mientras se desplaza (una historia de desplazamiento)	Películas: página de desplazamiento	films.md	scroll.md
Un tramo de historia para explorar en un mapa, año a año: fronteras que cambian, personas que se mueven (una página, su propio reproductor, no el motor)	Páginas que exploras	explore.md

Cada nivel comparte el núcleo:

Archivo	Qué contiene
core/style.md	cómo preguntar al usuario, los pasos del modelo, los pasos de pago (claves, precios, libro de contabilidad, saldo), style.json
core/publish.md	new_book.py, idioma, minutos, vista previa y entrega, exportación de video
core/sound.md	el archivo de narración, voces, niveles, efectos, música, subtítulos
core/review.md	ver tu propio trabajo en movimiento, fotogramas, suavidad, rondas del director
core/team.md	hacer capítulos con subagentes, el coordinador, trabajadores en paralelo
core/engine.md	el reproductor y la API de dibujo, temporización, cámara, rendimiento, trampas

Comienza con la ingesta del nivel siempre que books/<book>/style.json aún no exista; reutiliza respuestas y aprobaciones ya dadas.

Libros de referencia

Los libros de referencia son el listón: niveles a alcanzar, no formatos a copiar. Cada uno es la carpeta site/<slug>/ del repositorio Papermorph (https://github.com/DozenTwelve/Papermorph), servida en https://papermorph.diamonddoge.org/<slug>/, por lo que su fuente se puede leer en un checkout o recuperarse de cualquiera de las direcciones cuando el Skill está instalado por sí solo. Los archivos de nivel nombran el archivo en un libro que vale la pena abrir para un paso dado.

Nivel	Libros (slug)
Lecciones	nivel 1: Elementary Algebra (elementary-algebra), Math Notebook (math-notebook); nivel 2: Science (science); una pizarra ligera con tinta oscura: physics-notebook
Libros ilustrados	The Little Horse Crosses the River (little-horse) y Little Red Riding Hood (little-red-riding-hood): todo en código, un elenco con voces de ElevenLabs, una parada de escuchar y encontrar, lo más nuevo y el listón; Joke Collection (joke-collection): decorados pintados, marionetas en código, una serie de episodios; Millions of Cats (millions-of-cats, Wanda Gág, 1928): las imágenes propias de un libro escaneado elevadas a decorados y marionetas (no en el estante)
Documentales	Madness and Civilization (madness, después de Foucault, diez minutos), The Pandemic (pandemic), Shooting an Elephant (shooting-an-elephant, uno en el que el lector actúa)
Cortos	los cortos de Madness and Civilization (madness-shorts; el episodio 1, The Ship, es el ejemplo trabajado), los cortos de The Pandemic (pandemic-shorts)

Tulip Mania (tulip-mania) es una película de prueba hecha solo con el Skill, sin ayuda más allá de estos archivos; los archivos citan con qué se encontró.

Estructura del proyecto

books/<book>/                  privado: fuente, style.json, storyboards, arte, review/ (los archivos de nivel enumeran los suyos propios)
content/<book>/chNN/           narration.<lang>.json y el caché de voz
tools/<book>/                  pruebas, scripts de audio, evidencia
site/<book>/                   el libro estático (solo esto se entrega)
  index.html                   portada e índice, o una página de serie
  lib/                         el motor (sincronizado por engine.py), lib/book.css (la configuración de este libro), el kit del nivel, las piezas propias del libro
  img/                         las imágenes del libro
  chNN/index.html, audio/<lang>/   un capítulo o episodio, sus MP3 de beat y timings.js (películas y libros ilustrados: audio/sfx/, audio/bgm/)

SKILL significa la carpeta absoluta de este skill; <book> es el slug del libro, <lang> su código de idioma principal. new_book.py inicia un libro de cualquier nivel (core/publish.md).

Necesita: uv, ffmpeg/ffprobe, acceso de red a Edge TTS (o Kokoro, local), github.com para engine.py cuando la carpeta engine/ del repositorio no está a mano, una clave de OpenRouter solo para los pasos de pago que el usuario elija (paint.py, eleven.py, video.py; paint_openai.py toma una clave de OpenAI), y navegadores Playwright (uv run --with playwright playwright install chromium firefox; donde Chromium de Playwright no se ejecuta, establece CHROME a un Chrome, Chromium, Brave o Edge instalado). Vista previa: python3 SKILL/scripts/serve.py 8765 site (sin caché del navegador).

Scripts

Todos en SKILL/scripts/; cada uno imprime su uso con --help cuando se ejecuta con el uv run --with … que nombran las primeras líneas de su docstring (sin sus paquetes, incluso --help se detiene en la importación).

Para	Scripts
Cada libro	new_book.py iniciar una carpeta de libro · serve.py vista previa sin caché · engine.py sincronizar el motor en los libros · tts.py narración y tiempos de palabra · eleven.py lo mismo desde ElevenLabs (de pago) · level.py ecualizar el volumen · lint.py comprobaciones estáticas · check.py errores de página, advertencias de consola y duraciones de beat en Chromium y Firefox · shot.py capturas de pantalla de beat · strip.py hojas de storyboard y tiras de movimiento · still.py tramos donde nada se mueve · playlog.py sonidos y subtítulos contra la imagen · perf.py tiempos de fotograma en Firefox · export.py MP4 y .srt · sfx.py efectos sintetizados
Lecciones	outline.py y split_pages.py mapa de página y texto de capítulo · check_blank.py aperturas vacías · overlap.py flechas a través del texto · sprites.py pasos de procesamiento de imagen · refs.py citas verificadas · items.py banco de preguntas · scorm.py paquete LMS
Libros ilustrados	mouths.py formas de boca · join.py un clip por escena · bake_sets.py capas de decorado · bake_puppets.py mapas de bits de marioneta · paint.py / paint_openai.py imágenes de modelo de imagen · painted.py colocarlas en el libro · lift.py figuras, decorados y letras recortados de las imágenes propias de un libro escaneado · cutout.py imágenes de modelo de imagen sobre un color clave cortadas en piezas de marioneta y accesorios
Páginas que exploras	topo.py el TopoJSON del mapa desde Natural Earth · explore.py comprobaciones, tomas, temporización de Firefox y el archivo de narración para un mapa explorable
Películas	commons.py imágenes y grabaciones de dominio público con sus licencias · prep.py tratamientos de impresión, línea y sangrado completo · trace.py dibujos que se dibujan a sí mismos · video.py un clip a partir de un fotograma fijo · frames.py un clip como fotogramas tratados · geo.py los datos del kit de mapas desde Natural Earth · music.py una pista cortada para la película, la cama en los huecos de la voz, y la música, camas y efectos contra cada línea · safe.py palabras fuera del área segura de una película vertical

silence.py, ledger.py (el único libro de contabilidad de costos: fecha, capítulo, archivo, modelo, qué, costo) y browsers.py son ayudas que los demás importan.

Contexto

• Habla con el usuario desde la conversación principal: la ingesta, y cada hoja y elección del piloto. Cuando los subagentes están disponibles, los capítulos se hacen como un equipo, cada paso en el modelo que el usuario eligió, con la conversación principal como el coordinador del piloto (core/team.md dice lo que eso permite); sin ellos, ejecuta los mismos pasos en el agente actual con estado basado en archivos.
• Usa la API del motor e inspecciona funciones individuales cuando sea necesario; copia los archivos del kit en lugar de leer su fuente completa como instrucciones.
• Mantén style.json actualizado y breve; el estado del capítulo, las erratas y los comentarios históricos se guardan en chapters.md y chapters/chNN.md.