explicai 0.1.0 → 0.2.1

package/dist/core/export/callout.js

@@ -0,0 +1,26 @@
+/** Cor de cada tipo de alerta no manual exportado (fundo branco). O de `note` segue a cor de destaque do manual. */
+export const CALLOUT_COLORS = {
+    tip: "#17793a",
+    warning: "#b04a00",
+    caution: "#c3261b",
+    note: "#2b4fe0",
+};
+const MARKER = /^\[!(TIP|WARNING|CAUTION|NOTE)\][ \t]*\n?/i;
+/**
+ * Alerta GFM (`> [!TIP]` na primeira linha da citação): devolve o tipo e o corpo sem o marcador.
+ * Qualquer outra citação, inclusive `[!IMPORTANT]`, volta null e sai como citação comum.
+ */
+export function readCallout(tokens) {
+    const [first, ...rest] = tokens;
+    if (first?.type !== "paragraph")
+        return null;
+    const [lead, ...more] = first.tokens;
+    const m = lead?.type === "text" ? MARKER.exec(lead.raw) : null;
+    if (!lead || !m?.[1])
+        return null;
+    const left = lead.raw.slice(m[0].length);
+    const inline = left ? [{ ...lead, raw: left, text: left }, ...more] : more;
+    const body = inline.length ? [{ ...first, tokens: inline }, ...rest] : rest;
+    return { type: m[1].toLowerCase(), body };
+}
+//# sourceMappingURL=callout.js.map

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

@@ -20,8 +20,8 @@ export interface CollectOptions {
     onlyApproved?: boolean;
 }
 /**
- * As páginas na ordem da árvore, com o texto que vai para o manual final: a versão marcada
- * "No manual" quando existe, senão o texto atual. Página com problema fica de fora e vira aviso.
+ * As páginas na ordem da árvore, com o texto que vai para o manual final: a Versão do manual
+ * quando existe, senão o texto atual. Página com problema fica de fora e vira aviso.
  * A numeração conta só as páginas que entram, então o sumário não fica com buracos.
  */
 export declare function collectPages(dir: string, opts?: CollectOptions): Promise<Collected>;

package/dist/core/export/collect.js

@@ -4,8 +4,8 @@ import { readVersion } from "../versions.js";
 import { labelsFor } from "./labels.js";
 const APPROVED = ["aprovado", "publicado"];
 /**
- * As páginas na ordem da árvore, com o texto que vai para o manual final: a versão marcada
- * "No manual" quando existe, senão o texto atual. Página com problema fica de fora e vira aviso.
+ * As páginas na ordem da árvore, com o texto que vai para o manual final: a Versão do manual
+ * quando existe, senão o texto atual. Página com problema fica de fora e vira aviso.
  * A numeração conta só as páginas que entram, então o sumário não fica com buracos.
  */
 export async function collectPages(dir, opts = {}) {

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

@@ -0,0 +1,11 @@
+/** Contas de cor do tema do manual: hexadecimal de 6 dígitos, contraste WCAG com branco e com outra cor. */
+export declare const HEX: RegExp;
+/** Contraste entre duas cores, de 1 a 21. */
+export declare const contrast: (a: string, b: string) => number;
+export declare const contrastWithWhite: (hex: string) => number;
+/** `#rrggbb` com transparência, como `rgba()`. */
+export declare const withAlpha: (hex: string, alpha: number) => string;
+/** A cor sobre o papel branco, com a transparência dada: o que a pessoa vê de um marca-texto. */
+export declare const overWhite: (hex: string, alpha: number) => string;
+/** Versão mais clara da cor, para texto secundário: a mais clara que ainda passa de 4,5:1 com o branco. */
+export declare function muted(hex: string, min?: number): string;

package/dist/core/export/color.js

@@ -0,0 +1,33 @@
+/** Contas de cor do tema do manual: hexadecimal de 6 dígitos, contraste WCAG com branco e com outra cor. */
+export const HEX = /^#[0-9a-f]{6}$/i;
+const rgb = (hex) => [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+const toHex = (c) => `#${c.map((n) => Math.round(n).toString(16).padStart(2, "0")).join("")}`;
+function luminance(c) {
+    const [r, g, b] = c.map((n) => {
+        const s = n / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+const ratio = (a, b) => {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+};
+const WHITE = [255, 255, 255];
+/** Contraste entre duas cores, de 1 a 21. */
+export const contrast = (a, b) => ratio(rgb(a), rgb(b));
+export const contrastWithWhite = (hex) => ratio(rgb(hex), WHITE);
+/** `#rrggbb` com transparência, como `rgba()`. */
+export const withAlpha = (hex, alpha) => `rgba(${rgb(hex).join(",")},${alpha})`;
+/** A cor sobre o papel branco, com a transparência dada: o que a pessoa vê de um marca-texto. */
+export const overWhite = (hex, alpha) => toHex(rgb(hex).map((n) => n * alpha + 255 * (1 - alpha)));
+/** Versão mais clara da cor, para texto secundário: a mais clara que ainda passa de 4,5:1 com o branco. */
+export function muted(hex, min = 4.5) {
+    for (const keep of [0.8, 0.85, 0.9, 0.95]) {
+        const next = toHex(rgb(hex).map((n) => n * keep + 255 * (1 - keep)));
+        if (contrastWithWhite(next) >= min)
+            return next;
+    }
+    return hex;
+}
+//# sourceMappingURL=color.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * Fontes que o manual exportado pode usar. Todas OFL, empacotadas na pasta `fonts/` da raiz do pacote
+ * (copiadas do @fontsource por `npm run fonts:sync`). O export copia só as escolhidas, então o HTML abre offline.
+ */
+export interface FontSpec {
+    /** Nome do pacote do @fontsource, sem escopo: `inter`. É o valor gravado em `theme.fonts`. */
+    id: string;
+    family: string;
+    kind: "sans" | "serif";
+    /** Uma fonte variável (um arquivo para todos os pesos); senão, os arquivos de peso 400 e 700. */
+    variable: boolean;
+    /** Tem itálico empacotado: só essas servem para o texto do manual. */
+    italic: boolean;
+}
+/** Pasta das fontes (OFL), na raiz do pacote: o mesmo caminho vale de `src/` e de `dist/`. */
+export declare const FONTS_DIR: URL;
+/** Atkinson (texto) e Archivo (títulos) são as da marca, usadas quando o manual não escolhe outra. */
+export declare const DEFAULT_TEXT_FONT = "atkinson-hyperlegible-next";
+export declare const DEFAULT_HEADINGS_FONT = "archivo";
+export declare const FONTS: FontSpec[];
+/** Código do manual: sempre sai com ela, não é escolha. */
+export declare const MONO: FontSpec;
+export declare const fontById: (id: string) => FontSpec | undefined;
+interface FontFile {
+    file: string;
+    weight: string;
+    style: "normal" | "italic";
+}
+/** Os arquivos woff2 (latin) da fonte, com o nome que o @fontsource dá. */
+export declare function fontFiles(f: FontSpec): FontFile[];
+/** O `@font-face` de cada arquivo da fonte, apontando para `fonts/`. */
+export declare const fontFaceCss: (f: FontSpec) => string;
+/** Valor de `font-family`: a fonte e, se não carregar, uma parecida do sistema. */
+export declare const fontStack: (f: FontSpec) => string;
+export {};

package/dist/core/export/fonts.js

@@ -0,0 +1,40 @@
+/** Pasta das fontes (OFL), na raiz do pacote: o mesmo caminho vale de `src/` e de `dist/`. */
+export const FONTS_DIR = new URL("../../../fonts/", import.meta.url);
+/** Atkinson (texto) e Archivo (títulos) são as da marca, usadas quando o manual não escolhe outra. */
+export const DEFAULT_TEXT_FONT = "atkinson-hyperlegible-next";
+export const DEFAULT_HEADINGS_FONT = "archivo";
+export const FONTS = [
+    { id: "atkinson-hyperlegible-next", family: "Atkinson Hyperlegible Next", kind: "sans", variable: false, italic: true },
+    { id: "inter", family: "Inter", kind: "sans", variable: true, italic: true },
+    { id: "source-sans-3", family: "Source Sans 3", kind: "sans", variable: true, italic: true },
+    { id: "source-serif-4", family: "Source Serif 4", kind: "serif", variable: true, italic: true },
+    { id: "lora", family: "Lora", kind: "serif", variable: true, italic: true },
+    { id: "archivo", family: "Archivo", kind: "sans", variable: true, italic: false },
+    { id: "montserrat", family: "Montserrat", kind: "sans", variable: true, italic: false },
+    { id: "playfair-display", family: "Playfair Display", kind: "serif", variable: true, italic: false },
+];
+/** Código do manual: sempre sai com ela, não é escolha. */
+export const MONO = { id: "jetbrains-mono", family: "JetBrains Mono", kind: "sans", variable: true, italic: false };
+export const fontById = (id) => FONTS.find((f) => f.id === id);
+/** Os arquivos woff2 (latin) da fonte, com o nome que o @fontsource dá. */
+export function fontFiles(f) {
+    const name = (axis, style) => `${f.id}-latin-${axis}-${style}.woff2`;
+    if (f.variable) {
+        const files = [{ file: name("wght", "normal"), weight: "100 900", style: "normal" }];
+        if (f.italic)
+            files.push({ file: name("wght", "italic"), weight: "100 900", style: "italic" });
+        return files;
+    }
+    const files = [{ file: name("400", "normal"), weight: "400", style: "normal" }];
+    if (f.italic)
+        files.push({ file: name("400", "italic"), weight: "400", style: "italic" });
+    files.push({ file: name("700", "normal"), weight: "700", style: "normal" });
+    return files;
+}
+/** O `@font-face` de cada arquivo da fonte, apontando para `fonts/`. */
+export const fontFaceCss = (f) => fontFiles(f)
+    .map((x) => `@font-face{font-family:"${f.family}";src:url(fonts/${x.file}) format("woff2");font-weight:${x.weight};font-style:${x.style};font-display:block}`)
+    .join("\n");
+/** Valor de `font-family`: a fonte e, se não carregar, uma parecida do sistema. */
+export const fontStack = (f) => `"${f.family}",${f.kind === "serif" ? 'Georgia,"Times New Roman",serif' : '"Segoe UI",system-ui,sans-serif'}`;
+//# sourceMappingURL=fonts.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Níveis dos títulos do corpo de uma página no manual exportado, sem pular nível.
+ * O título mais alto da página vira o nível logo abaixo do título da página (`titleLevel + 1`),
+ * os outros mantêm a diferença entre si, e nenhum desce mais de um nível por vez.
+ * `depths` são os níveis do Markdown (1 a 6), na ordem em que aparecem.
+ */
+export declare function exportLevels(depths: number[], titleLevel: number): number[];

package/dist/core/export/headings.js

@@ -0,0 +1,17 @@
+/**
+ * Níveis dos títulos do corpo de uma página no manual exportado, sem pular nível.
+ * O título mais alto da página vira o nível logo abaixo do título da página (`titleLevel + 1`),
+ * os outros mantêm a diferença entre si, e nenhum desce mais de um nível por vez.
+ * `depths` são os níveis do Markdown (1 a 6), na ordem em que aparecem.
+ */
+export function exportLevels(depths, titleLevel) {
+    if (!depths.length)
+        return [];
+    const top = Math.min(...depths);
+    let prev = titleLevel;
+    return depths.map((d) => {
+        prev = Math.min(titleLevel + 1 + d - top, prev + 1, 6);
+        return prev;
+    });
+}
+//# sourceMappingURL=headings.js.map

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

@@ -1,6 +1,4 @@
 import type { Collected } from "./collect.js";
 import { type ImageInfo } from "./refs.js";
-/** Cor da marca, quando o manual não escolheu outra. */
-export declare const DEFAULT_ACCENT = "#2b4fe0";
 /** Um arquivo HTML com o manual inteiro: sumário ao lado, uma seção por página, marcações sobre os prints. */
-export declare function renderHtml(collected: Collected, images: Map<string, ImageInfo>): string;
+export declare function renderHtml(collected: Collected, images: Map<string, ImageInfo>, logo?: string | null): string;

package/dist/core/export/html.js

@@ -1,18 +1,25 @@
 import { Marked } from "marked";
+import { ANNOTATION_CSS } from "./annotationCss.js";
+import { arrowShape, legendRows } from "./annotationShapes.js";
+import { CALLOUT_COLORS, readCallout } from "./callout.js";
+import { exportLevels } from "./headings.js";
 import { labelsFor } from "./labels.js";
 import { assetFromSrc, headingAnchor, pageAnchor, pageLink, safeHref } from "./refs.js";
-/** Cor da marca, quando o manual não escolheu outra. */
-export const DEFAULT_ACCENT = "#2b4fe0";
+import { colorSpanOpen, TEXT_COLORS } from "./textColors.js";
+import { fontFacesCss, themeCss } from "./theme.js";
 const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const pct = (n) => `${(n * 100).toFixed(3)}%`;
 /** Um arquivo HTML com o manual inteiro: sumário ao lado, uma seção por página, marcações sobre os prints. */
-export function renderHtml(collected, images) {
+export function renderHtml(collected, images, logo = null) {
     const { meta, pages } = collected;
     const L = labelsFor(meta.language);
-    const accent = meta.theme?.accent ?? DEFAULT_ACCENT;
     const toc = pages
         .map((p) => `<li style="--d:${p.depth}"><a href="#${pageAnchor(p.id)}"><span class="num">${p.number}</span> ${esc(p.title)}</a></li>`)
         .join("\n");
+    const logoImg = logo
+        ? `<img class="logo" src="${esc(logo)}" alt="">
+`
+        : "";
     const sections = pages.map((p) => renderPage(p, pages, images, L)).join("\n");
     return `<!doctype html>
 <html lang="${esc(meta.language)}">
@@ -21,19 +28,20 @@ export function renderHtml(collected, images) {
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="generator" content="Explicaí Studio">
 <title>${esc(meta.title)}</title>
-<style>${CSS.replace("__ACCENT__", accent)}</style>
+<style>${fontFacesCss(meta.theme)}
+${CSS}${themeCss(meta.theme)}</style>
 </head>
 <body>
 <div class="layout">
 <nav class="toc" aria-label="${L.toc}">
-<p class="toc-title">${esc(meta.title)}</p>
+${logoImg}<p class="toc-title">${esc(meta.title)}</p>
 <ol>
 ${toc}
 </ol>
 </nav>
 <main>
 <header class="cover">
-<h1>${esc(meta.title)}</h1>
+${logoImg}<h1>${esc(meta.title)}</h1>
 <p>${L.pages(pages.length)}</p>
 </header>
 ${sections}
@@ -45,13 +53,23 @@ ${sections}
 `;
 }
 function renderPage(page, pages, images, L) {
+    const titleLevel = Math.min(page.depth + 2, 3);
+    const depths = [];
+    const lexer = new Marked({ gfm: true });
+    lexer.walkTokens(lexer.lexer(page.body), (t) => {
+        if (t.type === "heading")
+            depths.push(t.depth);
+    });
+    const levels = exportLevels(depths, titleLevel);
+    let next = 0;
+    let openSpans = 0;
     const marked = new Marked({
         gfm: true,
         renderer: {
-            // Os títulos da página descem um nível: o título da página é o h2 da seção.
-            heading({ tokens, depth, text }) {
-                const level = Math.min(depth + 2, 6);
-                return `<h${level} id="${headingAnchor(page.id, text)}">${this.parser.parseInline(tokens)}</h${level}>\n`;
+            // Os títulos ficam abaixo do título da página, sem pular nível (ver exportLevels).
+            heading({ tokens, text, depth }) {
+                const level = levels[next++] ?? 6;
+                return `<h${level} class="t${Math.min(depth, 3)}" id="${headingAnchor(page.id, text)}">${this.parser.parseInline(tokens)}</h${level}>\n`;
             },
             link({ href, tokens }) {
                 const target = pageLink(href, pages) ?? safeHref(href);
@@ -68,16 +86,36 @@ function renderPage(page, pages, images, L) {
                     return `<span class="missing">[${L.missingImage}: ${esc(text || href)}]</span>`;
                 return renderShot(info, text, pages, L);
             },
+            // Alerta GFM vira painel com rótulo em texto; outra citação segue como estava.
+            blockquote({ tokens }) {
+                const callout = readCallout(tokens);
+                if (!callout)
+                    return `<blockquote>
+${this.parser.parse(tokens)}</blockquote>
+`;
+                return `<div class="callout" data-callout="${callout.type}" role="note"><p class="callout-label">${L.callouts[callout.type]}</p>
+${this.parser.parse(callout.body)}</div>
+`;
+            },
             // HTML colado no texto sai como texto: o manual exportado não roda código de ninguém.
+            // Só a cor do texto passa, e só com um nome da paleta (ver textColors.ts).
             html({ text }) {
+                const color = colorSpanOpen(text);
+                if (color) {
+                    openSpans++;
+                    return `<span data-color="${color}">`;
+                }
+                if (text === "</span>" && openSpans > 0) {
+                    openSpans--;
+                    return text;
+                }
                 return esc(text);
             },
         },
     });
     const body = marked.parse(page.body, { async: false });
-    const level = Math.min(page.depth + 2, 3);
     return `<section class="page" id="${pageAnchor(page.id)}">
-<h${level} class="page-title"><span class="num">${page.number}</span> ${esc(page.title)}</h${level}>
+<h${titleLevel} class="page-title"><span class="num">${page.number}</span> ${esc(page.title)}</h${titleLevel}>
 <div class="page-body">${body}</div>
 </section>`;
 }
@@ -109,29 +147,32 @@ function renderShot(info, alt, pages, L) {
         .join("");
     const unit = Math.max(w, h);
     const px = (p) => ({ x: p.x * w, y: p.y * h });
+    const f1 = (n) => n.toFixed(1);
     const arrows = a.arrows.length
         ? `<svg class="arrows" viewBox="0 0 ${w} ${h}" preserveAspectRatio="none" aria-hidden="true">${a.arrows
             .map(({ from, to }) => {
-            const f = px(from);
-            const t = px(to);
-            const angle = Math.atan2(t.y - f.y, t.x - f.x);
-            const size = unit * 0.022;
-            const wing = (d) => `${(t.x - size * Math.cos(angle + d)).toFixed(1)},${(t.y - size * Math.sin(angle + d)).toFixed(1)}`;
-            return `<line x1="${f.x.toFixed(1)}" y1="${f.y.toFixed(1)}" x2="${t.x.toFixed(1)}" y2="${t.y.toFixed(1)}" stroke-width="${(unit * 0.005).toFixed(1)}"/><polygon points="${t.x.toFixed(1)},${t.y.toFixed(1)} ${wing(0.45)} ${wing(-0.45)}"/>`;
+            const t = unit * 0.005;
+            const { shaft: s, head } = arrowShape(px(from), px(to), t);
+            const line = `x1="${f1(s.x1)}" y1="${f1(s.y1)}" x2="${f1(s.x2)}" y2="${f1(s.y2)}"`;
+            const pts = head.map((p) => `${f1(p.x)},${f1(p.y)}`).join(" ");
+            return `<line class="halo" ${line} stroke-width="${f1(t * 2.2)}"/><polygon class="halo" points="${pts}" stroke-width="${f1(t * 1.2)}"/><line ${line} stroke-width="${f1(t)}"/><polygon points="${pts}"/>`;
         })
             .join("")}</svg>`
         : "";
     const markers = a.markers
-        .map((m) => `<span class="mk" style="left:${pct(m.x)};top:${pct(m.y)}" aria-hidden="true">${m.n}</span>`)
+        .map((m) => `<span class="mk" style="left:${pct(m.x)};top:${pct(m.y)}" data-n="${m.n}" aria-hidden="true"></span>`)
         .join("");
-    const legend = [...a.markers]
-        .sort((x, y) => x.n - y.n)
-        .map((m) => `<span role="listitem"><span class="n">${m.n}</span> ${esc(m.label ?? "")}</span>`)
+    const legend = legendRows(a.markers)
+        .map((r) => {
+        const nums = r.badges.map((n) => `<span class="n">${n}</span>`).join("");
+        const text = r.label ? esc(r.label) : `<span class="none">${L.noDescription}</span>`;
+        return `<span class="row" role="listitem">${nums}<span>${text}</span></span>`;
+    })
         .join("");
-    return `<span class="shot"><span class="frame" style="aspect-ratio:${w} / ${h}"><img src="${esc(info.asset)}" alt="${esc(alt)}" loading="lazy">${highlights}${arrows}${hotspots}${markers}</span>${legend ? `<span class="legend" role="list" aria-label="${L.legend}">${legend}</span>` : ""}</span>`;
+    return `<span class="shot${a.display ? ` shot-${a.display}` : ""}"><span class="frame" style="aspect-ratio:${w} / ${h}"><img src="${esc(info.asset)}" alt="${esc(alt)}" loading="lazy">${highlights}${arrows}${hotspots}${markers}</span>${legend ? `<span class="legend" role="list" aria-label="${L.legend}">${legend}</span>` : ""}</span>`;
 }
 const CSS = `
-:root{--accent:__ACCENT__;--anotacao:#2b4fe0;--marca:#ffd43b;--tinta:#151a33;--grafite:#575e78;--linha:#dce0eb;--papel:#f5f6fa;
+:root{--accent:#2b4fe0;--anotacao:#2b4fe0;--anotacao-fundo:rgba(43,79,224,.08);--sobre-anotacao:#fff;--marca:#ffd43b;--marca-faixa:rgba(255,212,59,.55);--t-cover:#000;--t-page:#000;--t-h1:#000;--t-h2:#000;--t-h3:#000;--marca-faixa:rgba(255,212,59,.55);--tinta:#151a33;--grafite:#575e78;--linha:#dce0eb;--papel:#f5f6fa;
 --texto:"Atkinson Hyperlegible Next","Segoe UI",system-ui,sans-serif;--display:"Archivo","Arial Narrow",system-ui,sans-serif;--mono:"JetBrains Mono",ui-monospace,Consolas,monospace}
 *{box-sizing:border-box}
 body{margin:0;background:#fff;color:var(--tinta);font:16px/1.65 var(--texto);-webkit-font-smoothing:antialiased}
@@ -145,11 +186,15 @@ body{margin:0;background:#fff;color:var(--tinta);font:16px/1.65 var(--texto);-we
 .num{font-family:var(--mono);font-size:.8em;color:var(--accent);margin-right:4px}
 main{max-width:52rem;padding:32px 40px 96px;margin:0 auto;width:100%}
 .cover{padding:48px 0 32px;border-bottom:3px solid var(--marca);margin-bottom:24px}
-.cover h1{margin:0;font:800 clamp(32px,5vw,48px)/1.1 var(--display);letter-spacing:-.02em}
+.cover h1{margin:0;color:var(--t-cover);font:800 clamp(32px,5vw,48px)/1.1 var(--display);letter-spacing:-.02em}
+.logo{display:block;width:auto;height:auto;object-fit:contain}
+.cover .logo{max-height:96px;max-width:min(280px,100%);margin:0 0 24px}
+.toc .logo{max-height:48px;max-width:100%;margin:0 0 16px}
 .cover p{margin:8px 0 0;color:var(--grafite)}
 .page{padding-top:32px;scroll-margin-top:16px}
-.page-title{margin:0 0 12px;font:800 30px/1.2 var(--display);letter-spacing:-.01em}
+.page-title{margin:0 0 12px;color:var(--t-page);font:800 30px/1.2 var(--display);letter-spacing:-.01em}
 .page-body h3,.page-body h4,.page-body h5,.page-body h6{font-family:var(--display);line-height:1.25;margin:1.4em 0 .4em;scroll-margin-top:16px}
+.page-body .t1{color:var(--t-h1)}.page-body .t2{color:var(--t-h2)}.page-body .t3{color:var(--t-h3)}
 .page-body h3{font-size:22px}.page-body h4{font-size:19px}.page-body h5,.page-body h6{font-size:17px}
 .page-body p{margin:.6em 0}
 .page-body a{color:var(--accent);text-underline-offset:.2em}
@@ -165,19 +210,21 @@ main{max-width:52rem;padding:32px 40px 96px;margin:0 auto;width:100%}
 .page-body>ol>li,.page-body li>ol>li{counter-increment:passo;position:relative}
 .page-body>ol>li+li,.page-body li>ol>li+li{margin-top:.6em}
 .page-body>ol>li::before,.page-body li>ol>li::before{content:counter(passo);position:absolute;left:-2.25em;top:.12em;display:grid;place-items:center;width:1.55em;height:1.55em;border-radius:50%;background:var(--accent);color:#fff;font:700 .82em var(--mono)}
-.page-body li>blockquote{padding:6px 12px;border-left:3px solid var(--marca);border-radius:0 6px 6px 0;background:rgba(255,212,59,.35);color:var(--tinta)}
+.page-body li>blockquote{margin:.6em 0 0;padding:0;border:0;color:var(--tinta)}
+.page-body li>blockquote>p{display:inline;background:linear-gradient(transparent 50%,var(--marca-faixa) 50%)}
+.page-body li>blockquote>p>strong:first-child{font:700 .78em var(--mono);letter-spacing:.04em;text-transform:uppercase}
+.page-body .callout{margin:.8em 0;padding:10px 14px;border:1px solid color-mix(in srgb,var(--c) 35%,#fff);border-left:4px solid var(--c);border-radius:3px;background:color-mix(in srgb,var(--c) 8%,#fff);color:var(--tinta)}
+.page-body .callout>:last-child{margin-bottom:0}
+.page-body .callout-label{margin:0 0 .3em;color:color-mix(in srgb,var(--c) 85%,#000);font:700 .78em var(--mono);letter-spacing:.06em;text-transform:uppercase}
+${Object.entries(CALLOUT_COLORS)
+    .map(([type, hex]) => `.callout[data-callout="${type}"]{--c:${type === "note" ? "var(--accent)" : hex}}`)
+    .join("")}
 .shot{display:block;margin:.6em 0}
-.frame{position:relative;display:block;max-width:100%;width:fit-content}
-.frame img{display:block;max-width:100%;height:auto;border:1px solid var(--linha);border-radius:8px}
-.hl{position:absolute;border:2px solid var(--marca);background:rgba(255,212,59,.3);border-radius:3px}
-.hot{position:absolute;border:2px dashed var(--anotacao);background:rgba(43,79,224,.08);border-radius:3px}
-.arrows{position:absolute;inset:0;width:100%;height:100%;overflow:visible;pointer-events:none}
-.arrows line{stroke:var(--anotacao);stroke-linecap:round}
-.arrows polygon{fill:var(--anotacao)}
-.mk{position:absolute;transform:translate(-50%,-50%);display:grid;place-items:center;width:28px;height:28px;border-radius:50%;background:var(--anotacao);color:#fff;font:600 13px var(--mono);box-shadow:0 0 0 2px #fff,0 2px 6px rgba(21,26,51,.35)}
-.legend{display:grid;gap:4px;margin-top:8px;font-size:15px}
-.legend .n{display:inline-grid;place-items:center;width:20px;height:20px;margin-right:6px;border-radius:50%;background:var(--anotacao);color:#fff;font:600 11px var(--mono);vertical-align:1px}
+${ANNOTATION_CSS}
 .missing{color:#c8411f;font-style:italic}
+${Object.entries(TEXT_COLORS)
+    .map(([name, hex]) => `[data-color="${name}"]{color:${hex}}`)
+    .join("")}
 .sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
 .colophon{margin-top:64px;padding-top:16px;border-top:1px solid var(--linha);color:var(--grafite);font-size:13px}
 @media (max-width:800px){.layout{display:block}.toc{position:static;height:auto;border-right:0;border-bottom:1px solid var(--linha)}main{padding:24px 20px 64px}}
@@ -187,7 +234,7 @@ body{font-size:11.5pt}
 .layout{display:block}.toc{display:none}main{max-width:none;padding:0}
 .cover{padding:30vh 0 0;border:0;break-after:page}
 .page{break-before:page;padding-top:0}
-.shot,.page-body table,.page-body pre,.page-body li{break-inside:avoid}
+.shot,.callout,.page-body table,.page-body pre,.page-body li{break-inside:avoid}
 .page-body a{color:var(--tinta)}
 .hot{border-style:dashed}
 }

package/dist/core/export/imageSize.js

@@ -1,10 +1,27 @@
-import { readFile } from "node:fs/promises";
+import { open, readFile } from "node:fs/promises";
+const HEAD = 64 * 1024;
 /**
  * Largura e altura de um print lendo só o cabeçalho do arquivo (PNG, JPEG, GIF, WebP e SVG).
  * A exportação precisa da proporção para desenhar setas sem entortar. Formato desconhecido: null.
  */
 export async function imageSize(file) {
-    const b = await readFile(file);
+    const b = await head(file);
+    const size = parse(b);
+    // JPEG com EXIF grande: o marcador SOF pode estar além do começo. Lê o arquivo todo.
+    return size ?? (b.length === HEAD && b[0] === 0xff && b[1] === 0xd8 ? parse(await readFile(file)) : null);
+}
+async function head(file) {
+    const fh = await open(file, "r");
+    try {
+        const buf = Buffer.alloc(HEAD);
+        const { bytesRead } = await fh.read(buf, 0, HEAD, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        await fh.close();
+    }
+}
+function parse(b) {
     if (b.length > 24 && b.toString("ascii", 1, 4) === "PNG")
         return { w: b.readUInt32BE(16), h: b.readUInt32BE(20) };
     if (b.length >= 10 && b.toString("ascii", 0, 3) === "GIF")
@@ -45,7 +62,7 @@ function jpeg(b) {
 }
 function svg(text) {
     const tag = /<svg[^>]*>/i.exec(text)?.[0] ?? "";
-    const num = (name) => Number.parseFloat(new RegExp(`s${name}="([d.]+)`, "i").exec(tag)?.[1] ?? "");
+    const num = (name) => Number.parseFloat(new RegExp(`\\s${name}="([\\d.]+)`, "i").exec(tag)?.[1] ?? "");
     const [w, h] = [num("width"), num("height")];
     if (w > 0 && h > 0)
         return { w, h };

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

@@ -1,5 +1,6 @@
-import type { ManualTheme } from "../types.js";
 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";
@@ -10,14 +11,19 @@ export interface ExportResult {
     /** Arquivo principal, relativo à pasta do manual (`exportacao/html/index.html`). */
     file: string;
     pages: number;
-    /** Páginas que ficaram de fora e por quê. */
+    /** 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 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 declare function exportManual(dir: string, format: ExportFormat, opts?: CollectOptions): Promise<ExportResult>;
-/** Cor do manual exportado. Só aceita hexadecimal de 6 dígitos; sem cor, volta à da marca. */
-export declare function setManualTheme(dir: string, theme: ManualTheme): Promise<void>;
+/**
+ * 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>;