explicai 0.1.0 → 0.2.0

package/dist/core/pages.js

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { readFile, rm } from "node:fs/promises";
+import { rm, stat } from "node:fs/promises";
 import path from "node:path";
+import { ExplicaiError } from "./errors.js";
 import { joinFrontmatter, splitFrontmatter } from "./frontmatter.js";
-import { atomicWrite, relativePosix, resolveInside, uniquePath } from "./fs.js";
-import { PAGES_DIR, readManual, updateManual } from "./manuals.js";
+import { atomicWrite, readText, relativePosix, resolveInside, uniquePath } from "./fs.js";
+import { inQueue, PAGES_DIR, readManual, updateManual } from "./manuals.js";
 import { slugify } from "./text.js";
 import { childrenOf, clampIndex, findIn, findNode, flatten } from "./tree.js";
 import { PAGE_STATUSES } from "./types.js";
@@ -17,16 +18,35 @@ export async function addPage(dir, opts) {
         body: opts.body ?? "",
         file: await newPageFile(dir, title),
     };
-    await updateManual(dir, (meta) => {
-        const siblings = childrenOf(meta.pages, opts.parentId);
-        siblings.splice(clampIndex(opts.index, siblings.length), 0, { id: page.id, file: page.file, children: [] });
-    });
+    // Arquivo primeiro: se gravar falhar, a árvore não aponta para o que não existe. Se a árvore falhar, desfaz o arquivo.
     await writePageFile(dir, page);
+    page.version = await fileVersion(dir, page.file);
+    try {
+        await updateManual(dir, (meta) => {
+            const siblings = childrenOf(meta.pages, opts.parentId);
+            siblings.splice(clampIndex(opts.index, siblings.length), 0, { id: page.id, file: page.file, children: [] });
+        });
+    }
+    catch (err) {
+        await rm(resolveInside(dir, page.file), { force: true });
+        throw err;
+    }
     return page;
 }
 export async function readPage(dir, id) {
     const { node } = findNode((await readManual(dir)).pages, id);
-    return { id, ...(await readPageFile(dir, node.file)), file: node.file };
+    return { id, ...(await readPageFile(dir, node.file)), file: node.file, version: await fileVersion(dir, node.file) };
+}
+/** Versão do arquivo: mtime + tamanho. Basta para saber se alguém mexeu nele desde a última leitura. */
+async function fileVersion(dir, file) {
+    const s = await stat(resolveInside(dir, file));
+    return `${s.mtimeMs}-${s.size}`;
+}
+/** Dentro da fila da pasta: recusa a gravação se o arquivo mudou no disco depois de `expected`. */
+async function assertVersion(dir, file, expected) {
+    if ((await fileVersion(dir, file)) === expected)
+        return;
+    throw new ExplicaiError("disk-conflict", "Esta página foi alterada fora do Studio depois que você a abriu. Recarregue do disco ou mantenha a sua versão.");
 }
 /**
  * Árvore do manual com o título de cada página (que fica no frontmatter). Lê o manual.json uma vez.
@@ -54,7 +74,7 @@ export async function readPageTree(dir) {
 async function readPageFile(dir, file) {
     let text;
     try {
-        text = await readFile(resolveInside(dir, file), "utf8");
+        text = await readText(resolveInside(dir, file));
     }
     catch (err) {
         if (err.code === "ENOENT") {
@@ -75,8 +95,10 @@ async function readPageFile(dir, file) {
 /**
  * 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 async function updatePage(dir, id, patch) {
+export async function updatePage(dir, id, patch, opts = {}) {
     const page = await readPage(dir, id);
     if (patch.status !== undefined && !PAGE_STATUSES.includes(patch.status)) {
         throw new Error(`Status inválido: ${patch.status}. Use ${PAGE_STATUSES.join(", ")}.`);
@@ -87,10 +109,23 @@ export async function updatePage(dir, id, patch) {
         ...(patch.title === undefined ? {} : { title: patch.title.trim() }),
         ...(patch.body === undefined ? {} : { body: patch.body }),
     };
-    if (slugify(next.title) === slugify(page.title)) {
-        await writePageFile(dir, next);
-        return next;
+    const sameName = opts.fileName === "keep" ||
+        (opts.fileName === "sync" ? fileMatchesTitle(page.file, next.title) : slugify(next.title) === slugify(page.title));
+    const { ifMatch } = opts;
+    if (sameName) {
+        if (ifMatch === undefined)
+            await writePageFile(dir, next);
+        else {
+            await inQueue(dir, async () => {
+                await assertVersion(dir, page.file, ifMatch);
+                await writePageFile(dir, next);
+            });
+        }
+        return { ...next, version: await fileVersion(dir, next.file) };
     }
+    // shortcut: com renomeio, a checagem e a gravação não são atômicas (janela de milissegundos); upgrade se aparecer na prática.
+    if (ifMatch !== undefined)
+        await inQueue(dir, () => assertVersion(dir, page.file, ifMatch));
     next.file = await newPageFile(dir, next.title);
     await writePageFile(dir, next);
     const others = await updateManual(dir, (meta) => {
@@ -99,7 +134,13 @@ export async function updatePage(dir, id, patch) {
     });
     await rm(resolveInside(dir, page.file), { force: true });
     await relink(dir, others.map((n) => n.file), page.file, next.file);
-    return next;
+    return { ...next, version: await fileVersion(dir, next.file) };
+}
+/** O arquivo já tem o nome do título: `titulo.md` ou `titulo-2.md` (sufixo que `uniquePath` põe). */
+function fileMatchesTitle(file, title) {
+    const base = path.posix.basename(file, ".md");
+    const want = slugify(title);
+    return base === want || (base.startsWith(`${want}-`) && /^\d+$/.test(base.slice(want.length + 1)));
 }
 /** Links entre páginas são `./arquivo.md`. Quando um arquivo muda de nome, as outras páginas acompanham. */
 async function relink(dir, files, from, to) {
@@ -110,7 +151,7 @@ async function relink(dir, files, from, to) {
     const pattern = new RegExp(`(\\]\\()(?:\\./)?${escaped}(?=[)#])`, "g");
     for (const file of files) {
         const abs = resolveInside(dir, file);
-        const text = await readFile(abs, "utf8");
+        const text = await readText(abs);
         const updated = text.replace(pattern, `$1./${name(to)}`);
         if (updated !== text)
             await atomicWrite(abs, updated);

package/dist/core/redact.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Troca o arquivo de `assets/` pela versão com as tarjas já queimadas (o navegador desenha e envia).
+ * Valida o formato e que a imagem abre, grava num temporário e renomeia por cima do caminho de sempre,
+ * então Markdown e marcações seguem valendo. O original não vai para a lixeira: some, junto com
+ * qualquer cópia idêntica dele na pasta de imagens sem uso.
+ */
+export declare function redactAsset(dir: string, assetPath: string, data: Uint8Array): Promise<void>;
+/** A pasta do manual está dentro de um repositório git? Procura `.git` na pasta e nas de cima. */
+export declare function insideGitRepo(dir: string): Promise<boolean>;

package/dist/core/redact.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+import { readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { assetFile } from "./assets.js";
+import { ExplicaiError } from "./errors.js";
+import { imageSize } from "./export/imageSize.js";
+import { exists } from "./fs.js";
+import { ASSETS_DIR } from "./manuals.js";
+const FORMATS = { ".png": "png", ".jpg": "jpeg", ".jpeg": "jpeg", ".webp": "webp" };
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+/** Blocos do PNG que carregam metadados (EXIF e texto): não entram no arquivo tarjado. */
+const PNG_METADATA = new Set(["eXIf", "tEXt", "zTXt", "iTXt"]);
+const invalid = (why) => new ExplicaiError("redact-invalid", `A imagem tarjada não pôde ser gravada: ${why}.`, { why });
+/** PNG sem metadados e sem nenhum byte depois do IEND (o erro do aCropalypse). */
+function cleanPng(b) {
+    if (!b.subarray(0, 8).equals(PNG_SIGNATURE))
+        throw invalid("o conteúdo não é um PNG");
+    const kept = [PNG_SIGNATURE];
+    for (let i = 8; i + 12 <= b.length;) {
+        const end = i + 12 + b.readUInt32BE(i);
+        if (end > b.length)
+            break;
+        const type = b.toString("ascii", i + 4, i + 8);
+        if (!PNG_METADATA.has(type))
+            kept.push(b.subarray(i, end));
+        if (type === "IEND")
+            return Buffer.concat(kept);
+        i = end;
+    }
+    throw invalid("o PNG está incompleto");
+}
+// shortcut: JPEG e WebP vêm do canvas do navegador, que não grava EXIF; aqui só recusa o que trouxer.
+// Quando outro cliente puder enviar, troque a recusa por limpeza dos segmentos APP1/EXIF.
+function cleanJpeg(b) {
+    const end = b.lastIndexOf(Buffer.from([0xff, 0xd9]));
+    if (b[0] !== 0xff || b[1] !== 0xd8 || end < 0)
+        throw invalid("o conteúdo não é um JPEG");
+    const clean = b.subarray(0, end + 2);
+    if (clean.includes("Exif\0\0", 0, "latin1"))
+        throw invalid("o arquivo traz EXIF");
+    return clean;
+}
+function cleanWebp(b) {
+    if (b.length < 12 || b.toString("ascii", 0, 4) !== "RIFF" || b.toString("ascii", 8, 12) !== "WEBP") {
+        throw invalid("o conteúdo não é um WebP");
+    }
+    const total = b.readUInt32LE(4) + 8;
+    if (total > b.length)
+        throw invalid("o WebP está incompleto");
+    const clean = b.subarray(0, total);
+    if (clean.includes("EXIF", 12, "latin1"))
+        throw invalid("o arquivo traz EXIF");
+    return clean;
+}
+/**
+ * Troca o arquivo de `assets/` pela versão com as tarjas já queimadas (o navegador desenha e envia).
+ * Valida o formato e que a imagem abre, grava num temporário e renomeia por cima do caminho de sempre,
+ * então Markdown e marcações seguem valendo. O original não vai para a lixeira: some, junto com
+ * qualquer cópia idêntica dele na pasta de imagens sem uso.
+ */
+export async function redactAsset(dir, assetPath, data) {
+    const target = assetFile(dir, assetPath);
+    const format = FORMATS[path.extname(target).toLowerCase()];
+    if (!format)
+        throw new ExplicaiError("redact-type", "Só dá para ocultar dados em PNG, JPEG ou WebP.");
+    if (!(await exists(target)))
+        throw new ExplicaiError("redact-missing", `A imagem ${assetPath} não existe.`, { asset: assetPath });
+    const original = await readFile(target);
+    const clean = { png: cleanPng, jpeg: cleanJpeg, webp: cleanWebp }[format](Buffer.from(data));
+    const tmp = `${target}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tmp, clean);
+        const after = await imageSize(tmp);
+        // tamanho livre: recortar e reduzir resolução (T-118, T-119) reusam esta troca
+        if (!after)
+            throw invalid("a imagem não pôde ser lida");
+        await rename(tmp, target);
+    }
+    finally {
+        await rm(tmp, { force: true });
+    }
+    await dropTrashedCopies(dir, path.basename(target), original);
+}
+/** Cópias idênticas ao original em `.lixeira/imagens-*` (imagens sem uso) também são apagadas. */
+async function dropTrashedCopies(dir, name, original) {
+    const trash = path.join(dir, ".lixeira");
+    if (!(await exists(trash)))
+        return;
+    for (const folder of await readdir(trash)) {
+        const copy = path.join(trash, folder, ASSETS_DIR, name);
+        if (folder.startsWith("imagens-") &&
+            (await stat(copy).catch(() => null))?.isFile() &&
+            (await readFile(copy)).equals(original)) {
+            await rm(copy);
+        }
+    }
+}
+/** A pasta do manual está dentro de um repositório git? Procura `.git` na pasta e nas de cima. */
+export async function insideGitRepo(dir) {
+    for (let cur = path.resolve(dir);; cur = path.dirname(cur)) {
+        if (await exists(path.join(cur, ".git")))
+            return true;
+        if (path.dirname(cur) === cur)
+            return false;
+    }
+}
+//# sourceMappingURL=redact.js.map

package/dist/core/text.d.ts

@@ -1,3 +1,5 @@
 export declare function slugify(title: string): string;
 /** Texto obrigatório, sem espaços nas pontas. `what` entra na mensagem: "O título da página não pode ficar vazio." */
 export declare function required(value: string, what: string): string;
+/** decodeURI que não lança: um `%` solto num link ou numa imagem (`100%.png`) é texto comum, não motivo para a exportação falhar. */
+export declare function decodeUri(text: string): string;

package/dist/core/text.js

@@ -16,4 +16,13 @@ export function required(value, what) {
         throw new Error(`O ${what} não pode ficar vazio.`);
     return v;
 }
+/** decodeURI que não lança: um `%` solto num link ou numa imagem (`100%.png`) é texto comum, não motivo para a exportação falhar. */
+export function decodeUri(text) {
+    try {
+        return decodeURI(text);
+    }
+    catch {
+        return text;
+    }
+}
 //# sourceMappingURL=text.js.map

package/dist/core/trash.js

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm } from "node:fs/promises";
+import { mkdir, readdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import { splitFrontmatter } from "./frontmatter.js";
-import { atomicWrite, exists, relativePosix, resolveInside, uniquePath } from "./fs.js";
+import { atomicWrite, exists, readText, relativePosix, resolveInside, uniquePath } from "./fs.js";
 import { PAGES_DIR, updateManual } from "./manuals.js";
 import { childrenOf, clampIndex, findIn, findNode, flatten } from "./tree.js";
 /** Páginas excluídas ficam aqui até serem restauradas ou apagadas à mão. */
@@ -17,11 +17,16 @@ export async function listTrash(dir) {
         const entryFile = path.join(root, trashId, "entry.json");
         if (!(await exists(entryFile)))
             continue;
-        const entry = JSON.parse(await readFile(entryFile, "utf8"));
-        const pageFile = path.join(root, trashId, entry.node.file);
-        const data = (await exists(pageFile)) ? splitFrontmatter(await readFile(pageFile, "utf8")).data : {};
-        const title = typeof data.title === "string" ? data.title : "";
-        items.push({ trashId, pageId: entry.node.id, title, pages: flatten([entry.node]).length, deletedAt: entry.deletedAt });
+        try {
+            const entry = JSON.parse(await readText(entryFile));
+            const pageFile = path.join(root, trashId, entry.node.file);
+            const data = (await exists(pageFile)) ? splitFrontmatter(await readText(pageFile)).data : {};
+            const title = typeof data.title === "string" ? data.title : "";
+            items.push({ trashId, pageId: entry.node.id, title, pages: flatten([entry.node]).length, deletedAt: entry.deletedAt });
+        }
+        catch {
+            // entry.json quebrado ou de forma errada: pula o item em vez de esconder a lixeira toda
+        }
     }
     return items.sort((a, b) => b.deletedAt.localeCompare(a.deletedAt));
 }
@@ -53,7 +58,7 @@ export async function removePage(dir, id) {
  */
 export async function restorePage(dir, trashId) {
     const trash = resolveInside(path.join(dir, TRASH_DIR), trashId);
-    const entry = JSON.parse(await readFile(path.join(trash, "entry.json"), "utf8"));
+    const entry = JSON.parse(await readText(path.join(trash, "entry.json")));
     for (const n of flatten([entry.node])) {
         const from = path.join(trash, n.file);
         let to = resolveInside(dir, n.file);

package/dist/core/types.d.ts

@@ -18,9 +18,29 @@ export interface ManualMeta {
     theme?: ManualTheme;
     pages: PageNode[];
 }
+/** Onde o manual exportado tem título: a capa, o título da página e os níveis 1 a 3 do editor. */
+export declare const HEADING_SLOTS: readonly ["cover", "page", "h1", "h2", "h3"];
+export type HeadingSlot = (typeof HEADING_SLOTS)[number];
+/**
+ * Cores do manual exportado, todas em hexadecimal (#2b4fe0). Campo ausente = cor da marca.
+ * Texto, títulos e destaque precisam de contraste de 4,5:1 com o branco.
+ */
 export interface ManualTheme {
-    /** Cor de destaque em hexadecimal (#2b4fe0): títulos, links e números dos passos no HTML e no PDF. */
+    /** Destaque: links, números dos passos e marcações sobre os prints. */
     accent?: string;
+    /** Texto do manual. */
+    text?: string;
+    /** Marca-texto: capa, "Resultado:" e destaque das imagens. */
+    highlight?: string;
+    /** Cor de cada tipo de título. Sem escolha, saem pretos. */
+    headings?: Partial<Record<HeadingSlot, string>>;
+    /** Fontes do manual, pelo nome da lista de `export/fonts.ts` (`inter`, `lora`…). Sem escolha: Atkinson e Archivo. */
+    fonts?: {
+        text?: string;
+        headings?: string;
+    };
+    /** Logo do cliente na capa e no topo do sumário: `assets/<arquivo>`, PNG, JPG ou SVG de até 1 MB. */
+    logo?: string;
 }
 export interface Manual {
     /** Caminho absoluto da pasta do manual. */
@@ -37,6 +57,8 @@ export interface Page {
     /** Conteúdo em Markdown, sem o frontmatter. */
     body: string;
     file: string;
+    /** Impressão do arquivo no disco (mtime+tamanho). Muda quando alguém edita fora do Studio. */
+    version?: string;
 }
 /** Coordenadas normalizadas de 0 a 1, relativas à largura e à altura da imagem. */
 export interface Point {
@@ -76,9 +98,12 @@ export interface Hotspot extends Rect {
     id: string;
     target: HotspotTarget;
 }
+/** Tamanho de exibição da imagem: pequena, média ou larga. Sem o campo, a imagem aparece como sempre. */
+export type ImageDisplay = "s" | "m" | "full";
 /** Conteúdo do JSON que fica ao lado de cada imagem (`assets/foto.png.json`). */
 export interface Annotations {
     version: typeof FORMAT_VERSION;
+    display?: ImageDisplay;
     markers: Marker[];
     highlights: Highlight[];
     arrows: Arrow[];

package/dist/core/types.js

@@ -1,5 +1,7 @@
 /** Formato em disco de um manual. Ver docs/manual-format.md. */
 export const FORMAT_VERSION = 1;
+/** Onde o manual exportado tem título: a capa, o título da página e os níveis 1 a 3 do editor. */
+export const HEADING_SLOTS = ["cover", "page", "h1", "h2", "h3"];
 /** Etapa da página no fluxo de aprovação. Sem status no arquivo, a página é rascunho. */
 export const PAGE_STATUSES = ["rascunho", "revisao", "aprovado", "publicado"];
 //# sourceMappingURL=types.js.map

package/dist/core/versions.js

@@ -1,7 +1,7 @@
-import { mkdir, readdir, readFile } from "node:fs/promises";
+import { mkdir, readdir } from "node:fs/promises";
 import path from "node:path";
 import { joinFrontmatter, splitFrontmatter } from "./frontmatter.js";
-import { atomicWrite, exists, resolveInside, uniquePath } from "./fs.js";
+import { atomicWrite, exists, readText, resolveInside, uniquePath } from "./fs.js";
 import { readManual, updateManual } from "./manuals.js";
 import { readPage, updatePage } from "./pages.js";
 import { findNode } from "./tree.js";
@@ -67,7 +67,7 @@ export async function publishVersion(dir, pageId, versionId) {
 async function readVersionFile(file, published) {
     let text;
     try {
-        text = await readFile(file, "utf8");
+        text = await readText(file);
     }
     catch (err) {
         if (err.code === "ENOENT")

package/dist/server/errorPage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Página de erro para quem abre o Studio no navegador e o servidor não consegue entregar o editor.
+ * Sem dependências: mesma composição do ErrorPage do editor (web/src/components/ErrorPage.tsx); mexeu lá, alinhe aqui.
+ * O trecho entre asteriscos no título leva o marca-texto.
+ */
+type Lang = "pt" | "en";
+export declare function pickLang(acceptLanguage: string | undefined): Lang;
+export declare function errorPage(status: number, code: string, lang: Lang): string;
+export {};

package/dist/server/errorPage.js

@@ -0,0 +1,122 @@
+/**
+ * Página de erro para quem abre o Studio no navegador e o servidor não consegue entregar o editor.
+ * Sem dependências: mesma composição do ErrorPage do editor (web/src/components/ErrorPage.tsx); mexeu lá, alinhe aqui.
+ * O trecho entre asteriscos no título leva o marca-texto.
+ */
+import { FONTS, fontFaceCss } from "../core/export/fonts.js";
+const TEXTS = {
+    "web-missing": {
+        pt: [
+            "O editor *não foi encontrado*",
+            "O servidor do Studio está no ar, mas a pasta do editor está vazia ou não existe. Rode npm run build (ou instale o pacote de novo) e abra esta página outra vez.",
+        ],
+        en: [
+            "The editor *was not found*",
+            "The Studio server is running, but the editor folder is empty or missing. Run npm run build (or reinstall the package) and open this page again.",
+        ],
+    },
+    "forbidden-host": {
+        pt: ["Acesso só *deste computador*", "O Studio só aceita pedidos deste computador. Abra-o por localhost ou 127.0.0.1."],
+        en: [
+            "Access from *this computer* only",
+            "The Studio only accepts requests from this computer. Open it through localhost or 127.0.0.1.",
+        ],
+    },
+    "forbidden-origin": {
+        pt: ["Acesso só *deste computador*", "O Studio só aceita pedidos deste computador. Abra-o por localhost ou 127.0.0.1."],
+        en: [
+            "Access from *this computer* only",
+            "The Studio only accepts requests from this computer. Open it through localhost or 127.0.0.1.",
+        ],
+    },
+    "malformed-url": {
+        pt: ["Endereço *malformado*", "Este endereço tem um % que o Studio não entende. Volte para o início e escolha o manual."],
+        en: ["Malformed *address*", "This address has a % the Studio cannot read. Go back to the start and pick the manual."],
+    },
+    "not-found": {
+        pt: ["Página *não encontrada*", "Este endereço não existe no Studio. Volte para o início e escolha o manual."],
+        en: ["Page *not found*", "This address does not exist in the Studio. Go back to the start and pick the manual."],
+    },
+    error: {
+        pt: [
+            "O Studio *não conseguiu responder*",
+            "Algo deu errado no servidor. Recarregue a página; se continuar, feche o comando explicai no terminal e rode de novo.",
+        ],
+        en: [
+            "The Studio *could not respond*",
+            "Something went wrong on the server. Reload the page; if it keeps happening, stop the explicai command in the terminal and run it again.",
+        ],
+    },
+};
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] ?? c);
+export function pickLang(acceptLanguage) {
+    return /^\s*pt/i.test(acceptLanguage ?? "") ? "pt" : "en";
+}
+const UI = {
+    pt: { home: "Ir para o início", reload: "Recarregar", copy: "Copiar código", copied: "Copiado" },
+    en: { home: "Go to the start", reload: "Reload", copy: "Copy code", copied: "Copied" },
+};
+// As fontes da marca vêm da rota /api/fonts do próprio servidor (sem CDN); se não carregarem, cai na do sistema.
+const FACES = FONTS.filter((f) => f.id === "atkinson-hyperlegible-next" || f.id === "archivo")
+    .map((f) => fontFaceCss(f).replaceAll("url(fonts/", "url(/api/fonts/"))
+    .join("");
+// Mesmos valores de web/src/styles/tokens.css e do wordmark de base.css.
+const CSS = `${FACES}
+:root{color-scheme:light dark;--p:#f5f6fa;--t:#151a33;--g:#575e78;--c:#2b4fe0;--s:#fff;--l:#dce0eb;--m:rgba(255,212,59,.55);--a:#2b4fe0}
+@media(prefers-color-scheme:dark){:root{--p:#0e1120;--t:#eceef7;--g:#9ca3bd;--c:#7088ff;--s:#0e1120;--l:#2a3050;--m:rgba(255,212,59,.3);--a:#ffd43b}}
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;display:flex;flex-direction:column;background:var(--p);color:var(--t);font:17px/1.5 "Atkinson Hyperlegible Next","Segoe UI",system-ui,sans-serif}
+header,main{width:100%;max-width:64rem;margin:0 auto}
+header{padding:1.25rem 1.25rem}
+.brand{display:inline-flex;align-items:center;gap:.5rem;color:var(--t);text-decoration:none;min-height:44px}
+.wordmark{font:800 21px/1 Archivo,"Arial Narrow",system-ui,sans-serif;font-stretch:112%;letter-spacing:-.035em}
+.wordmark i{position:relative;display:inline-block;font-style:normal}
+.wordmark i:after{content:"";position:absolute;left:.06em;bottom:.77em;width:.115em;height:.19em;background:var(--a);transform:skewX(-32deg);transform-origin:bottom left}
+.sub{font:12px ui-monospace,Consolas,monospace;color:var(--g)}
+main{margin:auto;padding:3rem 1.5rem;display:grid;justify-items:start;align-content:start;gap:1.25rem}
+main>*{max-width:min(42rem,100%)}
+@media(min-width:640px){header{padding-inline:2.25rem}main{padding-inline:2.5rem}}
+h1{margin:0;font:800 clamp(2.25rem,7vw,3rem)/1.08 Archivo,"Arial Narrow",system-ui,sans-serif;font-stretch:108%;letter-spacing:-.025em;text-wrap:balance;outline:none}
+mark{background:var(--m);color:inherit;padding:0 .25rem;margin:0 -.25rem;border-radius:2px;-webkit-box-decoration-break:clone;box-decoration-break:clone}
+p.text{text-wrap:pretty;margin:0;max-width:65ch;font-size:1.125rem;color:var(--g)}
+.actions{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1.25rem;padding-top:.25rem}
+.btn{display:inline-flex;align-items:center;min-height:44px;padding:0 1.25rem;border:0;border-radius:3px;background:var(--c);color:var(--s);font:700 1rem "Atkinson Hyperlegible Next","Segoe UI",system-ui,sans-serif;text-decoration:none;cursor:pointer}
+.link{min-height:44px;padding:0 .25rem;border:0;background:none;color:var(--c);font:700 1rem "Atkinson Hyperlegible Next","Segoe UI",system-ui,sans-serif;cursor:pointer}
+.link:hover{text-decoration:underline;text-underline-offset:4px}
+.btn:focus-visible,.link:focus-visible,.brand:focus-visible{outline:3px solid var(--t);outline-offset:2px}
+.code{display:flex;align-items:center;gap:.25rem;max-width:100%;margin-top:.5rem;padding:.125rem .25rem .125rem .75rem;border:1px dashed var(--l);border-radius:3px;font:12px ui-monospace,Consolas,monospace;color:var(--g)}
+.code code{min-width:0;padding:.375rem 0;overflow-wrap:anywhere}
+.code button{flex:none;min-height:44px;padding:0 .5rem;border:0;background:none;color:var(--c);font:700 12px "Atkinson Hyperlegible Next","Segoe UI",system-ui,sans-serif;cursor:pointer}
+.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}
+`;
+const LOGO = `<svg width="26" height="26" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="16" fill="#2B4FE0"/><rect x="26" y="27" width="11" height="25" rx="2.5" fill="#fff"/><path d="M27.5 22 35.5 22 44.5 9.5 36.5 9.5Z" fill="#FFD43B" stroke="#FFD43B" stroke-width="1.5" stroke-linejoin="round"/></svg>`;
+export function errorPage(status, code, lang) {
+    const [title, text] = (TEXTS[code] ?? TEXTS.error)?.[lang] ?? ["", ""];
+    const ui = UI[lang];
+    const plain = title.replaceAll("*", "");
+    const marked = esc(title).replace(/\*([^*]+)\*/g, "<mark>$1</mark>");
+    return `<!doctype html>
+<html lang="${lang === "pt" ? "pt-BR" : "en"}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(plain)} · Explicaí Studio</title>
+<style>${CSS}</style>
+</head>
+<body>
+<header><a class="brand" href="/" aria-label="Explicaí Studio">${LOGO}<span class="wordmark" aria-hidden="true">explica<i>ı</i></span><span class="sub" aria-hidden="true">studio</span></a></header>
+<main role="alert">
+<h1 id="t" tabindex="-1">${marked}</h1>
+<p class="text">${esc(text)}</p>
+<div class="actions"><a class="btn" href="/">${esc(ui.home)}</a><button class="link" type="button" onclick="location.reload()">${esc(ui.reload)}</button></div>
+<div class="code"><code>HTTP ${status} ${esc(code)}</code><button type="button" id="c">${esc(ui.copy)}</button><span class="sr" role="status" id="s"></span></div>
+</main>
+<script>
+document.getElementById("t").focus();
+document.getElementById("c").onclick=function(){var b=this;navigator.clipboard&&navigator.clipboard.writeText("HTTP ${status} ${esc(code)}").then(function(){b.textContent=${JSON.stringify(ui.copied)};document.getElementById("s").textContent=${JSON.stringify(ui.copied)}})};
+</script>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=errorPage.js.map

package/dist/server/http.d.ts

@@ -1,7 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 export declare class HttpError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** Identifica o erro para a interface traduzir (a mensagem fica em português para curl e MCP). */
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, 
+    /** Identifica o erro para a interface traduzir (a mensagem fica em português para curl e MCP). */
+    code?: string | undefined);
 }
 /** O que um handler devolve. O servidor transforma em resposta HTTP. */
 export type Reply = {
@@ -12,12 +16,16 @@ export type Reply = {
     kind: "file";
     path: string;
     cache: string;
+    untrusted: boolean;
 };
 export declare const json: (body: unknown, status?: number) => Reply;
-export declare const file: (filePath: string, cache?: string) => Reply;
-export declare function send(res: ServerResponse, reply: Reply): Promise<void>;
+/** `untrusted`: arquivo do manual (/files/), que pode ser um SVG com script; sai com CSP e sandbox. */
+export declare const file: (filePath: string, cache?: string, untrusted?: boolean) => Reply;
+export declare function send(res: ServerResponse, reply: Reply, req?: IncomingMessage): Promise<void>;
 export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
 export declare function readBody(req: IncomingMessage, limit: number): Promise<Uint8Array>;
 export declare function readJson(req: IncomingMessage): Promise<Record<string, unknown>>;
 /** Status HTTP para um erro vindo do core: "não encontrado" e arquivo inexistente viram 404, o resto 400. */
 export declare function statusOf(err: unknown): number;
+/** Texto do erro para a resposta: erro de arquivo do Node traz o caminho absoluto, então vira frase fixa. */
+export declare function publicMessage(err: unknown): string;