@anja.codes/vitakit 0.1.0 → 0.2.0

package/dist/shared/{vitakit.BlU-p01e.mjs → vitakit.CtChKO0I.mjs}

@@ -11,4 +11,4 @@ function richHtml(value) {
   return void 0;
 }
 
-export { richHtml as a, richSource as r };
+export { richSource as a, richHtml as r };

package/dist/shared/vitakit.D-DdJaDZ.mjs

@@ -0,0 +1,20 @@
+function fieldValue(entry, field) {
+  if (field === "year" && !Object.hasOwn(entry, "year")) {
+    return entry.date?.from?.year;
+  }
+  const value = entry[field];
+  if (typeof value === "object" && value !== null && "text" in value) return value.text;
+  if (typeof value === "object" && value !== null && "label" in value) return value.label;
+  return value;
+}
+function matchesWhere(entry, where) {
+  return Object.entries(where).every(([field, expected]) => {
+    const wanted = (Array.isArray(expected) ? expected : [expected]).map(String);
+    return wanted.includes(String(fieldValue(entry, field) ?? ""));
+  });
+}
+function filterWhere(entries, where) {
+  return where && Object.keys(where).length ? entries.filter((entry) => matchesWhere(entry, where)) : [...entries];
+}
+
+export { filterWhere as a, fieldValue as f, matchesWhere as m };

package/dist/shared/vitakit.D10HyDhF.mjs

@@ -0,0 +1,19 @@
+const PATH_KEY = "__vitakitPath";
+const isSitePath = (value) => value.startsWith("/") && !value.startsWith("//");
+const sitePathMarker = (path) => ({ [PATH_KEY]: path });
+function isSitePathMarker(value) {
+  return typeof value === "object" && value !== null && PATH_KEY in value;
+}
+function resolveSitePaths(value, resolve) {
+  if (isSitePathMarker(value)) return resolve(value[PATH_KEY]);
+  if (Array.isArray(value)) return value.map((item) => resolveSitePaths(item, resolve));
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolveSitePaths(item, resolve)]));
+  }
+  return value;
+}
+function absoluteSitePath(path, siteUrl) {
+  return siteUrl ? `${siteUrl.replace(/\/?$/, "/")}${path.slice(1)}` : path;
+}
+
+export { PATH_KEY as P, absoluteSitePath as a, isSitePath as i, resolveSitePaths as r, sitePathMarker as s };

package/dist/shared/vitakit.DQ6PmGoL.mjs

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function sourcePath(asset) {
+  return asset === "styles" ? asset : join("src", asset);
+}
+let root;
+function packageRoot() {
+  if (root) return root;
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 6; depth += 1) {
+    if (existsSync(join(dir, "package.json"))) return root = dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error("vitakit: cannot locate the package root; the installation is incomplete");
+}
+const built = /[/\\]dist[/\\]/.test(import.meta.url);
+function resolveAsset(asset) {
+  const base = packageRoot();
+  const order = built ? ["dist", void 0] : [void 0, "dist"];
+  const candidates = order.map((prefix) => prefix ? join(base, prefix, asset) : join(base, sourcePath(asset)));
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    `vitakit: missing bundled asset "${asset}"; looked in
+` + candidates.map((candidate) => `  ${candidate}`).join("\n") + "\nRun `pnpm build` in the package, or reinstall it."
+  );
+}
+
+export { packageRoot as p, resolveAsset as r };

package/dist/shared/vitakit.DbSeENVS.mjs

@@ -0,0 +1,58 @@
+import { pathToFileURL } from 'node:url';
+
+class ContentError extends Error {
+  constructor(where, message) {
+    super(`${where}: ${message}`);
+    this.where = where;
+    this.name = "ContentError";
+  }
+}
+function fail(where, message) {
+  throw new ContentError(where, message);
+}
+function messageOf(error) {
+  if (error instanceof ContentError) return error.message.slice(error.where.length + 2);
+  return error instanceof Error ? error.message : String(error);
+}
+function whereOf(error, fallback) {
+  return error instanceof ContentError ? error.where : fallback;
+}
+async function importProjectModule(path, mtimeMs, where) {
+  try {
+    return await import(`${pathToFileURL(path).href}?mtime=${mtimeMs}`);
+  } catch (error) {
+    fail(where, importFailure(error));
+  }
+}
+function importFailure(error, node = process.versions.node) {
+  if (error?.code === "ERR_UNKNOWN_FILE_EXTENSION") {
+    return `cannot load TypeScript on Node ${node}; vitakit needs Node 22.18 or newer`;
+  }
+  return messageOf(error);
+}
+function formatZodIssues(error) {
+  return error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+}
+class Issues {
+  constructor(strict) {
+    this.strict = strict;
+  }
+  list = [];
+  /** Record a problem, or throw it when strict. */
+  record(where, message) {
+    if (this.strict) fail(where, message);
+    this.list.push({ where, message });
+  }
+  /** Run `run`; when lenient, record any failure and use `fallback` instead. */
+  async attempt(where, run, fallback) {
+    try {
+      return await run();
+    } catch (error) {
+      if (this.strict) throw error;
+      this.list.push({ where: whereOf(error, where), message: messageOf(error) });
+      return fallback;
+    }
+  }
+}
+
+export { Issues as I, formatZodIssues as a, fail as f, importProjectModule as i, messageOf as m, whereOf as w };

package/dist/shared/vitakit.DcQOdM4I.mjs

@@ -0,0 +1,57 @@
+const REPLACEMENTS = {
+  "\\": "\\textbackslash{}",
+  "&": "\\&",
+  "%": "\\%",
+  $: "\\$",
+  "#": "\\#",
+  _: "\\_",
+  "{": "\\{",
+  "}": "\\}",
+  "~": "\\textasciitilde{}",
+  "^": "\\textasciicircum{}"
+};
+const TYPOGRAPHY = [
+  // Directional quotes: "..." -> ``...''
+  [/"([^"]*)"/g, "``$1''"],
+  // An en dash written literally
+  [/\u2013/g, "--"],
+  [/\u2014/g, "---"],
+  [/\u2026/g, "\\ldots{}"],
+  [/\u00a0/g, "~"]
+];
+function escapeTex(value, { typography = true, source } = {}) {
+  if (source !== void 0 && /(?<!\\)\$/.test(value)) {
+    throw new Error(`unbalanced math delimiters in: ${source}`);
+  }
+  let result = value.replace(/[\\&%$#_{}~^]/g, (character) => REPLACEMENTS[character]);
+  if (typography) {
+    for (const [pattern, replacement] of TYPOGRAPHY) result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+function escapeProse(prose, source) {
+  if (/(?<!\\)\$/.test(prose)) throw new Error(`unbalanced math delimiters in: ${source}`);
+  return escapeTex(prose.replace(/\\([!-/:-@[-`{-~])/g, "$1"));
+}
+function escapeRichTex(value) {
+  const parts = [];
+  const pattern = /(?<!\\)\$\$[\s\S]*?\$\$|(?<!\\)\$(?:\\.|[^$\\])*\$/g;
+  let index = 0;
+  for (const match of value.matchAll(pattern)) {
+    const start = match.index;
+    parts.push(escapeProse(value.slice(index, start), value));
+    parts.push(match[0]);
+    index = start + match[0].length;
+  }
+  parts.push(escapeProse(value.slice(index), value));
+  return parts.join("");
+}
+const URL_SPECIAL = /%[0-9A-Fa-f]{2}|[%\\{}^ #&]/g;
+function escapeUrl(value) {
+  return value.replace(URL_SPECIAL, (match) => {
+    if (match.length === 3 || match === "#" || match === "&") return `\\${match}`;
+    return `\\%${match.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+  });
+}
+
+export { escapeTex as a, escapeUrl as b, escapeRichTex as e };

package/dist/shared/vitakit.Do5HC_MD.mjs

@@ -0,0 +1,142 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+const posix = (path) => path.split(sep).join("/");
+async function vueFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...await vueFiles(path));
+    else if (entry.name.endsWith(".vue")) files.push(path);
+  }
+  return files.sort();
+}
+const pascal = (name) => name.split(/[-_.\s]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+function componentName(pathBelowComponents) {
+  const parts = posix(pathBelowComponents).replace(/\.vue$/, "").split("/").map(pascal);
+  let name = "";
+  for (const part of parts) name = part.startsWith(name) ? part : name + part;
+  return name;
+}
+function pageRoute(pathBelowPages) {
+  const path = posix(pathBelowPages).replace(/\.vue$/, "").replace(/(^|\/)index$/, "");
+  return path ? `/${path}/` : "/";
+}
+function literal(expression) {
+  return /^\s*(['"`])([^'"`$]*)\1\s*$/.exec(expression)?.[2];
+}
+const ELEMENT = 1;
+const ATTRIBUTE = 6;
+function attribute(node, name) {
+  for (const prop of node.props ?? []) {
+    if (prop.type === ATTRIBUTE && prop.name === name) return { static: prop.value?.content ?? "" };
+    if (prop.type !== ATTRIBUTE && prop.name === "bind" && prop.arg?.content === name) {
+      return { expression: prop.exp?.content ?? "" };
+    }
+  }
+  return void 0;
+}
+function lineOf(text, offset) {
+  let line = 1;
+  for (let index = 0; index < offset; index++) if (text.charCodeAt(index) === 10) line++;
+  return line;
+}
+async function findWebPlacements(rootDir) {
+  const { parse } = await import('@vue/compiler-sfc');
+  const appDir = join(rootDir, "app");
+  const componentsDir = join(appDir, "components");
+  const pagesDir = join(appDir, "pages");
+  const components = /* @__PURE__ */ new Map();
+  for (const file of await vueFiles(componentsDir)) {
+    components.set(componentName(relative(componentsDir, file)), posix(relative(rootDir, file)));
+  }
+  const placements = [];
+  const dynamic = [];
+  for (const path of await vueFiles(appDir)) {
+    const file = posix(relative(rootDir, path));
+    const inPages = !relative(pagesDir, path).startsWith("..");
+    const inComponents = !relative(componentsDir, path).startsWith("..");
+    const route = inPages ? pageRoute(relative(pagesDir, path)) : void 0;
+    const source = await readFile(path, "utf8");
+    const { descriptor } = parse(source, { filename: path });
+    const visit = (node) => {
+      if (node.type === ELEMENT && node.tag) {
+        const tag = node.tag.includes("-") ? pascal(node.tag) : node.tag;
+        if (tag === "VitaSection" || components.has(tag)) {
+          const id = attribute(node, "id");
+          const section = id?.static ?? (id?.expression !== void 0 ? literal(id.expression) : void 0);
+          if (section) {
+            const title = attribute(node, "title");
+            const where = attribute(node, "where");
+            const limit = attribute(node, "limit");
+            placements.push({
+              section,
+              file,
+              route,
+              line: node.loc.start.line,
+              component: tag,
+              ...title?.static !== void 0 ? { title: title.static } : {},
+              ...where?.expression !== void 0 ? { where: where.expression } : {},
+              ...limit ? { limit: limit.static ?? limit.expression } : {}
+            });
+          } else if (id?.expression !== void 0 && !inComponents) {
+            dynamic.push({ file, line: node.loc.start.line, usage: `<${node.tag} :id="${id.expression}">` });
+          }
+        }
+      }
+      for (const child of node.children ?? []) visit(child);
+    };
+    if (descriptor.template?.ast) visit(descriptor.template.ast);
+    for (const block of [descriptor.script, descriptor.scriptSetup]) {
+      if (!block) continue;
+      const start = block.loc.start.line - 1;
+      for (const match of block.content.matchAll(/\buseSection\(\s*([^)]*?)\s*\)/g)) {
+        const line = start + lineOf(block.content, match.index);
+        const section = literal(match[1]);
+        if (section) placements.push({ section, file, route, line, component: "code" });
+        else if (!inComponents) dynamic.push({ file, line, usage: `useSection(${match[1]})` });
+      }
+    }
+  }
+  return { placements, dynamic, components };
+}
+function stripComment(line) {
+  const match = /(^|[^\\])%/.exec(line);
+  return match ? line.slice(0, match.index + match[1].length) : line;
+}
+function findPdfPlacements(document, file, source) {
+  const placements = [];
+  const lines = source.split("\n");
+  let inBody = false;
+  for (const [index, raw] of lines.entries()) {
+    const line = stripComment(raw);
+    if (!inBody) {
+      if (/\\begin\{document\}/.test(line)) inBody = true;
+      else continue;
+    }
+    for (const match of line.matchAll(/\\vitasection(?:\[([^\]]*)\])?\{([^}]*)\}/g)) {
+      placements.push({
+        section: match[2].trim(),
+        document,
+        file,
+        line: index + 1,
+        macro: "vitasection",
+        ...match[1] !== void 0 ? { heading: match[1] } : {}
+      });
+    }
+    for (const match of line.matchAll(/\\vitainput\{([^}]*)\}/g)) {
+      placements.push({ section: match[1].trim(), document, file, line: index + 1, macro: "vitainput" });
+    }
+  }
+  return placements;
+}
+function documentDirective(source) {
+  for (const [index, raw] of source.split("\n").entries()) {
+    const match = /\\vitadocument\{([^}]*)\}/.exec(stripComment(raw));
+    if (match) return { name: match[1].trim(), line: index + 1 };
+  }
+  return void 0;
+}
+
+export { findWebPlacements as a, documentDirective as d, findPdfPlacements as f, pageRoute as p };

package/dist/shared/vitakit.TSMTC5Jl.mjs

@@ -0,0 +1,6 @@
+const LEVEL = { public: 0, cv: 1, private: 2 };
+function atMost(value, limit) {
+  return LEVEL[value ?? "public"] <= LEVEL[limit];
+}
+
+export { atMost as a };

package/dist/tex/templates/_generic.eta

@@ -1,6 +1,8 @@
 <% for (const item of it.entries) { %>
-\vitaentry{<%~ it.date(item.date) %>}{<%~ it.rich(it.titleOf(item)) %>}{<%~ it.secondaryOf(item) %>}
-<% if (item.note) { %>
-  \vitanote{<%~ it.rich(item.note) %>}
-<% } %>
+<%~ it.vita.entry({
+  date: it.date(item.date),
+  title: it.generic.title(item),
+  context: it.generic.context(item)
+}) %>
+<%~ it.vita.note(item.note) %>
 <% } %>

package/dist/tex/templates/education.eta

@@ -1,9 +1,14 @@
 <% for (const item of it.entries) { %>
-\vitaentry{<%~ it.date(item.date) %>}{<%~ it.rich(item.degree) %>}{<%~ it.inst(item.institution) %>}
+<%~ it.vita.entry({
+  date: it.date(item.date),
+  title: item.degree,
+  context: it.linked(item.institution)
+}) %>
 <% if (item.thesis) { %>
-  \vitanote{<%~ it.tex(item.thesis.type ?? 'Thesis') %>: \emph{<%~ it.rich(item.thesis.title) %>}<% if (item.thesis.supervisor) { %>, supervised by <%~ it.linkOrText(item.thesis.supervisor) %><% } %>}
-<% } %>
-<% if (item.note) { %>
-  \vitanote{<%~ it.rich(item.note) %>}
+<%~ it.vita.note(it.join([
+  it.optional`${item.thesis.type ?? 'Thesis'}: \emph{${item.thesis.title}}`,
+  it.optional`, supervised by ${it.linked(item.thesis.supervisor)}`
+], '')) %>
 <% } %>
+<%~ it.vita.note(item.note) %>
 <% } %>

package/dist/tex/templates/employment.eta

@@ -1,9 +1,16 @@
 <% for (const item of it.entries) { %>
-\vitaentry{<%~ it.date(item.date) %>}{<%~ it.rich(item.position) %>}{<%~ it.inst(item.institution) %>}
+<%~ it.vita.entry({
+  date: it.date(item.date),
+  title: item.position,
+  context: it.linked(item.institution)
+}) %>
 <% if (item.project) { %>
-  \vitanote{Project <% if (item.project.url) { %>\href{<%~ it.url(item.project.url) %>}{\emph{<%~ it.rich(item.project.title) %>}}<% } else { %>\emph{<%~ it.rich(item.project.title) %>}<% } %><% if (item.project.funder) { %> (<%~ it.tex(item.project.funder) %><% if (item.project.grant) { %>~<%~ it.tex(item.project.grant) %><% } %>)<% } %>}
-<% } %>
-<% if (item.note) { %>
-  \vitanote{<%~ it.rich(item.note) %>}
+<%~ it.vita.note(it.join([
+  it.optional`Project \emph{${it.linked(item.project.title, item.project.url)}}`,
+  item.project.funder
+    ? it.optional` (${it.join([item.project.funder, item.project.grant], it.optional`~`)})`
+    : ''
+], '')) %>
 <% } %>
+<%~ it.vita.note(item.note) %>
 <% } %>

package/dist/tex/templates/publications.eta

@@ -1,7 +1,9 @@
+<% if (it.groups.length) { %>
 \begin{refsection}
 \nocite{*}
 <% for (const group of it.groups) { %>
-<%~ it.bibgroup(group) %>
-\printbibliography[check=vita-<%~ group.id %>, title={<%~ it.tex(group.label) %>}, heading=subbibliography]
+<%~ it.bib.group(group) %>
+\printbibliography[check=vita-<%~ group.id %>, title={<%~ it.text(group.label) %>}, heading=subbibliography]
 <% } %>
 \end{refsection}
+<% } %>

package/dist/tex/templates/supervision.eta

@@ -1,4 +1,12 @@
 <% for (const item of it.entries) { %>
-\vitaentry{<%~ it.date(item.date) %><% if (item.ongoing) { %>--<% } %>}{<%~ it.tex(item.student) %>}{<%~ [item.degree && it.tex(item.degree), it.inst(item.institution)].filter(Boolean).join(', ') %>}
-  \vitanote{\emph{<%~ it.rich(item.title) %>}<% if (item.coSupervisor) { %>, with <%~ it.tex(item.coSupervisor) %><% } %><% if (item.ongoing) { %> (in progress)<% } %>}
+<%~ it.vita.entry({
+  date: it.join([it.date(item.date), item.ongoing ? '--' : ''], ''),
+  title: item.student,
+  context: it.join([item.degree, it.linked(item.institution)])
+}) %>
+<%~ it.vita.note(it.join([
+  it.optional`\emph{${item.title}}`,
+  it.optional`, with ${item.coSupervisor}`,
+  item.ongoing ? ' (in progress)' : ''
+], '')) %>
 <% } %>

package/dist/tex/templates/talks.eta

@@ -1,3 +1,7 @@
 <% for (const item of it.entries) { %>
-\vitaentry{<%~ it.date(item.date) %>}{<%~ it.rich(item.title) %>}{<%~ [item.event && it.tex(item.event), item.location && it.tex(item.location)].filter(Boolean).join(', ') %>}
+<%~ it.vita.entry({
+  date: it.date(item.date),
+  title: item.title,
+  context: it.join([item.event, item.location])
+}) %>
 <% } %>

package/dist/tex/templates/teaching.eta

@@ -1,6 +1,8 @@
 <% for (const item of it.entries) { %>
-\vitaentry{<%~ it.term(item) %>}{<%~ it.rich(item.title) %>}{<%~ [item.role, it.inst(item.institution)].filter(Boolean).join(', ') %>}
-<% if (item.note) { %>
-  \vitanote{<%~ it.rich(item.note) %>}
-<% } %>
+<%~ it.vita.entry({
+  date: it.text(item.term) || it.date(item.date),
+  title: item.title,
+  context: it.join([item.role, it.linked(item.institution)])
+}) %>
+<%~ it.vita.note(item.note) %>
 <% } %>

package/dist/tex/vitakit-cv.cls

@@ -13,6 +13,15 @@
 \ProcessOptions\relax
 \LoadClass[11pt,a4paper]{article}
 
+%% pdfLaTeX's default font encoding (OT1) has no „, ‚, ł, ő and many other
+%% characters of names, places and titles; T1 has them. LuaLaTeX and XeLaTeX
+%% use Unicode fonts instead.
+\RequirePackage{iftex}
+\ifPDFTeX
+  \RequirePackage[T1]{fontenc}
+  \RequirePackage{lmodern}
+\fi
+
 \RequirePackage[margin=2.5cm]{geometry}
 \RequirePackage{enumitem}
 \RequirePackage{xcolor}
@@ -105,12 +114,18 @@
 %% that it is safe after any preceding content, including none.
 \newcommand{\vitanote}[1]{\par{\small\color{vitamuted}#1}}
 
-%% \vitasection{id} -- heading plus the generated file for this document.
-\newcommand{\vitasection}[1]{%
-  \section{\vita@titlefor{#1}}%
-  \begin{vitaentries}%
-  \input{generated/\vita@document/#1.tex}%
-  \end{vitaentries}}
+%% Generated profile.tex marks sections whose selection is empty.
+\newcommand{\vitaemptysection}[1]{\expandafter\def\csname vita@empty@#1\endcsname{}}
+
+%% \vitasection[Heading]{id} -- an optional heading for this invocation only.
+%% Otherwise use the document/preamble label, falling back to the section id.
+\NewDocumentCommand{\vitasection}{o m}{%
+  \ifcsname vita@empty@#2\endcsname\else
+    \IfNoValueTF{#1}{\section{\vita@titlefor{#2}}}{\section{#1}}%
+    \begin{vitaentries}%
+    \input{generated/\vita@document/#2.tex}%
+    \end{vitaentries}%
+  \fi}
 
 %% \vitainput{id} -- the generated file without heading or list wrapper,
 %% for sections that bring their own structure (publications).

package/dist/tex.d.mts

@@ -7,6 +7,28 @@ interface BuildOptions {
     only?: string[];
     /** Emit .tex but skip latexmk. */
     noPdf?: boolean;
+    /**
+     * What happens to latexmk's output: shown as it runs (`inherit`, the
+     * default), or kept back and only its end shown on failure (`capture`).
+     */
+    latexOutput?: 'inherit' | 'capture';
+    /** Told about each finished step, for concise progress output. */
+    onProgress?: (event: BuildEvent) => void;
+}
+type BuildEvent = {
+    document: string;
+    step: 'tex';
+    dir: string;
+    files: number;
+} | {
+    document: string;
+    step: 'pdf';
+    file: string;
+};
+/** A tool of the TeX distribution is not installed. */
+declare class MissingToolError extends Error {
+    readonly tool: string;
+    constructor(tool: string);
 }
 declare function buildCv(options: BuildOptions): Promise<string[]>;
 /** Read a generated file, for tests and diagnostics. */
@@ -19,7 +41,7 @@ declare const documentSchema: z.ZodObject<{
         private: "private";
     }>>;
     sections: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        where: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+        where: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>>;
         limit: z.ZodOptional<z.ZodNumber>;
         since: z.ZodOptional<z.ZodNumber>;
         until: z.ZodOptional<z.ZodNumber>;
@@ -36,13 +58,31 @@ interface DocumentSource {
     texFile: string;
     options: DocumentOptions;
 }
-/** Read every `cv-tex/*.tex` and its options. */
+/** Read every `cv-tex/*.tex` and its options. Strict: the first problem throws. */
 declare function discoverDocuments(cvDir: string): Promise<DocumentSource[]>;
 /** Select the entries of one section for one document. */
 declare function selectEntries(entries: Entry[], options: DocumentOptions, sectionId: string): Entry[];
 
 /** `tex/` in the installed package: templates and the document class. */
 declare const bundledTexDir: string;
+/** Where a template came from, in the order they are tried. */
+interface ResolvedTemplate {
+    path: string;
+    source: string;
+    /** `local` is in `cv-tex/templates/`, `bundled` is the package's own. */
+    origin: 'local' | 'bundled';
+    /** Whether this is `_generic.eta` rather than a template named for the section. */
+    generic: boolean;
+}
+/**
+ * The template that renders section `id`. A file in the repo always wins over
+ * the package default; `_generic.eta` is the fallback for sections without a
+ * dedicated template. `exclude` skips one path, so that replacing a local
+ * template can start from whatever would be used without it.
+ */
+declare function resolveTemplate(id: string, userDir: string, { exclude }?: {
+    exclude?: string;
+}): Promise<ResolvedTemplate>;
 interface EmitOptions {
     sections: Record<string, Entry[]>;
     publications: PublicationGroup[];
@@ -56,6 +96,13 @@ interface EmitOptions {
     /** Path of the .bib file, relative to the generated directory. */
     bibPath?: string;
 }
+/**
+ * Render one section with its effective template, without writing anything.
+ * `entries` are all loaded entries; the document's selection is applied here.
+ */
+declare function renderSection(id: string, entries: Entry[], options: DocumentOptions, templateDir: string): Promise<string>;
+/** Render the publications of one document, without writing anything. */
+declare function renderPublications(publications: PublicationGroup[], options: DocumentOptions, templateDir: string, siteUrl?: string): Promise<string>;
 /** Write one `.tex` file per section, plus `publications.tex`. */
 declare function emitDocument(emit: EmitOptions): Promise<string[]>;
 
@@ -84,10 +131,11 @@ declare function escapeTex(value: string, { typography, source }?: EscapeOptions
  * Escape prose while preserving `$...$` and `$$...$$` spans verbatim.
  *
  * Used for `richText` fields, where a mathematician writes `Random $k$-ary
- * trees` and expects the formula to reach LaTeX untouched.
+ * trees` and expects the formula to reach LaTeX untouched. The prose is
+ * Markdown, so `\$` is a dollar sign and does not start a formula.
  */
 declare function escapeRichTex(value: string): string;
 declare function escapeUrl(value: string): string;
 
-export { buildCv, bundledTexDir, discoverDocuments, documentSchema, emitDocument, escapeRichTex, escapeTex, escapeUrl, readGenerated, selectEntries };
-export type { BuildOptions, DocumentOptions, DocumentSource, EmitOptions, EscapeOptions };
+export { MissingToolError, buildCv, bundledTexDir, discoverDocuments, documentSchema, emitDocument, escapeRichTex, escapeTex, escapeUrl, readGenerated, renderPublications, renderSection, resolveTemplate, selectEntries };
+export type { BuildEvent, BuildOptions, DocumentOptions, DocumentSource, EmitOptions, EscapeOptions, ResolvedTemplate };