@imontene/mdrender 1.0.1 → 2.1.0

package/dist/doctor.d.ts

@@ -0,0 +1,30 @@
+export type CheckStatus = "ok" | "warn" | "fail" | "info";
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+    /** What to do about a warning or failure. */
+    hint?: string;
+}
+export interface DoctorOptions {
+    /** Explicit browser executable (as with --browser). */
+    browser?: string;
+    /** Config file to check; undefined: nearest to `cwd`; false: none. */
+    config?: string | false;
+    /** Start the browser and convert a sample document (the slow part). Default: true. */
+    render?: boolean;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+}
+export interface DoctorReport {
+    version: string;
+    checks: Check[];
+    ok: boolean;
+}
+/** Where `mdrender` resolves on the PATH, like `which`/`where`. */
+export declare function findOnPath(env: Record<string, string | undefined>, platform?: NodeJS.Platform): string | undefined;
+/** Inspect the installation, browser and configuration, and try a real conversion. */
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+/** Plain-text report; ASCII markers so it reads well in any Windows console. */
+export declare function formatReport(report: DoctorReport): string;

package/dist/doctor.js

@@ -0,0 +1,278 @@
+import { existsSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import sea from "node:sea";
+import { assetPath, PACKAGE_JSON } from "./assets.js";
+import { cacheDir, installedBrowser } from "./browser/cache.js";
+import { findBrowser } from "./browser/detect.js";
+import { findConfigFile, readConfig } from "./config.js";
+import { BrowserPool, convertFile } from "./convert.js";
+import { DEFAULT_FONT_SIZE, mergeOptions, resolveMargins } from "./options.js";
+import { version } from "./version.js";
+const MIN_NODE = [22, 12];
+function runningAsExecutable() {
+    try {
+        return sea.isSea();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Where `mdrender` resolves on the PATH, like `which`/`where`. */
+export function findOnPath(env, platform = process.platform) {
+    const pathValue = Object.entries(env).find(([key]) => key.toUpperCase() === "PATH")?.[1] ?? "";
+    const separator = platform === "win32" ? ";" : ":";
+    const names = platform === "win32"
+        ? ["mdrender.exe", "mdrender.cmd", "mdrender.ps1", "mdrender"]
+        : ["mdrender"];
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
+    for (const dir of pathValue.split(separator).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = join(dir, name);
+            if (isFile(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function installationChecks(env, platform) {
+    const checks = [];
+    const executable = runningAsExecutable();
+    checks.push({
+        name: "mdrender",
+        status: "ok",
+        detail: executable
+            ? `${version}, standalone executable (${process.execPath})`
+            : `${version}, npm package (${path.dirname(assetPath(PACKAGE_JSON))})`,
+    });
+    if (!executable) {
+        const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+        const [needMajor, needMinor] = MIN_NODE;
+        const supported = major > needMajor || (major === needMajor && minor >= needMinor);
+        checks.push({
+            name: "Node.js",
+            status: supported ? "ok" : "fail",
+            detail: `${process.versions.node} (${process.execPath})`,
+            hint: supported ? undefined : `mdrender needs Node.js ${needMajor}.${needMinor} or newer`,
+        });
+    }
+    checks.push({
+        name: "System",
+        status: "info",
+        detail: `${platform} ${process.arch}, ${os.release()}`,
+    });
+    const onPath = findOnPath(env, platform);
+    checks.push(onPath
+        ? { name: "PATH", status: "ok", detail: `mdrender found at ${onPath}` }
+        : {
+            name: "PATH",
+            status: "warn",
+            detail: "the mdrender command is not in any PATH folder",
+            hint: "you can only run it by its full path or with npx; add its folder to PATH " +
+                "(for npm: the output of `npm prefix -g`, plus /bin on Linux)",
+        });
+    return checks;
+}
+function browserSource(found, explicit, env, downloaded) {
+    if (explicit)
+        return "from --browser";
+    if (env.MDRENDER_BROWSER)
+        return "from MDRENDER_BROWSER";
+    if (downloaded && path.resolve(found) === path.resolve(downloaded)) {
+        return "downloaded by mdrender setup";
+    }
+    return "installed on this system";
+}
+function configChecks(options, cwd) {
+    if (options.config === false) {
+        return [{ name: "Config", status: "info", detail: "config files disabled (--no-config)" }];
+    }
+    const file = options.config ? path.resolve(cwd, options.config) : findConfigFile(cwd);
+    if (!file) {
+        const defaults = mergeOptions();
+        return [
+            {
+                name: "Config",
+                status: "info",
+                detail: `no mdrender.config.json in ${cwd} or its parent folders; defaults apply`,
+            },
+            settingsCheck(defaults),
+        ];
+    }
+    if (!existsSync(file)) {
+        return [{ name: "Config", status: "fail", detail: `not found: ${file}` }];
+    }
+    try {
+        const config = readConfig(file);
+        const checks = [
+            config.warnings.length
+                ? {
+                    name: "Config",
+                    status: "warn",
+                    detail: `${file}\n${config.warnings.map((w) => `  - ${w}`).join("\n")}`,
+                    hint: "fix or remove the options above; they are ignored",
+                }
+                : { name: "Config", status: "ok", detail: file },
+        ];
+        checks.push(settingsCheck(mergeOptions(config.options)));
+        return checks;
+    }
+    catch (error) {
+        return [{ name: "Config", status: "fail", detail: error.message }];
+    }
+}
+function settingsCheck(options) {
+    const m = resolveMargins(options);
+    return {
+        name: "Settings",
+        status: "info",
+        detail: `${options.pageSize} ${options.orientation}, margins ${m.top} ${m.right} ${m.bottom} ` +
+            `${m.left} (top right bottom left), ${options.density} density, ` +
+            `${options.fontSize ?? DEFAULT_FONT_SIZE} text, language ${options.lang}, theme ` +
+            path.basename(options.theme),
+    };
+}
+const SAMPLE = `# mdrender doctor
+
+Equation: $e^{i\\pi} + 1 = 0$
+
+\`\`\`mermaid
+flowchart LR
+  A[Markdown] --> B[PDF]
+\`\`\`
+`;
+async function browserChecks(options, env, platform) {
+    const checks = [];
+    const dir = cacheDir(env, platform);
+    const downloaded = installedBrowser(dir);
+    checks.push({
+        name: "Setup cache",
+        status: "info",
+        detail: downloaded ? `${dir} (contains ${downloaded})` : `${dir} (no downloaded browser)`,
+    });
+    let executable;
+    try {
+        executable = findBrowser(options.browser, {
+            env,
+            platform,
+            downloaded: () => downloaded,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "Browser",
+            status: "fail",
+            detail: error.message.split("\n")[0],
+            hint: "run `mdrender setup` to download one, install Chrome/Edge/Chromium, or point to " +
+                "one with --browser <path> or MDRENDER_BROWSER",
+        });
+        return checks;
+    }
+    checks.push({
+        name: "Browser",
+        status: "ok",
+        detail: `${executable} (${browserSource(executable, options.browser, env, downloaded)})`,
+    });
+    if (options.render === false)
+        return checks;
+    const notes = [];
+    const pool = new BrowserPool(executable, (message) => notes.push(message));
+    const work = mkdtempSync(path.join(os.tmpdir(), "mdrender-doctor-"));
+    try {
+        let started = Date.now();
+        const session = await pool.get();
+        const browserVersion = await session.version();
+        const unsandboxed = notes.some((note) => note.includes("sandbox"));
+        checks.push({
+            name: "Browser start",
+            status: unsandboxed ? "warn" : "ok",
+            detail: `${browserVersion} in ${Date.now() - started} ms`,
+            hint: unsandboxed
+                ? "started without Chrome's sandbox (blocked by the system, e.g. Ubuntu 23.10+); " +
+                    "conversions still work. A browser installed from a package avoids it"
+                : undefined,
+        });
+        const input = path.join(work, "doctor.md");
+        writeFileSync(input, SAMPLE);
+        started = Date.now();
+        const result = await convertFile({
+            input,
+            output: path.join(work, "doctor.pdf"),
+            format: "pdf",
+            config: false,
+            browsers: pool,
+        });
+        const problems = result.diagnostics.map((d) => d.message);
+        checks.push({
+            name: "Test conversion",
+            status: problems.length ? "fail" : "ok",
+            detail: problems.length
+                ? problems.join("; ")
+                : `PDF with an equation and a Mermaid diagram in ${Date.now() - started} ms`,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "Browser start",
+            status: "fail",
+            detail: error.message.split("\n")[0],
+            hint: "try another browser with --browser <path>, or `mdrender setup --force`",
+        });
+    }
+    finally {
+        await pool.close();
+        rmSync(work, { recursive: true, force: true });
+    }
+    return checks;
+}
+function networkChecks(env) {
+    const proxy = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"].find((k) => env[k]);
+    return proxy
+        ? [{ name: "Proxy", status: "info", detail: `${proxy} is set (used by mdrender setup)` }]
+        : [];
+}
+/** Inspect the installation, browser and configuration, and try a real conversion. */
+export async function runDoctor(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const cwd = options.cwd ?? process.cwd();
+    const checks = [
+        ...installationChecks(env, platform),
+        ...(await browserChecks(options, env, platform)),
+        ...configChecks(options, cwd),
+        ...networkChecks(env),
+    ];
+    return { version, checks, ok: !checks.some((check) => check.status === "fail") };
+}
+const LABEL = {
+    ok: "[ok]  ",
+    warn: "[warn]",
+    fail: "[fail]",
+    info: "[info]",
+};
+/** Plain-text report; ASCII markers so it reads well in any Windows console. */
+export function formatReport(report) {
+    const width = Math.max(...report.checks.map((check) => check.name.length));
+    const lines = report.checks.map((check) => {
+        const [first, ...rest] = check.detail.split("\n");
+        const head = `${LABEL[check.status]} ${check.name.padEnd(width)}  ${first}`;
+        const more = rest.map((line) => `${" ".repeat(width + 9)}${line}`);
+        const hint = check.hint ? [`${" ".repeat(width + 9)}-> ${check.hint}`] : [];
+        return [head, ...more, ...hint].join("\n");
+    });
+    const failures = report.checks.filter((c) => c.status === "fail").length;
+    const warnings = report.checks.filter((c) => c.status === "warn").length;
+    const summary = report.ok
+        ? `All good${warnings ? ` (${warnings} warning${warnings > 1 ? "s" : ""})` : ""}.`
+        : `${failures} problem${failures > 1 ? "s" : ""} found.`;
+    return `mdrender doctor\n\n${lines.join("\n")}\n\n${summary}\n`;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/inputs.js

@@ -95,7 +95,7 @@ export function planOutputs(inputs, format, output, cwd = process.cwd()) {
         if (several) {
             throw new OptionsError(`with several input files, --output must be a folder: ${output}`);
         }
-        return [{ input: inputs[0].file, output: outDir }];
+        return checkJobs([{ input: inputs[0].file, output: outDir }], inputs);
     }
     const jobs = inputs.map(({ file, root }) => {
         const name = path.parse(file).name + ext;
@@ -104,9 +104,22 @@ export function planOutputs(inputs, format, output, cwd = process.cwd()) {
         const relativeDir = root ? path.relative(root, path.dirname(file)) : "";
         return { input: file, output: path.join(outDir, relativeDir, name) };
     });
+    return checkJobs(jobs, inputs);
+}
+/** Path comparison key: Windows paths are case-insensitive. */
+const pathKey = (file) => process.platform === "win32" ? path.resolve(file).toLowerCase() : path.resolve(file);
+/**
+ * Refuse plans that would destroy data: an output that is one of the input Markdown files
+ * (`mdrender doc.md -o doc.md`), or two inputs written to the same output.
+ */
+function checkJobs(jobs, inputs) {
+    const sources = new Set(inputs.map(({ file }) => pathKey(file)));
     const targets = new Map();
     for (const job of jobs) {
-        const key = process.platform === "win32" ? job.output.toLowerCase() : job.output;
+        const key = pathKey(job.output);
+        if (sources.has(key)) {
+            throw new OptionsError(`refusing to overwrite the input file ${job.output}; choose another --output`);
+        }
         const other = targets.get(key);
         if (other) {
             throw new OptionsError(`${other} and ${job.input} would both be written to ${job.output}`);

package/dist/markdown/code-blocks.d.ts

@@ -0,0 +1,9 @@
+import type { MarkdownIt } from "markdown-it";
+/**
+ * Code blocks up to this many lines are kept on one page; longer ones may break across pages
+ * (the theme keeps at least a few lines on each side), so a long listing does not push itself
+ * to the next page and leave a large gap behind.
+ */
+export declare const SHORT_CODE_LINES = 12;
+/** Mark short fenced and indented code blocks with `keep-together` (see SHORT_CODE_LINES). */
+export declare function codeBlocks(md: MarkdownIt): void;

package/dist/markdown/code-blocks.js

@@ -0,0 +1,21 @@
+/**
+ * Code blocks up to this many lines are kept on one page; longer ones may break across pages
+ * (the theme keeps at least a few lines on each side), so a long listing does not push itself
+ * to the next page and leave a large gap behind.
+ */
+export const SHORT_CODE_LINES = 12;
+const KEEP_CLASS = "keep-together";
+function markShort(html, content) {
+    const lines = content.replace(/\n$/, "").split("\n").length;
+    if (lines > SHORT_CODE_LINES || !html.startsWith("<pre"))
+        return html;
+    return html.replace(/^<pre(?: class="([^"]*)")?/, (_m, classes) => classes ? `<pre class="${classes} ${KEEP_CLASS}"` : `<pre class="${KEEP_CLASS}"`);
+}
+/** Mark short fenced and indented code blocks with `keep-together` (see SHORT_CODE_LINES). */
+export function codeBlocks(md) {
+    for (const rule of ["fence", "code_block"]) {
+        const render = md.renderer.rules[rule];
+        md.renderer.rules[rule] = (tokens, idx, options, env, self) => markShort(render(tokens, idx, options, env, self), tokens[idx].content);
+    }
+}
+//# sourceMappingURL=code-blocks.js.map

package/dist/markdown/index.js

@@ -4,6 +4,7 @@ import anchor from "markdown-it-anchor";
 import footnote from "markdown-it-footnote";
 import { DEFAULT_LANG } from "../i18n.js";
 import { alerts } from "./alerts.js";
+import { codeBlocks } from "./code-blocks.js";
 import { inlineChildLines } from "./env.js";
 import { highlightCode } from "./highlight.js";
 import { inlineLocalImages } from "./images.js";
@@ -25,6 +26,8 @@ export function createMarkdown() {
     md.use(tocMarker);
     md.use(inlineChildLines);
     md.use(inlineLocalImages);
+    // Before math and mermaid, which hand their non-code fences on to this renderer.
+    md.use(codeBlocks);
     md.use(math);
     md.use(mermaid);
     return md;

package/dist/options.d.ts

@@ -1,15 +1,30 @@
 import { MdRenderError } from "./errors.js";
 export declare const PAGE_SIZES: readonly ["A3", "A4", "A5", "Letter", "Legal", "Tabloid"];
 export type PageSize = (typeof PAGE_SIZES)[number];
+export declare const ORIENTATIONS: readonly ["portrait", "landscape"];
+export type Orientation = (typeof ORIENTATIONS)[number];
+export type Margins = {
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+};
 export declare const MERMAID_THEMES: readonly ["default", "neutral", "dark", "forest", "base"];
 export type MermaidTheme = (typeof MERMAID_THEMES)[number];
 export declare const BUILTIN_THEMES: readonly ["light", "dark"];
+export declare const DENSITIES: readonly ["normal", "compact"];
+export type Density = (typeof DENSITIES)[number];
 /** Rendering options, merged from defaults < config file < front matter < command line. */
 export interface DocumentOptions {
     pageSize: PageSize;
     /** CSS margin shorthand: 1 to 4 lengths in mm, cm, in or px. */
     margin: string;
-    landscape: boolean;
+    /** Single sides, overriding the shorthand (see `resolveMargins`). */
+    marginTop?: string;
+    marginRight?: string;
+    marginBottom?: string;
+    marginLeft?: string;
+    orientation: Orientation;
     toc: boolean;
     /** Deepest heading level listed in the table of contents. */
     tocDepth: number;
@@ -20,6 +35,10 @@ export interface DocumentOptions {
     footer?: string;
     /** Mermaid theme; when unset, "neutral" for light pages and "dark" for the dark theme. */
     mermaidTheme?: MermaidTheme;
+    /** Vertical spacing: "compact" tightens line height, paragraph and heading spacing. */
+    density: Density;
+    /** Base font size of the text, e.g. "10pt"; when unset, the theme's (10.5pt). */
+    fontSize?: string;
     /** "light", "dark", or the absolute path of a stylesheet that replaces the built-in theme. */
     theme: string;
     /** Extra stylesheets (absolute paths), applied after the built-in theme. */
@@ -36,12 +55,11 @@ export declare class OptionsError extends MdRenderError {
     constructor(message: string);
 }
 /** Parse a CSS margin shorthand into the four sides, or throw. */
-export declare function parseMargin(margin: string): {
-    top: string;
-    right: string;
-    bottom: string;
-    left: string;
-};
+export declare function parseMargin(margin: string): Margins;
+/** Text size of the built-in themes (theme.css), when --font-size is not given. */
+export declare const DEFAULT_FONT_SIZE = "10.5pt";
+/** A font size in CSS pixels ("10.5pt" → 14). */
+export declare function fontSizePx(size: string): number;
 /**
  * Validate options from a config file, front matter or the command line.
  *
@@ -51,5 +69,23 @@ export declare function parseMargin(margin: string): {
 export declare function normalizeOptions(raw: Record<string, unknown>, source: string, baseDir: string, 
 /** How to name a key in error messages (e.g. as a command-line flag). */
 label?: (key: string) => string): Partial<DocumentOptions>;
-/** Merge option layers, later ones winning. CSS lists accumulate instead of replacing. */
+/**
+ * Merge option layers, later ones winning. CSS lists accumulate instead of replacing. A layer
+ * that sets the `margin` shorthand also replaces single-side margins from earlier layers, so
+ * `--margin 15mm` on the command line is not partly undone by `marginLeft` in a config file.
+ */
 export declare function mergeOptions(...layers: Partial<DocumentOptions>[]): DocumentOptions;
+/** The four page margins: the `margin` shorthand, with single-side options on top. */
+export declare function resolveMargins(options: DocumentOptions): Margins;
+/** Every option name accepted in a config file, in camelCase. */
+export declare const OPTION_KEYS: readonly string[];
+export interface UnknownOption {
+    key: string;
+    /** Closest known option, written in the same style (camelCase or kebab-case) as `key`. */
+    suggestion?: string;
+}
+/**
+ * Keys that are not options, with the closest known option when one is near: catches typos
+ * such as "pagesize" or "margn" that would otherwise be ignored silently.
+ */
+export declare function unknownOptions(raw: Record<string, unknown>): UnknownOption[];

package/dist/options.js

@@ -3,15 +3,18 @@ import { ExitCode } from "./exit-codes.js";
 import { MdRenderError } from "./errors.js";
 import { DEFAULT_LANG } from "./i18n.js";
 export const PAGE_SIZES = ["A3", "A4", "A5", "Letter", "Legal", "Tabloid"];
+export const ORIENTATIONS = ["portrait", "landscape"];
 export const MERMAID_THEMES = ["default", "neutral", "dark", "forest", "base"];
 export const BUILTIN_THEMES = ["light", "dark"];
+export const DENSITIES = ["normal", "compact"];
 export const DEFAULT_OPTIONS = {
-    pageSize: "A4",
-    margin: "20mm",
-    landscape: false,
+    pageSize: "Letter",
+    margin: "10mm",
+    orientation: "portrait",
     toc: false,
     tocDepth: 3,
     pageNumbers: true,
+    density: "normal",
     theme: "light",
     css: [],
     lang: DEFAULT_LANG,
@@ -51,6 +54,34 @@ const oneOf = (choices) => (value, describe) => {
         return match;
     throw new OptionsError(`${describe} must be one of: ${choices.join(", ")}`);
 };
+const length = (value, describe) => {
+    const raw = text(value, describe, "");
+    const trimmed = raw.trim();
+    if (LENGTH.test(trimmed))
+        return trimmed;
+    throw new OptionsError(`${describe} must be a length in mm, cm, in or px, e.g. "10mm"`);
+};
+/** Text size of the built-in themes (theme.css), when --font-size is not given. */
+export const DEFAULT_FONT_SIZE = "10.5pt";
+/** Font sizes accepted by --font-size, in points or pixels. */
+const FONT_SIZE = /^(\d+(?:\.\d+)?)(pt|px)$/;
+const FONT_SIZE_PT = { min: 6, max: 24 };
+/** A font size in CSS pixels ("10.5pt" → 14). */
+export function fontSizePx(size) {
+    const match = FONT_SIZE.exec(size);
+    if (!match)
+        throw new Error(`invalid font size: ${size}`);
+    return match[2] === "pt" ? (Number(match[1]) * 4) / 3 : Number(match[1]);
+}
+const fontSize = (value, describe) => {
+    const size = text(value, describe, "").trim();
+    if (FONT_SIZE.test(size)) {
+        const pt = (fontSizePx(size) * 3) / 4;
+        if (pt >= FONT_SIZE_PT.min && pt <= FONT_SIZE_PT.max)
+            return size;
+    }
+    throw new OptionsError(`${describe} must be a size in pt or px from ${FONT_SIZE_PT.min}pt to ${FONT_SIZE_PT.max}pt, e.g. "10pt"`);
+};
 const VALIDATORS = {
     pageSize: oneOf(PAGE_SIZES),
     margin: (value, describe) => {
@@ -63,7 +94,11 @@ const VALIDATORS = {
         }
         return margin;
     },
-    landscape: bool,
+    marginTop: length,
+    marginRight: length,
+    marginBottom: length,
+    marginLeft: length,
+    orientation: oneOf(ORIENTATIONS),
     toc: bool,
     tocDepth: (value, describe) => {
         const depth = Number(value);
@@ -75,6 +110,8 @@ const VALIDATORS = {
     header: text,
     footer: text,
     mermaidTheme: oneOf(MERMAID_THEMES),
+    density: oneOf(DENSITIES),
+    fontSize,
     theme: (value, describe, baseDir) => {
         const theme = text(value, describe, baseDir);
         const builtin = BUILTIN_THEMES.find((t) => t === theme.toLowerCase());
@@ -109,6 +146,12 @@ label = (key) => `"${key}"`) {
     for (const [key, value] of Object.entries(raw)) {
         if (value === undefined || value === null)
             continue;
+        // `landscape: true` is kept as a shorthand for `orientation: landscape`.
+        if (toCamel(key) === "landscape") {
+            const landscape = bool(value, `${source}: ${label(key)}`, baseDir);
+            result.orientation = landscape ? "landscape" : "portrait";
+            continue;
+        }
         const name = toCamel(key);
         const validate = VALIDATORS[name];
         if (!validate)
@@ -117,15 +160,74 @@ label = (key) => `"${key}"`) {
     }
     return result;
 }
-/** Merge option layers, later ones winning. CSS lists accumulate instead of replacing. */
+const SIDES = ["marginTop", "marginRight", "marginBottom", "marginLeft"];
+/**
+ * Merge option layers, later ones winning. CSS lists accumulate instead of replacing. A layer
+ * that sets the `margin` shorthand also replaces single-side margins from earlier layers, so
+ * `--margin 15mm` on the command line is not partly undone by `marginLeft` in a config file.
+ */
 export function mergeOptions(...layers) {
     const merged = { ...DEFAULT_OPTIONS, css: [] };
     for (const layer of layers) {
         const { css, ...rest } = layer;
+        if (rest.margin !== undefined)
+            for (const side of SIDES)
+                delete merged[side];
         Object.assign(merged, rest);
         if (css)
             merged.css.push(...css);
     }
     return merged;
 }
+/** The four page margins: the `margin` shorthand, with single-side options on top. */
+export function resolveMargins(options) {
+    const base = parseMargin(options.margin);
+    return {
+        top: options.marginTop ?? base.top,
+        right: options.marginRight ?? base.right,
+        bottom: options.marginBottom ?? base.bottom,
+        left: options.marginLeft ?? base.left,
+    };
+}
+/** Edit distance between two strings (insertions, deletions, substitutions). */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+const toKebab = (key) => key.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+/** Every option name accepted in a config file, in camelCase. */
+export const OPTION_KEYS = [...Object.keys(VALIDATORS), "landscape"];
+/**
+ * Keys that are not options, with the closest known option when one is near: catches typos
+ * such as "pagesize" or "margn" that would otherwise be ignored silently.
+ */
+export function unknownOptions(raw) {
+    const unknown = [];
+    for (const key of Object.keys(raw)) {
+        if (OPTION_KEYS.includes(toCamel(key)))
+            continue;
+        const plain = key.toLowerCase().replace(/[-_]/g, "");
+        let best;
+        let bestDistance = Infinity;
+        for (const known of OPTION_KEYS) {
+            const distance = editDistance(plain, known.toLowerCase());
+            if (distance < bestDistance) {
+                best = known;
+                bestDistance = distance;
+            }
+        }
+        const close = best !== undefined && bestDistance <= Math.max(1, Math.floor(plain.length / 4));
+        const suggestion = close ? (key.includes("-") ? toKebab(best) : best) : undefined;
+        unknown.push({ key, suggestion });
+    }
+    return unknown;
+}
 //# sourceMappingURL=options.js.map

package/dist/render/browser.d.ts

@@ -8,7 +8,6 @@ import { type Page, type PDFOptions } from "puppeteer-core";
  */
 export declare function shouldRetryWithoutSandbox(error: unknown, args: string[], platform?: NodeJS.Platform): boolean;
 export interface PrintOptions {
-    output: string;
     format?: PDFOptions["format"];
     landscape?: boolean;
     margin?: {
@@ -41,8 +40,12 @@ export declare class BrowserSession {
      * rendered by then (math by KaTeX, diagrams by Mermaid), and any <script> in the Markdown
      * must not run.
      */
+    /** Returns the PDF bytes (the caller writes them) and the URLs that were blocked. */
     printPdf(html: string, options: PrintOptions): Promise<{
+        pdf: Uint8Array;
         blocked: string[];
     }>;
+    /** Browser name and version, e.g. "HeadlessChrome/141.0.7390.37". */
+    version(): Promise<string>;
     close(): Promise<void>;
 }