Grafos 2D y 3D: el cerebro compartido de markeup-graphs

La skill markeup-graphs —«Toca los grafos 2D y 3D sin romper su cerebro compartido»— es una de las habilidades que el sistema MarkeUP tiene escritas para Hermes Agent y para Cline. Esta página es su ficha pública: lo que sabe hacer, cuándo se usa y qué comandos ejecuta.

Los dos mapas de notas se miran con los mismos ojos: la skill cuida que se comporten igual y que ninguno rompa el encuadre.

El texto de la sección «Instrucciones del canon» está transcrito del fichero fuente —que se escribe sin tildes por convención de su propio gate—, así que es exactamente lo que lee el agente cuando le pides algo. La cabecera y esta entradilla sí están redactadas para leerlas.

Dato	Valor
Skill	`markeup-graphs`
Responsabilidad	Toca los grafos 2D y 3D sin romper su cerebro compartido.
Versión	1.0.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	grafos · d3 · force-graph · three · consultas · markeup
Skills relacionadas	markeup-context · markeup-cli · markeup-motion
Fuente	`~/.hermes/skills/markeup/markeup-graphs/SKILL.md`

Responsabilidad unica: los dos grafos del sitio (/Grafo2D con canvas + d3, /Grafo3D con Three.js) y el cerebro que comparten.

Detalle y trampas medidas: docs/graphs-architecture.md · contrato: references/graph-contract.md.

Se anade una ruta de grafo (de vault o de seccion).
Un filtro, una vista o una consulta (tag:, path:, type:, -excluir, OR) no se comporta igual en el 2D y en el 3D.
El encuadre automatico, el Reset o el arrastre fallan.
npm run verify:graphs o npm run validate:graph en rojo.

Que se ve se decide en src/lib/graph-state.ts, no en el renderizador. Si una condicion acaba en Graph2D.astro o en ForceGraph3D.astro, el otro grafo se queda atras: cada mejora habria que escribirla dos veces y las dos vistas divergirian.

Capa	Donde
Estado (vistas, consulta, foco + profundidad, etiquetas, fuerzas)	`src/lib/graph-state.ts` → `visibleGraph(data, state)`
Vecindad del resaltado (compartida)	`src/lib/graph-hover.ts`
Datos del vault (nodos `post`/`category`/`tag`; enlaces `wikilink`/`categoria`/`tag`)	`src/lib/graph.ts`
Geometria y estilos puros (radios, grosores, flechas, curvas, encuadre)	`src/lib/graph-render.ts`
2D (canvas + `force-graph`)	`src/components/graph/Graph2D.astro`
3D (`3d-force-graph` + Three.js)	`src/components/graph/ForceGraph3D.astro`

Ruta	Grafo
`/Grafo2D`, `/Grafo3D`	Vault completo (acceso explicito)
`/category/<Categoria>/Grafo2D`, `/category/<Categoria>/Grafo3D`	Solo esa seccion

Las rutas antiguas (/graph-2d, /graphify, /graph y las de seccion) redirigen 301 desde public/_redirects. Cloudflare Pages distingue mayusculas: la forma canonica es la capitalizada (/Grafo2D), no /grafo2d.

La vista por defecto es notas (posts + wikilinks, sin tags): los tags son el 75% de los nodos y ahogaban la estructura. El estado va en la URL (?v=…&q=…&f=…&d=…), asi que una vista se enlaza y se comparte; parseGraphState ignora lo que no entiende (una URL no puede romper el grafo).

cd ~/markeup
npm run validate:graph     # contrato de los DATOS: ids unicos, extremos que existen,
                           # numeros finitos (corre DENTRO de npm run build)
npm run verify:graphs      # GATE en navegador: render, errores de pagina, guardas de
                           # reduce, encuadre, Reset, vistas, URL y etiquetas del 3D
npm run test               # graph-state.test.ts · graph-render.test.ts · graph.test.ts...

verify:graphs necesita Chrome y no esta en el CI bloqueante: es el gate que hay que lanzar despues de tocar grafos, como verify:motion tras tocar animacion.

Nunca pintar sin coordenadas finitas. En el primer frame la simulacion aun no ha asignado x/y: un createRadialGradient(NaN) lanza y deja el lienzo en blanco. Comprobar Number.isFinite(n.x) antes de pintar y tambien en el encuadre.
Nada de metodos de d3 sobre el elemento suelto: d3.select(canvas).dispatch('zoom', …), nunca canvas.dispatch('zoom', …). El TypeError de un manejador asincrono pasa desapercibido y rompio el encuadre automatico y el Reset del 2D hasta el 2026-09-25.
force-graph (2D) no tiene d3AlphaTarget (eso es la version 3D): para recalcular la simulacion se usa d3ReheatSimulation().
El encuadre no se pide justo despues de graphData(...) (los nodos no tienen posiciones): lo hace onEngineStop.
Etiquetas del 3D: se encienden y apagan mutando sprite.visible; cambiar nodeThreeObject reconstruiria los ~425 sprites en cada hover.
Filtrar no recoloca el mapa: un nodo que ya estaba en pantalla conserva su posicion (nodeIdx), asi que buscar o cambiar de vista no desordena el grafo.
El bucle del 2D no puede morir: el requestAnimationFrame va fuera del try/catch y un error se avisa una vez (antes, una excepcion dejaba el lienzo congelado en silencio).
Arrastrar trae la vecindad (PESO_VECINO 0,85 / 0,45, hubs excluidos). El translate de onNodeDrag es el delta de ese evento (hay que medir desde la posicion inicial) y el motor no distingue clic de arrastre: el clic se ignora 250 ms despues de soltar.

Cambia el estado en graph-state.ts; el renderizador solo pinta lo que le dan.
Toda vista se enlaza: si el estado no cabe en la URL, la vista se pierde al recargar.
Una ruta de grafo nueva se deriva de las paginas existentes (seccion = getAllCategories()): no se hardcodea una lista de secciones.
Despues de tocar grafos: npm run validate:graph y npm run verify:graphs.
No anadir un motor de grafos nuevo: 2D y 3D comparten vocabulario (nodeCanvasObject / nodeThreeObject, d3Force, cooldownTicks, autoPauseRedraw, onEngineStop, zoomToFit).

references/graph-contract.md — estado, parametros de URL, vistas y checklist de verificación.
markeup-context — mapa de rutas del sitio.
Codigo: src/lib/graph-*.ts, src/components/graph/.

¿Quieres saber cómo se piden estas cosas? La guía completa está en skills de Hermes Agent, con la chuleta de objetivos y los casos paso a paso.

Grafos 2D y 3D

Grafos 2D y 3D: el cerebro compartido de markeup-graphs

Posts que enlazan a este artículo