shenwuyue841/obsidian-excalidraw

Constructor de Lienzos Excalidraw para Obsidian

Genera archivos .excalidraw.md que se abren correctamente en el plugin Obsidian Excalidraw, incluyendo bloques LaTeX escritos a mano, flechas enlazadas y colores con corrección temática.

Cuándo usarlo

• Construir un mapa de conocimiento / árbol de decisión / pizarra de fórmulas como un lienzo Excalidraw en una bóveda.
• Convertir un esquema o nota en Markdown en un lienzo visual.
• Arreglar un lienzo que se renderiza con imágenes rotas, texto invisible, fórmulas enormes o un fondo blanco/oscuro inesperado.
• Hacer coincidir un lienzo nuevo con el lenguaje visual de un lienzo existente en la misma bóveda.

NO usar para archivos .excalidraw JSON independientes para la aplicación web, ni para renderizar PNG/SVG — consulta references/when-not-to-use.md si esa distinción importa.

Reglas de oro (aprendidas con esfuerzo)

1. LaTeX no es texto. Las fórmulas son elementos de tipo "image" cuya fuente vive en la sección ## Embedded Files como <40-hex-id>: $$tex$$. Un elemento imagen sin una entrada correspondiente en Embedded Files se renderiza como imagen rota. Consulta references/latex.md.
2. Nunca escribas $$...$$ dentro de un elemento de texto para este plugin — muestra la fuente sin procesar. El plugin solo renderiza ecuaciones que existen en Embedded Files.
3. El tema de la escena no es autoritario. El plugin sobrescribe appState.theme con el tema de la aplicación. Por lo tanto, el color del lienzo proviene de viewBackgroundColor, pero un tema claro lo pinta de blanco independientemente. Consulta references/theme-and-color.md.
4. Copia la paleta de un lienzo existente en la misma bóveda antes de inventar colores. Descomprime uno con scripts/inspect_canvas.mjs, lee sus colores de trazo y familia de fuente, y reutilízalos.
5. Altura uniforme de fórmulas, ancho basado en longitud. Un ancho fijo grande estira fórmulas cortas convirtiéndolas en gigantes. Consulta references/layout.md.
6. El plugin guarda de nuevo como compressed-json (LZString base64, envuelto cada ~120 caracteres). Regenera el lienzo desde tu script generador en lugar de parchear el archivo guardado. Leerlo requiere descompresión — scripts/inspect_canvas.mjs lo hace.
7. Verifica antes de afirmar éxito. Ejecuta el script de inspección y comprueba: el número de ecuaciones es igual al número de imágenes, no hay enlaces colgantes, el tema/fondo es el deseado.
8. "Se ve bien" es medible. Relación de contenedor ≤ 30%, ≤ 4 tamaños de fuente, varianza de altura de fórmulas 0, número de solapamientos 0. scripts/inspect_canvas.mjs ahora imprime estas como "advertencias estéticas"; trata cualquier advertencia como un defecto, no una preferencia. Consulta references/design-metrics.md.
9. Escribe una vez, con ids estables, eliminando primero. Los ids de los elementos deben derivarse del contenido (hash del texto / TeX / etiqueta), nunca aleatorios. Y desvincula el archivo destino antes de escribirlo. Sin ambos, regenerar un lienzo que está abierto en Obsidian fusiona los nuevos elementos en la escena activa: todo se duplica, y el plugin autoguarda la escena duplicada de vuelta al disco. Consulta references/troubleshooting.md → "Elementos se duplican / triplican".
10. Renderiza antes de entregar. scripts/render_preview.mjs rasteriza el archivo sin interfaz gráfica (Node, sin navegador). Mira el PNG — las auditorías JSON detectan estructura, solo los píxeles detectan "el espaciado se ve mal". LaTeX sale en blanco en esa vista previa (MathJax vive en el plugin de Obsidian, no en el renderizador), así que juzga el diseño allí y la corrección de las fórmulas desde ## Embedded Files.
11. Solo una capa de $$. El TeX en el modelo de datos está desnudo (A=\int…); los delimitadores solo se añaden al emitir la línea ## Embedded Files. Cualquier $$$ en un archivo generado es un error de doble envoltura que renderiza signos de dólar literales.

Dos escuelas de diseño — elige una antes de dibujar

	Cuadrícula de columnas (表格派)	Líneas como estructura (结构派)
Forma	cajas de columna + divisores de fila	línea troncal + líneas de bajada + texto flotante
Relación de contenedor	alta (una caja por columna)	cerca de 0
Se lee como	una tabla de consulta, riguroso	pizarrón de clases, ligero
Mejor para	muchas filas del mismo nivel que revisas celda por celda	ramificación, o columnas que se derivan entre sí
Modo de fallo	"parece una plantilla de diapositivas"	demasiadas ramas → líneas que se cruzan

Regla general: columnas hermanas → cuadrícula de columnas; una columna derivada de las otras → líneas de estructura. Ambos ejemplos existen en design-metrics.md con contenido idéntico (el lienzo 第十讲), así que puedes comparar antes de elegir.

Flujo de trabajo

1. Lee las convenciones de la bóveda destino. Encuentra un .excalidraw.md existente que al usuario le guste, ejecuta node scripts/inspect_canvas.mjs <archivo> y anota: tema, viewBackgroundColor, colores de trazo dominantes, fontFamily, roughness, tamaños de fuente típicos.
2. Diseña el contenido como columnas o filas (consulta references/layout.md) — una columna por familia de cantidad/paso, una fila por fórmula, y agrupa solo cosas que son realmente la misma cantidad. Elige la escuela de diseño (cuadrícula de columnas vs líneas de estructura) según la tabla anterior.
3. Escribe un script generador modelado a partir de scripts/gen_canvas.mjs: edita su bloque CONFIG (título, columnas, filas) y ejecútalo. No edites manualmente el JSON de 30 kB. Mantén los dos mecanismos de seguridad con los que viene: ids derivados del contenido y rmSync antes de writeFileSync.
4. Inspecciona el resultado con scripts/inspect_canvas.mjs, corrige conteos/colores/enlaces. También verifica que no haya $$$ en el archivo y que el número de elementos coincida con lo que imprimió el generador (un múltiplo significa que ocurrió el error de fusión). Luego renderízalo con scripts/render_preview.mjs y mira realmente el PNG; corrige espaciado/solapamiento/líneas cortas antes de informar.
5. Informa qué debe hacer el usuario en Obsidian (cerrar y reabrir el archivo, o usar el comando "Descomprimir archivo Excalidraw actual") — el plugin solo relee un archivo cuando se vuelve a abrir.

Mapa de referencias

Archivo	Contenido
references/file-format.md	Esqueleto exacto de .excalidraw.md, ambas codificaciones, orden de secciones, comentario de cabecera
references/element-schema.md	Campos requeridos por tipo de elemento, texto enlazado, enlaces de flecha, ordenamiento index
references/latex.md	Contrato de Embedded Files, \color, dimensionamiento, las tres variantes de renderizado probadas, firmas de fallo
references/theme-and-color.md	Por qué los lienzos se abren en blanco, matchThemeAlways, extracción de paleta, colores establecidos de esta bóveda
references/layout.md	Geometría de columnas/filas, heurísticas de dimensionamiento de fórmulas, qué hace que un lienzo se vea inacabado
references/script-engine.md	El motor de scripts JS dentro del plugin: dónde poner los scripts, qué pueden hacer, API ExcalidrawAutomate, si se pueden hacer tablas, compensaciones frente a generación a nivel de archivo
references/design-metrics.md	Estética cuantificada: relación de contenedor, conteo de niveles de fuente, varianza de fórmulas, espacios en blanco, color semántico; dos escuelas de diseño; cómo validar sin un renderizador
references/troubleshooting.md	Tabla de síntoma → causa → arreglo para cada fallo visto hasta ahora
scripts/gen_canvas.mjs	Generador de lienzos impulsado por configuración (texto, látex, rect, hline, arrow)
scripts/inspect_canvas.mjs	Descomprimir + auditar: tema, conteos, coincidencia ecuación/imagen, enlaces, fuentes, métricas estéticas. --describe imprime un inventario compacto de id/posición/etiqueta/conexión; --dump imprime el JSON de la escena sin procesar
scripts/render_preview.mjs	Vista previa PNG sin interfaz gráfica mediante mcp-excalidraw-server render (sin navegador). LaTeX se renderiza en blanco — solo diseño
evals/evals.json	Prompts de regresión: uno por modo de fallo que realmente ha ocurrido
examples/ea-table.md	Un script ejecutable dentro de la aplicación que construye una tabla a partir de rectángulos + texto

Edición de un lienzo existente

1. Descomprímelo para entender el estado actual (inspect_canvas.mjs --dump <archivo> imprime el JSON de la escena).
2. Prefiere regenerarlo a partir del script generador. Si el usuario ha hecho ediciones manuales que vale la pena conservar, escribe una transformación acotada (leer escena → mutar elementos específicos → reserializar sin comprimir) en lugar de reescribir todo el lienzo.
3. Nunca dejes un lienzo a medio migrar: o cada imagen tiene su ecuación, o ninguna.

Valores predeterminados de tamaño y tipografía para esta bóveda

• Texto del cuerpo fontFamily: 6, roughness: 0, strokeWidth: 1.
• Título 28–30 px, encabezado de columna 19–22 px, etiqueta de fila 15–16 px, altura de imagen de fórmula 50–52 px.
• Espaciado entre filas 116–130 px; ancho de columna 320–340 px; espacio 28–40 px.
• Fondo del lienzo #ffffff; tinta #1e1e1e; apagado #868e96; línea fina #e9ecef.