explicai 0.0.0-stage → 0.2.0

package/dist/core/export/annotationShapes.js

@@ -0,0 +1,38 @@
+/**
+ * Seta com ponta fechada. O tamanho da ponta é proporcional à espessura e encolhe em setas curtas
+ * (no máximo 70% do comprimento), sem perder a forma. `thickness` na mesma unidade de `from` e `to`.
+ */
+export function arrowShape(from, to, thickness) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const len = Math.hypot(dx, dy);
+    const ux = len === 0 ? 1 : dx / len;
+    const uy = len === 0 ? 0 : dy / len;
+    const headLen = Math.min(thickness * 4.5, len * 0.7);
+    const half = headLen * 0.45;
+    const bx = to.x - ux * headLen;
+    const by = to.y - uy * headLen;
+    const inside = headLen * 0.2;
+    return {
+        shaft: { x1: from.x, y1: from.y, x2: bx + ux * inside, y2: by + uy * inside },
+        head: [to, { x: bx - uy * half, y: by + ux * half }, { x: bx + uy * half, y: by - ux * half }],
+    };
+}
+/** Linhas da legenda por número; marcadores sem descrição em sequência dividem uma linha só. */
+export function legendRows(markers) {
+    const rows = [];
+    for (const m of [...markers].sort((a, b) => a.n - b.n)) {
+        const label = (m.label ?? "").trim();
+        const last = rows.at(-1);
+        if (!label && last && !last.label)
+            last.numbers.push(m.n);
+        else
+            rows.push({ numbers: [m.n], badges: [], label });
+    }
+    for (const r of rows) {
+        const [first, last] = [r.numbers[0], r.numbers.at(-1)];
+        r.badges = !r.label && r.numbers.length >= 3 ? [`${first}–${last}`] : r.numbers.map(String);
+    }
+    return rows;
+}
+//# sourceMappingURL=annotationShapes.js.map

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

@@ -0,0 +1,11 @@
+import type { Token } from "marked";
+/** Cor de cada tipo de alerta no manual exportado (fundo branco). O de `note` segue a cor de destaque do manual. */
+export declare const CALLOUT_COLORS: Record<string, string>;
+/**
+ * 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 declare function readCallout(tokens: Token[]): {
+    type: string;
+    body: Token[];
+} | null;

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

@@ -0,0 +1,27 @@
+import type { ManualMeta } from "../types.js";
+export interface ExportPage {
+    id: string;
+    title: string;
+    /** Posição na árvore, como no sumário: "2", "2.1". */
+    number: string;
+    depth: number;
+    /** Nome do arquivo (`cadastrar-cliente.md`), para achar a página pelos links `./arquivo.md`. */
+    fileName: string;
+    body: string;
+}
+export interface Collected {
+    meta: ManualMeta;
+    pages: ExportPage[];
+    /** Páginas que ficaram de fora, com o motivo (arquivo apagado, versão sumida). */
+    warnings: string[];
+}
+export interface CollectOptions {
+    /** Só páginas aprovadas ou publicadas. Subpágina aprovada entra mesmo com a mãe em rascunho. */
+    onlyApproved?: boolean;
+}
+/**
+ * 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

@@ -0,0 +1,49 @@
+import { readManual } from "../manuals.js";
+import { readPage } from "../pages.js";
+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 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 = {}) {
+    const meta = await readManual(dir);
+    const pages = [];
+    const warnings = [];
+    // `count` é compartilhado com os filhos de uma página que ficou de fora: eles sobem para o lugar dela.
+    const walk = async (nodes, prefix, depth, count) => {
+        for (const node of nodes) {
+            let included = false;
+            let number = prefix;
+            try {
+                const current = await readPage(dir, node.id);
+                if (!opts.onlyApproved || APPROVED.includes(current.status)) {
+                    const source = node.published ? await readVersion(dir, node.id, node.published) : current;
+                    count.n += 1;
+                    number = prefix ? `${prefix}.${count.n}` : String(count.n);
+                    pages.push({
+                        id: node.id,
+                        title: source.title || labelsFor(meta.language).untitled,
+                        number,
+                        depth,
+                        fileName: node.file.split("/").pop() ?? node.file,
+                        body: source.body,
+                    });
+                    included = true;
+                }
+            }
+            catch (err) {
+                warnings.push(`${node.file}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (included)
+                await walk(node.children, number, depth + 1, { n: 0 });
+            else
+                await walk(node.children, prefix, depth, count);
+        }
+    };
+    await walk(meta.pages, "", 0, { n: 0 });
+    return { meta, pages, warnings };
+}
+//# sourceMappingURL=collect.js.map

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

@@ -0,0 +1,4 @@
+import type { Collected } from "./collect.js";
+import { type ImageInfo } from "./refs.js";
+/** 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>, logo?: string | null): string;

package/dist/core/export/html.js

@@ -0,0 +1,242 @@
+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";
+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, logo = null) {
+    const { meta, pages } = collected;
+    const L = labelsFor(meta.language);
+    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)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="Explicaí Studio">
+<title>${esc(meta.title)}</title>
+<style>${fontFacesCss(meta.theme)}
+${CSS}${themeCss(meta.theme)}</style>
+</head>
+<body>
+<div class="layout">
+<nav class="toc" aria-label="${L.toc}">
+${logoImg}<p class="toc-title">${esc(meta.title)}</p>
+<ol>
+${toc}
+</ol>
+</nav>
+<main>
+<header class="cover">
+${logoImg}<h1>${esc(meta.title)}</h1>
+<p>${L.pages(pages.length)}</p>
+</header>
+${sections}
+<footer class="colophon">${L.colophon}</footer>
+</main>
+</div>
+</body>
+</html>
+`;
+}
+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 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);
+                const text = this.parser.parseInline(tokens);
+                if (!target)
+                    return text;
+                const external = /^https?:/i.test(target) ? ' rel="noopener noreferrer"' : "";
+                return `<a href="${esc(target)}"${external}>${text}</a>`;
+            },
+            image({ href, text }) {
+                const asset = assetFromSrc(href);
+                const info = asset ? images.get(asset) : undefined;
+                if (!info)
+                    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 });
+    return `<section class="page" id="${pageAnchor(page.id)}">
+<h${titleLevel} class="page-title"><span class="num">${page.number}</span> ${esc(page.title)}</h${titleLevel}>
+<div class="page-body">${body}</div>
+</section>`;
+}
+function hotspotHref(target, pages) {
+    if (target.type === "url") {
+        const href = safeHref(target.href);
+        return href ? { href, label: target.href } : null;
+    }
+    const page = pages.find((p) => p.id === target.pageId);
+    if (!page)
+        return null;
+    const href = target.type === "anchor" ? `#${headingAnchor(page.id, target.anchor)}` : `#${pageAnchor(page.id)}`;
+    return { href, label: page.title };
+}
+/** O print com as marcações por cima (posições em %, acompanham o tamanho) e a legenda embaixo. */
+function renderShot(info, alt, pages, L) {
+    const a = info.annotations;
+    const w = info.size?.w ?? 1000;
+    const h = info.size?.h ?? 1000;
+    const box = (r) => `left:${pct(r.x)};top:${pct(r.y)};width:${pct(r.w)};height:${pct(r.h)}`;
+    const highlights = a.highlights.map((r) => `<span class="hl" style="${box(r)}"></span>`).join("");
+    const hotspots = a.hotspots
+        .map((r) => {
+        const link = hotspotHref(r.target, pages);
+        return link
+            ? `<a class="hot" href="${esc(link.href)}" style="${box(r)}"><span class="sr">${L.goTo} ${esc(link.label)}</span></a>`
+            : "";
+    })
+        .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 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)}" data-n="${m.n}" aria-hidden="true"></span>`)
+        .join("");
+    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${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:#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}
+.layout{display:grid;grid-template-columns:17rem minmax(0,1fr)}
+.toc{position:sticky;top:0;height:100vh;overflow:auto;padding:24px 16px;background:var(--papel);border-right:1px solid var(--linha)}
+.toc-title{margin:0 0 12px;font:800 18px/1.2 var(--display)}
+.toc ol{list-style:none;margin:0;padding:0}
+.toc li{padding-left:calc(var(--d) * 14px)}
+.toc a{display:block;padding:4px 6px;border-radius:6px;color:var(--tinta);text-decoration:none;font-size:14px}
+.toc a:hover{background:#e9ecf5}
+.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;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;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}
+.page-body code{font:.88em var(--mono);background:var(--papel);border:1px solid var(--linha);border-radius:4px;padding:.05em .35em}
+.page-body pre{font:14px/1.5 var(--mono);background:var(--papel);border:1px solid var(--linha);border-radius:8px;padding:12px 14px;overflow-x:auto}
+.page-body pre code{background:none;border:0;padding:0}
+.page-body blockquote{margin:.6em 0;padding:2px 0 2px 16px;border-left:2px solid var(--linha);color:var(--grafite)}
+.page-body table{border-collapse:collapse;width:100%;margin:.8em 0;font-size:15px}
+.page-body th,.page-body td{border:1px solid var(--linha);padding:6px 10px;text-align:left;vertical-align:top}
+.page-body th{background:var(--papel)}
+.page-body ul{padding-left:1.4em}
+.page-body>ol,.page-body li>ol{list-style:none;counter-reset:passo;padding-left:2.25em}
+.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{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}
+${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}}
+@media print{
+@page{margin:18mm 16mm}
+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,.callout,.page-body table,.page-body pre,.page-body li{break-inside:avoid}
+.page-body a{color:var(--tinta)}
+.hot{border-style:dashed}
+}
+`;
+//# sourceMappingURL=html.js.map

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

@@ -0,0 +1,9 @@
+export interface Size {
+    w: number;
+    h: number;
+}
+/**
+ * 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 declare function imageSize(file: string): Promise<Size | null>;

package/dist/core/export/imageSize.js

@@ -0,0 +1,72 @@
+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 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")
+        return { w: b.readUInt16LE(6), h: b.readUInt16LE(8) };
+    if (b.length > 30 && b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP")
+        return webp(b);
+    if (b[0] === 0xff && b[1] === 0xd8)
+        return jpeg(b);
+    if (b.toString("utf8", 0, 512).includes("<svg"))
+        return svg(b.toString("utf8"));
+    return null;
+}
+function webp(b) {
+    const chunk = b.toString("ascii", 12, 16);
+    if (chunk === "VP8 ")
+        return { w: b.readUInt16LE(26) & 0x3fff, h: b.readUInt16LE(28) & 0x3fff };
+    if (chunk === "VP8L") {
+        const bits = b.readUInt32LE(21);
+        return { w: (bits & 0x3fff) + 1, h: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === "VP8X")
+        return { w: b.readUIntLE(24, 3) + 1, h: b.readUIntLE(27, 3) + 1 };
+    return null;
+}
+function jpeg(b) {
+    let i = 2;
+    while (i + 9 < b.length) {
+        if (b[i] !== 0xff)
+            return null;
+        const marker = b[i + 1] ?? 0;
+        // SOF0 a SOF15, menos DHT (C4), JPG (C8) e DAC (CC): é onde ficam as dimensões.
+        if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+            return { h: b.readUInt16BE(i + 5), w: b.readUInt16BE(i + 7) };
+        }
+        i += 2 + b.readUInt16BE(i + 2);
+    }
+    return null;
+}
+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 [w, h] = [num("width"), num("height")];
+    if (w > 0 && h > 0)
+        return { w, h };
+    const box = /viewBox="[\d.\s-]*?([\d.]+)\s+([\d.]+)"/i.exec(tag);
+    return box ? { w: Number(box[1]), h: Number(box[2]) } : null;
+}
+//# sourceMappingURL=imageSize.js.map