explicai 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# 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.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 2 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.0...HEAD
+[0.2.0]: https://github.com/gabriel-codesampaio/explicai-studio/compare/v0.1.0...v0.2.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+<p>
+  <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>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Construtor de manuais open source e gratuito. Do print ao manual pronto em PDF, HTML e Markdown.
+
+> Tira o print e explica. O Explicaí monta o manual.
+
+[Português](#português) · [English](#english)
+
+## 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` troca a porta;
+- `--no-open` não abre o navegador;
+- `--help` mostra o uso.
+
+### O que dá para fazer
+
+- 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.
+
+### Exportar
+
+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:
+
+```
+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
+
+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");
+```
+
+### Contribuir
+
+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
+
+### 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
+
+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).
+
+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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+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]
+
+Abre o Explicaí Studio no navegador. Os manuais ficam em [pasta] (padrão: pasta atual).`);
+    process.exit(0);
+}
+const workspace = path.resolve(positionals[0] ?? ".");
+const port = Number(values.port);
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.error(`Porta inválida: ${values.port}`);
+    process.exit(1);
+}
+await mkdir(workspace, { recursive: true });
+const webDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "web");
+const server = createStudioServer({ workspace, webDir });
+server.on("error", (err) => {
+    console.error(err.code === "EADDRINUSE" ? `A porta ${port} já está em uso. Tente --port ${port + 1}.` : err.message);
+    process.exit(1);
+});
+server.listen(port, "127.0.0.1", () => {
+    const url = `http://localhost:${port}`;
+    console.log(`Explicaí Studio em ${url}\nManuais em ${workspace}\nCtrl+C para sair.`);
+    if (!values["no-open"])
+        openBrowser(url);
+});
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : process.platform === "darwin"
+            ? ["open", [url]]
+            : ["xdg-open", [url]];
+    spawn(cmd, args, { stdio: "ignore", detached: true })
+        .on("error", () => { })
+        .unref();
+}
+//# sourceMappingURL=cli.js.map

package/dist/core/annotations.d.ts

@@ -0,0 +1,7 @@
+import { type Annotations } from "./types.js";
+export declare function emptyAnnotations(): Annotations;
+/**
+ * Valida anotações vindas do disco ou do Agent. Lança Error com o caminho do campo inválido.
+ * Coordenadas fora de 0..1 são rejeitadas para que nada aponte para fora da imagem.
+ */
+export declare function parseAnnotations(input: unknown): Annotations;

package/dist/core/annotations.js

@@ -0,0 +1,110 @@
+import { FORMAT_VERSION } from "./types.js";
+export function emptyAnnotations() {
+    return { version: FORMAT_VERSION, markers: [], highlights: [], arrows: [], hotspots: [] };
+}
+/**
+ * Valida anotações vindas do disco ou do Agent. Lança Error com o caminho do campo inválido.
+ * Coordenadas fora de 0..1 são rejeitadas para que nada aponte para fora da imagem.
+ */
+export function parseAnnotations(input) {
+    const obj = record(input, "anotações");
+    if (obj.version !== FORMAT_VERSION)
+        throw new Error(`anotações.version: esperado ${FORMAT_VERSION}`);
+    const ids = new Set();
+    const id = (v, path) => {
+        const s = text(v, path);
+        if (ids.has(s))
+            throw new Error(`${path}: id repetido "${s}"`);
+        ids.add(s);
+        return s;
+    };
+    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;
+            if (!Number.isInteger(n) || n < 1)
+                throw new Error(`markers[${i}].n: inteiro a partir de 1`);
+            return {
+                id: id(r.id, `markers[${i}].id`),
+                n: n,
+                ...point(r, `markers[${i}]`),
+                ...(r.label === undefined ? {} : { label: text(r.label, `markers[${i}].label`, true) }),
+            };
+        }),
+        highlights: list(obj.highlights, "highlights").map((h, i) => {
+            const r = record(h, `highlights[${i}]`);
+            return { id: id(r.id, `highlights[${i}].id`), ...rect(r, `highlights[${i}]`) };
+        }),
+        arrows: list(obj.arrows, "arrows").map((a, i) => {
+            const r = record(a, `arrows[${i}]`);
+            return {
+                id: id(r.id, `arrows[${i}].id`),
+                from: point(record(r.from, `arrows[${i}].from`), `arrows[${i}].from`),
+                to: point(record(r.to, `arrows[${i}].to`), `arrows[${i}].to`),
+            };
+        }),
+        hotspots: list(obj.hotspots, "hotspots").map((h, i) => {
+            const r = record(h, `hotspots[${i}]`);
+            return {
+                id: id(r.id, `hotspots[${i}].id`),
+                ...rect(r, `hotspots[${i}]`),
+                target: target(r.target, `hotspots[${i}].target`),
+            };
+        }),
+    };
+}
+function target(v, path) {
+    const r = record(v, path);
+    switch (r.type) {
+        case "page":
+            return { type: "page", pageId: text(r.pageId, `${path}.pageId`) };
+        case "anchor":
+            return { type: "anchor", pageId: text(r.pageId, `${path}.pageId`), anchor: text(r.anchor, `${path}.anchor`) };
+        case "url": {
+            const href = text(r.href, `${path}.href`);
+            // Só http(s) e mailto: um href "javascript:" viraria XSS no HTML exportado.
+            if (!/^(https?:|mailto:)/i.test(href))
+                throw new Error(`${path}.href: use http, https ou mailto`);
+            return { type: "url", href };
+        }
+        default:
+            throw new Error(`${path}.type: esperado "page", "anchor" ou "url"`);
+    }
+}
+function point(r, path) {
+    return { x: unit(r.x, `${path}.x`), y: unit(r.y, `${path}.y`) };
+}
+function rect(r, path) {
+    const box = { ...point(r, path), w: unit(r.w, `${path}.w`), h: unit(r.h, `${path}.h`) };
+    if (box.w === 0 || box.h === 0)
+        throw new Error(`${path}: largura e altura maiores que zero`);
+    if (box.x + box.w > 1 + 1e-9 || box.y + box.h > 1 + 1e-9)
+        throw new Error(`${path}: a área passa da borda da imagem`);
+    return box;
+}
+function unit(v, path) {
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || v > 1)
+        throw new Error(`${path}: número entre 0 e 1`);
+    return v;
+}
+function text(v, path, allowEmpty = false) {
+    if (typeof v !== "string" || (!allowEmpty && v.trim() === ""))
+        throw new Error(`${path}: texto obrigatório`);
+    return v;
+}
+function list(v, path) {
+    if (v === undefined)
+        return [];
+    if (!Array.isArray(v))
+        throw new Error(`${path}: esperado uma lista`);
+    return v;
+}
+function record(v, path) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        throw new Error(`${path}: esperado um objeto`);
+    return v;
+}
+//# sourceMappingURL=annotations.js.map

package/dist/core/assets.d.ts

@@ -0,0 +1,17 @@
+import type { Annotations } from "./types.js";
+/** Grava a imagem em `assets/` com nome único e devolve o caminho relativo ao manual. */
+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`.
+ */
+export declare function findUnusedAssets(dir: string): Promise<string[]>;
+/** Move o que `findUnusedAssets` achou para `.lixeira/imagens-<data>/`. Nada é apagado. */
+export declare function cleanUnusedAssets(dir: string): Promise<{
+    moved: number;
+    folder: string | null;
+}>;

package/dist/core/assets.js

@@ -0,0 +1,116 @@
+import { mkdir, readdir, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { emptyAnnotations, parseAnnotations } from "./annotations.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 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();
+    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;
+}
+/** 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;
+}
+/** `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;
+/**
+ * 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`.
+ */
+export async function findUnusedAssets(dir) {
+    const assetsDir = path.join(dir, ASSETS_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)))
+            continue;
+        for (const file of await readdir(root, { recursive: true })) {
+            if (!file.endsWith(".md"))
+                continue;
+            for (const [, name] of (await readText(path.join(root, file))).matchAll(MENTION)) {
+                if (name)
+                    used.add(decodeUri(name));
+            }
+        }
+    }
+    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)
+        .map((f) => `${ASSETS_DIR}/${f}`);
+}
+/** Move o que `findUnusedAssets` achou para `.lixeira/imagens-<data>/`. Nada é apagado. */
+export async function cleanUnusedAssets(dir) {
+    const unused = await findUnusedAssets(dir);
+    if (unused.length === 0)
+        return { moved: 0, folder: null };
+    const folder = path.join(".lixeira", `imagens-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+    await mkdir(path.join(dir, folder, ASSETS_DIR), { recursive: true });
+    for (const asset of unused)
+        await rename(resolveInside(dir, asset), path.join(dir, folder, asset));
+    return { moved: unused.length, folder: folder.split(path.sep).join("/") };
+}
+//# sourceMappingURL=assets.js.map

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 {};