shenwuyue841/obsidian-excalidraw

Construtor de Canvas Excalidraw para Obsidian

Gera arquivos .excalidraw.md que abrem corretamente no plugin Excalidraw do Obsidian, incluindo blocos LaTeX escritos à mão, setas vinculadas e cores ajustadas ao tema.

Quando usar

• Construir um mapa de conhecimento / árvore de decisão / quadro de fórmulas como um canvas Excalidraw em um cofre
• Converter um esboço ou nota em Markdown em um canvas visual
• Corrigir um canvas que renderiza com imagens quebradas, texto invisível, fórmulas enormes ou um fundo branco/escuro inesperado
• Alinhar um novo canvas à linguagem visual de um canvas existente no mesmo cofre

NÃO use para JSON .excalidraw autônomo entregue ao aplicativo web, ou para renderizar PNG/SVG — veja references/when-not-to-use.md se essa distinção fizer diferença.

Regras de ouro (aprendidas da maneira mais difícil)

1. LaTeX não é texto. Fórmulas são elementos do tipo "image" cuja fonte está na seção ## Embedded Files como <40-hex-id>: $$tex$$. Um elemento de imagem sem uma entrada correspondente em Embedded Files renderiza como uma imagem quebrada. Veja references/latex.md.
2. Nunca escreva $$...$$ manualmente dentro de um elemento de texto para este plugin — ele mostra o código-fonte bruto. O plugin só renderiza equações que existem em Embedded Files.
3. O tema da cena não é autoritativo. O plugin sobrescreve appState.theme com o tema do aplicativo. A cor do canvas, portanto, vem de viewBackgroundColor, mas um tema claro pinta de branco independentemente. Veja references/theme-and-color.md.
4. Copie a paleta de um canvas existente no mesmo cofre antes de inventar cores. Descomprima um com scripts/inspect_canvas.mjs, leia suas cores de traço e família de fonte, e reutilize-as.
5. Altura uniforme de fórmula, largura baseada no comprimento. Uma largura fixa grande estica fórmulas curtas em gigantes. Veja references/layout.md.
6. O plugin salva novamente como compressed-json (LZString base64, quebrado a cada ~120 caracteres). Regere o canvas a partir do seu script gerador em vez de corrigir o arquivo salvo. A leitura requer descompressão — scripts/inspect_canvas.mjs faz isso.
7. Verifique antes de afirmar sucesso. Execute o script de inspeção e verifique: contagem de equações igual à contagem de imagens, nenhuma ligação órfã, tema/fundo conforme o esperado.
8. "Parece bom" é mensurável. Proporção do contêiner ≤ 30%, ≤ 4 tamanhos de fonte, variância de altura de fórmula igual a 0, contagem de sobreposição igual a 0. scripts/inspect_canvas.mjs agora imprime estes como avisos estéticos; trate qualquer aviso como um defeito, não uma preferência. Veja references/design-metrics.md.
9. Escreva uma vez, com IDs estáveis, excluindo primeiro. Os IDs dos elementos devem ser derivados do conteúdo (hash do texto / TeX / rótulo), nunca aleatórios. E desvincule o arquivo de destino antes de escrevê-lo. Sem ambos, regenerar um canvas que está atualmente aberto no Obsidian mescla os novos elementos na cena ativa: tudo duplica, e o plugin salva automaticamente a cena duplicada de volta no disco. Veja references/troubleshooting.md → "Elementos duplicam / triplicam".
10. Renderize antes de entregar. scripts/render_preview.mjs rasteriza o arquivo sem cabeçalho (Node, sem navegador). Olhe para o PNG — auditorias JSON detectam estrutura, apenas pixels detectam "o espaçamento parece errado". LaTeX aparece em branco nessa pré-visualização (MathJax vive no plugin Obsidian, não no renderizador), então julgue o layout aí e a correção da fórmula a partir de ## Embedded Files.
11. Apenas uma camada de $$. TeX no modelo de dados é simples (A=\int…); os delimitadores são adicionados apenas ao emitir a linha ## Embedded Files. Qualquer $$$ em um arquivo gerado é um bug de dupla camada que renderiza cifrões literais.

Duas escolas de layout — escolha uma antes de desenhar

	Grade de colunas (表格派)	Linhas como estrutura (结构派)
Forma	caixas de coluna + divisores de linha	linha tronco + linhas de descida + texto flutuante
Proporção do contêiner	alta (uma caixa por coluna)	perto de 0
Leitura como	uma tabela de consulta, rigorosa	quadro de palestra, leve
Melhor para	muitas linhas do mesmo nível que você verifica célula por célula	ramificação, ou colunas que derivam umas das outras
Modo de falha	"parece um modelo de slide"	muitas ramificações → linhas cruzadas

Regra prática: colunas irmãs → grade de colunas; uma coluna derivada das outras → linhas de estrutura. Ambos os exemplos existem em design-metrics.md com conteúdo idêntico (o canvas da Décima Aula), para que você possa comparar antes de escolher.

Fluxo de trabalho

1. Leia as convenções do cofre de destino. Encontre um .excalidraw.md existente que o usuário goste, execute node scripts/inspect_canvas.mjs <arquivo> e anote: tema, viewBackgroundColor, cores de traço dominantes, fontFamily, roughness, tamanhos de fonte típicos.
2. Projete o conteúdo como colunas ou linhas (veja references/layout.md) — uma coluna por família de quantidade/etapa, uma linha por fórmula, e agrupe apenas coisas que são realmente a mesma quantidade. Escolha a escola de layout (grade de colunas vs linhas como estrutura) conforme a tabela acima.
3. Escreva um script gerador modelado em scripts/gen_canvas.mjs: edite seu bloco CONFIG (título, colunas, linhas) e execute-o. Não edite manualmente o JSON de 30 kB. Mantenha os dois mecanismos de segurança que ele possui: IDs derivados de conteúdo e rmSync antes de writeFileSync.
4. Inspecione o resultado com scripts/inspect_canvas.mjs, corrija contagens/cores/ligações. Além disso, verifique se não há $$$ no arquivo e se a contagem de elementos é igual ao que o gerador imprimiu (um múltiplo significa que o bug de mesclagem ocorreu). Em seguida, renderize-o com scripts/render_preview.mjs e realmente olhe para o PNG; corrija espaçamento/sobreposição/linhas curtas antes de relatar.
5. Relate o que o usuário deve fazer no Obsidian (fechar e reabrir o arquivo, ou usar o comando "Descomprimir arquivo Excalidraw atual") — o plugin só relê um arquivo quando ele é reaberto.

Mapa de referência

Arquivo	Conteúdo
references/file-format.md	Esqueleto exato do .excalidraw.md, ambas as codificações, ordem das seções, comentário de cabeçalho
references/element-schema.md	Campos obrigatórios por tipo de elemento, texto vinculado, ligações de seta, ordenação index
references/latex.md	Contrato de Embedded Files, \color, dimensionamento, as três variantes de renderização testadas, assinaturas de falha
references/theme-and-color.md	Por que os canvas abrem branco, matchThemeAlways, extração de paleta, cores estabelecidas deste cofre
references/layout.md	Geometria de colunas/linhas, heurísticas de dimensionamento de fórmulas, o que faz um canvas parecer inacabado
references/script-engine.md	Mecanismo de script JS dentro do plugin: onde colocar scripts, o que eles podem fazer, API ExcalidrawAutomate, se pode fazer tabelas, trade-offs com geração em nível de arquivo
references/design-metrics.md	Estética quantificada: proporção do contêiner, contagem de níveis de fonte, variância de fórmula, espaços em branco, cor semântica; duas escolas de layout; como validar sem um renderizador
references/troubleshooting.md	Tabela sintoma → causa → correção para cada falha vista até agora
scripts/gen_canvas.mjs	Gerador de canvas orientado por configuração (texto, latex, retângulo, linha horizontal, seta)
scripts/inspect_canvas.mjs	Descompressão + auditoria: tema, contagens, correspondência equação/imagem, ligações, fontes, métricas estéticas. --describe imprime um inventário compacto de id/posição/rótulo/conexão; --dump imprime o JSON bruto da cena
scripts/render_preview.mjs	Pré-visualização PNG sem cabeçalho via mcp-excalidraw-server render (sem navegador). LaTeX renderiza em branco — apenas layout
evals/evals.json	Prompts de regressão: um por modo de falha que realmente ocorreu
examples/ea-table.md	Um script executável dentro do aplicativo que constrói uma tabela de retângulos + texto

Editando um canvas existente

1. Descomprima-o para entender o estado atual (inspect_canvas.mjs --dump <arquivo> imprime o JSON da cena).
2. Prefira regenerar a partir do script gerador. Se o usuário fez edições manuais que valem a pena manter, escreva uma transformação com escopo (ler cena → modificar elementos específicos → re-serializar descomprimido) em vez de reescrever o canvas inteiro.
3. Nunca deixe um canvas meio migrado: ou toda imagem tem sua equação, ou nenhuma.

Padrões de dimensionamento e tipografia para este cofre

• Texto do corpo: fontFamily: 6, roughness: 0, strokeWidth: 1.
• Título: 28–30 px, cabeçalho de coluna: 19–22 px, rótulo de linha: 15–16 px, altura da imagem de fórmula: 50–52 px.
• Espaçamento entre linhas: 116–130 px; largura da coluna: 320–340 px; lacuna: 28–40 px.
• Fundo do canvas: #ffffff; tinta: #1e1e1e; suave: #868e96; linha fina: #e9ecef.