@imontene/mdrender 2.0.0 → 2.2.0

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/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/env.d.ts

@@ -4,6 +4,8 @@ export interface MermaidBlock {
     source: string;
     /** 1-based source line of the opening fence. */
     line?: number;
+    /** Printed together with the heading just above it (see markdown/keep-with-heading.ts). */
+    afterHeading?: boolean;
 }
 /** Per-document state shared by the Markdown plugins during one render. */
 export interface RenderEnv extends Env {

package/dist/markdown/index.js

@@ -4,9 +4,11 @@ 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";
+import { keepWithHeading } from "./keep-with-heading.js";
 import { math } from "./math.js";
 import { mermaid } from "./mermaid.js";
 import { taskLists } from "./task-lists.js";
@@ -23,8 +25,11 @@ export function createMarkdown() {
     md.use(taskLists);
     md.use(alerts);
     md.use(tocMarker);
+    md.use(keepWithHeading);
     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/markdown/keep-with-heading.d.ts

@@ -0,0 +1,8 @@
+import type { MarkdownIt } from "markdown-it";
+export declare const KEEP_WITH_HEADING_CLASS = "keep-with-heading";
+/**
+ * Wrap a top-level heading and the diagram or lone image right after it in a block that is not
+ * split across pages (`.keep-with-heading` in theme.css). Otherwise a figure that does not fit at
+ * the bottom of a page moves to the next one and leaves its heading alone at the bottom.
+ */
+export declare function keepWithHeading(md: MarkdownIt): void;

package/dist/markdown/keep-with-heading.js

@@ -0,0 +1,44 @@
+export const KEEP_WITH_HEADING_CLASS = "keep-with-heading";
+const isMermaidFence = (token) => token?.type === "fence" && token.info.trim().toLowerCase() === "mermaid";
+/** A paragraph holding nothing but one image (`![alt](img.png)`). */
+function imageParagraphEnd(tokens, i) {
+    if (tokens[i]?.type !== "paragraph_open" || tokens[i + 2]?.type !== "paragraph_close") {
+        return undefined;
+    }
+    const children = tokens[i + 1]?.children?.filter((child) => !(child.type === "text" && child.content.trim() === ""));
+    return children?.length === 1 && children[0].type === "image" ? i + 2 : undefined;
+}
+/**
+ * Wrap a top-level heading and the diagram or lone image right after it in a block that is not
+ * split across pages (`.keep-with-heading` in theme.css). Otherwise a figure that does not fit at
+ * the bottom of a page moves to the next one and leaves its heading alone at the bottom.
+ */
+export function keepWithHeading(md) {
+    md.core.ruler.push("keep_with_heading", (state) => {
+        const tokens = state.tokens;
+        for (let i = 0; i < tokens.length; i++) {
+            const open = tokens[i];
+            if (open.type !== "heading_open" || open.level !== 0)
+                continue;
+            const next = i + 3; // heading_open, inline, heading_close
+            let end;
+            if (isMermaidFence(tokens[next])) {
+                end = next;
+                tokens[next].meta = { ...tokens[next].meta, afterHeading: true };
+            }
+            else {
+                end = imageParagraphEnd(tokens, next);
+            }
+            if (end === undefined)
+                continue;
+            const before = new state.Token("html_block", "", 0);
+            before.content = `<div class="${KEEP_WITH_HEADING_CLASS}">\n`;
+            const after = new state.Token("html_block", "", 0);
+            after.content = "</div>\n";
+            tokens.splice(end + 1, 0, after);
+            tokens.splice(i, 0, before);
+            i = end + 2;
+        }
+    });
+}
+//# sourceMappingURL=keep-with-heading.js.map

package/dist/markdown/mermaid.js

@@ -15,7 +15,9 @@ export function mermaid(md) {
             return fence(tokens, idx, options, rawEnv, self);
         }
         const env = rawEnv;
-        const index = env.mermaid.push({ source: token.content, line: tokenLine(token) }) - 1;
+        const block = { source: token.content, line: tokenLine(token) };
+        const afterHeading = token.meta?.afterHeading;
+        const index = env.mermaid.push(afterHeading ? { ...block, afterHeading } : block) - 1;
         return `<figure class="mermaid-diagram">${mermaidPlaceholder(env.nonce, index)}</figure>\n`;
     };
 }

package/dist/options.d.ts

@@ -11,7 +11,11 @@ export type Margins = {
 };
 export declare const MERMAID_THEMES: readonly ["default", "neutral", "dark", "forest", "base"];
 export type MermaidTheme = (typeof MERMAID_THEMES)[number];
+export declare const MERMAID_FLIPS: readonly ["auto", "never"];
+export type MermaidFlip = (typeof MERMAID_FLIPS)[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;
@@ -33,6 +37,14 @@ export interface DocumentOptions {
     footer?: string;
     /** Mermaid theme; when unset, "neutral" for light pages and "dark" for the dark theme. */
     mermaidTheme?: MermaidTheme;
+    /** Try several layouts of each flowchart and keep the one whose text prints largest. */
+    mermaidAutofit: boolean;
+    /** Whether autofit may turn a flowchart to the other axis (LR ↔ TB) when it reads far better. */
+    mermaidFlip: MermaidFlip;
+    /** 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. */
@@ -50,6 +62,10 @@ export declare class OptionsError extends MdRenderError {
 }
 /** Parse a CSS margin shorthand into the four sides, or throw. */
 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.
  *

package/dist/options.js

@@ -5,7 +5,9 @@ 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 MERMAID_FLIPS = ["auto", "never"];
 export const BUILTIN_THEMES = ["light", "dark"];
+export const DENSITIES = ["normal", "compact"];
 export const DEFAULT_OPTIONS = {
     pageSize: "Letter",
     margin: "10mm",
@@ -13,6 +15,9 @@ export const DEFAULT_OPTIONS = {
     toc: false,
     tocDepth: 3,
     pageNumbers: true,
+    mermaidAutofit: true,
+    mermaidFlip: "auto",
+    density: "normal",
     theme: "light",
     css: [],
     lang: DEFAULT_LANG,
@@ -59,6 +64,27 @@ const length = (value, describe) => {
         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) => {
@@ -87,6 +113,10 @@ const VALIDATORS = {
     header: text,
     footer: text,
     mermaidTheme: oneOf(MERMAID_THEMES),
+    mermaidAutofit: bool,
+    mermaidFlip: oneOf(MERMAID_FLIPS),
+    density: oneOf(DENSITIES),
+    fontSize,
     theme: (value, describe, baseDir) => {
         const theme = text(value, describe, baseDir);
         const builtin = BUILTIN_THEMES.find((t) => t === theme.toLowerCase());

package/dist/render/browser.d.ts

@@ -45,5 +45,7 @@ export declare class BrowserSession {
         pdf: Uint8Array;
         blocked: string[];
     }>;
+    /** Browser name and version, e.g. "HeadlessChrome/141.0.7390.37". */
+    version(): Promise<string>;
     close(): Promise<void>;
 }

package/dist/render/browser.js

@@ -127,6 +127,10 @@ export class BrowserSession {
             await page.close();
         }
     }
+    /** Browser name and version, e.g. "HeadlessChrome/141.0.7390.37". */
+    version() {
+        return this.browser.version();
+    }
     async close() {
         await this.browser.close();
     }

package/dist/render/mermaid-fit.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Autofit for Mermaid flowcharts: pick, among several layouts of the same diagram, the one whose
+ * text prints largest once the diagram is scaled to the text column and the page height.
+ *
+ * Mermaid wraps label lines at `flowchart.wrappingWidth`, and a flowchart laid out along one axis
+ * can be far wider (or taller) than the page; the theme then shrinks the whole drawing, text
+ * included. Wider wrapping makes tall diagrams shorter; turning a long left-to-right chain
+ * top-to-bottom makes it fit the column. Neither has one value that suits every diagram, so each
+ * flowchart is rendered a few times and measured. Everything here is pure; the rendering loop is
+ * in render/mermaid.ts.
+ */
+export declare const FLOW_DIRECTIONS: readonly ["TB", "TD", "BT", "LR", "RL"];
+export type FlowDirection = (typeof FLOW_DIRECTIONS)[number];
+/** Label wrapping widths tried, in px; undefined is Mermaid's own default (the layout as today). */
+export declare const WRAPPING_WIDTHS: readonly (number | undefined)[];
+/** Candidates within this scale of the best one read the same; the shorter one wins. */
+export declare const SCALE_TOLERANCE = 0.05;
+/** Only turn a diagram whose best scale in its own direction is below this (text under ~10 px)… */
+export declare const FLIP_BELOW = 0.75;
+/** …and only when turning it raises the scale by at least this much. */
+export declare const FLIP_GAIN = 0.15;
+/** Below this scale the diagram is reported: no layout makes it readable, its content must change. */
+export declare const SMALL_SCALE = 0.5;
+export interface FlowchartHeader {
+    /** Index of the header line in `source.split("\n")`. */
+    line: number;
+    /** Direction as written; flowcharts without one are top-to-bottom. */
+    direction: FlowDirection;
+}
+/**
+ * The flowchart's header line and main direction, or undefined when the source is another kind
+ * of diagram. Blank lines and `%%` comments before the header are skipped.
+ */
+export declare function flowchartHeader(source: string): FlowchartHeader | undefined;
+/** The source with its main direction replaced; subgraph directions are left alone. */
+export declare function withDirection(source: string, header: FlowchartHeader, direction: FlowDirection): string;
+export declare function flippedDirection(direction: FlowDirection): FlowDirection;
+/**
+ * The diagram sets its own Mermaid configuration (an `%%{init: …}%%` directive or `config:` in
+ * its front matter): it is drawn exactly as written.
+ */
+export declare function authorConfigured(source: string): boolean;
+/** Width and height of an SVG from its viewBox. */
+export declare function measureSvg(svg: string): {
+    width: number;
+    height: number;
+} | undefined;
+export interface Fit {
+    /** Text column width in CSS px. */
+    width: number;
+    /** Largest printed height in CSS px; Infinity without pages (HTML). */
+    height: number;
+}
+/** How much the diagram is shrunk when printed: 1 is its natural size. */
+export declare function printScale(size: {
+    width: number;
+    height: number;
+}, fit: Fit): number;
+export interface Candidate {
+    svg: string;
+    /** Label wrapping width in px; undefined is Mermaid's default. */
+    wrap: number | undefined;
+    flipped: boolean;
+    width: number;
+    height: number;
+    scale: number;
+}
+export declare function candidate(svg: string, wrap: number | undefined, flipped: boolean, fit: Fit): Candidate | undefined;
+/** Whether a turned layout is worth trying, given the best layout in the written direction. */
+export declare const flipWorthTrying: (best: Candidate) => boolean;
+/**
+ * The chosen layout. `base` is the diagram as written (Mermaid's default wrapping, its own
+ * direction); the result is never smaller than it. A turned layout wins only when the written
+ * direction stays below FLIP_BELOW and turning gains at least FLIP_GAIN.
+ */
+export declare function chooseCandidate(candidates: Candidate[], base: Candidate): Candidate;
+/**
+ * Whether wider wrapping in this direction can still help: once the diagram is wider than the
+ * column and its scale went down, wider labels only make it wider.
+ */
+export declare function wrapsExhausted(current: Candidate, previous: Candidate | undefined, fit: Fit): boolean;