explicai 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+Todas as mudanças importantes do Explicaí Studio ficam aqui. O formato segue o [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e o projeto usa [Versionamento Semântico](https://semver.org/lang/pt-BR/).
+
+All notable changes to Explicaí Studio are listed here, in Portuguese first with a short English summary at the end of each release. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-11-03
+
+### Corrigido
+
+- Aparência: com Sistema marcado, o painel diz se o tema valendo agora é claro ou escuro.
+- Editor: imagem colada ou solta acompanha o texto digitado durante o envio e entra no ponto certo, sem erro quando a página encolhe.
+- CLI: `--version` mostra a versão, e opção desconhecida mostra o uso em vez de um erro do Node.
+
+### English summary
+
+An image pasted while you type now lands in the right place. With System selected, the Appearance panel says which theme is active. `--version` works, and an unknown CLI option shows the usage instead of a Node error.
+
+## [0.2.0] - 2026-11-03
+
+A 0.1.0 foi a primeira versão do Studio; este bloco reúne o que entrou desde a tag `v0.1.0`.
+
+### Adicionado
+
+- Exportação: fontes empacotadas (Archivo, Atkinson Hyperlegible Next, Inter, Source Sans 3, Source Serif 4, Lora, Montserrat, Playfair Display e JetBrains Mono, todas OFL) que vão junto do HTML exportado, e escolha da fonte do texto e dos títulos no diálogo e pela barra do editor.
+- Exportação: tema do manual com cor do texto, dos títulos por nível, de realce e de destaque, com o nome de cada cor, e logo do cliente na capa (enviado e retirado no diálogo de exportação, limite de 1 MB).
+- Exportação: o diálogo mostra a etapa, o resultado e o erro com nova tentativa; "Exportar manual" foi para o fim do topo, à direita.
+- Editor: cor do texto com paleta fixa e nome de cada cor, também pelo teclado e na barra fixa; barra flutuante na seleção com o tipo do bloco, formatação e cor.
+- Editor: bloco de alerta (salvo como alerta GFM, exportado com rótulo em texto e cor por tipo), menu `/` com blocos agrupados e prévia, controles de linha e coluna direto na tabela, botão "Colar print" com Ctrl+V visível, barra de formatação rolável no celular.
+- Marcações do print: atalhos de letra (V, M, D, S, A) e barra compacta; seta, marcador e legenda redesenhados como no brand book, no editor e no export.
+- Páginas: numeração na árvore e na busca com a mesma regra do sumário exportado, status escrito e legível, e o nome do arquivo da página só muda quando se para de digitar o título.
+- Interface: telas de erro em tela cheia (servidor fora com reconexão de espera crescente, rota inexistente, erro inesperado), erros do núcleo com código e parâmetros estáveis, traduzidos em português e inglês, menu Ajustes com Idioma e Aparência, e página HTML de erro do servidor alinhada à marca.
+- Layout: árvore em coluna estreita de 900 a 1023 px, marca na barra do topo, alvos de toque de 44 px no celular.
+- Testes e CI: GitHub Actions com lint, tipos, testes com cobertura e ponta a ponta; cobertura medida com `npm run test:cov`; testes novos para sistema de arquivos, segurança, UTF-8, exportação, editor e pacote npm.
+- Edição feita fora do Studio (MCP, outro editor): o servidor devolve a versão da página (`If-Match`, 409 `disk-conflict`) e o Studio avisa em vez de sobrescrever, com "Recarregar do disco" e "Manter a minha versão".
+- Imagem: ferramenta Ocultar (O) para dados sensíveis, com Tarja (padrão) ou Desfoque forte (pixelado e borrado), queimados nos pixels; o original é apagado, com aviso quando a pasta está no git e lembrete de que exports antigos ainda têm o original.
+- Imagem: tamanho de exibição Pequena, Média ou Larga, guardado no JSON ao lado da imagem e respeitado no editor, no HTML e no PDF.
+- Imagem: Recortar (R), com as marcações reposicionadas e a confirmação listando as que vão sumir; Reduzir resolução e peso, sugerindo 1600 px de largura e sem nunca ampliar.
+- Pacote npm: CHANGELOG, descrição bilíngue, palavras-chave e README para quem chega pelo npm.
+
+### Alterado
+
+- O Studio usa sempre o cobalto da marca, com seleção de texto em cobalto translúcido; raio de 3 px vindo de um token; rótulos de seção em mono maiúsculo; ícones decorativos removidos.
+- "Versão do manual" é o nome único da versão apontada para o manual final.
+- Imagens do Studio carregam com `loading="lazy"` e o servidor entrega arquivos com ETag, 304 e streaming.
+- O botão do balão da imagem e o título do editor dizem "Editar imagem" (era "Marcar imagem").
+- Legenda da imagem: três ou mais marcadores seguidos sem descrição viram um selo só com intervalo ("1–8").
+- Lixeira: o painel não conta mais as imagens sem uso ao abrir; o botão fica sempre visível e avisa quando não há nada.
+- O pacote publicado não leva mais os mapas de código (`.map`).
+
+### Corrigido
+
+- Autosave: grava uma página por vez, guarda uma mudança pendente por página e descarta a resposta antiga ao trocar de página.
+- Autosave: o renome do arquivo (5 s depois do título) espera a gravação em voo e leva a versão nova, sem faixa de conflito falsa; com a faixa de conflito aberta, o rodapé diz "Aguardando sua escolha" em vez de "Não foi possível salvar".
+- Núcleo: `updateManual` passou a ter fila por pasta (sem perder mudanças simultâneas); `addPage` grava o arquivo antes da árvore; a lixeira pula item com `entry.json` quebrado; `findUnusedAssets` ignora arquivo que sumiu; dois envios do mesmo nome de imagem não dão mais `EEXIST`; manual com BOM no começo abre; restaurar uma página fecha a lixeira.
+- Limpeza de imagens sem uso: grava a fila do autosave antes, poupa imagem gravada há menos de 1 minuto e volta a 60 s quando a carência é inválida.
+- Exportação: gera em pasta temporária e troca só no fim; marcação com JSON quebrado ou de forma errada vira aviso e a imagem sai pura; aviso quando a página cita imagem que não existe; `%` solto em link ou imagem não derruba mais a exportação; lê `width` e `height` de SVG; sem pulo de nível de título; "Só páginas aprovadas" fica desabilitado quando nenhuma está aprovada.
+- Servidor: `%` malformado na URL responde 400 com código estável; corpo JSON que não é UTF-8 válido é recusado; diretório vira 404.
+- Editor: Enter depois de imagem, ordem de várias imagens coladas, Esc no balão da imagem devolve o foco, Ctrl+End leva ao fim da página, menu `/` não fica atrás da barra fixa nem deixa de rolar com a seta, negrito e link junto de código no texto, popover da imagem ancorado dentro da área útil.
+- Interface: título longo da página não corta ao carregar a fonte; erro ao trocar a fonte do manual aparece; contraste de 3:1 na borda de campo e na amostra de cor nos dois temas, seletor de tema com uma só opção marcada, título longo da árvore truncado, marca que não quebra em duas linhas.
+
+- Telas: foco do painel Aparência sem opção marcada, rodapé em tela estreita mostra o caminho inteiro, botões da barra de marcação com 44 px e nome no toque, grupo Versões/Exportar alinhado em 375 px, uma marca só com a gaveta aberta, "Nesta página" sem rolagem lateral, nome inteiro do título truncado na árvore ao passar o mouse.
+- Desempenho: `imageSize` lê só o começo do arquivo.
+
+### Segurança
+
+- Recusa link simbólico que sai da pasta do manual ao servir e ao copiar arquivos (`realpath`).
+- CSP em `/files/` (SVG não executa script) e `Origin` aceito só da mesma porta do `Host`.
+- Erros de arquivo sem caminho absoluto na resposta.
+- Testes de escape contra XSS na exportação e de HTML colado no texto.
+
+### Interno
+
+- CI: publicação no npm com provenance e release no GitHub ao enviar uma tag `vX.Y.Z`; suíte e2e estável no CI (espera a seleção do editor antes do próximo passo); pastas temporárias do e2e apagadas ao fim.
+- Regras do projeto (Conventional Commits, arquitetura, testes, revisão) e plugin da equipe de agentes; tickets em `docs/tickets`; documentação do formato do manual atualizada com tema, cor do texto, alertas e logo.
+
+### English summary
+
+New since 0.1.0: bundled OFL fonts and font choice for exports, manual theme colors and client logo, alert blocks, text colors with names, a floating selection toolbar, a richer `/` menu, table row and column controls, annotation shortcuts, full-screen error pages, translated errors, GitHub Actions CI and a much larger test suite. New: warning instead of overwrite when a page changed on disk outside the Studio. Image tools: hide sensitive data (solid bar or strong blur burned into the pixels), display size (small, medium, wide), crop with annotations remapped, and resolution/weight reduction. Fixes cover autosave races, per-folder write queue, atomic exports, unused-image cleanup and many editor and accessibility details. Security: symlinks that leave the manual folder are refused, CSP on `/files/`, same-port `Origin` check. The npm package no longer ships source maps.
+
+[Unreleased]: https://github.com/gabriel-codesampaio/explicai-studio/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/gabriel-codesampaio/explicai-studio/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/gabriel-codesampaio/explicai-studio/compare/v0.1.0...v0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Gabriel Sampaio
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Gabriel Sampaio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,54 +1,114 @@
 <p>
-  <img src="https://gabriel-codesampaio.github.io/explicai-brandbook/logo/explicai-logo-horizontal.svg" alt="Explicaí" height="56">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://gabriel-codesampaio.github.io/explicai-brandbook/logo/explicai-logo-horizontal-escuro.svg">
+    <img src="https://gabriel-codesampaio.github.io/explicai-brandbook/logo/explicai-logo-horizontal.svg" alt="Explicaí" height="56">
+  </picture>
 </p>
 
 Construtor de manuais open source e gratuito. Do print ao manual pronto em PDF, HTML e Markdown.
 
-> Tira o print, que o Explicaí explica.
+> Tira o print e explica. O Explicaí monta o manual.
 
-## Como usar
+[Português](#português) · [English](#english)
 
-Precisa do Node 20.12 ou mais novo.
+## Português
+
+### Como usar
+
+Precisa do Node 20.12 ou mais novo. Para exportar em PDF, precisa também do Chrome, do Edge ou do Chromium instalado na máquina.
 
 ```bash
 npx explicai manuais
 ```
 
-O Explicaí Studio abre no navegador, e os manuais ficam na pasta `manuais` (sem pasta, vale a pasta atual). Opções: `--port 4321` para trocar a porta e `--no-open` para não abrir o navegador.
+O Explicaí Studio abre no navegador, e os manuais ficam na pasta `manuais` (sem pasta, vale a pasta atual). Opções:
 
-No Studio você:
+- `--port 4321` troca a porta;
+- `--no-open` não abre o navegador;
+- `--help` mostra o uso.
 
-- escreve cada tela ou tarefa do sistema numa página, organizada em árvore;
-- cola prints e marca com números, destaques, setas e áreas clicáveis;
-- escreve passos numerados com o print e o resultado esperado de cada um;
-- guarda versões de cada página e escolhe qual vai para o manual final;
-- marca cada página como rascunho, em revisão, aprovada ou publicada;
-- exporta em HTML, PDF ou Markdown. O PDF usa o Chrome, o Edge ou o Chromium que já estiver na máquina.
+### O que dá para fazer
 
-Cada manual é uma pasta de arquivos Markdown que você pode versionar no git junto com o código. O formato está em [docs/manual-format.md](docs/manual-format.md).
+- Escrever cada tela ou tarefa do sistema numa página, organizada em árvore.
+- Colar prints e marcar com números, destaques, setas e áreas clicáveis.
+- Escrever passos numerados com o print e o resultado esperado de cada um.
+- Guardar versões de cada página e escolher qual vai para o manual final.
+- Marcar cada página como rascunho, em revisão, aprovada ou publicada.
+- Escolher cores, fontes e logo do manual exportado.
 
-A interface está em português e em inglês, e segue o idioma do navegador. O [Explicaí Agent](https://github.com/gabriel-codesampaio/explicai-mcp) vai deixar uma IA montar manuais no mesmo formato, pelo MCP.
+### Exportar
 
-## Desenvolvimento
+Pelo botão Exportar do Studio, em três formatos:
+
+| Formato | O que sai |
+| --- | --- |
+| HTML | Um manual com sumário, que abre offline, com as imagens e as fontes ao lado. |
+| PDF | O mesmo HTML impresso pelo navegador da máquina (Chrome, Edge ou Chromium). Se ele estiver num caminho fora do comum, aponte com a variável `EXPLICAI_BROWSER`. |
+| Markdown | Um arquivo só, com a legenda de cada print em texto, bom para ler com IA. |
+
+Os arquivos saem em `exportacao/`, dentro da pasta do manual.
+
+### Formato da pasta
+
+Cada manual é uma pasta de arquivos Markdown que você pode versionar no git junto com o código:
 
-```bash
-npm install
-npm run check      # lint, tipos e testes
-npm run test:e2e   # testes de ponta a ponta no Chrome instalado
-npm run build
 ```
+manuais/
+  financeiro/
+    manual.json              título, idioma e árvore de páginas
+    pages/cadastrar-cliente.md
+    assets/tela-clientes.png
+    assets/tela-clientes.png.json   marcações do print
+    exportacao/              HTML, PDF e Markdown gerados
+```
+
+O formato completo está em [docs/manual-format.md](https://github.com/gabriel-codesampaio/explicai-studio/blob/main/docs/manual-format.md).
+
+### Usar como biblioteca
 
-Para trabalhar no editor: `npm run dev:server` em um terminal e `npm run dev:web` em outro.
+O mesmo código que o Studio usa para ler, gravar e exportar manuais está em `explicai/core`. É assim que o [Explicaí Agent](https://github.com/gabriel-codesampaio/explicai-mcp) monta manuais pelo MCP.
+
+```js
+import { createManual, addPage, exportManual } from "explicai/core";
+
+const manual = await createManual("manuais", { title: "Financeiro", language: "pt-BR" });
+await addPage(manual.dir, { title: "Cadastrar cliente", body: "1. Clique em **Novo cliente**." });
+await exportManual(manual.dir, "html");
+```
 
-Contribuições são bem-vindas. Abra uma issue para conversar sobre a ideia, ou mande um pull request com `npm run check` passando.
+### Contribuir
 
-- Formato do manual em disco: [docs/manual-format.md](docs/manual-format.md)
-- Brand book: [gabriel-codesampaio.github.io/explicai-brandbook](https://gabriel-codesampaio.github.io/explicai-brandbook/)
+Contribuições são bem-vindas. Abra uma [issue](https://github.com/gabriel-codesampaio/explicai-studio/issues) para conversar sobre a ideia, ou mande um pull request com `npm run check` passando. O código está em [github.com/gabriel-codesampaio/explicai-studio](https://github.com/gabriel-codesampaio/explicai-studio).
 
 ## English
 
-Explicaí is a free, open source manual builder. Run `npx explicai manuals` (Node 20.12+), write one page per screen or task, paste screenshots and mark them up with numbered markers, highlights, arrows and clickable areas, then export to HTML, PDF or Markdown. Each manual is a folder of Markdown files you can keep in git next to your code. The interface is available in Portuguese and English. Pronounced *ex-plee-kah-EE*.
+### Usage
+
+Needs Node 20.12 or newer. PDF export also needs Chrome, Edge or Chromium installed on the machine.
+
+```bash
+npx explicai manuals
+```
+
+Explicaí Studio opens in your browser, and the manuals live in the `manuals` folder (with no folder, the current one is used). Options: `--port 4321` changes the port, `--no-open` skips opening the browser, `--help` prints the usage. The interface is available in Portuguese and English and follows the browser language.
+
+### What you can do
+
+- Write one page per screen or task, organized as a tree.
+- Paste screenshots and mark them up with numbered markers, highlights, arrows and clickable areas.
+- Keep versions of each page and pick the one that goes into the final manual.
+- Export to HTML (offline, with images and fonts next to it), PDF (printed by your Chrome, Edge or Chromium; set `EXPLICAI_BROWSER` if it lives somewhere unusual) or a single Markdown file.
+
+### Folder format
+
+Each manual is a folder of Markdown files you can keep in git next to your code: a `manual.json` with the page tree, one `.md` per page under `pages/`, images and their annotations under `assets/`, and the exports under `exportacao/`. Details (in Portuguese) in [docs/manual-format.md](https://github.com/gabriel-codesampaio/explicai-studio/blob/main/docs/manual-format.md).
+
+### Library
+
+`explicai/core` exports the functions the Studio uses to read, write and export manuals (`createManual`, `addPage`, `exportManual` and more), as in the example above. Types are included.
+
+## Licença / License
 
-## Licença
+MIT. Um projeto [codesampa.io](https://codesampa.io) / A [codesampa.io](https://codesampa.io) project. Veja o arquivo [LICENSE](https://github.com/gabriel-codesampaio/explicai-studio/blob/main/LICENSE).
 
-MIT. Um projeto [codesampa.io](https://codesampa.io).
+As fontes em `fonts/` (Archivo, Atkinson Hyperlegible Next, Inter, JetBrains Mono, Lora, Montserrat, Playfair Display, Source Sans 3 e Source Serif 4) seguem a SIL Open Font License 1.1, com a licença de cada uma ao lado. Elas vão junto com o manual exportado em HTML. / The fonts in `fonts/` are licensed under the SIL Open Font License 1.1, with each license next to the files.

package/dist/cli.js

@@ -1,22 +1,41 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { createStudioServer } from "./server/index.js";
-const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-        port: { type: "string", short: "p", default: "4321" },
-        "no-open": { type: "boolean", default: false },
-        help: { type: "boolean", short: "h", default: false },
-    },
-});
-if (values.help) {
-    console.log(`Uso: explicai [pasta] [--port 4321] [--no-open]
+const USAGE = `Uso: explicai [pasta] [--port 4321] [--no-open] [--version]
 
-Abre o Explicaí Studio no navegador. Os manuais ficam em [pasta] (padrão: pasta atual).`);
+Abre o Explicaí Studio no navegador. Os manuais ficam em [pasta] (padrão: pasta atual).`;
+function parseCliArgs() {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            options: {
+                port: { type: "string", short: "p", default: "4321" },
+                "no-open": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch {
+        console.error(`Opção inválida.
+
+${USAGE}`);
+        process.exit(1);
+    }
+}
+const { values, positionals } = parseCliArgs();
+if (values.help) {
+    console.log(USAGE);
+    process.exit(0);
+}
+if (values.version) {
+    const pkg = new URL("../package.json", import.meta.url);
+    console.log(JSON.parse(readFileSync(pkg, "utf8")).version);
     process.exit(0);
 }
 const workspace = path.resolve(positionals[0] ?? ".");

package/dist/core/annotations.js

@@ -20,6 +20,8 @@ export function parseAnnotations(input) {
     };
     return {
         version: FORMAT_VERSION,
+        // Valor desconhecido é ignorado (imagem aparece como sempre), não derruba o arquivo.
+        ...(obj.display === "s" || obj.display === "m" || obj.display === "full" ? { display: obj.display } : {}),
         markers: list(obj.markers, "markers").map((m, i) => {
             const r = record(m, `markers[${i}]`);
             const n = r.n;

package/dist/core/assets.d.ts

@@ -3,6 +3,8 @@ import type { Annotations } from "./types.js";
 export declare function saveAsset(dir: string, fileName: string, data: Uint8Array): Promise<string>;
 export declare function readAnnotations(dir: string, assetPath: string): Promise<Annotations>;
 export declare function writeAnnotations(dir: string, assetPath: string, input: unknown): Promise<Annotations>;
+/** Caminho absoluto de uma imagem que está direto em assets/; qualquer outro lugar é recusado. */
+export declare function assetFile(dir: string, assetPath: string): string;
 /**
  * Arquivos de assets/ que ninguém usa: imagens que nenhuma página, versão ou item da lixeira cita,
  * e marcações (.json) cuja imagem não existe mais. Devolve caminhos como `assets/tela.png`.

package/dist/core/assets.js

@@ -1,39 +1,59 @@
-import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readdir, rename, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { emptyAnnotations, parseAnnotations } from "./annotations.js";
-import { atomicWrite, exists, relativePosix, resolveInside, uniquePath } from "./fs.js";
-import { ASSETS_DIR } from "./manuals.js";
-import { slugify } from "./text.js";
+import { ExplicaiError } from "./errors.js";
+import { atomicWrite, exists, readText, relativePosix, resolveInside, uniquePath } from "./fs.js";
+import { ASSETS_DIR, readManual } from "./manuals.js";
+import { decodeUri, slugify } from "./text.js";
 const IMAGE_EXT = /^\.(png|jpe?g|gif|webp|svg)$/;
 /** Grava a imagem em `assets/` com nome único e devolve o caminho relativo ao manual. */
 export async function saveAsset(dir, fileName, data) {
     const ext = path.extname(fileName).toLowerCase();
     if (!IMAGE_EXT.test(ext))
         throw new Error(`Formato de imagem não suportado: ${ext || "sem extensão"}`);
-    const name = path.basename(fileName);
-    const abs = await uniquePath(path.join(dir, ASSETS_DIR), slugify(name.slice(0, name.length - ext.length)), ext);
-    await writeFile(abs, data, { flag: "wx" });
-    return relativePosix(dir, abs);
+    const base = slugify(path.basename(fileName).slice(0, -ext.length));
+    // Dois envios do mesmo nome ao mesmo tempo (duas abas) escolhem o mesmo caminho livre; quem perde tenta o próximo.
+    for (;;) {
+        const abs = await uniquePath(path.join(dir, ASSETS_DIR), base, ext);
+        try {
+            await writeFile(abs, data, { flag: "wx" });
+            return relativePosix(dir, abs);
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+    }
 }
 export async function readAnnotations(dir, assetPath) {
     const file = annotationsFile(dir, assetPath);
     if (!(await exists(file)))
         return emptyAnnotations();
-    return parseAnnotations(JSON.parse(await readFile(file, "utf8")));
+    const raw = await readText(file);
+    try {
+        return parseAnnotations(JSON.parse(raw));
+    }
+    catch {
+        // JSON quebrado ou de forma errada: o mesmo aviso
+        const name = relativePosix(dir, file);
+        throw new ExplicaiError("annotations-invalid", `As marcações de ${name} estão com erro de sintaxe. Corrija ou apague o arquivo.`, { file: name });
+    }
 }
 export async function writeAnnotations(dir, assetPath, input) {
     const annotations = parseAnnotations(input);
     await atomicWrite(annotationsFile(dir, assetPath), `${JSON.stringify(annotations, null, 2)}\n`);
     return annotations;
 }
-/** `assets/foto.png` → `assets/foto.png.json`. Só imagens dentro de assets/ têm anotações. */
-function annotationsFile(dir, assetPath) {
+/** Caminho absoluto de uma imagem que está direto em assets/; qualquer outro lugar é recusado. */
+export function assetFile(dir, assetPath) {
     const abs = resolveInside(dir, assetPath);
     if (path.dirname(abs) !== path.join(path.resolve(dir), ASSETS_DIR)) {
         throw new Error("Anotações só existem para imagens em assets/.");
     }
-    return `${abs}.json`;
+    return abs;
 }
+/** `assets/foto.png` → `assets/foto.png.json`. Só imagens dentro de assets/ têm anotações. */
+const annotationsFile = (dir, assetPath) => `${assetFile(dir, assetPath)}.json`;
 /** Pastas cujos Markdown podem citar imagens: páginas, versões guardadas e lixeira. */
 const MENTION_DIRS = ["pages", ".versoes", ".lixeira"];
 const MENTION = /assets\/([^)\s"'#?]+)/g;
@@ -46,6 +66,10 @@ export async function findUnusedAssets(dir) {
     if (!(await exists(assetsDir)))
         return [];
     const used = new Set();
+    // O logo do tema não está em nenhuma página, mas o export precisa dele.
+    const logo = (await readManual(dir)).theme?.logo;
+    if (logo?.startsWith(`${ASSETS_DIR}/`))
+        used.add(logo.slice(ASSETS_DIR.length + 1));
     for (const sub of MENTION_DIRS) {
         const root = path.join(dir, sub);
         if (!(await exists(root)))
@@ -53,15 +77,26 @@ export async function findUnusedAssets(dir) {
         for (const file of await readdir(root, { recursive: true })) {
             if (!file.endsWith(".md"))
                 continue;
-            for (const [, name] of (await readFile(path.join(root, file), "utf8")).matchAll(MENTION)) {
+            for (const [, name] of (await readText(path.join(root, file))).matchAll(MENTION)) {
                 if (name)
-                    used.add(decodeURI(name));
+                    used.add(decodeUri(name));
             }
         }
     }
-    const files = await readdir(assetsDir);
-    const names = new Set(files);
+    const listed = await readdir(assetsDir);
+    const names = new Set(listed);
+    // Arquivo recém-gravado pode estar numa página que ainda não chegou ao disco: poupa (EXPLICAI_ASSET_GRACE_MS só para o e2e).
+    const envGrace = Number(process.env.EXPLICAI_ASSET_GRACE_MS ?? 60_000);
+    const grace = Number.isFinite(envGrace) && envGrace >= 0 ? envGrace : 60_000;
+    const stats = await Promise.all(listed.map((f) => stat(path.join(assetsDir, f)).catch((err) => {
+        if (err.code !== "ENOENT")
+            throw err;
+        return null; // sumiu desde a listagem
+    })));
+    const files = listed.filter((_, i) => stats[i]);
+    const recent = new Set(listed.filter((_, i) => stats[i] && Date.now() - stats[i].mtimeMs < grace));
     return files
+        .filter((f) => !recent.has(f))
         .filter((f) => (f.endsWith(".json") ? !names.has(f.slice(0, -".json".length)) : !used.has(f)))
         .flatMap((f) => (!f.endsWith(".json") && names.has(`${f}.json`) ? [f, `${f}.json`] : [f]))
         .filter((f, i, all) => all.indexOf(f) === i)

package/dist/core/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Erro do núcleo que a interface sabe traduzir: a mensagem fica em português (CLI e MCP leem ela),
+ * e `code` + `params` são estáveis para o Studio montar o texto no idioma escolhido.
+ */
+export declare class ExplicaiError extends Error {
+    readonly code: string;
+    readonly params: Record<string, string | number>;
+    constructor(code: string, message: string, params?: Record<string, string | number>);
+}

package/dist/core/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Erro do núcleo que a interface sabe traduzir: a mensagem fica em português (CLI e MCP leem ela),
+ * e `code` + `params` são estáveis para o Studio montar o texto no idioma escolhido.
+ */
+export class ExplicaiError extends Error {
+    code;
+    params;
+    constructor(code, message, params = {}) {
+        super(message);
+        this.code = code;
+        this.params = params;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/export/annotationCss.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CSS das marcações no HTML exportado. O editor desenha o mesmo (AnnotationOverlay e AnnotationLegend):
+ * mexeu aqui, confira lá. Variáveis --anotacao e --sobre-anotacao vêm do :root do export.
+ */
+export declare const ANNOTATION_CSS = "\n.shot{display:block;margin:.6em 0}\n.shot-s{--shot-w:40%}.shot-m{--shot-w:70%}.shot-full{--shot-w:100%}\n.frame{position:relative;display:block;max-width:var(--shot-w,100%);width:fit-content;isolation:isolate}\n.frame img{display:block;max-width:100%;height:auto;border:1px solid var(--linha);border-radius:8px}\n.hl{position:absolute;border:2px solid var(--marca);border-radius:3px}\n.hl::before{content:\"\";position:absolute;inset:0;background:var(--marca);mix-blend-mode:multiply}\n.hot{position:absolute;border:2px dashed var(--anotacao);background:var(--anotacao-fundo);border-radius:3px}\n.arrows{position:absolute;inset:0;width:100%;height:100%;overflow:visible;pointer-events:none}\n.arrows line{stroke:var(--anotacao);stroke-linecap:round}\n.arrows polygon{fill:var(--anotacao)}\n.arrows .halo{stroke:#fff;stroke-opacity:.9;stroke-linejoin:round}\n.arrows polygon.halo{fill:#fff}\n.mk{position:absolute;transform:translate(-50%,-50%);width:32px;height:32px;border:2px dashed var(--anotacao);border-radius:50%;box-shadow:0 0 0 2px #fff,inset 0 0 0 2px #fff}\n.mk::before{content:attr(data-n);position:absolute;left:-12px;top:-12px;display:grid;place-items:center;width:20px;height:20px;border-radius:50%;background:var(--anotacao);color:var(--sobre-anotacao);font:600 11px var(--mono);box-shadow:0 0 0 2px #fff}\n.legend{display:grid;gap:2px;margin-top:12px;font-size:15px;line-height:1.4}\n.legend .row{display:flex;align-items:center;gap:4px}\n.legend .n{display:inline-grid;place-items:center;min-width:20px;height:20px;padding:0 4px;border-radius:50%;background:var(--anotacao);color:var(--sobre-anotacao);font:600 11px var(--mono)}\n.legend .n+span{margin-left:2px}\n.legend .none{color:var(--grafite);font-style:italic}\n";

package/dist/core/export/annotationCss.js

@@ -0,0 +1,26 @@
+/**
+ * CSS das marcações no HTML exportado. O editor desenha o mesmo (AnnotationOverlay e AnnotationLegend):
+ * mexeu aqui, confira lá. Variáveis --anotacao e --sobre-anotacao vêm do :root do export.
+ */
+export const ANNOTATION_CSS = `
+.shot{display:block;margin:.6em 0}
+.shot-s{--shot-w:40%}.shot-m{--shot-w:70%}.shot-full{--shot-w:100%}
+.frame{position:relative;display:block;max-width:var(--shot-w,100%);width:fit-content;isolation:isolate}
+.frame img{display:block;max-width:100%;height:auto;border:1px solid var(--linha);border-radius:8px}
+.hl{position:absolute;border:2px solid var(--marca);border-radius:3px}
+.hl::before{content:"";position:absolute;inset:0;background:var(--marca);mix-blend-mode:multiply}
+.hot{position:absolute;border:2px dashed var(--anotacao);background:var(--anotacao-fundo);border-radius:3px}
+.arrows{position:absolute;inset:0;width:100%;height:100%;overflow:visible;pointer-events:none}
+.arrows line{stroke:var(--anotacao);stroke-linecap:round}
+.arrows polygon{fill:var(--anotacao)}
+.arrows .halo{stroke:#fff;stroke-opacity:.9;stroke-linejoin:round}
+.arrows polygon.halo{fill:#fff}
+.mk{position:absolute;transform:translate(-50%,-50%);width:32px;height:32px;border:2px dashed var(--anotacao);border-radius:50%;box-shadow:0 0 0 2px #fff,inset 0 0 0 2px #fff}
+.mk::before{content:attr(data-n);position:absolute;left:-12px;top:-12px;display:grid;place-items:center;width:20px;height:20px;border-radius:50%;background:var(--anotacao);color:var(--sobre-anotacao);font:600 11px var(--mono);box-shadow:0 0 0 2px #fff}
+.legend{display:grid;gap:2px;margin-top:12px;font-size:15px;line-height:1.4}
+.legend .row{display:flex;align-items:center;gap:4px}
+.legend .n{display:inline-grid;place-items:center;min-width:20px;height:20px;padding:0 4px;border-radius:50%;background:var(--anotacao);color:var(--sobre-anotacao);font:600 11px var(--mono)}
+.legend .n+span{margin-left:2px}
+.legend .none{color:var(--grafite);font-style:italic}
+`;
+//# sourceMappingURL=annotationCss.js.map

package/dist/core/export/annotationShapes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Desenho das marcações, em funções puras. O editor tem uma cópia em web/src/lib/annotationShapes.ts
+ * (o web não importa de src/); test/annotation-shapes.test.ts garante que as duas dão o mesmo resultado.
+ */
+interface Pt {
+    x: number;
+    y: number;
+}
+export interface ArrowShape {
+    /** Haste: do começo até dentro da ponta, para não sobrar fresta. */
+    shaft: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+    /** Vértices do triângulo da ponta: a ponta em `to`, a base perpendicular à haste. */
+    head: [Pt, Pt, Pt];
+}
+/**
+ * Seta com ponta fechada. O tamanho da ponta é proporcional à espessura e encolhe em setas curtas
+ * (no máximo 70% do comprimento), sem perder a forma. `thickness` na mesma unidade de `from` e `to`.
+ */
+export declare function arrowShape(from: Pt, to: Pt, thickness: number): ArrowShape;
+export interface LegendRow {
+    numbers: number[];
+    /** Selos a mostrar: um por número, ou um só intervalo ("1–8") para 3 ou mais sem descrição. */
+    badges: string[];
+    /** Vazio quando o marcador não tem descrição. */
+    label: string;
+}
+/** Linhas da legenda por número; marcadores sem descrição em sequência dividem uma linha só. */
+export declare function legendRows(markers: {
+    n: number;
+    label?: string;
+}[]): LegendRow[];
+export {};

package/dist/core/export/annotationShapes.js

@@ -0,0 +1,38 @@
+/**
+ * Seta com ponta fechada. O tamanho da ponta é proporcional à espessura e encolhe em setas curtas
+ * (no máximo 70% do comprimento), sem perder a forma. `thickness` na mesma unidade de `from` e `to`.
+ */
+export function arrowShape(from, to, thickness) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const len = Math.hypot(dx, dy);
+    const ux = len === 0 ? 1 : dx / len;
+    const uy = len === 0 ? 0 : dy / len;
+    const headLen = Math.min(thickness * 4.5, len * 0.7);
+    const half = headLen * 0.45;
+    const bx = to.x - ux * headLen;
+    const by = to.y - uy * headLen;
+    const inside = headLen * 0.2;
+    return {
+        shaft: { x1: from.x, y1: from.y, x2: bx + ux * inside, y2: by + uy * inside },
+        head: [to, { x: bx - uy * half, y: by + ux * half }, { x: bx + uy * half, y: by - ux * half }],
+    };
+}
+/** Linhas da legenda por número; marcadores sem descrição em sequência dividem uma linha só. */
+export function legendRows(markers) {
+    const rows = [];
+    for (const m of [...markers].sort((a, b) => a.n - b.n)) {
+        const label = (m.label ?? "").trim();
+        const last = rows.at(-1);
+        if (!label && last && !last.label)
+            last.numbers.push(m.n);
+        else
+            rows.push({ numbers: [m.n], badges: [], label });
+    }
+    for (const r of rows) {
+        const [first, last] = [r.numbers[0], r.numbers.at(-1)];
+        r.badges = !r.label && r.numbers.length >= 3 ? [`${first}–${last}`] : r.numbers.map(String);
+    }
+    return rows;
+}
+//# sourceMappingURL=annotationShapes.js.map

package/dist/core/export/callout.d.ts

@@ -0,0 +1,11 @@
+import type { Token } from "marked";
+/** Cor de cada tipo de alerta no manual exportado (fundo branco). O de `note` segue a cor de destaque do manual. */
+export declare const CALLOUT_COLORS: Record<string, string>;
+/**
+ * Alerta GFM (`> [!TIP]` na primeira linha da citação): devolve o tipo e o corpo sem o marcador.
+ * Qualquer outra citação, inclusive `[!IMPORTANT]`, volta null e sai como citação comum.
+ */
+export declare function readCallout(tokens: Token[]): {
+    type: string;
+    body: Token[];
+} | null;