explicai 0.1.0 → 0.2.0

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++) {

package/dist/core/index.d.ts

@@ -1,9 +1,12 @@
 export { emptyAnnotations, parseAnnotations } from "./annotations.js";
 export { cleanUnusedAssets, findUnusedAssets, readAnnotations, saveAsset, writeAnnotations } from "./assets.js";
-export { EXPORT_DIR, EXPORT_FORMATS, type ExportFormat, type ExportResult, exportManual, findBrowser, setManualTheme, } from "./export/index.js";
-export { resolveInside } from "./fs.js";
+export { ExplicaiError } from "./errors.js";
+export { FONTS, FONTS_DIR, type FontSpec, fontFiles } from "./export/fonts.js";
+export { EXPORT_DIR, EXPORT_FORMATS, type ExportFormat, type ExportResult, exportManual, findBrowser, logoSizeError, setManualLogo, setManualTheme, } from "./export/index.js";
+export { resolveInside, resolveInsideReal } from "./fs.js";
 export { createManual, listManuals, readManual } from "./manuals.js";
 export { addPage, movePage, type PageTreeNode, readPage, readPageTree, updatePage } from "./pages.js";
+export { insideGitRepo, redactAsset } from "./redact.js";
 export { slugify } from "./text.js";
 export { listTrash, removePage, restorePage, TRASH_DIR, type TrashItem } from "./trash.js";
 export { flatten } from "./tree.js";

package/dist/core/index.js

@@ -1,9 +1,12 @@
 export { emptyAnnotations, parseAnnotations } from "./annotations.js";
 export { cleanUnusedAssets, findUnusedAssets, readAnnotations, saveAsset, writeAnnotations } from "./assets.js";
-export { EXPORT_DIR, EXPORT_FORMATS, exportManual, findBrowser, setManualTheme, } from "./export/index.js";
-export { resolveInside } from "./fs.js";
+export { ExplicaiError } from "./errors.js";
+export { FONTS, FONTS_DIR, fontFiles } from "./export/fonts.js";
+export { EXPORT_DIR, EXPORT_FORMATS, exportManual, findBrowser, logoSizeError, setManualLogo, setManualTheme, } from "./export/index.js";
+export { resolveInside, resolveInsideReal } from "./fs.js";
 export { createManual, listManuals, readManual } from "./manuals.js";
 export { addPage, movePage, readPage, readPageTree, updatePage } from "./pages.js";
+export { insideGitRepo, redactAsset } from "./redact.js";
 export { slugify } from "./text.js";
 export { listTrash, removePage, restorePage, TRASH_DIR } from "./trash.js";
 export { flatten } from "./tree.js";

package/dist/core/manuals.d.ts

@@ -13,5 +13,11 @@ export declare function createManual(workspace: string, opts: {
 export declare function listManuals(workspace: string): Promise<Manual[]>;
 export declare function readManual(dir: string): Promise<ManualMeta>;
 export declare function writeManual(dir: string, meta: ManualMeta): Promise<void>;
-/** Lê o manual, aplica a mudança e grava de volta. Concentra o ciclo ler-alterar-gravar da árvore. */
+/**
+ * Lê o manual, aplica a mudança e grava de volta. Concentra o ciclo ler-alterar-gravar da árvore.
+ * Chamadas da mesma pasta entram numa fila, senão duas leituras simultâneas se atropelam e a última
+ * gravação apaga a mudança da outra. `change` não pode chamar updateManual da mesma pasta (travaria).
+ */
 export declare function updateManual<T>(dir: string, change: (meta: ManualMeta) => T): Promise<T>;
+/** Roda `task` na fila da pasta (a mesma do updateManual). `task` não pode entrar na fila da mesma pasta de novo. */
+export declare function inQueue<T>(dir: string, task: () => Promise<T>): Promise<T>;

package/dist/core/manuals.js

@@ -1,6 +1,6 @@
-import { mkdir, readdir, readFile } from "node:fs/promises";
+import { mkdir, readdir } from "node:fs/promises";
 import path from "node:path";
-import { atomicWrite, exists, uniquePath } from "./fs.js";
+import { atomicWrite, exists, readText, uniquePath } from "./fs.js";
 import { required, slugify } from "./text.js";
 import { FORMAT_VERSION } from "./types.js";
 const META_FILE = "manual.json";
@@ -41,7 +41,7 @@ export async function listManuals(workspace) {
 export async function readManual(dir) {
     let meta;
     try {
-        meta = JSON.parse(await readFile(path.join(dir, META_FILE), "utf8"));
+        meta = JSON.parse(await readText(path.join(dir, META_FILE)));
     }
     catch (err) {
         if (err instanceof SyntaxError)
@@ -56,11 +56,31 @@ export async function readManual(dir) {
 export async function writeManual(dir, meta) {
     await atomicWrite(path.join(dir, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
 }
-/** Lê o manual, aplica a mudança e grava de volta. Concentra o ciclo ler-alterar-gravar da árvore. */
-export async function updateManual(dir, change) {
-    const meta = await readManual(dir);
-    const result = change(meta);
-    await writeManual(dir, meta);
-    return result;
+const queues = new Map();
+/**
+ * Lê o manual, aplica a mudança e grava de volta. Concentra o ciclo ler-alterar-gravar da árvore.
+ * Chamadas da mesma pasta entram numa fila, senão duas leituras simultâneas se atropelam e a última
+ * gravação apaga a mudança da outra. `change` não pode chamar updateManual da mesma pasta (travaria).
+ */
+export function updateManual(dir, change) {
+    return inQueue(dir, async () => {
+        const meta = await readManual(dir);
+        const result = change(meta);
+        await writeManual(dir, meta);
+        return result;
+    });
+}
+/** Roda `task` na fila da pasta (a mesma do updateManual). `task` não pode entrar na fila da mesma pasta de novo. */
+export function inQueue(dir, task) {
+    const key = path.resolve(dir);
+    const run = (queues.get(key) ?? Promise.resolve()).catch(() => { }).then(task);
+    queues.set(key, run);
+    // Fila vazia: tira a pasta do Map. Falha já chega a quem chamou por `run`.
+    const clean = () => {
+        if (queues.get(key) === run)
+            queues.delete(key);
+    };
+    run.then(clean, clean);
+    return run;
 }
 //# sourceMappingURL=manuals.js.map

package/dist/core/pages.d.ts

@@ -26,11 +26,16 @@ export declare function readPageTree(dir: string): Promise<PageTreeNode[]>;
 /**
  * Quando o título muda, o arquivo é renomeado para acompanhar, para a pasta continuar legível
  * para pessoas e IAs. O id no frontmatter não muda, e é ele que as áreas clicáveis usam.
+ * `fileName`: "keep" grava o título no mesmo arquivo (digitação em andamento); "sync" renomeia
+ * se o nome do arquivo não combina com o título (ao parar de digitar ou sair da página).
  */
 export declare function updatePage(dir: string, id: string, patch: {
     title?: string;
     body?: string;
     status?: PageStatus;
+}, opts?: {
+    fileName?: "keep" | "sync" | undefined;
+    ifMatch?: string | undefined;
 }): Promise<Page>;
 export declare function movePage(dir: string, id: string, to: {
     parentId: string | null;