jiaosdesign-pixel/popbook

¿Qué hace popbook?

Una página de un libro pop-up es un archivo JSON (un "momento") construido a partir de un kit de piezas de papel. scripts/build.mjs convierte uno o más momentos en un solo archivo HTML. La foto es solo referencia: nunca se incluye en el libro.

Lee primero: references/kit.md (cada pieza, sus parámetros, las claves de paleta que utiliza, las reglas de plegado), luego el ejemplo en examples/ más cercano al tema de la foto: una costa o un paseo (bay-trail), un jardín, una casa o una escena festiva (filoli-halloween), un punto de referencia (golden-gate), una tienda o un café (cafe).

Entradas

• Una foto (mírala), una línea en las propias palabras del remitente, o ambas. Generalmente ambas.
• Lugar y fecha, en este orden de confianza: su línea, los EXIF de la foto, el nombre del archivo. scripts/photo.py <photo> imprime la fecha, GPS, tamaño y una estimación de paleta (usa sus colores de escena; ignora su portada y franjas, el bloque de la casa mantiene esos). Lee el lugar del nombre del archivo tú mismo si lo tiene. Una fecha de archivo sin EXIF suele ser incorrecta (una foto regrabada lleva la fecha de guardado): pregunta. Si el lugar es desconocido, haz una pregunta y sigue trabajando en todo lo demás.
• Si ya tienen un libro (una carpeta de archivos de momento), la nueva página se une a él: construye todos los archivos juntos.

El estándar

Los cuatro ejemplos son el estándar. Evalúa contra el más cercano antes de entregar cualquier cosa.

• 4 a 6 piezas narrativas en 3 o más capas, fondo, medio y frente. El motor rechaza más de 6; menos de 4 se considera vacío.
• Dos cosas con las que jugar además del dial del cielo: una que el lector toca (una campana, una gaviota, una puerta) y una que arrastra (una lengüeta, una palanca, un deslizador, una imagen giratoria). check.mjs enumera ambas y falla si alguna está vacía. kit.md sección 1, "Qué responde al lector", enumera cada pieza que acepta un toque o un arrastre. Si nada en su foto o línea se puede tocar, haz una pregunta antes de añadir algo ("¿Había algo más allí, como un pájaro, una bandera, una campana o una puerta?"). Si la respuesta es no, entrega la página por debajo del estándar y dilo.
• Un bucle vivo. Algo en la escena se mueve solo durante el día: tráfico, un jinete, un barco, vapor, un pájaro, una bandera, hojas. Elige lo que viaja o respira en la foto o la línea. Los toques, arrastres y las pistas iniciales no cuentan. check.mjs imprime alive: y falla cuando está vacío.
• Kit primero. Construye todo lo que puedas con piezas existentes: colinas, árboles y setos como bandas de capa, lámparas, una figura, un jinete, pájaros. Una nueva pieza del kit solo para lo único que el remitente señalaría, y como máximo una por página (ver "Una pieza nueva").
• Solo lo que está en la foto o la línea. Sin accesorios decorativos. Si la escena queda escasa porque la foto es simple, dilo en lugar de inventar.
• La luz de la casa y el libro, sin cambios. new.mjs escribe el bloque de la casa (forma del libro, portada, bordes de página, lámpara, luz, cámara). El día es una luz de estudio suave, la noche es luz de luna con las lámparas encendidas; la hora del día y el clima viven en la paleta, el dial del cielo y las lámparas, nunca en la luz.
• La figura es el remitente a menos que digan lo contrario. Vístelos según la foto (palette.figure: abrigo, bufanda, piernas, cabello, piel). Con solo una línea, mantén los colores de la figura del ejemplo a menos que digan lo que usaron, y di en la nota lo que supusiste. Sin bufanda en la foto: establece scarf al color del abrigo. Nunca añadas una persona, mascota o acompañante que no mencionaron.

El bucle

1. Lee la foto. python3 scripts/photo.py <photo> --swatches swatches.png, luego mírala tú mismo: qué está al fondo, medio, frente; lo único que señalarían; qué se mueve solo y qué se podría tocar; hora del día; clima.
2. Resumen de escena (tus propias notas): encuadernación (side, el panorama en V, para casi todo); capas de atrás a adelante y la pieza del kit para cada una; el toque y el arrastre; el bucle vivo; lo que lleva la noche (lámparas, ventanas, la luna del dial, un faro); la paleta de la estimación de photo.py, elevada y calentada un paso (el libro es papel, no una impresión), podada a las claves que leen las piezas (kit.md sección 3).
3. Inicia la página. node scripts/new.mjs <id> --place "Lugar, Ciudad" --date YYYY-MM-DD --dir <carpeta de su libro> --like <ejemplo más cercano>. El id es corto y en kebab-case (bay-trail, cafe). Rellena pieces y la paleta de escena. Dale a cada pieza que el lector pueda tocar o arrastrar una label, de dos o tres palabras simples ("Velero", "Puerta del café"): la ruta del teclado y los lectores de pantalla la usan.
4. Plegado plano. Cada capa debe quedar plana cuando el libro se cierra. Encuadernación lateral: cada mitad de una capa en el pliegue x0 se dobla a lo largo del lomo, así que x0 + altura * 0.966 <= 0.75 (ancho del libro 1.5, bisagra 105 grados). Las capas del fondo tienen menos espacio: en x0 0.46 una mitad puede medir 0.3, en x0 0.52 solo 0.24. Un dial, un pájaro o una figura en una capa cuenta en su altura. Una capa cerca del lector también se pliega hacia el borde del lector, así que mantén su alcance corto: aproximadamente x0 - alcance * 0.26 >= -0.75. El validador revisa ambos y nombra la mitad y cuánto se extendió. Una mitad vfold-wrap sin nada todavía recibe una tira de unión, así que declara su reach al menos tieReach (0.12), no menos. El dial del cielo está remachado detrás de su capa anfitriona: mantén esa capa baja donde se asienta el dial (una línea de árboles estate toma un dip), o el dial se oculta.
5. Construye y revisa. node scripts/build.mjs <dir>/*.json --out <dir>/book.html --title "<su título>" --author "<su nombre, si lo dieron>", luego node scripts/check.mjs <dir>/book.html --page <id> (las capturas caen en <dir>/shots/<id>/). Imprime los errores del validador, las listas de juego y alive:, y guarda capturas de teléfono y escritorio de día y de noche más card.png. Mira las capturas, noche primero: el brillo, las lámparas y las ventanas solo muestran sus errores de noche. Pon la captura de teléfono de día al lado del ejemplo más cercano (build.mjs examples/<ese>.json y revísala): si la tuya se ve más vacía, no está terminada. Itera aquí, no después de entregarla.
   • ¿No tienes Playwright? El libro también se revisa solo: abre book.html en un navegador. Una página con errores se omite y los errores se imprimen en la página.
6. Pie de foto. Su línea, pulida de dos maneras: primera persona, una oración, palabras simples, unas 10 palabras o menos. La línea del lugar se sitúa justo debajo del pie de foto, así que el pie de foto nunca repite el lugar: di qué pasó o cómo se sintió, no dónde. Haz que las dos opciones sean genuinamente diferentes (una más cercana a sus palabras, la otra más corta). Nunca añadas un hecho, un sentimiento o una persona que no te dieron. Pon la opción 1 en caption y ofrece la opción 2.
7. Entrégalo. Envía book.html (es el libro completo: pueden abrirlo, enviarlo por correo electrónico o alojarlo en cualquier lugar), card.png si hiciste una, y una nota breve:

   <Lugar> · <Mes D>
   En la escena: <una línea, de atrás a adelante>
   Juego: toca <qué>, arrastra <qué>, gira el dial del sol
   Por sí solo: <qué se mueve solo>
   Pie de foto: 1. <opción 1>  2. <opción 2>
   

   Agrega una sola línea solo para algo que deban saber (una fecha supuesta, una foto simple, una nueva pieza del kit).

El equipo

Si tu agente puede delegar trabajo a ayudantes (subagentes), una página que necesita una nueva pieza del kit va más rápido dividida en cuatro. Una página solo con kit es más rápida haciéndola solo: las transferencias cuestan más de lo que ahorran. El Explorador y el Editor solo necesitan las palabras y la foto del remitente, así que ejecútalos al mismo tiempo; el Constructor espera al Explorador, el Revisor al Constructor.

• Explorador: pasos 1 y 2. Obtiene la foto y la línea. Devuelve el resumen de escena, la paleta de escena como fragmento JSON y la única pregunta para el remitente si la hay.
• Constructor: pasos 3 a 5, más la nueva pieza si el resumen la necesita. Obtiene el resumen, la paleta y la foto. Ejecuta la construcción y revisión y arregla lo que muestran. Devuelve el archivo de momento, la salida de check.mjs y la carpeta de capturas.
• Revisor: no construye nada. Obtiene las capturas, la foto o la línea, y las capturas del ejemplo más cercano. Mira la noche primero, el teléfono primero: el estándar (un toque, un arrastre y el bucle vivo), plegado plano, nada recortado en el borde de la página ni oculto detrás de otra capa, y cada pieza está en la foto o la línea. Devuelve "listo" o una lista numerada de correcciones, cada una nombrando la pieza. El Constructor arregla y reconstruye, y el Revisor vuelve a mirar. Después de tres rondas, entrega con lo que aún esté abierto.
• Editor: paso 6. Obtiene la línea, el lugar y la fecha, nunca las capturas. Devuelve las dos opciones de pie de foto.

Tú haces el paso 7 tú mismo. Pon un punto de revisión en la nota solo si quedó abierto.

Una pieza nueva

Cuando el héroe de la foto es algo que el kit no puede hacer (un faro, un carrusel), agrega una pieza en book/kit/ siguiendo la existente más cercana: materiales de papel de book/engine/paper.js, toques y arrastres como lo hacen shop-front (book/kit/cafe.js) y layer-rider (book/kit/panorama2.js), bucles inactivos en tick(t, dt, loops) que se ejecutan solo mientras loops es verdadero. Regístrala en book/kit/index.js con build, about y, para encuadernación lateral, panorama: true y declare. El motor escribe la matriz de cada parte en cada fotograma, así que cualquier cosa que coloques o animes se sienta en un grupo dentro de la parte, nunca en la raíz de la parte. La luz, la oscuridad, el movimiento reducido y el tacto vienen del motor; no los trates como casos especiales. Espera una hora o más; una página solo con kit toma minutos.

Lo que recibe el lector

Un archivo HTML de aproximadamente 1.8 MB: el libro abierto, el pie de foto y lugar debajo, un interruptor Día / Noche (el dial en el libro también lo gira), y flechas y pestañas de fecha cuando hay más de una página. Necesita WebGL y un navegador reciente; no hace solicitudes de red. Arrastre, toque y teclado funcionan (Tab llega a cada pieza jugable, Enter toca, flechas arrastran).

Reglas que no se doblan

• La foto nunca se incluye en el libro ni en la carpeta que devuelves. Sin nombres, edades ni detalles de nadie que el remitente no haya puesto en la línea.
• Cada palabra en el pie de foto y el lugar es de ellos o confirmada por ellos.
• Di lo que no pudiste revisar: los scripts nunca cubren Safari, Firefox, un teléfono real o un lector de pantalla.