codepawl/machine-anatomy

Anatomía de Máquina

Un kit compartido: una máquina nueva solo escribe su modelo, su diseño y dibujo, sus ganchos en vivo y sus hechos. El kit posee la página, los temas y estilos, el marco de zoom, la vista explosionada, el lint de verdad, el grabador, el sonido y las comprobaciones. El ejemplo trabajado es examples/edison-light-bulb/; copia su forma.

1. Pregunta una vez, luego construye

Antes de cualquier código, haz al usuario las preguntas de inicio en una ronda con la herramienta de preguntas del anfitrión (AskUserQuestion en Claude Code), cada una con su valor predeterminado recomendado, omitiendo cualquier cosa que ya hayan dicho. Luego continúa sin más barreras. Preguntas, valores predeterminados y cómo cada respuesta se asigna a la configuración: references/intake.md.

2. Investiga, luego los hechos

Lee fuentes reales (patente, artículos del inventor, página de museo, enciclopedia). Escribe reference/notes.md con URLs y citas, luego facts.json: una entrada por hecho con texto, fuente, cita o nota, y estado (verificado o inferido). Reglas y qué aplica el lint: references/truth-control.md. Enumera cada función de la máquina y su entorno de las fuentes en functions.

Luego recopila al menos 3 fotos o dibujos reales de la máquina y su entorno en reference/images/ con sources.json, y abre cada uno antes de dibujar; cada ensamblaje nombra las imágenes de las que se dibujó. El lint lo aplica y record escribe shots/reference-compare.png para verificarlo contra: references/reference-images.md.

3. Construye la carpeta de la máquina

node cli.mjs new <carpeta> --title "..." crea una estructura a partir del ejemplo Edison. Reemplaza en este orden:

1. model.mjs — modelo puro, sin DOM; todo el comportamiento y cada número mostrado. test-model.mjs lo prueba contra valores reales o invariantes. Las pruebas son obligatorias.
2. layout.mjs — tamaños en unidades del mundo y curvas calculadas (los caminos siguen partes reales, nunca cuerdas).
3. figure.mjs — drawFigure(draw): dibuja las partes reales como elementos de ensamblajes numerados con los ayudantes del kit; devuelve etiqueta, defs, css, anclas de insignias, puntos de paso y el objetivo de zoom.
4. live.js — createMachineHooks(kit): estado, dibujo de partes móviles, controles, lectura, acciones. Usa kit.Motion para resortes, inercia y juntas: references/motion.md.
5. machine.mjs — ensamblajes con ejes de extracción y procedencia, cada texto visible como { texto, hechos }, plantillas de lectura, controles, historia cinematográfica, voces de sonido.

Lee los archivos correspondientes del ejemplo antes de escribir cada uno; no leas archivos *.html compilados.

4. Mira

El tema y el estilo de renderizado son capas independientes: references/themes-and-styles.md. Establece los valores predeterminados en machine.mjs (theme, style); cualquier página los cambia con ?theme= y ?style=.

5. Película y sonido

La película por defecto tiene la forma aprobada de 30 s (funcionando primero, un nacimiento con zoom, una carrera lenta etiquetada, funcionamiento normal con un momento de contraste, desmontaje escalonado, vuelta a armar, terminar funcionando): references/film.md. El sonido son golpes suaves de micrófono cercano, sin pitidos, sin limitador: references/sound.md. Reglas de subtítulos para publicar la película: references/caption.md.

6. Comandos y comprobaciones (todos requeridos antes de entregar)

node cli.mjs lint   <carpeta>     # textos vinculados a hechos, fuentes, superlativos, procedencia
node cli.mjs test   <carpeta>     # pruebas del modelo
node cli.mjs build  <carpeta> [--format 16:9,9:16,square]
node cli.mjs audit  <carpeta>     # orden de pintura de vista explosionada y paso a través
node cli.mjs verify <carpeta>     # página real en Chrome sin cabeza, cada tema y estilo
node scripts/lines.mjs <carpeta>/<slug>-anatomy.html   # las líneas de textura terminan en algo
node cli.mjs record <carpeta> [--format 9:16] [--style dither] [--no-sound]
node cli.mjs remux  <carpeta>     # cambio solo de sonido en los fotogramas grabados
npm test                         # pruebas unitarias del kit

Playwright no está incluido: npm install --no-save playwright, o establece MACHINE_ANATOMY_PLAYWRIGHT en un index.mjs de Playwright existente. La grabación se ejecuta con prioridad normal y sin la GPU.

Luego abre shots/<variante>/video-sheet.png, tres fotogramas, las capturas de pantalla de verificación y shots/reference-compare.png tú mismo; corrige recortes, superposiciones, texto ilegible, patrones flotantes y cada diferencia con las imágenes de referencia que no sea una simplificación declarada.

Reglas que el propietario estableció (aplicadas donde existe una comprobación)

• Nada cubre nada: una comprobación de colisión en record y verify (references/film.md); declara solo superposición físicamente real, con su razón, en film.overlapAllowed.
• Muestra la máquina en su entorno real completo (pregunta de inicio 10), con fuente y procedencia.
• El sujeto ocupa al menos el 25 % de la altura del cuadro en cada fase y los eventos clave ocurren en pantalla (minimum.subject, film.onScreen); una máquina en movimiento ejecuta una cámara con hooks.camera().
• Los patrones permanecen fijados a las superficies y no flotan; mide con scripts/swim.mjs (references/themes-and-styles.md).
• Fuego, vapor, humo y resplandor provienen de kit/effects.mjs, impulsados por el modelo (references/motion.md).
• Cada parte funcional se muestra funcionando o tiene una razón declarada; sin movimiento sin una causa dibujada y activa; el tiempo comprimido se muestra en pantalla (references/completeness-and-causality.md, lint y record).

Informe

Rutas de la página, fragmento de publicación y películas; recuentos de lint, test, audit, verify y lines; sonoridad, pico verdadero y espectro de la película (di que nadie escuchó); la línea de tiempo de la película; cada hecho de subtítulo con su fuente; lo que está simplificado, inferido o no verificado.

Crédito: construido sobre Anatomy de Ryan (github.com/wheresryan22/anatomy, MIT). Consulta THIRD_PARTY_NOTICES.md.