explicai 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,29 @@
+import { type CollectOptions } from "./collect.js";
+import { type ThemePatch } from "./theme.js";
+export { logoSizeError } from "./logo.js";
+export { findBrowser } from "./pdf.js";
+/** Pasta da exportação, dentro do manual. Cada exportação substitui a anterior do mesmo formato. */
+export declare const EXPORT_DIR = "exportacao";
+export type ExportFormat = "html" | "pdf" | "markdown";
+export declare const EXPORT_FORMATS: ExportFormat[];
+export interface ExportResult {
+    format: ExportFormat;
+    /** Arquivo principal, relativo à pasta do manual (`exportacao/html/index.html`). */
+    file: string;
+    pages: number;
+    /** Páginas que ficaram de fora e imagens que não existem, com o motivo. */
+    warnings: string[];
+}
+/**
+ * Exporta o manual: HTML (um arquivo com sumário, para publicar ou abrir no navegador), PDF (impresso
+ * a partir desse HTML) ou Markdown (um arquivo só, para quem lê com IA). Usa a Versão do manual
+ * de cada página.
+ */
+export declare function exportManual(dir: string, format: ExportFormat, opts?: CollectOptions): Promise<ExportResult>;
+/**
+ * Muda a aparência do manual exportado. Só os campos de `patch` mudam (`null` apaga o campo);
+ * cores sem contraste suficiente são recusadas.
+ */
+export declare function setManualTheme(dir: string, patch: ThemePatch): Promise<void>;
+/** Grava o logo em `assets/` (PNG, JPG ou SVG, até 1 MB) e o põe no tema. Devolve o caminho. */
+export declare function setManualLogo(dir: string, fileName: string, data: Uint8Array): Promise<string>;

package/dist/core/export/index.js

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { saveAsset } from "../assets.js";
+import { ExplicaiError } from "../errors.js";
+import { atomicWrite, relativePosix, resolveInside, resolveInsideReal } from "../fs.js";
+import { updateManual } from "../manuals.js";
+import { slugify } from "../text.js";
+import { collectPages } from "./collect.js";
+import { FONTS_DIR, fontFiles } from "./fonts.js";
+import { renderHtml } from "./html.js";
+import { checkLogoFile, checkLogoPath, LOGO_EXT, LOGO_MAX_BYTES, logoSizeError, logoTypeError } from "./logo.js";
+import { renderMarkdown } from "./markdown.js";
+import { printPdf } from "./pdf.js";
+import { loadImages } from "./refs.js";
+import { mergeTheme, usedFonts } from "./theme.js";
+export { logoSizeError } from "./logo.js";
+export { findBrowser } from "./pdf.js";
+/** Pasta da exportação, dentro do manual. Cada exportação substitui a anterior do mesmo formato. */
+export const EXPORT_DIR = "exportacao";
+export const EXPORT_FORMATS = ["html", "pdf", "markdown"];
+/**
+ * Exporta o manual: HTML (um arquivo com sumário, para publicar ou abrir no navegador), PDF (impresso
+ * a partir desse HTML) ou Markdown (um arquivo só, para quem lê com IA). Usa a Versão do manual
+ * de cada página.
+ */
+export async function exportManual(dir, format, opts = {}) {
+    const collected = await collectPages(dir, opts);
+    if (opts.onlyApproved && collected.pages.length === 0) {
+        throw new ExplicaiError("no-approved-pages", "Nenhuma página está aprovada ou publicada. Aprove uma página ou exporte todas.");
+    }
+    const missing = [];
+    const broken = [];
+    const images = await loadImages(dir, collected.pages, missing, broken);
+    const warnings = [...collected.warnings, ...missing.map((asset) => `Imagem não encontrada: ${asset}`), ...broken];
+    const root = resolveInside(dir, EXPORT_DIR);
+    const result = (file) => ({
+        format,
+        file: relativePosix(dir, file),
+        pages: collected.pages.length,
+        warnings,
+    });
+    if (format === "markdown") {
+        const out = await buildThenSwap(path.join(root, "markdown"), async (tmp) => {
+            await copyImages(dir, images, tmp);
+            await atomicWrite(path.join(tmp, "manual.md"), renderMarkdown(collected, images));
+        });
+        return result(path.join(out, "manual.md"));
+    }
+    const out = await buildThenSwap(path.join(root, "html"), async (tmp) => {
+        await copyImages(dir, images, tmp);
+        await copyFonts(tmp, collected.meta.theme);
+        const logo = await copyLogo(dir, tmp, collected.meta.theme, warnings);
+        await atomicWrite(path.join(tmp, "index.html"), renderHtml(collected, images, logo));
+    });
+    const html = path.join(out, "index.html");
+    if (format === "html")
+        return result(html);
+    const pdf = path.join(root, `${slugify(collected.meta.title) || "manual"}.pdf`);
+    await rm(pdf, { force: true });
+    await printPdf(html, pdf);
+    return result(pdf);
+}
+/**
+ * Muda a aparência do manual exportado. Só os campos de `patch` mudam (`null` apaga o campo);
+ * cores sem contraste suficiente são recusadas.
+ */
+export async function setManualTheme(dir, patch) {
+    if (typeof patch.logo === "string")
+        await checkLogoFile(dir, checkLogoPath(patch.logo));
+    await updateManual(dir, (meta) => {
+        const theme = mergeTheme(meta.theme, patch);
+        if (Object.keys(theme).length)
+            meta.theme = theme;
+        else
+            delete meta.theme;
+    });
+}
+/** Grava o logo em `assets/` (PNG, JPG ou SVG, até 1 MB) e o põe no tema. Devolve o caminho. */
+export async function setManualLogo(dir, fileName, data) {
+    if (!LOGO_EXT.test(path.extname(fileName)))
+        throw logoTypeError();
+    if (data.byteLength > LOGO_MAX_BYTES)
+        throw logoSizeError();
+    const logo = await saveAsset(dir, fileName, data);
+    try {
+        await setManualTheme(dir, { logo });
+    }
+    catch (err) {
+        await rm(resolveInside(dir, logo), { force: true }); // não deixa o arquivo novo órfão
+        throw err;
+    }
+    return logo;
+}
+/** Gera em pasta temporária ao lado e só no fim troca pela `final`: se algo falhar, a exportação anterior fica intacta. */
+async function buildThenSwap(final, build) {
+    const tmp = path.join(path.dirname(final), `.${path.basename(final)}-${randomUUID()}`);
+    await mkdir(tmp, { recursive: true });
+    try {
+        await build(tmp);
+        // Antigo vai para o lado, não para o lixo: se o rename falhar (EBUSY no Windows), ele volta.
+        const old = `${tmp}.old`;
+        const hadOld = await rename(final, old).then(() => true, () => false);
+        try {
+            await rename(tmp, final);
+        }
+        catch (err) {
+            if (hadOld)
+                await rename(old, final).catch(() => undefined);
+            throw err;
+        }
+        if (hadOld)
+            await rm(old, { recursive: true, force: true });
+    }
+    catch (err) {
+        await rm(tmp, { recursive: true, force: true });
+        throw err;
+    }
+    return final;
+}
+/** Copia só as imagens usadas, mantendo `assets/` para os caminhos do HTML e do Markdown valerem. */
+async function copyImages(dir, images, out) {
+    await mkdir(path.join(out, "assets"), { recursive: true });
+    for (const asset of images.keys())
+        await copyFile(await resolveInsideReal(dir, asset), path.join(out, asset));
+}
+/** Copia o logo do tema. Sumiu do disco: avisa e o manual sai sem ele. */
+async function copyLogo(dir, out, theme, warnings) {
+    if (!theme?.logo)
+        return null;
+    try {
+        const logo = checkLogoPath(theme.logo);
+        await copyFile(await resolveInsideReal(dir, logo), path.join(out, logo));
+        return logo;
+    }
+    catch (err) {
+        const missing = err.code === "ENOENT";
+        warnings.push(missing ? `Logo não encontrado: ${theme.logo}` : `Logo não copiado (${theme.logo}): ${err.message}`);
+        return null;
+    }
+}
+/** Só as fontes que o tema usa vão com o HTML (e a licença OFL de cada uma), para o manual abrir igual sem internet. */
+async function copyFonts(out, theme) {
+    await mkdir(path.join(out, "fonts"), { recursive: true });
+    for (const font of usedFonts(theme)) {
+        for (const name of [...fontFiles(font).map((f) => f.file), `OFL-${font.id}.txt`]) {
+            await copyFile(new URL(name, FONTS_DIR), path.join(out, "fonts", name));
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,17 @@
+/** Textos que o Explicaí escreve no manual exportado. Seguem o idioma do manual, não o da interface. */
+export interface Labels {
+    toc: string;
+    pages: (n: number) => string;
+    colophon: string;
+    missingImage: string;
+    goTo: string;
+    legend: string;
+    noDescription: string;
+    hotspotUrl: (href: string) => string;
+    hotspotPage: (title: string) => string;
+    removedPage: string;
+    untitled: string;
+    callouts: Record<string, string>;
+}
+/** Manual em português (pt, pt-BR, pt-PT) recebe os textos em português; os outros, em inglês. */
+export declare const labelsFor: (language: string) => Labels;

package/dist/core/export/labels.js

@@ -0,0 +1,31 @@
+const PT = {
+    toc: "Sumário",
+    pages: (n) => `${n} ${n === 1 ? "página" : "páginas"}`,
+    colophon: "Manual feito com o Explicaí Studio.",
+    missingImage: "imagem não encontrada",
+    goTo: "Ir para",
+    legend: "Legenda da imagem",
+    noDescription: "(sem descrição)",
+    hotspotUrl: (href) => `Área clicável: leva a ${href}`,
+    hotspotPage: (title) => `Área clicável: leva à página "${title}"`,
+    removedPage: "removida",
+    untitled: "Sem título",
+    callouts: { tip: "Dica", warning: "Atenção", caution: "Erro", note: "Nota" },
+};
+const EN = {
+    toc: "Contents",
+    pages: (n) => `${n} ${n === 1 ? "page" : "pages"}`,
+    colophon: "Manual made with Explicaí Studio.",
+    missingImage: "image not found",
+    goTo: "Go to",
+    legend: "Image legend",
+    noDescription: "(no description)",
+    hotspotUrl: (href) => `Clickable area: goes to ${href}`,
+    hotspotPage: (title) => `Clickable area: goes to the page "${title}"`,
+    removedPage: "removed",
+    untitled: "Untitled",
+    callouts: { tip: "Tip", warning: "Warning", caution: "Error", note: "Note" },
+};
+/** Manual em português (pt, pt-BR, pt-PT) recebe os textos em português; os outros, em inglês. */
+export const labelsFor = (language) => (language.toLowerCase().startsWith("pt") ? PT : EN);
+//# sourceMappingURL=labels.js.map

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

@@ -0,0 +1,10 @@
+import { ExplicaiError } from "../errors.js";
+/** Tamanho máximo do logo: um logo é pequeno, e arquivo grande pesa em todo HTML exportado. */
+export declare const LOGO_MAX_BYTES: number;
+export declare const LOGO_EXT: RegExp;
+export declare const logoTypeError: () => ExplicaiError;
+export declare const logoSizeError: () => ExplicaiError;
+/** O caminho vira `assets/<arquivo>`: sem pasta, sem `..`, sem barra invertida, só PNG, JPG ou SVG. */
+export declare function checkLogoPath(value: unknown): string;
+/** Confere o arquivo no disco: existe e cabe em 1 MB. */
+export declare function checkLogoFile(dir: string, logo: string): Promise<void>;

package/dist/core/export/logo.js

@@ -0,0 +1,29 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { ExplicaiError } from "../errors.js";
+import { exists, resolveInside } from "../fs.js";
+/** Tamanho máximo do logo: um logo é pequeno, e arquivo grande pesa em todo HTML exportado. */
+export const LOGO_MAX_BYTES = 1024 * 1024;
+export const LOGO_EXT = /^\.(png|jpe?g|svg)$/i;
+const LOGO_TYPE_MSG = "O logo precisa ser PNG, JPG ou SVG.";
+const LOGO_SIZE_MSG = "O logo passa de 1 MB. Reduza o arquivo e envie de novo.";
+export const logoTypeError = () => new ExplicaiError("logo-type", LOGO_TYPE_MSG);
+export const logoSizeError = () => new ExplicaiError("logo-size", LOGO_SIZE_MSG, { max: 1 });
+/** O caminho vira `assets/<arquivo>`: sem pasta, sem `..`, sem barra invertida, só PNG, JPG ou SVG. */
+export function checkLogoPath(value) {
+    if (typeof value !== "string" || !/^assets\/[^/\\]+$/.test(value) || value.includes("..")) {
+        throw new ExplicaiError("logo-path", "O logo precisa estar em assets/ (assets/logo.png).");
+    }
+    if (!LOGO_EXT.test(path.posix.extname(value)))
+        throw logoTypeError();
+    return value;
+}
+/** Confere o arquivo no disco: existe e cabe em 1 MB. */
+export async function checkLogoFile(dir, logo) {
+    const abs = resolveInside(dir, logo);
+    if (!(await exists(abs)))
+        throw new ExplicaiError("logo-missing", `O logo ${logo} não existe no manual.`, { logo });
+    if ((await stat(abs)).size > LOGO_MAX_BYTES)
+        throw logoSizeError();
+}
+//# sourceMappingURL=logo.js.map

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

@@ -0,0 +1,8 @@
+import type { Collected } from "./collect.js";
+import { type ImageInfo } from "./refs.js";
+/**
+ * O manual num Markdown só, pensado para quem lê com IA: sumário, uma seção por página na ordem da
+ * árvore, títulos um nível abaixo do da página, e depois de cada print a legenda e as áreas clicáveis
+ * em texto (a IA não vê a imagem, mas lê o que ela aponta).
+ */
+export declare function renderMarkdown(collected: Collected, images: Map<string, ImageInfo>): string;

package/dist/core/export/markdown.js

@@ -0,0 +1,83 @@
+import { decodeUri, slugify } from "../text.js";
+import { exportLevels } from "./headings.js";
+import { labelsFor } from "./labels.js";
+import { assetFromSrc } from "./refs.js";
+import { TEXT_COLORS } from "./textColors.js";
+const IMAGE_LINE = /!\[([^\]]*)\]\(([^)\s]+)\)/g;
+/** Cor do texto: no Markdown para IA fica só o texto. */
+const COLOR_SPAN = /<span data-color="([a-z]+)">([\s\S]*?)<\/span>/g;
+const PAGE_LINK = /\]\((?:\.\/)?([^/)#\s]+\.md)(#[^)\s]*)?\)/g;
+/**
+ * O manual num Markdown só, pensado para quem lê com IA: sumário, uma seção por página na ordem da
+ * árvore, títulos um nível abaixo do da página, e depois de cada print a legenda e as áreas clicáveis
+ * em texto (a IA não vê a imagem, mas lê o que ela aponta).
+ */
+export function renderMarkdown(collected, images) {
+    const { meta, pages } = collected;
+    const L = labelsFor(meta.language);
+    const anchor = (p) => slugify(`${p.number} ${p.title}`);
+    const toc = pages.map((p) => `${"  ".repeat(p.depth)}- [${p.number} ${p.title}](#${anchor(p)})`).join("\n");
+    const sections = pages.map((page) => {
+        const level = Math.min(page.depth + 2, 6);
+        const body = shiftHeadings(page.body, level)
+            .replace(COLOR_SPAN, (all, name, text) => (Object.hasOwn(TEXT_COLORS, name) ? text : all))
+            .replace(PAGE_LINK, (all, file, hash) => {
+            const target = pages.find((p) => p.fileName === decodeUri(file));
+            return target ? `](#${hash ? hash.slice(1) : anchor(target)})` : all;
+        })
+            .split("\n")
+            .map((line) => {
+            // A legenda vai depois da linha do print, com a mesma indentação (o print pode estar num passo).
+            const indent = /^\s*/.exec(line)?.[0] ?? "";
+            const notes = [];
+            const out = line.replace(IMAGE_LINE, (all, alt, src) => {
+                const asset = assetFromSrc(src);
+                const info = asset ? images.get(asset) : undefined;
+                if (!info)
+                    return all;
+                notes.push(...imageNotes(info, pages, L));
+                return `![${alt}](${info.asset})`;
+            });
+            if (!notes.length)
+                return out;
+            return `${out}\n\n${indent}> ${L.legend}:\n${notes.map((n) => `${indent}> ${n}`).join("\n")}`;
+        })
+            .join("\n");
+        return `${"#".repeat(level)} ${page.number} ${page.title}\n\n${body.trim()}`;
+    });
+    return `# ${meta.title}\n\n## ${L.toc}\n\n${toc}\n\n${sections.join("\n\n")}\n`;
+}
+/** Legenda e áreas clicáveis do print, em texto, uma por linha. */
+function imageNotes(info, pages, L) {
+    const { markers, hotspots } = info.annotations;
+    const lines = [...markers]
+        .sort((a, b) => a.n - b.n)
+        .map((m) => `${m.n}. ${m.label ?? L.noDescription}`)
+        .concat(hotspots.map((h) => {
+        if (h.target.type === "url")
+            return L.hotspotUrl(h.target.href);
+        const id = h.target.pageId;
+        const page = pages.find((p) => p.id === id);
+        return L.hotspotPage(page?.title ?? L.removedPage);
+    }));
+    return lines;
+}
+/** Põe os títulos da página abaixo do título dela (`level`), sem pular nível. Ignora blocos de código. */
+function shiftHeadings(body, level) {
+    const lines = body.split("\n");
+    const found = [];
+    let fence = false;
+    lines.forEach((line, at) => {
+        if (/^\s*(```|~~~)/.test(line))
+            fence = !fence;
+        const m = fence ? null : /^(#{1,6}) /.exec(line);
+        if (m?.[1])
+            found.push({ at, hashes: m[1].length });
+    });
+    const levels = exportLevels(found.map((f) => f.hashes), level);
+    found.forEach((f, i) => {
+        lines[f.at] = `${"#".repeat(levels[i] ?? 6)} ${(lines[f.at] ?? "").slice(f.hashes + 1)}`;
+    });
+    return lines.join("\n");
+}
+//# sourceMappingURL=markdown.js.map

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

@@ -0,0 +1,6 @@
+export declare function findBrowser(): Promise<string | null>;
+/**
+ * Imprime o HTML exportado em PDF com o Chrome (ou Edge) da máquina, sem janela.
+ * Usa um perfil temporário: com o perfil normal, um Chrome já aberto "engolia" o pedido.
+ */
+export declare function printPdf(htmlFile: string, pdfFile: string): Promise<void>;

package/dist/core/export/pdf.js

@@ -0,0 +1,68 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { ExplicaiError } from "../errors.js";
+import { exists } from "../fs.js";
+const run = promisify(execFile);
+/** Onde costumam ficar Chrome, Edge e Chromium. EXPLICAI_BROWSER aponta outro. */
+function candidates() {
+    const env = process.env;
+    const custom = env.EXPLICAI_BROWSER ? [env.EXPLICAI_BROWSER] : [];
+    if (process.platform === "win32") {
+        const roots = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA].filter(Boolean);
+        return custom.concat(roots.flatMap((r) => [
+            path.join(r, "Google", "Chrome", "Application", "chrome.exe"),
+            path.join(r, "Microsoft", "Edge", "Application", "msedge.exe"),
+            path.join(r, "Chromium", "Application", "chrome.exe"),
+        ]));
+    }
+    if (process.platform === "darwin") {
+        return custom.concat([
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]);
+    }
+    const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const names = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"];
+    return custom.concat(names.flatMap((n) => dirs.map((d) => path.join(d, n))));
+}
+export async function findBrowser() {
+    for (const file of candidates())
+        if (await exists(file))
+            return file;
+    return null;
+}
+/**
+ * Imprime o HTML exportado em PDF com o Chrome (ou Edge) da máquina, sem janela.
+ * Usa um perfil temporário: com o perfil normal, um Chrome já aberto "engolia" o pedido.
+ */
+export async function printPdf(htmlFile, pdfFile) {
+    const browser = await findBrowser();
+    if (!browser) {
+        throw new ExplicaiError("no-browser", "Para gerar o PDF, o Explicaí usa o Chrome, o Edge ou o Chromium da sua máquina, e nenhum foi encontrado. " +
+            "Instale um deles ou informe o caminho na variável EXPLICAI_BROWSER.");
+    }
+    const profile = await mkdtemp(path.join(tmpdir(), "explicai-pdf-"));
+    try {
+        await run(browser, [
+            "--headless=new",
+            "--disable-gpu",
+            "--no-first-run",
+            "--no-default-browser-check",
+            `--user-data-dir=${profile}`,
+            "--no-pdf-header-footer",
+            `--print-to-pdf=${pdfFile}`,
+            pathToFileURL(htmlFile).href,
+        ], { timeout: 120_000 });
+    }
+    finally {
+        await rm(profile, { recursive: true, force: true }).catch(() => { });
+    }
+    if (!(await exists(pdfFile)))
+        throw new Error("O navegador terminou sem gerar o PDF.");
+}
+//# sourceMappingURL=pdf.js.map

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

@@ -0,0 +1,24 @@
+import type { Annotations } from "../types.js";
+import type { ExportPage } from "./collect.js";
+import { type Size } from "./imageSize.js";
+export interface ImageInfo {
+    /** Caminho no manual: `assets/tela.png`. */
+    asset: string;
+    size: Size | null;
+    annotations: Annotations;
+}
+/** `../assets/tela.png` (como está na página) → `assets/tela.png`. Imagem de fora do manual: null. */
+export declare function assetFromSrc(src: string): string | null;
+/** Marcações e tamanho de cada imagem do manual usada nas páginas. Imagem apagada fica de fora e vai para `missing`. */
+export declare function loadImages(dir: string, pages: ExportPage[], missing?: string[], warnings?: string[]): Promise<Map<string, ImageInfo>>;
+/** Id da seção de uma página no manual exportado. */
+export declare const pageAnchor: (pageId: string) => string;
+/** Id de um título dentro de uma página: `#secao` de um link vira este id. */
+export declare const headingAnchor: (pageId: string, text: string) => string;
+/**
+ * Link entre páginas (`./arquivo.md` ou `./arquivo.md#secao`) → âncora dentro do manual exportado.
+ * Outro tipo de link: null (fica como está).
+ */
+export declare function pageLink(href: string, pages: ExportPage[]): string | null;
+/** Só endereços seguros saem como link no manual exportado. */
+export declare function safeHref(href: string): string | null;

package/dist/core/export/refs.js

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { emptyAnnotations } from "../annotations.js";
+import { readAnnotations } from "../assets.js";
+import { ExplicaiError } from "../errors.js";
+import { exists, resolveInside } from "../fs.js";
+import { decodeUri, slugify } from "../text.js";
+import { imageSize } from "./imageSize.js";
+const IMAGE = /!\[[^\]]*\]\(([^)\s]+)/g;
+/** `../assets/tela.png` (como está na página) → `assets/tela.png`. Imagem de fora do manual: null. */
+export function assetFromSrc(src) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(src))
+        return null;
+    const p = path.posix.normalize(path.posix.join("pages", decodeUri(src)));
+    return p.startsWith("assets/") ? p : null;
+}
+/** Marcações e tamanho de cada imagem do manual usada nas páginas. Imagem apagada fica de fora e vai para `missing`. */
+export async function loadImages(dir, pages, missing = [], warnings = []) {
+    const images = new Map();
+    for (const page of pages) {
+        for (const [, src] of page.body.matchAll(IMAGE)) {
+            const asset = src && assetFromSrc(src);
+            if (!asset || images.has(asset) || missing.includes(asset))
+                continue;
+            const abs = resolveInside(dir, asset);
+            if (!(await exists(abs))) {
+                missing.push(asset);
+                continue;
+            }
+            let annotations;
+            try {
+                annotations = await readAnnotations(dir, asset);
+            }
+            catch (err) {
+                if (!(err instanceof ExplicaiError))
+                    throw err;
+                warnings.push(err.message); // imagem pura, sem marcações
+            }
+            images.set(asset, { asset, size: await imageSize(abs), annotations: annotations ?? emptyAnnotations() });
+        }
+    }
+    return images;
+}
+/** Id da seção de uma página no manual exportado. */
+export const pageAnchor = (pageId) => `p-${pageId}`;
+/** Id de um título dentro de uma página: `#secao` de um link vira este id. */
+export const headingAnchor = (pageId, text) => `p-${pageId}--${slugify(text)}`;
+/**
+ * Link entre páginas (`./arquivo.md` ou `./arquivo.md#secao`) → âncora dentro do manual exportado.
+ * Outro tipo de link: null (fica como está).
+ */
+export function pageLink(href, pages) {
+    const m = /^(?:\.\/)?([^/#?]+\.md)(?:#(.+))?$/.exec(href);
+    if (!m)
+        return null;
+    const page = pages.find((p) => p.fileName === decodeUri(m[1] ?? ""));
+    if (!page)
+        return null;
+    return `#${m[2] ? headingAnchor(page.id, decodeUri(m[2])) : pageAnchor(page.id)}`;
+}
+/** Só endereços seguros saem como link no manual exportado. */
+export function safeHref(href) {
+    if (/^(#|mailto:|https?:\/\/)/i.test(href))
+        return href;
+    return null;
+}
+//# sourceMappingURL=refs.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Cor do texto no manual exportado (fundo branco), pelo nome salvo em `<span data-color="…">`.
+ * Os mesmos nomes estão no editor (web/src/features/editor/textColor.ts), com a cor de cada tema em tokens.css.
+ */
+export declare const TEXT_COLORS: Record<string, string>;
+/** `<span data-color="red">`, só com nome da paleta. Devolve o nome ou null. */
+export declare function colorSpanOpen(html: string): string | null;

package/dist/core/export/textColors.js

@@ -0,0 +1,18 @@
+/**
+ * Cor do texto no manual exportado (fundo branco), pelo nome salvo em `<span data-color="…">`.
+ * Os mesmos nomes estão no editor (web/src/features/editor/textColor.ts), com a cor de cada tema em tokens.css.
+ */
+export const TEXT_COLORS = {
+    gray: "#5c6478",
+    red: "#c3261b",
+    orange: "#b04a00",
+    green: "#17793a",
+    blue: "#1f58d6",
+    purple: "#7a3cc8",
+};
+/** `<span data-color="red">`, só com nome da paleta. Devolve o nome ou null. */
+export function colorSpanOpen(html) {
+    const name = /^<span data-color="([a-z]+)">$/.exec(html)?.[1];
+    return name && Object.hasOwn(TEXT_COLORS, name) ? name : null;
+}
+//# sourceMappingURL=textColors.js.map

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

@@ -0,0 +1,28 @@
+import { type HeadingSlot, type ManualTheme } from "../types.js";
+import { type FontSpec } from "./fonts.js";
+/** Contraste mínimo do texto com o fundo (WCAG AA). */
+export declare const MIN_CONTRAST = 4.5;
+/** Valores de hoje: o manual sem `theme` exporta com estes. */
+export declare const DEFAULT_TEXT = "#151a33";
+export declare const DEFAULT_ACCENT = "#2b4fe0";
+export declare const DEFAULT_HIGHLIGHT = "#ffd43b";
+/** Mudança no tema: campo ausente fica como está, `null` apaga o campo. */
+export type ThemePatch = Partial<Record<"accent" | "text" | "highlight", string | null>> & {
+    headings?: Partial<Record<HeadingSlot, string | null>> | null;
+    fonts?: Partial<Record<"text" | "headings", string | null>> | null;
+    /** Caminho do logo em `assets/`; `null` tira o logo. */
+    logo?: string | null;
+};
+/** As fontes que o tema usa (as da marca, onde não houve escolha). */
+export declare function themeFonts(theme: ManualTheme | undefined): {
+    text: FontSpec;
+    headings: FontSpec;
+};
+/** Aplica `patch` sobre o tema atual e confere tudo. Devolve o tema novo; o que não mudou continua igual. */
+export declare function mergeTheme(current: ManualTheme | undefined, patch: ThemePatch): ManualTheme;
+/** Variáveis CSS do tema, só as que mudam. Vazio quando o manual usa as cores da marca. */
+export declare function themeCss(theme: ManualTheme | undefined): string;
+/** As fontes que vão no export: texto, títulos (sem repetir) e a de código. */
+export declare function usedFonts(theme: ManualTheme | undefined): FontSpec[];
+/** `@font-face` das fontes usadas, no mesmo formato do export. */
+export declare const fontFacesCss: (theme: ManualTheme | undefined) => string;