docrev 0.9.16 → 0.9.18

package/dist/lib/build.d.ts

@@ -37,14 +37,26 @@ export interface PdfConfig {
     sansfont?: string;
     /** Monospace font (xelatex/lualatex only). */
     monofont?: string;
+    /** Extra pandoc args appended for this format (after top-level pandocArgs). */
+    pandocArgs?: string[];
 }
 export interface DocxConfig {
     reference?: string | null;
     keepComments?: boolean;
+    affiliationNewline?: boolean;
     toc?: boolean;
+    pandocArgs?: string[];
+    /**
+     * Auto-translate the common-shape raw `\begin{figure}...\end{figure}` block
+     * to portable `![caption](path){#fig:label width=N%}` markdown so figures
+     * survive the docx build (pandoc otherwise drops raw LaTeX silently).
+     * Default true. Set false to opt out — blocks then warn and are left alone.
+     */
+    translateRawFigures?: boolean;
 }
 export interface TexConfig {
     standalone?: boolean;
+    pandocArgs?: string[];
 }
 export interface BeamerConfig {
     theme?: string;
@@ -55,6 +67,7 @@ export interface BeamerConfig {
     section?: boolean;
     notes?: string | false;
     fit_images?: boolean;
+    pandocArgs?: string[];
 }
 export interface PptxConfig {
     theme?: string;
@@ -69,6 +82,7 @@ export interface PptxConfig {
         accent?: string;
         enabled?: boolean;
     };
+    pandocArgs?: string[];
 }
 export interface TablesConfig {
     nowrap?: string[];
@@ -103,6 +117,19 @@ export interface BuildConfig {
      * behavior).
      */
     outputDir?: string | null;
+    /**
+     * Per-format output filenames. Keys are format names (pdf/docx/tex/beamer/
+     * pptx); values are paths. Relative paths resolve under outputDir; absolute
+     * paths are honored as-is. Extension is added if missing. CLI `-o` wins
+     * over this map.
+     */
+    output?: Record<string, string>;
+    /**
+     * Extra pandoc args applied to every format. Format-specific args
+     * (e.g. docx.pandocArgs) are appended *after* these, and CLI --pandoc-arg
+     * values are appended last.
+     */
+    pandocArgs?: string[];
     _configPath?: string | null;
 }
 export interface BuildResult {
@@ -114,8 +141,20 @@ export interface BuildResult {
 interface BuildOptions {
     verbose?: boolean;
     config?: BuildConfig;
+    /**
+     * Internal: forces the exact output path. Used by dual-mode/temp builds that
+     * route to specific temp files. Bypasses the `output:` resolver.
+     */
     outputPath?: string;
+    /**
+     * CLI override (`-o, --output <path>`). Beats `config.output[format]` but
+     * loses to `options.outputPath`. Relative paths resolve under outputDir;
+     * absolute paths bypass outputDir.
+     */
+    output?: string;
     crossref?: boolean;
+    /** Extra pandoc args from CLI (--pandoc-arg). Appended after config args. */
+    pandocArgs?: string[];
     _refsAutoInjected?: boolean;
     _forwardRefsResolved?: number;
 }
@@ -203,14 +242,86 @@ export declare function applyFormatTransforms(content: string, format: string, c
  */
 export declare function prepareForFormat(paperPath: string, format: string, config: BuildConfig, _options?: BuildOptions): string;
 /**
- * Build pandoc arguments for format
+ * A raw LaTeX `\begin{figure}...\end{figure}` block found in source markdown.
+ * `exotic` blocks contain features we don't auto-translate (multiple
+ * `\includegraphics`, `\subfloat`, `\rotatebox`, unrecognised width units);
+ * pandoc strips raw LaTeX silently in docx output, so users get warned about
+ * anything that won't be translated.
+ */
+export interface RawLatexFigure {
+    file?: string;
+    line: number;
+    block: string;
+    exotic: boolean;
+}
+/**
+ * Find raw LaTeX figure blocks containing `\includegraphics` in markdown.
+ * `file`, if given, is attached to each result. `line` is 1-based within the
+ * supplied content (the line where `\begin{figure}` sits).
+ */
+export declare function detectRawLatexFigures(content: string, file?: string): RawLatexFigure[];
+/**
+ * Translate the 80% case: single `\includegraphics` figure with optional
+ * `\caption{...}` and `\label{...}`, wrapped in `\begin{figure}...\end{figure}`,
+ * to portable `![caption](path){#fig:label width=N%}` markdown. Exotic blocks
+ * (see `isExoticFigureBlock`) are left untouched.
+ */
+export declare function translateRawLatexFigures(content: string): {
+    translated: string;
+    translatedCount: number;
+};
+/**
+ * Walk section files and gather a warning for any raw LaTeX figure blocks that
+ * won't survive the docx build. Returns null when there's nothing to warn about.
+ */
+export declare function collectRawLatexFigureWarning(directory: string, config: BuildConfig): string | null;
+/**
+ * Build pandoc arguments for format.
+ *
+ * Returns only the built-in args derived from config. Passthrough args
+ * (config.pandocArgs, config[format].pandocArgs, CLI --pandoc-arg) are
+ * appended later in runPandoc so they win against pptx/crossref defaults
+ * added there.
  */
 export declare function buildPandocArgs(format: string, config: BuildConfig, outputPath: string): string[];
+/**
+ * Collect passthrough pandoc args for a format in the canonical order:
+ * top-level config → format-specific config → CLI extras. Later wins for
+ * repeated flags.
+ */
+export declare function collectPandocPassthroughArgs(format: string, config: BuildConfig, extraArgs?: string[]): string[];
 /**
  * Resolve the absolute directory where final outputs should land.
  * Honors config.outputDir; falls back to the project directory when null/empty.
  */
 export declare function resolveOutputDir(directory: string, config: BuildConfig): string;
+/** Get file extension for a format, defaulting to `.pdf`. */
+export declare function getFormatExtension(format: string): string;
+/**
+ * Slugify a title for use as a default output filename. Lowercases, replaces
+ * non-alphanumeric runs with `-`, and truncates at the last `-` boundary
+ * at-or-before MAX_TITLE_FILENAME_LENGTH so words stay whole (the old blind
+ * `.slice` cut mid-word).
+ */
+export declare function slugifyTitle(title: string): string;
+/**
+ * Resolve the final output path for a build.
+ *
+ * Priority: `options.outputPath` (internal force) > `cliOverride` (-o flag) >
+ * `config.output[format]` > slugified title fallback.
+ *
+ * Relative paths from `cliOverride`/`config.output` resolve under outputDir;
+ * absolute paths bypass outputDir. The fallback path always lives under
+ * outputDir.
+ *
+ * @param suffix - Appended before the extension (e.g. "-changes", "-slides").
+ *                 Suppressed when user supplied an explicit name via CLI or
+ *                 config — they pick their own suffix.
+ */
+export declare function resolveOutputPath(directory: string, config: BuildConfig, format: string, options?: {
+    cliOverride?: string;
+    suffix?: string;
+}): string;
 /**
  * Run pandoc build
  */

package/dist/lib/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../lib/build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../lib/build.ts"],"names":[],"mappings":"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"}

package/dist/lib/build.js

@@ -27,8 +27,13 @@ import { resolveCSL } from './csl.js';
 // =============================================================================
 /** Supported output formats */
 const SUPPORTED_FORMATS = ['pdf', 'docx', 'tex', 'beamer', 'pptx'];
-/** Maximum title length for output filename */
-const MAX_TITLE_FILENAME_LENGTH = 50;
+/**
+ * Maximum length for slugified-title output filenames. Only used when no
+ * explicit `output:` filename is configured. Long titles are truncated at the
+ * last `-` boundary at-or-before this length so words stay intact (the old
+ * blind `.slice(0, 50)` cut mid-word).
+ */
+const MAX_TITLE_FILENAME_LENGTH = 80;
 /**
  * Default rev.yaml configuration
  */
@@ -58,8 +63,10 @@ export const DEFAULT_CONFIG = {
     },
     docx: {
         reference: null,
-        keepComments: true,
+        keepComments: false,
+        affiliationNewline: true,
         toc: false,
+        translateRawFigures: true,
     },
     tex: {
         standalone: true,
@@ -157,6 +164,21 @@ export function mergeJournalFormatting(config, formatting, directory) {
     }
     return merged;
 }
+/**
+ * In-place: copy `pandoc-args` → `pandocArgs` on an object (if not already set).
+ * Idempotent. Coerces a single string into a one-element array.
+ */
+function normalizePandocArgsKey(obj) {
+    if (!obj || typeof obj !== 'object')
+        return;
+    const hy = obj['pandoc-args'];
+    if (hy === undefined)
+        return;
+    if (obj.pandocArgs === undefined) {
+        obj.pandocArgs = Array.isArray(hy) ? hy : [hy];
+    }
+    delete obj['pandoc-args'];
+}
 /**
  * Load rev.yaml config from directory
  * @param directory - Project directory path
@@ -175,6 +197,15 @@ export function loadConfig(directory) {
     try {
         const content = fs.readFileSync(configPath, 'utf-8');
         const userConfig = YAML.parse(content) || {};
+        // Accept hyphenated `pandoc-args` (the form pandoc itself uses) in addition
+        // to camelCase `pandocArgs`. Hyphenated is what we document; camelCase is
+        // accepted for users who already prefer that convention.
+        normalizePandocArgsKey(userConfig);
+        for (const fmt of ['pdf', 'docx', 'tex', 'beamer', 'pptx']) {
+            if (userConfig[fmt] && typeof userConfig[fmt] === 'object') {
+                normalizePandocArgsKey(userConfig[fmt]);
+            }
+        }
         // Deep merge with defaults
         let config = {
             ...DEFAULT_CONFIG,
@@ -451,12 +482,16 @@ function generateMarkdownAuthorBlock(config) {
     lines.push(authorParts.join(', '));
     lines.push('');
     // Affiliation lines: ^1^ Department of ...
-    for (const [key, text] of Object.entries(config.affiliations)) {
+    const affiliationEntries = Object.entries(config.affiliations);
+    const useLineBreaks = config.docx.affiliationNewline !== false;
+    affiliationEntries.forEach(([key, text], idx) => {
         const num = keyToNum.get(key);
         if (num !== undefined) {
-            lines.push(`^${num}^ ${text}`);
+            const isLast = idx === affiliationEntries.length - 1;
+            const suffix = useLineBreaks && !isLast ? '\\' : '';
+            lines.push(`^${num}^ ${text}${suffix}`);
         }
-    }
+    });
     // Corresponding author footnote
     const corresponding = config.authors.find(a => typeof a !== 'string' && a.corresponding);
     if (corresponding?.email) {
@@ -571,6 +606,13 @@ export function applyFormatTransforms(content, format, config, registry) {
     }
     else if (format === 'docx') {
         content = convertDynamicRefsToDisplay(content, registry);
+        // Pandoc strips raw LaTeX in docx output. Translate the common
+        // `\begin{figure}...\end{figure}` shape to portable markdown so figures
+        // actually appear; exotic blocks are left alone (warned about in build()).
+        if (config.docx?.translateRawFigures !== false) {
+            const { translated } = translateRawLatexFigures(content);
+            content = translated;
+        }
         if (hasNumberedAffiliations(config)) {
             const mdBlock = generateMarkdownAuthorBlock(config);
             content = content.replace(/^(---\r?\n[\s\S]*?---\r?\n)/, `$1\n${mdBlock}\n`);
@@ -624,8 +666,202 @@ function convertDynamicRefsToDisplay(text, registry) {
     }
     return result;
 }
+/** Match `\begin{figure}` / `\begin{figure*}` … `\end{figure}` blocks. */
+function makeRawFigureRegex() {
+    return /\\begin\{figure\*?\}(?:\[[^\]]*\])?[\s\S]*?\\end\{figure\*?\}/g;
+}
 /**
- * Build pandoc arguments for format
+ * Convert a LaTeX width spec to a markdown image attribute value.
+ * - `0.8\textwidth` → `80%`
+ * - `\linewidth` → `100%`
+ * - `8cm`, `2in`, `12pt` → kept verbatim
+ * Returns null for anything we don't translate (block stays "exotic").
+ */
+function convertLatexWidth(raw) {
+    const trimmed = raw.trim();
+    // Coefficient × relative length
+    const rel = trimmed.match(/^([\d.]+)\s*\\(textwidth|linewidth|columnwidth)$/);
+    if (rel) {
+        const pct = Math.round(parseFloat(rel[1]) * 100);
+        if (!isFinite(pct) || pct <= 0)
+            return null;
+        return `${pct}%`;
+    }
+    // Bare relative length
+    if (/^\\(textwidth|linewidth|columnwidth)$/.test(trimmed))
+        return '100%';
+    // Absolute units
+    if (/^[\d.]+\s*(cm|mm|in|pt|px|em|ex)$/.test(trimmed))
+        return trimmed.replace(/\s+/g, '');
+    return null;
+}
+/** Extract a balanced `{...}` argument that follows `command` in `text`. */
+function extractBracedArg(text, command) {
+    const idx = text.indexOf(command);
+    if (idx === -1)
+        return null;
+    let i = idx + command.length;
+    while (i < text.length && /\s/.test(text[i]))
+        i++;
+    if (text[i] !== '{')
+        return null;
+    i++;
+    const start = i;
+    let depth = 1;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '\\' && i + 1 < text.length) {
+            i += 2;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i);
+        }
+        i++;
+    }
+    return null;
+}
+/** True if a `\begin{figure}` block contains features we don't auto-translate. */
+function isExoticFigureBlock(block) {
+    if (/\\subfloat\b/.test(block))
+        return true;
+    if (/\\rotatebox\b/.test(block))
+        return true;
+    const includes = (block.match(/\\includegraphics\b/g) || []).length;
+    if (includes !== 1)
+        return true;
+    const m = block.match(/\\includegraphics\s*(?:\[([^\]]*)\])?\s*\{([^}]+)\}/);
+    if (!m)
+        return true;
+    const opts = m[1] || '';
+    const widthMatch = opts.match(/(?:^|,)\s*width\s*=\s*([^,]+)/);
+    if (widthMatch && !convertLatexWidth(widthMatch[1]))
+        return true;
+    return false;
+}
+/**
+ * Find raw LaTeX figure blocks containing `\includegraphics` in markdown.
+ * `file`, if given, is attached to each result. `line` is 1-based within the
+ * supplied content (the line where `\begin{figure}` sits).
+ */
+export function detectRawLatexFigures(content, file) {
+    const figures = [];
+    const re = makeRawFigureRegex();
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const block = m[0];
+        if (!block.includes('\\includegraphics'))
+            continue;
+        const line = content.slice(0, m.index).split(/\r?\n/).length;
+        figures.push({ file, line, block, exotic: isExoticFigureBlock(block) });
+    }
+    return figures;
+}
+/**
+ * Translate the 80% case: single `\includegraphics` figure with optional
+ * `\caption{...}` and `\label{...}`, wrapped in `\begin{figure}...\end{figure}`,
+ * to portable `![caption](path){#fig:label width=N%}` markdown. Exotic blocks
+ * (see `isExoticFigureBlock`) are left untouched.
+ */
+export function translateRawLatexFigures(content) {
+    let translatedCount = 0;
+    const re = makeRawFigureRegex();
+    const translated = content.replace(re, (block) => {
+        if (!block.includes('\\includegraphics'))
+            return block;
+        if (isExoticFigureBlock(block))
+            return block;
+        const inc = block.match(/\\includegraphics\s*(?:\[([^\]]*)\])?\s*\{([^}]+)\}/);
+        if (!inc)
+            return block;
+        const optsStr = inc[1] || '';
+        const imgPath = inc[2].trim();
+        let width;
+        const widthMatch = optsStr.match(/(?:^|,)\s*width\s*=\s*([^,]+)/);
+        if (widthMatch) {
+            const w = convertLatexWidth(widthMatch[1]);
+            if (!w)
+                return block; // already filtered by isExoticFigureBlock, defensive
+            width = w;
+        }
+        const caption = (extractBracedArg(block, '\\caption') ?? '').trim();
+        const labelRaw = extractBracedArg(block, '\\label');
+        const attrs = [];
+        if (labelRaw) {
+            const label = labelRaw.trim();
+            const labelWithPrefix = /^[a-z]+:/i.test(label) ? label : `fig:${label}`;
+            attrs.push(`#${labelWithPrefix}`);
+        }
+        if (width)
+            attrs.push(`width=${width}`);
+        translatedCount++;
+        const attrStr = attrs.length > 0 ? ` {${attrs.join(' ')}}` : '';
+        return `![${caption}](${imgPath})${attrStr}`;
+    });
+    return { translated, translatedCount };
+}
+/**
+ * Format the warning surfaced for raw LaTeX figure blocks that won't render
+ * in docx. `translateEnabled` reflects whether auto-translate ran (true = the
+ * listed blocks are exotic leftovers; false = no translation was attempted).
+ */
+function formatRawLatexFigureWarning(figs, translateEnabled) {
+    const reason = translateEnabled ? 'too complex to auto-translate' : 'translateRawFigures: false';
+    const lines = [
+        `${figs.length} raw LaTeX figure block(s) won't render in docx (${reason}).`,
+    ];
+    for (const f of figs) {
+        const loc = f.file ? `${f.file}:${f.line}` : `line ${f.line}`;
+        const pathMatch = f.block.match(/\\includegraphics\s*(?:\[[^\]]*\])?\s*\{([^}]+)\}/);
+        const pathInfo = pathMatch ? `  ${pathMatch[1].trim()}` : '';
+        lines.push(`  ${loc}${pathInfo}`);
+    }
+    lines.push('  Hint: use ![caption](path){#fig:label width=80%} for format-portable figures,');
+    lines.push('        or pass --pandoc-arg=--lua-filter=<your.lua> to translate them yourself.');
+    return lines.join('\n');
+}
+/**
+ * Walk section files and gather a warning for any raw LaTeX figure blocks that
+ * won't survive the docx build. Returns null when there's nothing to warn about.
+ */
+export function collectRawLatexFigureWarning(directory, config) {
+    const translateEnabled = config.docx?.translateRawFigures !== false;
+    const all = [];
+    for (const section of findSections(directory, config.sections)) {
+        const sectionPath = path.join(directory, section);
+        if (!fs.existsSync(sectionPath))
+            continue;
+        try {
+            const content = fs.readFileSync(sectionPath, 'utf-8');
+            const figs = detectRawLatexFigures(content, section);
+            for (const f of figs) {
+                // When auto-translate is on, non-exotic blocks get rewritten cleanly —
+                // only the exotic leftovers need warning. When opted out, everything
+                // is at risk and we warn about every block.
+                if (translateEnabled && !f.exotic)
+                    continue;
+                all.push(f);
+            }
+        }
+        catch {
+            // ignore unreadable sections
+        }
+    }
+    if (all.length === 0)
+        return null;
+    return formatRawLatexFigureWarning(all, translateEnabled);
+}
+/**
+ * Build pandoc arguments for format.
+ *
+ * Returns only the built-in args derived from config. Passthrough args
+ * (config.pandocArgs, config[format].pandocArgs, CLI --pandoc-arg) are
+ * appended later in runPandoc so they win against pptx/crossref defaults
+ * added there.
  */
 export function buildPandocArgs(format, config, outputPath) {
     const args = [];
@@ -743,6 +979,25 @@ export function buildPandocArgs(format, config, outputPath) {
     }
     return args;
 }
+/**
+ * Collect passthrough pandoc args for a format in the canonical order:
+ * top-level config → format-specific config → CLI extras. Later wins for
+ * repeated flags.
+ */
+export function collectPandocPassthroughArgs(format, config, extraArgs = []) {
+    const out = [];
+    if (config.pandocArgs && config.pandocArgs.length > 0) {
+        out.push(...config.pandocArgs);
+    }
+    const formatConfig = config[format];
+    if (formatConfig?.pandocArgs && formatConfig.pandocArgs.length > 0) {
+        out.push(...formatConfig.pandocArgs);
+    }
+    if (extraArgs.length > 0) {
+        out.push(...extraArgs);
+    }
+    return out;
+}
 /**
  * Write crossref.yaml if needed
  */
@@ -772,31 +1027,98 @@ export function resolveOutputDir(directory, config) {
         return directory;
     return path.isAbsolute(out) ? out : path.join(directory, out);
 }
+/** File extension (with leading dot) for each supported pandoc format. */
+const FORMAT_EXTENSIONS = {
+    tex: '.tex',
+    pdf: '.pdf',
+    docx: '.docx',
+    beamer: '.pdf',
+    pptx: '.pptx',
+};
+/** Get file extension for a format, defaulting to `.pdf`. */
+export function getFormatExtension(format) {
+    return FORMAT_EXTENSIONS[format] ?? '.pdf';
+}
+/**
+ * Slugify a title for use as a default output filename. Lowercases, replaces
+ * non-alphanumeric runs with `-`, and truncates at the last `-` boundary
+ * at-or-before MAX_TITLE_FILENAME_LENGTH so words stay whole (the old blind
+ * `.slice` cut mid-word).
+ */
+export function slugifyTitle(title) {
+    if (!title)
+        return 'paper';
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!slug)
+        return 'paper';
+    if (slug.length <= MAX_TITLE_FILENAME_LENGTH)
+        return slug;
+    const cut = slug.slice(0, MAX_TITLE_FILENAME_LENGTH);
+    const lastDash = cut.lastIndexOf('-');
+    // Only truncate at a hyphen if it leaves a reasonable amount of content.
+    // Otherwise hard-cut (handles degenerate titles with no spaces at all).
+    if (lastDash >= MAX_TITLE_FILENAME_LENGTH / 2) {
+        return slug.slice(0, lastDash);
+    }
+    return cut;
+}
+/**
+ * Ensure `name` ends with `ext` (case-insensitive). If the user already supplied
+ * the correct extension, return unchanged; if they supplied none or a different
+ * one, append the format's canonical extension.
+ *
+ * Different-extension case (e.g. `output.docx` when building tex): we append
+ * rather than replace, since stripping looks like an unsafe guess. The result
+ * `output.docx.tex` is loud enough to flag the misconfiguration.
+ */
+function ensureExtension(name, ext) {
+    if (name.toLowerCase().endsWith(ext.toLowerCase()))
+        return name;
+    return name + ext;
+}
+/**
+ * Resolve the final output path for a build.
+ *
+ * Priority: `options.outputPath` (internal force) > `cliOverride` (-o flag) >
+ * `config.output[format]` > slugified title fallback.
+ *
+ * Relative paths from `cliOverride`/`config.output` resolve under outputDir;
+ * absolute paths bypass outputDir. The fallback path always lives under
+ * outputDir.
+ *
+ * @param suffix - Appended before the extension (e.g. "-changes", "-slides").
+ *                 Suppressed when user supplied an explicit name via CLI or
+ *                 config — they pick their own suffix.
+ */
+export function resolveOutputPath(directory, config, format, options = {}) {
+    const { cliOverride, suffix = '' } = options;
+    const ext = getFormatExtension(format);
+    const explicit = cliOverride ?? config.output?.[format];
+    if (explicit) {
+        const baseDir = path.isAbsolute(explicit)
+            ? path.dirname(explicit)
+            : resolveOutputDir(directory, config);
+        const baseName = path.basename(explicit);
+        const stem = baseName.replace(/\.[^./\\]+$/, '');
+        return path.join(baseDir, ensureExtension(`${stem}${suffix}`, ext));
+    }
+    const slug = slugifyTitle(config.title);
+    return path.join(resolveOutputDir(directory, config), `${slug}${suffix}${ext}`);
+}
 /**
  * Run pandoc build
  */
 export async function runPandoc(inputPath, format, config, options = {}) {
     const directory = path.dirname(inputPath);
-    const baseName = config.title
-        ? config.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)
-        : 'paper';
-    // Map format to file extension
-    const extMap = {
-        tex: '.tex',
-        pdf: '.pdf',
-        docx: '.docx',
-        beamer: '.pdf', // beamer outputs PDF
-        pptx: '.pptx',
-    };
-    const ext = extMap[format] || '.pdf';
-    // For beamer, use -slides suffix to distinguish from regular PDF
+    // outputPath (internal force) wins over the resolver. For beamer, we keep
+    // the `-slides` suffix on the slug fallback to distinguish from a regular
+    // PDF build; when the user supplies an explicit name, they pick their own.
     const suffix = format === 'beamer' ? '-slides' : '';
-    // Allow custom output path via options. Auto-named outputs go through the
-    // configured outputDir (default 'output/'); explicit paths are honored as-is
-    // so callers can route temp/intermediate artefacts where they want.
     const outputPath = options.outputPath
-        ? options.outputPath
-        : path.join(resolveOutputDir(directory, config), `${baseName}${suffix}${ext}`);
+        ?? resolveOutputPath(directory, config, format, {
+            cliOverride: options.output,
+            suffix,
+        });
     if (!options.outputPath) {
         const outDir = path.dirname(outputPath);
         if (!fs.existsSync(outDir)) {
@@ -856,8 +1178,15 @@ export async function runPandoc(inputPath, format, config, options = {}) {
             args.push('--metadata-file', 'crossref.yaml');
         }
     }
+    // Passthrough args go last so they win against built-in defaults.
+    args.push(...collectPandocPassthroughArgs(format, config, options.pandocArgs));
     // Input file (use basename since we set cwd to directory)
     args.push(path.basename(inputPath));
+    if (options.verbose) {
+        const quoted = args.map(a => /[\s"'$`]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a).join(' ');
+        console.error(`[pandoc ${format}] (cwd: ${directory})`);
+        console.error(`  pandoc ${quoted}`);
+    }
     return new Promise((resolve) => {
         const pandoc = spawn('pandoc', args, {
             cwd: directory,
@@ -961,6 +1290,12 @@ export async function build(directory, formats = ['pdf', 'docx'], options = {})
         if (imageReg.figures?.length > 0) {
             writeImageRegistry(directory, imageReg);
         }
+        // Warn about raw LaTeX figure blocks that won't render in docx (pandoc
+        // drops them silently). With auto-translate on (default), this surfaces
+        // only the exotic leftovers; with it off, every block.
+        const rawFigWarning = collectRawLatexFigureWarning(directory, config);
+        if (rawFigWarning)
+            warnings.push(rawFigWarning);
     }
     const results = [];
     for (const format of formats) {