explicai 0.1.0 → 0.2.1

package/dist/core/export/index.js

@@ -1,43 +1,59 @@
-import { copyFile, mkdir, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
-import { atomicWrite, relativePosix, resolveInside } from "../fs.js";
+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 marcada
- * "No manual" de cada página.
+ * 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);
-    const images = await loadImages(dir, collected.pages);
+    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: collected.warnings,
+        warnings,
     });
     if (format === "markdown") {
-        const out = await freshDir(path.join(root, "markdown"));
-        await copyImages(dir, images, out);
-        const file = path.join(out, "manual.md");
-        await atomicWrite(file, renderMarkdown(collected, images));
-        return result(file);
+        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 freshDir(path.join(root, "html"));
-    await copyImages(dir, images, out);
+    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");
-    await atomicWrite(html, renderHtml(collected, images));
     if (format === "html")
         return result(html);
     const pdf = path.join(root, `${slugify(collected.meta.title) || "manual"}.pdf`);
@@ -45,27 +61,91 @@ export async function exportManual(dir, format, opts = {}) {
     await printPdf(html, pdf);
     return result(pdf);
 }
-/** Cor do manual exportado. Só aceita hexadecimal de 6 dígitos; sem cor, volta à da marca. */
-export async function setManualTheme(dir, theme) {
-    if (theme.accent !== undefined && !/^#[0-9a-f]{6}$/i.test(theme.accent)) {
-        throw new Error("Cor inválida: use o formato #2b4fe0.");
-    }
+/**
+ * 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) => {
-        if (theme.accent)
-            meta.theme = { ...meta.theme, accent: theme.accent.toLowerCase() };
+        const theme = mergeTheme(meta.theme, patch);
+        if (Object.keys(theme).length)
+            meta.theme = theme;
         else
             delete meta.theme;
     });
 }
-async function freshDir(dir) {
-    await rm(dir, { recursive: true, force: true });
-    await mkdir(dir, { recursive: true });
-    return dir;
+/** 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(resolveInside(dir, asset), path.join(out, asset));
+        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

@@ -11,6 +11,7 @@ export interface Labels {
     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

@@ -10,6 +10,7 @@ const PT = {
     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",
@@ -23,6 +24,7 @@ const EN = {
     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);

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.js

@@ -1,7 +1,11 @@
-import { slugify } from "../text.js";
+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
@@ -16,8 +20,9 @@ export function renderMarkdown(collected, images) {
     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));
+            const target = pages.find((p) => p.fileName === decodeUri(file));
             return target ? `](#${hash ? hash.slice(1) : anchor(target)})` : all;
         })
             .split("\n")
@@ -57,18 +62,22 @@ function imageNotes(info, pages, L) {
     }));
     return lines;
 }
-/** Desce os títulos da página para ficarem abaixo do título dela (`level`). Ignora blocos de código. */
+/** 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;
-    return body
-        .split("\n")
-        .map((line) => {
+    lines.forEach((line, at) => {
         if (/^\s*(```|~~~)/.test(line))
             fence = !fence;
-        if (fence)
-            return line;
-        return line.replace(/^(#{1,6}) /, (_, hashes) => `${"#".repeat(Math.min(hashes.length + level, 6))} `);
-    })
-        .join("\n");
+        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.js

@@ -4,6 +4,7 @@ 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. */
@@ -42,7 +43,7 @@ export async function findBrowser() {
 export async function printPdf(htmlFile, pdfFile) {
     const browser = await findBrowser();
     if (!browser) {
-        throw new Error("Para gerar o PDF, o Explicaí usa o Chrome, o Edge ou o Chromium da sua máquina, e nenhum foi encontrado. " +
+        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-"));

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

@@ -9,8 +9,8 @@ export interface ImageInfo {
 }
 /** `../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. */
-export declare function loadImages(dir: string, pages: ExportPage[]): Promise<Map<string, ImageInfo>>;
+/** 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. */

package/dist/core/export/refs.js

@@ -1,28 +1,41 @@
 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 { slugify } from "../text.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)));
+    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. */
-export async function loadImages(dir, pages) {
+/** 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))
+            if (!asset || images.has(asset) || missing.includes(asset))
                 continue;
             const abs = resolveInside(dir, asset);
-            if (!(await exists(abs)))
+            if (!(await exists(abs))) {
+                missing.push(asset);
                 continue;
-            images.set(asset, { asset, size: await imageSize(abs), annotations: await readAnnotations(dir, asset) });
+            }
+            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;
@@ -39,10 +52,10 @@ export function pageLink(href, pages) {
     const m = /^(?:\.\/)?([^/#?]+\.md)(?:#(.+))?$/.exec(href);
     if (!m)
         return null;
-    const page = pages.find((p) => p.fileName === decodeURI(m[1] ?? ""));
+    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)}`;
+    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) {

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;

package/dist/core/export/theme.js

@@ -0,0 +1,140 @@
+import { ExplicaiError } from "../errors.js";
+import { HEADING_SLOTS } from "../types.js";
+import { contrast, contrastWithWhite, HEX, muted, overWhite, withAlpha } from "./color.js";
+import { DEFAULT_HEADINGS_FONT, DEFAULT_TEXT_FONT, FONTS, fontById, fontFaceCss, fontStack, MONO, } from "./fonts.js";
+import { checkLogoPath } from "./logo.js";
+/** Contraste mínimo do texto com o fundo (WCAG AA). */
+export const MIN_CONTRAST = 4.5;
+/** Valores de hoje: o manual sem `theme` exporta com estes. */
+export const DEFAULT_TEXT = "#151a33";
+export const DEFAULT_ACCENT = "#2b4fe0";
+export const DEFAULT_HIGHLIGHT = "#ffd43b";
+/** Opacidade do marca-texto sobre o papel (a mesma do CSS do export). */
+const HIGHLIGHT_ALPHA = 0.55;
+const SLOT_NAMES = {
+    cover: "título da capa",
+    page: "título da página",
+    h1: "título de nível 1",
+    h2: "título de nível 2",
+    h3: "título de nível 3",
+};
+const num = (n) => n.toFixed(1).replace(".", ",");
+function hexOf(value, label) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || !HEX.test(value))
+        throw new Error(`Cor inválida em ${label}: use o formato #2b4fe0.`);
+    return value.toLowerCase();
+}
+function readable(hex, label) {
+    const c = contrastWithWhite(hex);
+    if (c < MIN_CONTRAST) {
+        throw new ExplicaiError("low-contrast", `A cor de ${label} tem contraste ${num(c)}:1 com o branco; o mínimo é ${num(MIN_CONTRAST)}:1. Escolha uma cor mais escura.`, { label, ratio: c, min: MIN_CONTRAST });
+    }
+    return hex;
+}
+/** A fonte da lista com esse nome. O texto precisa de uma com itálico empacotado. */
+function fontOf(id, role) {
+    const font = typeof id === "string" ? fontById(id) : undefined;
+    const valid = FONTS.filter((f) => role === "headings" || f.italic);
+    if (!font || !valid.includes(font)) {
+        throw new Error(`Fonte fora da lista: ${String(id)}. Use uma destas: ${valid.map((f) => f.id).join(", ")}.`);
+    }
+    return font;
+}
+/** As fontes que o tema usa (as da marca, onde não houve escolha). */
+export function themeFonts(theme) {
+    return {
+        text: fontById(theme?.fonts?.text ?? DEFAULT_TEXT_FONT),
+        headings: fontById(theme?.fonts?.headings ?? DEFAULT_HEADINGS_FONT),
+    };
+}
+/** Aplica `patch` sobre o tema atual e confere tudo. Devolve o tema novo; o que não mudou continua igual. */
+export function mergeTheme(current, patch) {
+    const next = { ...current, headings: { ...current?.headings }, fonts: { ...current?.fonts } };
+    const set = (key, label, check) => {
+        if (patch[key] === undefined)
+            return;
+        const hex = hexOf(patch[key], label);
+        if (hex === null)
+            delete next[key];
+        else
+            next[key] = check ? readable(hex, label) : hex;
+    };
+    set("accent", "destaque", true);
+    set("text", "texto", true);
+    set("highlight", "realce", false);
+    if (patch.headings === null)
+        next.headings = {};
+    else if (patch.headings) {
+        for (const slot of HEADING_SLOTS) {
+            const value = patch.headings[slot];
+            if (value === undefined)
+                continue;
+            const hex = hexOf(value, SLOT_NAMES[slot]);
+            if (hex === null)
+                delete next.headings?.[slot];
+            else if (next.headings)
+                next.headings[slot] = readable(hex, SLOT_NAMES[slot]);
+        }
+    }
+    if (patch.fonts === null)
+        next.fonts = {};
+    else if (patch.fonts) {
+        for (const role of ["text", "headings"]) {
+            const id = patch.fonts[role];
+            if (id === undefined)
+                continue;
+            if (id === null)
+                delete next.fonts?.[role];
+            else if (next.fonts)
+                next.fonts[role] = fontOf(id, role).id;
+        }
+    }
+    if (patch.logo === null)
+        delete next.logo;
+    else if (patch.logo !== undefined)
+        next.logo = checkLogoPath(patch.logo);
+    // O realce é fundo: o texto por cima precisa continuar legível.
+    if (next.highlight) {
+        const c = contrast(overWhite(next.highlight, HIGHLIGHT_ALPHA), next.text ?? DEFAULT_TEXT);
+        if (c < MIN_CONTRAST) {
+            throw new ExplicaiError("low-contrast-highlight", `O texto sobre o realce tem contraste ${num(c)}:1; o mínimo é ${num(MIN_CONTRAST)}:1. Escolha um realce mais claro.`, { ratio: c, min: MIN_CONTRAST });
+        }
+    }
+    if (!Object.keys(next.headings ?? {}).length)
+        delete next.headings;
+    if (!Object.keys(next.fonts ?? {}).length)
+        delete next.fonts;
+    return next;
+}
+/** Variáveis CSS do tema, só as que mudam. Vazio quando o manual usa as cores da marca. */
+export function themeCss(theme) {
+    if (!theme)
+        return "";
+    const v = [];
+    if (theme.accent)
+        v.push(`--accent:${theme.accent}`, `--anotacao:${theme.accent}`, `--anotacao-fundo:${withAlpha(theme.accent, 0.08)}`);
+    if (theme.text)
+        v.push(`--tinta:${theme.text}`, `--grafite:${muted(theme.text)}`);
+    if (theme.highlight) {
+        v.push(`--marca:${theme.highlight}`, `--marca-faixa:${withAlpha(theme.highlight, HIGHLIGHT_ALPHA)}`, `--marca-halo:${withAlpha(theme.highlight, 0.3)}`);
+    }
+    for (const slot of HEADING_SLOTS)
+        if (theme.headings?.[slot])
+            v.push(`--t-${slot}:${theme.headings[slot]}`);
+    const fonts = themeFonts(theme);
+    if (theme.fonts?.text)
+        v.push(`--texto:${fontStack(fonts.text)}`);
+    if (theme.fonts?.headings)
+        v.push(`--display:${fontStack(fonts.headings)}`);
+    return v.length ? `:root{${v.join(";")}}` : "";
+}
+/** As fontes que vão no export: texto, títulos (sem repetir) e a de código. */
+export function usedFonts(theme) {
+    const { text, headings } = themeFonts(theme);
+    return [...new Set([text, headings, MONO])];
+}
+/** `@font-face` das fontes usadas, no mesmo formato do export. */
+export const fontFacesCss = (theme) => usedFonts(theme).map(fontFaceCss).join("\n");
+//# sourceMappingURL=theme.js.map

package/dist/core/fs.d.ts

@@ -1,7 +1,11 @@
 /** Grava num arquivo temporário e renomeia, para um travamento no meio não deixar o arquivo pela metade. */
 export declare function atomicWrite(file: string, content: string): Promise<void>;
+/** Lê UTF-8 sem o BOM que o Bloco de Notas e alguns editores do Windows põem no começo: ele quebraria o JSON e o frontmatter. */
+export declare function readText(file: string): Promise<string>;
 /** Barreira de confiança: caminhos vêm do Agent e do navegador, então nada pode sair da pasta base. */
 export declare function resolveInside(dir: string, relative: string): string;
+/** Como `resolveInside`, mas segue links simbólicos: um link dentro do manual que aponta para fora é recusado. O arquivo precisa existir. */
+export declare function resolveInsideReal(dir: string, relative: string): Promise<string>;
 /** `base.ext`, ou `base-2.ext`, `base-3.ext`… se já existir. */
 export declare function uniquePath(parent: string, base: string, ext: string): Promise<string>;
 export declare function exists(p: string): Promise<boolean>;

package/dist/core/fs.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { rename, stat, writeFile } from "node:fs/promises";
+import { readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 /** Grava num arquivo temporário e renomeia, para um travamento no meio não deixar o arquivo pela metade. */
 export async function atomicWrite(file, content) {
@@ -7,6 +7,10 @@ export async function atomicWrite(file, content) {
     await writeFile(tmp, content, "utf8");
     await rename(tmp, file);
 }
+/** Lê UTF-8 sem o BOM que o Bloco de Notas e alguns editores do Windows põem no começo: ele quebraria o JSON e o frontmatter. */
+export async function readText(file) {
+    return (await readFile(file, "utf8")).replace(/^/, "");
+}
 /** Barreira de confiança: caminhos vêm do Agent e do navegador, então nada pode sair da pasta base. */
 export function resolveInside(dir, relative) {
     const root = path.resolve(dir);
@@ -15,6 +19,14 @@ export function resolveInside(dir, relative) {
         throw new Error(`Caminho fora do manual: ${relative}`);
     return abs;
 }
+/** Como `resolveInside`, mas segue links simbólicos: um link dentro do manual que aponta para fora é recusado. O arquivo precisa existir. */
+export async function resolveInsideReal(dir, relative) {
+    const abs = resolveInside(dir, relative);
+    const [real, root] = await Promise.all([realpath(abs), realpath(path.resolve(dir))]);
+    if (real !== root && !real.startsWith(root + path.sep))
+        throw new Error(`Caminho fora do manual: ${relative}`);
+    return abs;
+}
 /** `base.ext`, ou `base-2.ext`, `base-3.ext`… se já existir. */
 export async function uniquePath(parent, base, ext) {
     for (let i = 1;; i++) {