Anatomy Three.js — Figuras Técnicas 3D Interactivas

¿Qué hace Anatomy Three.js — Figuras Técnicas 3D Interactivas?

Construye ilustraciones técnicas 3D isométricas interactivas en Three.js + GLSL. Cada figura explica una idea técnica como un instrumento físico de banco o un modelo seccionado que podrías colocar sobre un escritorio: una placa base biselada y pesada sobre pies torneados, carcasas y eslabones auténticos del dominio, un rotor interno principal o sujeto móvil, controles e instrumentos 3D directamente arrastrables construidos específicamente para esa máquina, y un shader GLSL personalizado restringido estrictamente al medio físico (fuego, plasma, fluido, corriente descendente, haz) dentro de la máquina.

En lugar de escribir un archivo HTML monolítico de 1.500 líneas y adivinar las coordenadas 3D en tu cabeza, primero te alineas con el usuario sobre el aparato y las interacciones (Etapa 0), luego construyes cada figura en seis etapas aisladas dentro de figures/<slug>/, respaldado por el motor inmutable kit/ y verificado en cada paso por un sistema de verificación 3D Espacial + Ortofotográfico de dos niveles.

---

Estructura de Directorios

anatomy-threejs/
├── SKILL.md                    # Brief Etapa 0 + flujo de trabajo de 6 etapas y punto de entrada del agente
├── kit/                        # MOTOR INMUTABLE — importar desde aquí; nunca editar por figura
│   ├── shaders.mjs             # 5 temas, shader cel de 4 tonos + tapa superior, casco invertido, pliegues
│   ├── primitives.mjs          # Losas, cilindros, engranajes, tornillos, moleteados, marcas
│   ├── registry.mjs            # Recorder3D: .group(), .part(), .anchor(), .tube(), .interactable(), .tag()
│   ├── audit3d.mjs             # Auditoría espacial 3D sin cabeza Node (colisiones, flotación, orificios, tubos)
│   ├── runtime.mjs             # Sistema ortofotográfico, arrastre 3D por raycast, controles personalizados, resortes, __ANATOMY_DEBUG__
│   ├── bundle.mjs              # Compila los módulos de la figura en un único archivo HTML autónomo
│   └── shell.html              # Marco de tarjeta responsiva, variables CSS de 5 temas, controles conscientes de características
├── scripts/
│   ├── inspect.mjs             # Chrome sin cabeza (CDP) superposición ortofotográfica 2x2 y de uniones
│   ├── drive.mjs               # Hoja de contactos interactiva + imágenes principales + verificación móvil 390px
│   └── chrome-port.mjs         # WebSocket sin dependencias + combinador de PNG para Chrome sin cabeza
├── references/
│   ├── craft-3d.md             # Sistema de coordenadas 3D, jerarquía de tonos, controles a medida, anti-patrones
│   ├── kit-3d.md               # Referencia de API para Recorder3D, primitivas, shaders y runtime
│   └── verify-3d.md            # Cómo interpretar y corregir [COLISIÓN], [FLOTANTE], [TUBO DOBLADO] y vistas ortofotográficas
└── figures/
    └── <slug>/                 # Tu espacio de trabajo para una figura (ej. figures/wankel-engine/)
        ├── model.mjs           # Etapa 1: Matemáticas puras, dimensiones, SPEC.features, SPEC.controls, anclajes
        ├── base.mjs            # Etapa 2: Placa base, pies, halo, regla, placa de latón
        ├── structure.mjs       # Etapa 3: Pedestales, marco/carcasa, puertos, sujetadores
        ├── subject.mjs         # Etapa 4: Conjunto móvil principal (rotor, palas, sellos, engranajes)
        ├── mechanism.mjs       # Etapa 5: Controles a medida, instrumentos, interactivos 3D, tubos, updateKinematics()
        ├── shader.mjs          # Etapa 6: Shader GLSL personalizado confinado al medio físico activo
        ├── build.mjs           # Punto de entrada CLI: --test-model, --audit y paquete HTML completo
        └── dist/
            └── <slug>.html     # Figura interactiva autónoma compilada

Regla 1 — Nunca reescribir kit/: La cámara Three.js, los shaders cel, el manejador de arrastre por raycast, el solucionador de resortes, el marco DOM y el sistema de depuración viven en kit/. Tus archivos de figura solo definen matemáticas de dominio, piezas 3D, cinemática, interactivos y el shader de medio personalizado.

Regla 2 — Leer las referencias antes de escribir geometría:

• Lee references/craft-3d.md antes de la Etapa 0/1 para diseñar el soporte físico, los controles a medida, los indicadores de características, la jerarquía de tonos y el marco de coordenadas 3D.
• Lee references/kit-3d.md antes de la Etapa 2 para las firmas exactas de Recorder3D y kit/primitives.mjs.
• Lee references/verify-3d.md cuando --audit, inspect.mjs o drive.mjs informen un problema.

---

Etapa 0 — Brief del Aparato y la Interacción (Alinear Antes de Construir)

Antes de crear archivos o escribir código de la Etapa 1, propón un Brief del Aparato y la Interacción conciso al usuario y alinéense sobre lo que hace la máquina y cómo el lector interactúa con ella (omite la espera solo si el usuario dice explícitamente que construyas inmediatamente sin preguntas):

1. Aparato de Banco y Sujeto Principal: Nombra el mecanismo físico y qué ensamblaje único lleva el acento lit.
2. Manipulación 3D Directa (reg.interactable): Identifica qué ensamblajes 3D o controles el lector puede agarrar y arrastrar directamente en el viewport (ej., arrastrar una placa oscilante para inclinarla/elevarla y ver cómo las palas del rotor se inclinan, deslizar un carro vernier, tirar de una palanca de enlace), incluso mientras la rotación/simulación está en pausa.
3. Controles y Telemetría Auténticos del Dominio (SPEC.controls): Elige hardware de banco y deslizadores de barra de control que pertenezcan a esta máquina (ej., palma cíclica de 2 ejes, palanca de paso colectivo, arco de transportador, tambor micrométrico, escala vernier, tubo manométrico). Nunca copies la perilla rotativa, el manómetro Bourdon o la caja hidráulica de otra figura a menos que el sujeto use genuinamente ese instrumento exacto.
4. Modos de Vista (SPEC.features): Decide explícitamente qué modos opcionales merecen su lugar:
   • explode: Habilitar (true) solo para máquinas concéntricas cerradas con capas axiales apiladas (ej., motores, cajas de cambios, bombas). Establecer explode: false para enlaces mecánicos abiertos, platos oscilantes, bancos ópticos o soportes de superficie donde separar las piezas rompe la geometría del enlace y agrega desorden.
   • cutaway: Habilitar (true) cuando una carcasa exterior oculta las piezas internas móviles; establecer false para mecanismos de marco abierto.
   • shader: Habilitar (true) cuando un medio físico confinado (gas de combustión, estela del rotor, haz, flujo de fluido) aclara el mecanismo.

Puerta de la Etapa 0: El usuario confirma o refina el brief (o instruye explícitamente una construcción inmediata no interactiva).

---

El Flujo de Trabajo de Seis Etapas

Ejecuta estas etapas en orden. Cada etapa termina con una Puerta de Verificación: ejecuta el comando, corrige cualquier error e inspecciona visualmente el PNG renderizado con tu herramienta de lectura de archivos antes de pasar a la siguiente etapa.

Etapa 1 — Modelo y Cinemática (model.mjs + build.mjs)

Traduce el brief acordado a un módulo matemático puramente físico antes de tocar Three.js:

1. Codifica la Metáfora Física en figures/<slug>/model.mjs:
   • SPEC.features: { explode: boolean, cutaway: boolean, shader: boolean, crank: boolean } coincidiendo con la Etapa 0.
   • SPEC.interactionHint: Breve pista mostrada en la esquina inferior izquierda que indica al usuario qué piezas 3D puede arrastrar directamente (ej., "Arrastra plato oscilante, palo o palanca de colectivo").
   • SPEC.controls: Array de controles deslizantes específicos del dominio ({ id, label, min, max, step, initial, title }). runtime.mjs los renderiza en la barra de control, los suaviza con resortes y los pasa a updateKinematics y formatReadout.
   • SPEC.auditPoses y SPEC.drivePoses: Poses representativas del dominio (ángulos de control extremos, manipulación en pausa, verificaciones de corte/tema) utilizadas por --audit y scripts/drive.mjs. Omitir poses explosionadas cuando features.explode === false.
   • SPEC: Todas las dimensiones críticas (BASE_W, BASE_D, BASE_H, BASE_Y, topSurfaceY, isoElevDeg: 30, isoAzimDeg: -36, initialZoom, initialPanY, minVertSpan, minHorizSpan).
   • ANCHORS: Coordenadas de montaje [x, y, z] nombradas en la placa base (plaqueCenter, rulerCenter, y los anclajes de control/instrumento a medida de tu figura). Recuerda que en isométrica canónica (30° elev, -36° azim), el borde +Z es el frente delantal y las esquinas frontales despejadas son -X, +Z / +X, +Z.
   • Funciones de estado puro y cinemática (sin importaciones de Three.js) impulsadas por theta y los params activos de SPEC.controls.
   • formatReadout({ theta, effectiveRpm, params }) que devuelve cadenas { readout, phase } para la barra de telemetría.
2. Crea el andamio figures/<slug>/build.mjs (referencia figures/wankel-engine/build.mjs o figures/helicopter-swashplate/build.mjs) y ajusta título, subtítulo, lectura inicial y leyenda.

Puerta de la Etapa 1:

node figures/<slug>/build.mjs --test-model

Criterio de aprobación: Sale con 0 con todos los anclajes finitos y el estado/lectura verificados en un ciclo completo de $0 \dots 6\pi$.

---

Etapa 2 — La Base (base.mjs)

Construye la placa base de datos pesada que fundamenta todo el instrumento:

1. Crea base.group (stage: "base").
2. Añade la sombra suave del suelo (makeHaloMesh) en BASE_Y - 0.24.
3. Añade base.plate usando buildSlabGeometry(BASE_W, BASE_D, BASE_H, { radius: 0.26, bevel: true, bevelSize: 0.025, bevelThickness: 0.025 }) con ramp: "lo", mountOn: "ground". Nota que topSurfaceY = BASE_Y + BASE_H + 0.025 tiene en cuenta el grosor del bisel superior para que las piezas montadas en topSurfaceY queden al ras de la cara superior sin hundirse.
4. Registra todos los anclajes de montaje de la placa base mediante reg.anchor(id, x, y, z, baseGroup) para que las Etapas 3 y 5 encajen directamente en base.plate.
5. Añade ranuras perimetrales empotradas (makePlanOutline), 4 pies de esquina torneados (base.foot.collar.i + base.foot.pad.i) con tornillos avellanados superiores (makeScrewDetail), una escala graduada (base.ruler + makeRulerTicks), y una placa de especificaciones de brass remachada (base.plaque) en el delantal delantero visible (+Z) con una etiqueta grabada (reg.tag("tag-plate", ...)).

Puerta de la Etapa 2:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base --ortho --out figures/<slug>/dist/inspect-base.png

Lee inspect-base.png para verificar que los pies se asienten limpiamente debajo de la placa base y que la placa de latón + regla estén sin obstrucciones en el delantal frontal.

---

Etapa 3 — La Estructura (structure.mjs)

Construye los soportes estacionarios de carga, el marco principal o la carcasa seccionada, los puertos/manifolds y los sujetadores:

1. Monta pedestales de soporte o cajas de engranajes sobre base.plate con bases con bridas, detalles de pernos, columnas cónicas y asientos de cojinetes.
2. Construye la carcasa o marco principal (ramp: "mid", outline: "hi"). Deja el frente (+Z) abierto o equipado con una cubierta seccionada (cutawayHide: true) para que los mecanismos internos permanezcan completamente visibles desde la cámara isométrica canónica cuando features.cutaway esté habilitado.
3. Añade puertos auténticos del dominio, carcasas de actuadores o soportes estacionarios que apunten hacia afuera limpiamente. Registra anclajes de puerto/terminal 3D con sus normales de puerto locales hacia afuera (reg.anchor("plug.leading.tip", 0, 0.68, 0, spGroup, { dir: [0, 1, 0] })) dentro de cada subgrupo local para que los tubos de la Etapa 5 encajen en sus posiciones mundiales exactas y entren/salgan coaxialmente.
4. Establece vectores explode: [ex, ey, ez] en subgrupos removibles solo cuando SPEC.features.explode es true y el aparato tiene capas concéntricas cerradas destinadas a separarse axialmente.

Puerta de la Etapa 3:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure --ortho --out figures/<slug>/dist/inspect-structure.png

Lee inspect-structure.png (TOP, FRONT, RIGHT, CANONICAL ISO): verifica que los puertos apunten hacia afuera, los pedestales toquen tanto la placa base como la carcasa sin recortes y que nada flote.

---

Etapa 4 — El Sujeto (subject.mjs)

Construye el ensamblaje interno principal que capta el enfoque visual:

1. Asigna ramp: "hi" al cuerpo móvil principal (ej., cuerpo del rotor, horquilla del cubo), ramp: "lit" a los elementos de trabajo activos (rotor.apexSeal.i, blade.airfoil.*), y ramp: "brass" a engranajes de precisión y pivotes.
2. Crea grupos cinemáticos anidados (orbit -> spin, o azimuth -> flap -> pitch) para que el movimiento jerárquico se componga limpiamente sin bloqueo de giroscopio de Euler.
3. Pasa insideBoreOf y boreClearanceFn en piezas que se mueven dentro de un orificio para que audit3d.mjs verifique matemáticamente la penetración de pared cero en cada pose auditada.
4. Añade bolsillos mecanizados, ranuras en la cara, costuras de larguero o patrones de pernos para que el movimiento sea inconfundible.

Puerta de la Etapa 4:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate subject --ortho --out figures/<slug>/dist/inspect-subject.png

Lee inspect-subject.png para confirmar que la silueta, los biseles y las uniones del sujeto se lean claramente desde todos los ángulos.

---

Etapa 5 — Mecanismo, Controles a Medida e Interacción 3D Directa (mechanism.mjs)

Conecta el sujeto con controles de operador auténticos del dominio, instrumentos de telemetría, interacción de arrastre 3D directa y enrutamiento:

1. Construye controles auténticos del dominio en sus ANCHORS de la Etapa 0/1 (por ejemplo: una palma cíclica de 2 ejes tipo gimbal, una palanca de paso colectivo con muescas, un husillo vernier, o un tambor de acelerador moleteado). Nunca copies la perilla moleteada o el bloque manifold de otra figura cuando la máquina requiera su propio hardware de control.
2. Construye telemetría auténtica del dominio (por ejemplo: un arco transportador de paso de pala curvo, escala de viaje lineal, columna manométrica o indicador de cuadrante) posicionada hacia adelante en +Z o fuera de la silueta principal en CANONICAL ISO.
3. Registra la manipulación 3D directa con reg.interactable(targetId, { cursor, hint, onDrag }) en el mecanismo principal y/o palancas físicas para que el usuario pueda arrastrar piezas 3D directamente en el viewport mediante setParam(...), incluso cuando la rotación esté en pausa (RPM = 0 o PAUSED).
4. Enruta todas las tuberías y cables usando reg.tube(id, fromAnchorId, waypoints, toAnchorId, opts):
   • Consulta reg.getAnchorWorldPos(anchorId) y reg.getAnchorWorldDir(anchorId) para construir waypoints de arco 3D suaves (length / chord >= 1.12) que barren limpiamente alrededor de las piezas adyacentes y entran coaxialmente a lo largo de la normal de salida de cada puerto.
5. Construye la transmisión y los enlaces articulados. Pasa cutawayHide: true en las cubiertas de la carcasa delantera o las protecciones que ocultan el mecanismo interno de la vista.

Puerta de la Etapa 5:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate mechanism --ortho --out figures/<slug>/dist/inspect-mechanism.png
node scripts/drive.mjs figures/<slug>/dist/<slug>.html --interactive

Lee inspect-mechanism.png para verificar que los controles estén montados limpiamente en el delantal, los tubos entren coaxialmente a los puertos y los interactivos 3D respondan en el rango esperado --interactive.

---

Etapa 6 — Shader de Medio (shader.mjs)

Implementa un shader GLSL personalizado confinado exclusivamente al medio físico activo:

1. Habilita features.shader: true en SPEC.features.
2. Exporta vertexShader y fragmentShader desde figures/<slug>/shader.mjs. Solo se ejecuta en la geometría etiquetada con reg.shaderGroup(...).
3. El shader debe aclarar visualmente el mecanismo en lugar de decorar; por ejemplo, gas de combustión dentro de una cámara de rotor, estela de flujo de aire detrás de un rotor de helicóptero, un haz láser dentro de un sistema de guía, o fluido hidráulico presurizado a través de una tubería transparente.
4. Pasa las variables uniformes a través de runtime.mjs: tiempos, intensidad del shader, ángulo de la cámara, parámetros de control activos. Apoya el modo cutaway para que el medio no se renderice a través de carcasas opacas.

Puerta de la Etapa 6:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --ortho --out figures/<slug>/dist/inspect-final.png
node scripts/drive.mjs figures/<slug>/dist/<slug>.html

Se ejecuta la verificación de la hoja de contactos de scripts/drive.mjs en todos los temas y vistas, incluida la verificación móvil de 390 px. Inspecciona manualmente los fotogramas de la hoja de contactos para confirmar que el medio se vea físico y contenido, no decorativo.

---

Flujo de Trabajo del Agente

Cuando se te solicite construir una "figura Three.js isométrica", una "figura de estilo Linear/Anatomy" o un "diagrama técnico 3D interactivo", sigue este flujo en bucle:

flowchart TD
    A[Solicitud del usuario] --> B[Etapa 0: Proponer Brief del Aparato y la Interacción]
    B --> C[Usuario alineado/confirmado]
    C --> D[Etapa 1: Modelo y Cinemática --- modelo.mjs]
    D --> E{Puerta 1: --test-model}
    E -->|Fallo| D
    E -->|Éxito| F[Etapa 2: Base --- base.mjs]
    F --> G{Puerta 2: --audit + inspect}
    G -->|Fallo| F
    G -->|Éxito| H[Etapa 3: Estructura --- structure.mjs]
    H --> I{Puerta 3: --audit + inspect}
    I -->|Fallo| H
    I -->|Éxito| J[Etapa 4: Sujeto --- subject.mjs]
    J --> K{Puerta 4: --audit + inspect}
    K -->|Fallo| J
    K -->|Éxito| L[Etapa 5: Mecanismo --- mechanism.mjs]
    L --> M{Puerta 5: --audit + inspect + drive --interactive}
    M -->|Fallo| L
    M -->|Éxito| N[Etapa 6: Shader de Medio --- shader.mjs]
    N --> O{Puerta 6: --audit + inspect + drive}
    O -->|Fallo| N
    O -->|Éxito| P[Figura terminada: figures/<slug>/dist/<slug>.html]

---

Cómo Interpretar el Reporte de Auditoría

node figures/<slug>/build.mjs --audit ejecuta audit3d.mjs e imprime:

[AUDIT] Check: figures/wankel-engine
  ✅ No collisions detected
  ❌ COLLISION: rotor.housing shell@pose2 penetrates rotor.apexSeal.0 by 0.042mm
  💡 Fix: increase boreClearanceFn threshold or move housing shell by -dz 0.015
  ✅ Anchors are finite
  ❌ FLOATING: base.foot3 at y=-0.012 (bedplate is y=0)
  💡 Fix: set base.foot3 y=0 or adjust base.plate Y offset
  ✅ Vehicle spans are within bounds
  ❌ TUBE KINK: tube.fuelLine waypoint 3 angle=167° (>160°)
  💡 Fix: add an intermediate waypoint or spread waypoints 4-5

Corrige cada error en su archivo de etapa antes de volver a ejecutar. Lee siempre references/verify-3d.md si no estás seguro de la interpretación.

---

Buenas Prácticas

• Mantén la placa base en el suelo con la cara superior en topSurfaceY: Todos los pedestales, carcasas y soportes se montan en topSurfaceY. Las piezas que se hunden por debajo de topSurfaceY - 0.01 activarán [FLOATING] o [COLLISION].
• Usa herramientas de referencia: Siempre consulta references/craft-3d.md para el diseño de la maquinaria, references/kit-3d.md para las API del motor y references/verify-3d.md para los detalles de auditoría.
• No copies controles: Los controles a medida e instrumentos deben ser auténticos para esta máquina, no prestados de otras figuras.
• Verifica temprano, verifica a menudo: Cada puerta de etapa atrapa errores de coordenadas que se volverían imposibles de depurar después de seis etapas de geometría apilada.