sagadeck 1.2.0

package/src/lessons.js

@@ -0,0 +1,171 @@
+// Slides de aula que qualquer matéria usa:
+//   solution — exercício resolvido: enunciado e dados à esquerda; cada clique revela o próximo passo da conta;
+//              no fim, a resposta em destaque
+//   calc     — calculadora ao vivo: entradas com controle deslizante, saídas por fórmula (inclusive por faixas:
+//              "abaixo de 2300 é laminar"), régua com as faixas e o ponteiro do valor atual
+// A conta usa o mesmo compilador de fórmulas do slide de funções (src/runtime/formula.js): sem eval.
+import katex from "katex";
+import { md, esc } from "./markup.js";
+import "./runtime/formula.js";
+import "./runtime/calc.js";
+
+const F = globalThis.SagaFormula;
+const tex = (s, display = true) => katex.renderToString(String(s ?? ""), { displayMode: display, throwOnError: false, strict: "ignore", trust: false, maxExpand: 1000, maxSize: 20 });
+// valor de um dado em LaTeX: número vira vírgula decimal (e 10 elevado, se for muito grande ou muito pequeno)
+const commaTex = (v) => {
+  if (typeof v === "number" && Number.isFinite(v)) {
+    if (v !== 0 && (Math.abs(v) < 1e-3 || Math.abs(v) >= 1e6)) { const [m, e] = v.toExponential(2).split("e"); return `${String(Number(m)).replace(".", "{,}")}\\times10^{${Number(e)}}`; }
+    // 1500 → 1\,500 (espaço fino no milhar) · 1.5 → 1{,}5
+    const [int, frac] = String(+v.toFixed(6)).split(".");
+    return `${int.replace(/\B(?=(\d{3})+(?!\d))/g, "\\,")}${frac ? `{,}${frac}` : ""}`;
+  }
+  return String(v ?? "").replace(/(\d),(\d)/g, "$1{,}$2");
+};
+const panel = (i, inner, cls = "") => `<section class="lesson-panel dyn-frame ${cls}${i === 0 ? " active" : ""}" data-lesson-panel="${i}">${inner}</section>`;
+
+// ------------------------------------------------------------------------------------------------ solution
+// frase (palavra de 3+ letras, fora sen/log/max…) sem nada de LaTeX: é texto, não fórmula — senão "ver tabela" vira
+// "vertabela" em itálico, sem espaços
+const PROSE = /\p{L}{3,}/u;
+const isProse = (s) => !/\\[a-zA-Z]|[\^_{}]/.test(s) && PROSE.test(String(s).replace(/\b(sen|cos|tan|tg|log|ln|exp|max|min|lim|mod)\b/g, ""));
+const mathOrText = (s) => (isProse(String(s ?? "")) ? `<span class="sol-txt t f-body">${md(String(s))}</span>` : tex(s, false));
+function givenTex(g) {
+  if (typeof g === "string") return g;
+  if (g.latex) return g.latex;
+  const value = typeof g.value === "string" && isProse(g.value) ? `\\text{${g.value.replace(/[{}\\$]/g, "")}}` : commaTex(g.value);
+  // % (e # & _ $) são comandos no LaTeX: "60 %" saía como erro vermelho na conta da criança
+  const unit = g.unit ? String(g.unit).replace(/[%#&_$]/g, (c) => `\\${c}`).replace(/°/g, "^{\\circ}").replace(/ /g, "\\,") : "";
+  return `${g.symbol ?? ""} = ${value}${unit ? `\\ \\mathrm{${unit}}` : ""}`;
+}
+export function solutionHTML(s, ctx, head) {
+  const steps = (s.steps || []).map((x) => (typeof x === "string" ? { latex: x } : x || {}));
+  const givens = [].concat(s.givens || s.data || []);
+  const hasAnswer = !!s.answer;
+  const n = 1 + steps.length + (hasAnswer ? 1 : 0); // enunciado · cada passo · resposta
+  const left = `<div class="sol-problem">${s.problem ? `<div class="sol-text t f-body">${md(s.problem)}</div>` : ""}
+    ${givens.length ? `<div class="sol-givens"><div class="sol-label t f-label">Dados</div>${givens.map((g) => `<div class="sol-given"><div class="sol-tex">${typeof g === "string" ? mathOrText(g) : tex(givenTex(g), false)}</div>${g.label ? `<span class="t f-body">${md(g.label)}</span>` : ""}</div>`).join("")}</div>` : ""}
+    ${s.find ? `<div class="sol-find"><span class="sol-label t f-label">Pede-se</span><div class="sol-tex">${mathOrText(s.find)}</div></div>` : ""}</div>`;
+  const stepHTML = (st, i, k) => `<article class="sol-step${i === k - 1 ? " now" : ""}"><span class="sol-n t f-label">${String(i + 1).padStart(2, "0")}</span><div class="sol-body">${st.text ? `<div class="sol-why t f-body">${md(st.text)}</div>` : ""}${st.latex ? `<div class="sol-math">${tex(st.latex)}</div>` : ""}${st.note ? `<div class="sol-note t f-body">${md(st.note)}</div>` : ""}</div></article>`;
+  const answer = hasAnswer ? (typeof s.answer === "string" ? { latex: s.answer } : s.answer) : null;
+  const frames = Array.from({ length: n }, (_, k) => {
+    const done = Math.min(k, steps.length);
+    const list = steps.slice(0, done).map((st, i) => stepHTML(st, i, done)).join("");
+    const final = hasAnswer && k === n - 1 ? `<div class="sol-answer"><span class="sol-label t f-label">${esc(answer.label || "Resposta")}</span>${answer.latex ? `<div class="sol-math">${tex(answer.latex)}</div>` : ""}${answer.text ? `<div class="t f-body">${md(answer.text)}</div>` : ""}</div>` : "";
+    const empty = k === 0 ? `<div class="sol-think t f-display">${md(s.prompt || "Por onde você começaria?")}</div>` : "";
+    return panel(k, `<div class="sol-steps">${empty}${list}${final}</div>`);
+  }).join("");
+  return `<div class="L-solution dyn" data-lesson="solution" data-lesson-count="${n}">${head(s)}<div class="sol-row">${left}<div class="dyn-frames">${frames}</div></div></div>`;
+}
+
+// ------------------------------------------------------------------------------------------------ calc
+// o modelo da calculadora (o mesmo no motor e na apresentação): entradas, saídas em ordem, faixas e régua
+export function calcModel(s) {
+  const inputs = Object.entries(s.inputs || {}).map(([name, v]) => {
+    const o = typeof v === "number" ? { value: v } : v || {};
+    const value = Number(o.value ?? 1);
+    return { name, label: String(o.label || name), unit: o.unit ? String(o.unit) : "", value, min: Number(o.min ?? (value > 0 ? value / 10 : -10)), max: Number(o.max ?? (value > 0 ? value * 10 : 10)), step: Number(o.step ?? ((Number(o.max ?? value * 10) - Number(o.min ?? 0)) / 200 || 0.01)), fixed: !!o.fixed, ...(o.latex ? { latex: String(o.latex) } : {}), ...(o.decimals != null ? { decimals: Number(o.decimals) } : {}) };
+  });
+  const outputs = [].concat(s.outputs || []).map((o, i) => ({ name: String(o.name || `saida${i + 1}`), label: String(o.label || o.name || `Resultado ${i + 1}`), fn: o.fn ? String(o.fn) : "", of: o.of ? String(o.of) : "", unit: o.unit ? String(o.unit) : "", latex: o.latex ? String(o.latex) : "",
+    ...(o.decimals != null ? { decimals: Number(o.decimals) } : {}), ...(o.sci ? { sci: true } : {}),
+    cases: [].concat(o.cases || []).map((c) => ({ ...(c.below != null ? { below: Number(c.below) } : {}), ...(c.fn ? { fn: String(c.fn) } : {}), ...(c.text ? { text: String(c.text) } : {}), ...(c.color ? { color: String(c.color) } : {}) })),
+    ...(o.scale ? { scale: { min: Number(o.scale.min ?? 0), max: Number(o.scale.max ?? 1), ...(o.scale.log ? { log: true } : {}) } } : {}) }));
+  return { inputs, outputs, scenarios: s.scenarios || [], sweep: s.sweep || '', explanation: String(s.explanation || ''), prediction: String(s.prediction || ''), illustrative: !!s.illustrative };
+}
+const C = globalThis.SagaCalc;
+export const calcEvaluate = (m, v) => C.evaluate(m, v);
+const formatNum = (v, o) => C.format(v, o);
+const scalePos = (v, sc) => C.scalePos(v, sc);
+export function calcHTML(s, ctx, head) {
+  const m = calcModel(s);
+  const res = calcEvaluate(m);
+  const errs = Object.entries(res).filter(([, r]) => r.error).map(([k, r]) => `${k}: ${r.error}`);
+  if (errs.length) ctx?.warnings?.push(...errs.map((e) => `calculadora: ${e}`));
+  const input = (i) => i.fixed
+    ? `<div class="calc-in fixed"><span class="calc-l t f-label">${esc(i.label)}</span><b class="calc-const">${i.latex ? tex(i.latex, false) : `${esc(formatNum(i.value, i))}${i.unit ? ` <small>${esc(i.unit)}</small>` : ""}`}</b></div>`
+    : `<label class="calc-in"><span class="calc-l t f-label">${esc(i.label)}${i.latex ? ` <span class="calc-sym">${tex(i.latex, false)}</span>` : ""}</span><input type="range" data-calc-in="${esc(i.name)}"${s.inputs?.[i.name]?.decision ? ` data-decision-input="${esc(s.inputs[i.name].decision)}"` : ""} min="${i.min}" max="${i.max}" step="${i.step}" value="${i.value}" aria-label="${esc(i.label)}"><output class="calc-v" data-calc-show="${esc(i.name)}">${esc(formatNum(i.value, i))}</output><small class="calc-u">${esc(i.unit)}</small></label>`;
+  const output = (o) => {
+    const r = res[o.name];
+    const scale = o.scale ? (() => {
+      const zones = o.cases.filter((c) => c.below != null || c.text);
+      let prev = o.scale.min;
+      const bands = zones.map((c) => { const to = c.below ?? o.scale.max, a = scalePos(prev, o.scale), b = scalePos(to, o.scale); prev = to; // rótulo da faixa: fora do ajuste de texto (não é .t) e só se a faixa tiver largura para ele
+        return `<span class="calc-band" style="left:${a}%;width:${Math.max(0, b - a)}%;background:${c.color ? `var(--${c.color})` : "var(--line)"}">${b - a >= 14 ? `<em class="f-label">${esc(c.text || "")}</em>` : ""}</span>`; }).join("");
+      const val = o.of ? res[o.of]?.value ?? null : r.value;
+      return `<div class="calc-scale"><div class="calc-track">${bands}</div><span class="calc-pointer" data-calc-pointer="${esc(o.name)}" style="left:${scalePos(val, o.scale)}%"></span></div>`;
+    })() : "";
+    const badge = r.text ? `<span class="calc-badge t f-display" data-calc-badge="${esc(o.name)}" style="${r.color ? `background:var(--${r.color})` : ""}">${esc(r.text)}</span>` : (o.cases.some((c) => c.text) ? `<span class="calc-badge t f-display" data-calc-badge="${esc(o.name)}"></span>` : "");
+    const value = o.fn || o.cases.some((c) => c.fn) ? `<div class="calc-out-v"><b data-calc-out="${esc(o.name)}">${esc(formatNum(r.value, o))}</b>${o.unit ? ` <small>${esc(o.unit)}</small>` : ""}</div>` : "";
+    const compare = `<small class="calc-compare" data-calc-compare="${esc(o.name)}" hidden></small>`;
+    const sweep = m.inputs.find(i => i.name === m.sweep);
+    const curve = sweep && o.fn ? C.curveData(m, {}, o.name) : null;
+    const chart = curve ? `<figure class="calc-curve"><svg viewBox="0 0 320 80" role="img" aria-label="${esc(o.label)} em função de ${esc(sweep.label)}"><path data-calc-curve="${esc(o.name)}" d="${curve.path}" fill="none" stroke="currentColor" stroke-width="3"/></svg><figcaption><span data-calc-axis="${esc(o.name)}">${esc(o.label)}: ${esc(formatNum(curve.min, o))} a ${esc(formatNum(curve.max, o))} ${esc(o.unit)} (escala automática)</span><br>${esc(sweep.label)}: ${esc(formatNum(sweep.min))} a ${esc(formatNum(sweep.max))} ${esc(sweep.unit)}</figcaption></figure>` : '';
+    return `<div class="calc-out"><div class="calc-l t f-label">${esc(o.label)}</div>${o.latex ? `<div class="calc-formula">${tex(o.latex, false)}</div>` : ""}${value}${badge}${scale}${chart}${compare}</div>`;
+  };
+  const payload = JSON.stringify(m).replace(/</g, "\\u003c");
+  const controls = `<div class="calc-tools">${m.scenarios.map((c, i) => `<button type="button" data-calc-scenario="${i}">${esc(c.label || `Cenário ${i + 1}`)}</button>`).join('')}<button type="button" data-calc-free>Explorar</button><button type="button" data-calc-freeze>Comparar com este</button><button type="button" data-calc-reset>Restaurar</button></div>`;
+  const prediction = m.prediction ? `<div class="calc-prediction"><span>${esc(m.prediction)}</span> <button type="button" data-calc-reveal>Ver resultado</button></div>` : '';
+  const explanation = `<p class="calc-explanation" data-calc-explanation aria-live="polite">${esc(m.explanation)}</p>`;
+  return `<div class="L-calc${m.outputs.length >= 4 ? ' calc-many' : ''}" style="--calc-columns:${m.outputs.length >= 7 ? 4 : 3}" data-calc>${head(s)}${m.illustrative ? '<small class="calc-disclaimer">Simulação ilustrativa</small>' : ''}${prediction}${controls}<div class="calc-body"><div class="calc-inputs">${m.inputs.map(input).join("")}</div><div class="calc-outputs">${m.outputs.map(output).join("")}</div></div>${explanation}<script type="application/json" class="calc-model">${payload}</script>${s.note ? `<div class="calc-note t f-body">${md(s.note)}</div>` : ""}</div>`;
+}
+
+// ------------------------------------------------------------------------------------------------ algo
+import { traceAlgorithm, ALGO_CODE, ALGO_NAMES } from "./algo-trace.js";
+import { tracePlan, traceHTML } from "./trace-view.js";
+// Prever → rodar → explicar: `predict` vira o primeiro quadro (a turma aposta antes de ver), `explain` o último (o
+// porquê, com a resposta da aposta em destaque). Os passos do algoritmo ficam no meio, renumerados.
+function bookends(s, html) {
+  const p = s.predict == null || s.predict === "" ? null : typeof s.predict === "string" ? { question: s.predict } : s.predict;
+  const x = s.explain == null || s.explain === "" ? null : typeof s.explain === "string" ? { text: s.explain } : s.explain;
+  if (!p && !x) return html;
+  let out = html;
+  if (p) {
+    const opts = Array.isArray(p.options) ? p.options : [];
+    const pre = `<div class="algo-predict-in"><div class="algo-predict-tag t f-label">${esc(p.label || "Antes de rodar")}</div><div class="algo-predict-q t f-heading">${md(p.question || "")}</div>${opts.length ? `<ol class="algo-predict-opts">${opts.map((o, i) => `<li class="t f-body"><b>${String.fromCharCode(65 + i)}</b>${md(String(o))}</li>`).join("")}</ol>` : ""}</div>`;
+    out = out.replace(/data-lesson-panel="(\d+)"/g, (_, k) => `data-lesson-panel="${+k + 1}"`).replace(/(<section class="lesson-panel dyn-frame [^"]*?) active"/, "$1\"");
+    out = out.replace('<div class="dyn-frames">', `<div class="dyn-frames">${panel(0, pre, "algo-predict")}`);
+  }
+  const count = Number(out.match(/data-lesson-count="(\d+)"/)?.[1] || 0) + (p ? 1 : 0) + (x ? 1 : 0);
+  out = out.replace(/data-lesson-count="\d+"/, `data-lesson-count="${count}"`);
+  if (x) {
+    const ans = x.answer ?? p?.answer;
+    const post = `<div class="algo-explain-in"><div class="algo-predict-tag t f-label">${esc(x.label || "Por quê")}</div>${ans != null && ans !== "" ? `<div class="algo-explain-ans t f-heading">${md(String(ans))}</div>` : ""}<div class="algo-explain-text t f-body">${md(x.text || "")}</div></div>`;
+    const at = out.lastIndexOf("</section>");
+    if (at >= 0) out = out.slice(0, at + 10) + panel(count - 1, post, "algo-explain") + out.slice(at + 10);
+  }
+  return out;
+}
+
+export function algoHTML(s, ctx, head) {
+  return bookends(s, algoCore(s, ctx, head));
+}
+function algoCore(s, ctx, head) {
+  // programa do professor (program:) ou do catálogo (kmp, bfs…): execução rastreada genérica (src/pytrace.js)
+  const plan = tracePlan(s);
+  if (plan) return traceHTML(s, plan, ctx, head, panel);
+  const algorithm = String(s.algorithm || "bubble");
+  let steps;
+  try { steps = traceAlgorithm(algorithm, s.array || [5, 1, 4, 2, 8, 3], { target: s.target }); }
+  catch (e) { ctx?.warnings?.push(`algoritmo: ${e.message}`); return `<div class="L-algo">${head(s)}<div class="dyn-error f-body">${esc(e.message)}</div></div>`; }
+  // passos demais para clicar: some só com as comparações sem troca (o essencial fica)
+  const max = Number(s.maxSteps) || 90;
+  if (steps.length > max) steps = steps.filter((st, i) => i === 0 || i === steps.length - 1 || !(st.compare && !st.swap && st.write == null && st.found == null));
+  if (steps.length > max) { ctx?.warnings?.push(`algoritmo: ${steps.length} passos; use um vetor menor para caber no clique (até ${max})`); steps = steps.slice(0, max - 1).concat(steps.slice(-1)); }
+  const code = s.code ? String(s.code).split("\n") : ALGO_CODE[algorithm];
+  const top = Math.max(...steps.flatMap((st) => st.arr), 1);
+  const n = steps.length, search = ["linear", "binary"].includes(algorithm);
+  const bars = (st, prev) => {
+    const cmp = new Set(st.compare || []), sw = new Set(st.swap || []), sorted = new Set(st.sorted || []);
+    const [lo, hi] = st.range || [0, st.arr.length - 1];
+    return `<div class="algo-bars" style="--n:${st.arr.length}">${st.arr.map((v, i) => {
+      const from = st.swap && sw.has(i) ? (i === st.swap[0] ? st.swap[1] - st.swap[0] : st.swap[0] - st.swap[1]) : 0;
+      const cls = [cmp.has(i) && "cmp", sw.has(i) && "swp", st.write === i && "wr", st.pivot === i && "piv", sorted.has(i) && "ok", (i < lo || i > hi) && "out", st.found === i && "found"].filter(Boolean).join(" ");
+      return `<div class="algo-bar ${cls}" style="--h:${(v / top) * 100}%;--from:${from}"><span class="algo-val t f-display">${v}</span><i></i><span class="algo-idx t f-label">${i}</span></div>`;
+    }).join("")}</div>`;
+  };
+  const codeHTML = (line) => `<ol class="algo-code dyn-mono">${code.map((l, i) => `<li${i === line ? ' class="now"' : ""}>${esc(l)}</li>`).join("")}</ol>`;
+  const body = steps.map((st, k) => panel(k, `<div class="algo-row"><div class="algo-stage">${bars(st, steps[k - 1])}<div class="algo-caption t f-body">${md(st.text || "")}</div></div>
+    <aside class="algo-side"><div class="algo-name t f-label">${esc(s.name || ALGO_NAMES[algorithm] || algorithm)}${search && s.target != null ? ` · alvo <b>${esc(s.target)}</b>` : ""}</div>${codeHTML(st.line)}
+      <div class="algo-counters"><div><b class="t f-display">${st.comparisons}</b><span class="t f-label">comparações</span></div>${search ? "" : `<div><b class="t f-display">${st.swaps}</b><span class="t f-label">${algorithm === "merge" ? "escritas" : "trocas"}</span></div>`}<div><b class="t f-display">${k}/${n - 1}</b><span class="t f-label">passo</span></div></div>
+    </aside></div>`)).join("");
+  return `<div class="L-algo dyn" data-lesson="algo" data-lesson-count="${n}" data-autoplay-ms="${Number(s.speed) || 900}">${head(s)}<button type="button" class="algo-play" data-autoplay aria-pressed="false" title="Tocar sozinho (clique de novo para pausar)"><span class="algo-play-ic" aria-hidden="true"></span><span>Tocar</span></button><div class="dyn-frames">${body}</div></div>`;
+}

package/src/library.js

@@ -0,0 +1,399 @@
+// Biblioteca de apresentações: uma PASTA, sem banco de dados. Funciona igual no Windows do banco (só você)
+// e no servidor (uma biblioteca por usuário). Dá para mexer pelo Explorer também: a biblioteca reflete.
+//
+//   <biblioteca>/
+//     Palestras/                      tópico = pasta (cor em .topico.json)
+//       E se o humano for o bug/      apresentação = pasta (igual a um .sagadeck extraído)
+//         E se o humano for o bug.yaml
+//         imagens/ …
+//       rascunho.yaml                 um .yaml solto no tópico também é uma apresentação
+//     rascunho.yaml                   .yaml solto na raiz = apresentação sem tópico
+// Na raiz, pasta é SEMPRE tópico. "Nova sem tópico" vai para "Sem tópico"; importar sem tópico, para "Importados".
+//     .lixeira/                       excluídas (30 dias), com .origem.json
+//     .cache/                         capas geradas
+//
+// O id de uma apresentação é o caminho do .yaml dela, relativo à biblioteca, com "/" (ex.: "Palestras/X/X.yaml").
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+import * as MASTER from "./master.js";
+import { unpackDeck } from "./package.js";
+import { writeDeckFile } from "./deck-file.js";
+
+export const TRASH_DAYS = 30;
+const TRASH = ".lixeira";
+const TOPIC_META = ".topico.json";
+const COLORS = ["#d33a2c", "#0f6cbd", "#e5a50a", "#8b5cf6", "#0e9f6e", "#e8590c", "#d6336c", "#495057"];
+
+export function defaultLibraryRoot(env = process.env) {
+  return path.resolve(env.SAGADECK_HOME || path.join(os.homedir(), "sagadeck"));
+}
+
+// Onde uma apresentação NOVA é gravada: sempre na biblioteca. Um caminho dentro dela é respeitado; qualquer
+// outro (pasta atual, pasta temporária, cópia do repositório) vira só o nome, em <biblioteca>/<tópico>/<nome>/<nome>.yaml.
+// Decks espalhados por fora foram o que fez .js e imagens "sumirem". unique: não sobrescreve, usa "nome (2)".
+export function newDeckPath(wanted, { root = defaultLibraryRoot(), topic = "Sem tópico", title, unique = false } = {}) {
+  root = path.resolve(root);
+  const abs = wanted ? path.resolve(root, String(wanted)) : "";
+  const rel = abs && path.relative(root, abs);
+  // caminho de Windows (C:\… ou \\servidor\…) num servidor Linux não é "absoluto" para o path de lá, mas também é
+  // de fora da biblioteca: vira só o nome, como em qualquer sistema
+  const foreign = process.platform !== "win32" && /^([A-Za-z]:[\\/]|\\\\)/.test(String(wanted || ""));
+  let dir, name, file;
+  if (rel && !foreign && !rel.startsWith("..") && !path.isAbsolute(rel) && /[\\/]/.test(String(wanted))) {
+    if (/\.ya?ml$/i.test(abs)) file = abs;
+    else { dir = abs; name = path.basename(abs); }
+  } else {
+    name = safeName(wanted ? String(wanted).split(/[\\/]/).pop().replace(/\.ya?ml$/i, "") : title || "Nova apresentação");
+    dir = path.join(root, safeName(topic, "Sem tópico"), name);
+  }
+  file ||= path.join(dir, name + ".yaml");
+  if (!unique || !fs.existsSync(file)) return file;
+  // pasta própria (<nome>/<nome>.yaml): numera a pasta e o arquivo; .yaml solto: só o arquivo
+  const own = path.basename(path.dirname(file)) === path.basename(file, path.extname(file));
+  const ext = path.extname(file), base = path.basename(file, ext);
+  for (let n = 2; ; n++) {
+    const f = own ? path.join(path.dirname(path.dirname(file)), `${base} (${n})`, `${base} (${n})${ext}`) : path.join(path.dirname(file), `${base} (${n})${ext}`);
+    if (!fs.existsSync(f)) return f;
+  }
+}
+
+const posix = (p) => p.split(path.sep).join("/");
+const hidden = (name) => name.startsWith(".") || name.startsWith("~$");
+const isYaml = (name) => /\.ya?ml$/i.test(name) && !hidden(name);
+
+// nome de pasta/arquivo válido no Windows (e no Linux): sem <>:"/\|?*, sem ponto/espaço no fim
+export function safeName(s, fallback = "Sem título") {
+  const clean = String(s || "").normalize("NFC").replace(/[<>:"/\\|?*\u0000-\u001f]/g, " ").replace(/\s+/g, " ").trim()
+    .replace(/[. ]+$/, "").slice(0, 80).trim();
+  return /^(con|prn|aux|nul|com\d|lpt\d)$/i.test(clean) || !clean ? fallback : clean;
+}
+
+function uniquePath(dir, name, ext = "") {
+  let p = path.join(dir, name + ext);
+  for (let n = 2; fs.existsSync(p); n++) p = path.join(dir, `${name} (${n})${ext}`);
+  return p;
+}
+
+export function openLibrary(root) {
+  root = path.resolve(root);
+  fs.mkdirSync(root, { recursive: true });
+
+  // caminho absoluto de um id, sem sair da biblioteca
+  function resolveId(id) {
+    const abs = path.resolve(root, ...String(id || "").split("/"));
+    const rel = path.relative(root, abs);
+    if (!id || rel.startsWith("..") || path.isAbsolute(rel)) throw new Error("apresentação fora da biblioteca");
+    return abs;
+  }
+  const idOf = (abs) => posix(path.relative(root, abs));
+
+  // a apresentação principal de uma pasta: manifesto do .sagadeck, ou o .yaml com o nome da pasta, ou o 1º
+  function mainYaml(dir) {
+    const files = fs.readdirSync(dir).filter(isYaml);
+    if (!files.length) return null;
+    try {
+      const m = JSON.parse(fs.readFileSync(path.join(dir, "sagadeck.json"), "utf8"));
+      if (m.main && files.includes(m.main)) return path.join(dir, m.main);
+    } catch {}
+    const same = files.find((f) => f.replace(/\.ya?ml$/i, "") === path.basename(dir));
+    return path.join(dir, same || files.sort()[0]);
+  }
+
+  function deckInfo(file, topic) {
+    const st = fs.statSync(file);
+    let spec = {};
+    try { spec = YAML.parse(fs.readFileSync(file, "utf8")) || {}; } catch {}
+    const own = idOf(file).split("/").length === 3;
+    return {
+      id: idOf(file), topic: topic || "", title: String(spec.title || path.basename(file).replace(/\.ya?ml$/i, "")),
+      slides: Array.isArray(spec.slides) ? spec.slides.length : 0, theme: spec.theme || "", edited: st.mtimeMs,
+      folder: own, // true = pasta própria (com imagens etc.); false = .yaml solto
+    };
+  }
+
+  function topicMeta(dir) {
+    try { return JSON.parse(fs.readFileSync(path.join(dir, TOPIC_META), "utf8")); } catch { return {}; }
+  }
+
+  function list() {
+    // a pasta pode ter sido apagada por fora (Explorer, limpeza) com o servidor no ar: recria
+    fs.mkdirSync(root, { recursive: true });
+    purgeOld();
+    const topics = [], decks = [];
+    for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+      if (hidden(e.name)) continue;
+      const abs = path.join(root, e.name);
+      if (e.isFile() && isYaml(e.name)) { decks.push(deckInfo(abs, "")); continue; }
+      if (!e.isDirectory()) continue;
+      const meta = topicMeta(abs);
+      const mine = [];
+      for (const d of fs.readdirSync(abs, { withFileTypes: true })) {
+        if (hidden(d.name)) continue;
+        const p = path.join(abs, d.name);
+        if (d.isFile() && isYaml(d.name)) mine.push(deckInfo(p, e.name));
+        else if (d.isDirectory()) { const m = mainYaml(p); if (m) mine.push(deckInfo(m, e.name)); }
+      }
+      decks.push(...mine);
+      topics.push({ id: e.name, name: e.name, color: meta.color || COLORS[topics.length % COLORS.length], count: mine.length, created: meta.created || 0 });
+    }
+    topics.sort((a, b) => a.name.localeCompare(b.name, "pt-BR"));
+    return { root, topics, decks, trash: listTrash() };
+  }
+
+  // ---- tópicos ----
+  function topicDir(id) {
+    const dir = resolveId(id);
+    if (path.dirname(dir) !== root) throw new Error("tópico inválido");
+    return dir;
+  }
+  function createTopic(name, color) {
+    const n = safeName(name, "Novo tópico");
+    fs.mkdirSync(root, { recursive: true });
+    // Repeated requests (including Enter + click) reuse the topic, never multiply folders.
+    const existing = fs.readdirSync(root, { withFileTypes: true }).find(e => e.isDirectory() && !hidden(e.name) && e.name.normalize("NFC").toLocaleLowerCase("pt-BR") === n.toLocaleLowerCase("pt-BR"));
+    if (existing) return existing.name;
+    const dir = uniquePath(root, n);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, TOPIC_META), JSON.stringify({ color: color || COLORS[list().topics.length % COLORS.length], created: Date.now() }));
+    return path.basename(dir);
+  }
+  function updateTopic(id, { name, color } = {}) {
+    let dir = topicDir(id);
+    if (color) fs.writeFileSync(path.join(dir, TOPIC_META), JSON.stringify({ ...topicMeta(dir), color }));
+    if (name && safeName(name) !== path.basename(dir)) {
+      const to = uniquePath(root, safeName(name));
+      fs.renameSync(dir, to);
+      dir = to;
+    }
+    return path.basename(dir);
+  }
+  function deleteTopic(id) {
+    const dir = topicDir(id);
+    const left = fs.readdirSync(dir).filter((n) => !hidden(n));
+    if (left.length) throw new Error("o tópico não está vazio: mova ou exclua as apresentações antes");
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+
+  // ---- apresentações ----
+  const ensureTopic = (name) => (fs.existsSync(path.join(root, name)) ? name : createTopic(name));
+
+  function createDeck(topic, spec) {
+    const title = spec?.title || "Nova apresentação";
+    const base = topicDir(topic || ensureTopic("Sem tópico"));
+    const dir = uniquePath(base, safeName(title));
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, path.basename(dir) + ".yaml");
+    fs.writeFileSync(file, YAML.stringify(spec, { indent: 2, lineWidth: 0 }));
+    return idOf(file);
+  }
+
+  // pasta que "é" a apresentação (para mover/duplicar/excluir): a pasta própria, ou só o .yaml solto
+  // o id diz onde está: "x.yaml" (raiz), "Tópico/x.yaml" (solto no tópico), "Tópico/Pasta/x.yaml" (pasta própria)
+  function unitOf(id) {
+    const file = resolveId(id);
+    if (!fs.existsSync(file) || !isYaml(path.basename(file))) throw new Error("apresentação não encontrada");
+    const parts = idOf(file).split("/");
+    if (parts.length > 3) throw new Error("apresentação fora da estrutura da biblioteca");
+    const info = deckInfo(file, parts.length > 1 ? parts[0] : "");
+    return { file, unit: parts.length === 3 ? path.dirname(file) : file, info };
+  }
+
+  function moveDeck(id, topic) {
+    const { file, unit } = unitOf(id);
+    if (!topic && path.dirname(unit) === root) return id; // .yaml solto na raiz: já está sem tópico
+    // sem tópico = a pasta "Sem tópico": na raiz só ficam tópicos, nunca a pasta de uma apresentação
+    const dest = topicDir(topic || ensureTopic("Sem tópico"));
+    if (path.dirname(unit) === dest) return id;
+    const ext = unit === file ? path.extname(file) : "";
+    const to = uniquePath(dest, path.basename(unit, ext), ext);
+    fs.renameSync(unit, to);
+    return idOf(unit === file ? to : path.join(to, path.basename(file)));
+  }
+
+  function renameDeck(id, title) {
+    const { file, unit } = unitOf(id);
+    const spec = YAML.parse(fs.readFileSync(file, "utf8")) || {};
+    spec.title = title;
+    writeDeckFile(file, spec); // só o título muda no arquivo
+    if (unit === file) return id; // .yaml solto: só o título
+    const to = uniquePath(path.dirname(unit), safeName(title));
+    if (path.basename(to) === path.basename(unit)) return id;
+    fs.renameSync(unit, to);
+    // o .yaml com o nome da pasta acompanha a pasta
+    let yaml = path.join(to, path.basename(file));
+    if (path.basename(file).replace(/\.ya?ml$/i, "") === path.basename(unit)) {
+      const renamed = path.join(to, path.basename(to) + path.extname(file));
+      fs.renameSync(yaml, renamed);
+      yaml = renamed;
+    }
+    return idOf(yaml);
+  }
+
+  function duplicateDeck(id) {
+    const { file, unit, info } = unitOf(id);
+    const title = `${info.title} (cópia)`;
+    const ext = unit === file ? path.extname(file) : "";
+    const to = uniquePath(path.dirname(unit), safeName(title), ext);
+    fs.cpSync(unit, to, { recursive: true });
+    let yaml = unit === file ? to : path.join(to, path.basename(file));
+    if (unit !== file && path.basename(file).replace(/\.ya?ml$/i, "") === path.basename(unit)) {
+      const renamed = path.join(to, path.basename(to) + path.extname(file));
+      fs.renameSync(yaml, renamed);
+      yaml = renamed;
+    }
+    const spec = YAML.parse(fs.readFileSync(yaml, "utf8")) || {};
+    spec.title = title;
+    writeDeckFile(yaml, spec);
+    return idOf(yaml);
+  }
+
+  // ---- lixeira ----
+  function trashDeck(id) {
+    const { file, unit, info } = unitOf(id);
+    const tdir = path.join(root, TRASH);
+    fs.mkdirSync(tdir, { recursive: true });
+    const slot = path.join(tdir, `${Date.now()}-${path.basename(unit)}`);
+    fs.mkdirSync(slot);
+    fs.renameSync(unit, path.join(slot, path.basename(unit)));
+    fs.writeFileSync(path.join(slot, ".origem.json"), JSON.stringify({
+      topic: info.topic, title: info.title, deleted: Date.now(), yaml: path.relative(unit === file ? path.dirname(file) : unit, file),
+      unit: path.basename(unit), slides: info.slides,
+    }));
+    return path.basename(slot);
+  }
+  function listTrash() {
+    const tdir = path.join(root, TRASH);
+    if (!fs.existsSync(tdir)) return [];
+    return fs.readdirSync(tdir).map((slot) => {
+      try { return { id: slot, ...JSON.parse(fs.readFileSync(path.join(tdir, slot, ".origem.json"), "utf8")) }; } catch { return null; }
+    }).filter(Boolean).sort((a, b) => b.deleted - a.deleted);
+  }
+  function restoreDeck(slotId) {
+    const slot = path.join(root, TRASH, path.basename(slotId));
+    const o = JSON.parse(fs.readFileSync(path.join(slot, ".origem.json"), "utf8"));
+    const dest = o.topic && fs.existsSync(path.join(root, o.topic)) ? path.join(root, o.topic) : o.topic ? path.join(root, createTopic(o.topic)) : root;
+    const isFile = /\.ya?ml$/i.test(o.unit);
+    const ext = isFile ? path.extname(o.unit) : "";
+    const to = uniquePath(dest, path.basename(o.unit, ext), ext);
+    fs.renameSync(path.join(slot, o.unit), to);
+    fs.rmSync(slot, { recursive: true, force: true });
+    return idOf(isFile ? to : path.join(to, o.yaml));
+  }
+  function purgeDeck(slotId) {
+    fs.rmSync(path.join(root, TRASH, path.basename(slotId)), { recursive: true, force: true });
+  }
+  // esvaziar a lixeira: tudo de uma vez (a pessoa confirma antes, no Studio)
+  function emptyTrash() {
+    const all = listTrash();
+    all.forEach((t) => purgeDeck(t.id));
+    return all.length;
+  }
+  function purgeOld(now = Date.now()) {
+    for (const t of listTrash()) if (now - t.deleted > TRASH_DAYS * 864e5) purgeDeck(t.id);
+  }
+
+  // ---- importar .sagadeck / .zip ----
+  async function importPackage(buffer, topic, name = "Importada") {
+    const base = topicDir(topic || ensureTopic("Importados"));
+    const dir = uniquePath(base, safeName(name.replace(/\.(sagadeck|zip)$/i, "")));
+    const { file } = await unpackDeck(buffer, dir);
+    return idOf(file);
+  }
+
+  // .pptx (PowerPoint, Google Slides, Keynote exportado) vira uma apresentação da biblioteca, fiel ao original
+  // (src/import): cada slide na mesma posição, mídias em imagens/original/, cópia e fotos do original em original/
+  async function importOffice(buffer, topic, name = "Importada.pptx", opts = {}) {
+    if (!/\.pptx$/i.test(name)) throw new Error("Por enquanto a importação lê .pptx (o PowerPoint salva em .pptx; o Google Slides e o Keynote exportam).");
+    const { importToDir } = await import("./import/index.js");
+    const base = topicDir(topic || ensureTopic("Importados"));
+    const dir = uniquePath(base, safeName(opts.title || name.replace(/\.pptx$/i, "")));
+    const r = await importToDir(buffer, dir, { fileName: path.basename(name), snapshots: opts.snapshots !== false, log: opts.log });
+    if (opts.title) r.spec.title = opts.title;
+    const file = path.join(dir, path.basename(dir) + ".yaml");
+    fs.writeFileSync(file, YAML.stringify(r.spec, { indent: 2, lineWidth: 0 }));
+    return { id: idOf(file), file, slides: r.spec.slides.length, snapshots: r.snapshots, snapBy: r.snapBy, converted: r.converted, warnings: r.warnings };
+  }
+
+  // ---- estilos da pessoa (tema + mestre), reutilizáveis: <biblioteca>/.estilos/<slug>/estilo.yaml + imagens
+  const stylesRoot = path.join(root, ".estilos");
+  const slug = (n) => safeName(String(n || "estilo")).toLowerCase().replace(/\s+/g, "-");
+  // estilo padrão (Brand Kit): toda apresentação nova (em branco ou com IA, sem tema escolhido) já nasce com ele.
+  // Guardado na própria biblioteca (.estilos/padrao.json): vale para quem usar esta biblioteca, em qualquer máquina.
+  const defaultFile = path.join(stylesRoot, "padrao.json");
+  function defaultStyle() {
+    try { const id = JSON.parse(fs.readFileSync(defaultFile, "utf8")).id; return id && fs.existsSync(path.join(stylesRoot, slug(id), "estilo.yaml")) ? slug(id) : null; } catch { return null; }
+  }
+  function setDefaultStyle(id) {
+    if (!id) { fs.rmSync(defaultFile, { force: true }); return null; }
+    loadStyle(id); // existe?
+    fs.mkdirSync(stylesRoot, { recursive: true });
+    fs.writeFileSync(defaultFile, JSON.stringify({ id: slug(id) }));
+    return slug(id);
+  }
+  // apresentação nova: com o padrão, se houver e se ela ainda não tem estilo próprio
+  function withDefaultStyle(spec, deckDir) {
+    const id = defaultStyle();
+    if (!id || spec?.master || spec?.style) return spec;
+    try { return applyStyleTo(spec, deckDir, id); } catch { return spec; }
+  }
+
+  function listStyles() {
+    if (!fs.existsSync(stylesRoot)) return [];
+    return fs.readdirSync(stylesRoot, { withFileTypes: true }).filter((d) => d.isDirectory() && fs.existsSync(path.join(stylesRoot, d.name, "estilo.yaml"))).map((d) => {
+      try { const st = YAML.parse(fs.readFileSync(path.join(stylesRoot, d.name, "estilo.yaml"), "utf8")); return { id: d.name, name: st.name || d.name, default: d.name === defaultStyle(), from: st.from || null, accent: st.theme?.colors?.accent || null, paper: st.theme?.colors?.paper || null }; }
+      catch { return null; }
+    }).filter(Boolean).sort((x, y) => x.name.localeCompare(y.name, "pt-BR"));
+  }
+  function saveStyle(style, fromDir, { replace = false } = {}) {
+    const { masterImages } = MASTER;
+    let id = slug(style.name);
+    if (!replace) { const base = id; for (let n = 2; fs.existsSync(path.join(stylesRoot, id)); n++) id = `${base}-${n}`; }
+    const dir = path.join(stylesRoot, id);
+    fs.mkdirSync(dir, { recursive: true });
+    for (const rel of masterImages(style.master)) {
+      const src = path.resolve(fromDir, rel);
+      if (!src.startsWith(path.resolve(fromDir)) || !fs.existsSync(src)) continue;
+      const dst = path.join(dir, ...rel.split("/"));
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.copyFileSync(src, dst);
+    }
+    fs.writeFileSync(path.join(dir, "estilo.yaml"), YAML.stringify(style, { indent: 2, lineWidth: 0 }));
+    return { id, name: style.name };
+  }
+  function loadStyle(id) {
+    const dir = path.join(stylesRoot, slug(id));
+    if (!dir.startsWith(stylesRoot) || !fs.existsSync(path.join(dir, "estilo.yaml"))) throw new Error("estilo não encontrado");
+    return { style: YAML.parse(fs.readFileSync(path.join(dir, "estilo.yaml"), "utf8")), dir, id: slug(id) };
+  }
+  // aplica num deck (spec + pasta): as imagens da moldura vão para imagens/estilo/<id>/ e o deck fica portátil
+  function applyStyleTo(spec, deckDir, id) {
+    const { style, dir } = loadStyle(id);
+    const { masterImages } = MASTER;
+    const map = new Map();
+    for (const rel of masterImages(style.master)) {
+      const src = path.join(dir, ...rel.split("/"));
+      if (!fs.existsSync(src)) continue;
+      const to = `imagens/estilo/${slug(id)}/${path.basename(rel)}`;
+      const dst = path.join(deckDir, ...to.split("/"));
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.copyFileSync(src, dst);
+      map.set(rel, to);
+    }
+    const master = structuredClone(style.master);
+    const fix = (list) => (list || []).forEach((e) => { if (e.image && map.has(e.image)) e.image = map.get(e.image); if (e.drawing) e.drawing = String(e.drawing).replace(/href="media:([^"]+)"/g, (m, r) => `href="media:${map.get(r) || r}"`); });
+    fix(master.elements); fix(master.cover);
+    return { ...spec, theme: style.theme, master, footer: false, style: { id: slug(id), name: style.name } };
+  }
+
+  return {
+    listStyles, saveStyle, loadStyle, applyStyleTo, defaultStyle, setDefaultStyle, withDefaultStyle,
+    importOffice,
+    root, list, resolveId, idOf,
+    createTopic, updateTopic, deleteTopic,
+    createDeck, moveDeck, renameDeck, duplicateDeck,
+    trashDeck, restoreDeck, purgeDeck, purgeOld, listTrash, emptyTrash,
+    importPackage,
+  };
+}