@danielsimonjr/mathts-plot 0.2.0 → 0.3.0

package/dist/render-file.d.ts

@@ -0,0 +1,42 @@
+/** Thrown when an external tool is missing or a conversion fails. Deliberate
+ *  exception to plot's never-throw rule: I/O and missing tools must surface. */
+declare class PlotRenderError extends Error {
+    readonly missingTool?: string | undefined;
+    constructor(message: string, missingTool?: string | undefined);
+}
+interface RenderOptions {
+    tool?: string;
+    timeoutMs?: number;
+    density?: number;
+    background?: string;
+    /** Enable LaTeX \write18 shell-escape. UNSAFE for untrusted TeX — allows
+     *  arbitrary command execution during compile. Default false. */
+    shellEscape?: boolean;
+}
+interface RunResult {
+    code: number | null;
+    stdout: Buffer;
+    stderr: string;
+}
+/** Spawn a command, feeding optional stdin, collecting stdout/stderr. Rejects
+ *  with PlotRenderError(ENOENT) if the binary is not found. */
+declare function runTool(cmd: string, args: string[], opts?: {
+    timeoutMs?: number;
+    input?: string;
+}): Promise<RunResult>;
+/** True if `name` responds to a version probe (i.e. is on PATH). */
+declare function hasTool(name: string): Promise<boolean>;
+/** SVG string → file. Extension of `outPath` selects the target: `.svg` writes
+ *  the SVG through; `.png`/`.pdf` convert via rsvg-convert (preferred) or resvg.
+ *  Rejects with PlotRenderError naming the tool to install if none is present. */
+declare function renderToFile(svg: string, outPath: string, opts?: RenderOptions): Promise<void>;
+/** Build the CLI args for a LaTeX engine. Shell-escape (\write18) is OFF unless
+ *  `shellEscape` is true — enabling it is UNSAFE for untrusted TeX (arbitrary
+ *  command execution during compile). */
+declare function latexArgs(engine: string, workDir: string, texPath: string, shellEscape: boolean): string[];
+/** Standalone LaTeX/TikZ source → PDF via pdflatex (preferred) or tectonic.
+ *  Compiles in an OS temp dir and copies the resulting PDF to `outPath`.
+ *  Rejects with PlotRenderError naming the engine to install if none is found. */
+declare function latexToPdf(texSource: string, outPath: string, opts?: RenderOptions): Promise<void>;
+
+export { PlotRenderError, type RenderOptions, hasTool, latexArgs, latexToPdf, renderToFile, runTool };

package/dist/render-file.js

@@ -0,0 +1,155 @@
+// src/render-file.ts
+import { spawn } from "child_process";
+import { writeFile, rm, rename, mkdtemp, readFile } from "fs/promises";
+import { extname, join as joinPath } from "path";
+import { tmpdir } from "os";
+var PlotRenderError = class extends Error {
+  constructor(message, missingTool) {
+    super(message);
+    this.missingTool = missingTool;
+    this.name = "PlotRenderError";
+  }
+  missingTool;
+};
+function runTool(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { timeout: opts.timeoutMs ?? 3e4 });
+    const out = [];
+    let err = "";
+    child.stdout.on("data", (d) => out.push(d));
+    child.stderr.on("data", (d) => err += d.toString());
+    child.on(
+      "error",
+      (e) => reject(new PlotRenderError(`${cmd} could not be run: ${e.message}`, cmd))
+    );
+    child.on("close", (code) => resolve({ code, stdout: Buffer.concat(out), stderr: err }));
+    if (opts.input !== void 0) {
+      child.stdin.on("error", () => {
+      });
+      child.stdin.end(opts.input);
+    }
+  });
+}
+async function hasTool(name) {
+  try {
+    const r = await runTool(name, ["--version"], { timeoutMs: 5e3 });
+    return r.code === 0;
+  } catch {
+    return false;
+  }
+}
+async function renderToFile(svg, outPath, opts = {}) {
+  const ext = extname(outPath).toLowerCase();
+  if (ext === ".svg") {
+    await writeFile(outPath, svg, "utf-8");
+    return;
+  }
+  if (ext !== ".png" && ext !== ".pdf") {
+    throw new PlotRenderError(
+      `Unsupported output extension '${ext}' (expected .svg, .png, or .pdf)`
+    );
+  }
+  const format = ext.slice(1);
+  const candidates = opts.tool ? [opts.tool] : ["rsvg-convert", "resvg"];
+  for (const tool of candidates) {
+    if (!await hasTool(tool)) continue;
+    const tmpOut = outPath + ".tmp";
+    if (tool === "rsvg-convert") {
+      const args = ["-f", format, "-o", tmpOut];
+      if (format === "png" && opts.density)
+        args.push("--dpi-x", String(opts.density), "--dpi-y", String(opts.density));
+      if (format === "png" && opts.background) args.push("--background-color", opts.background);
+      const r = await runTool("rsvg-convert", args, { timeoutMs: opts.timeoutMs, input: svg });
+      if (r.code !== 0) {
+        await rm(tmpOut, { force: true });
+        throw new PlotRenderError(`rsvg-convert failed: ${r.stderr}`);
+      }
+      await rename(tmpOut, outPath);
+      return;
+    }
+    const tmpSvg = outPath + ".tmp.svg";
+    await writeFile(tmpSvg, svg, "utf-8");
+    try {
+      const args = [tmpSvg, tmpOut];
+      const r = await runTool("resvg", args, { timeoutMs: opts.timeoutMs });
+      if (r.code !== 0) {
+        await rm(tmpOut, { force: true });
+        throw new PlotRenderError(`resvg failed: ${r.stderr}`);
+      }
+    } finally {
+      await rm(tmpSvg, { force: true });
+    }
+    if (format === "pdf") {
+      await rm(tmpOut, { force: true });
+      throw new PlotRenderError(
+        "resvg does not emit PDF; install rsvg-convert for SVG\u2192PDF",
+        "rsvg-convert"
+      );
+    }
+    await rename(tmpOut, outPath);
+    return;
+  }
+  throw new PlotRenderError(
+    `No SVG converter found for .${format}. Install rsvg-convert (librsvg) or resvg and ensure it is on PATH.`,
+    "rsvg-convert"
+  );
+}
+function latexArgs(engine, workDir, texPath, shellEscape) {
+  if (engine === "tectonic") {
+    return [...shellEscape ? ["-Z", "shell-escape"] : [], "--outdir", workDir, texPath];
+  }
+  return [
+    shellEscape ? "-shell-escape" : "-no-shell-escape",
+    "-interaction=nonstopmode",
+    "-halt-on-error",
+    "-output-directory",
+    workDir,
+    texPath
+  ];
+}
+async function latexToPdf(texSource, outPath, opts = {}) {
+  if (extname(outPath).toLowerCase() !== ".pdf") {
+    throw new PlotRenderError(`latexToPdf output must be a .pdf path (got '${outPath}')`);
+  }
+  const candidates = opts.tool ? [opts.tool] : ["pdflatex", "tectonic"];
+  let engine;
+  for (const c of candidates) {
+    if (await hasTool(c)) {
+      engine = c;
+      break;
+    }
+  }
+  if (!engine) {
+    throw new PlotRenderError(
+      "No LaTeX engine found. Install TeX Live (pdflatex) or tectonic and ensure it is on PATH.",
+      "pdflatex"
+    );
+  }
+  const work = await mkdtemp(joinPath(tmpdir(), "plot-tex-"));
+  try {
+    const texPath = joinPath(work, "doc.tex");
+    await writeFile(texPath, texSource, "utf-8");
+    const args = latexArgs(engine, work, texPath, opts.shellEscape === true);
+    const r = await runTool(engine, args, { timeoutMs: opts.timeoutMs ?? 6e4 });
+    const pdfPath = joinPath(work, "doc.pdf");
+    let pdf;
+    try {
+      pdf = await readFile(pdfPath);
+    } catch {
+      throw new PlotRenderError(
+        `${engine} produced no PDF (exit ${r.code}): ${r.stderr || r.stdout.toString().slice(-500)}`
+      );
+    }
+    await writeFile(outPath, pdf);
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+export {
+  PlotRenderError,
+  hasTool,
+  latexArgs,
+  latexToPdf,
+  renderToFile,
+  runTool
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-plot",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Headless SVG 2D/3D plotting for MathTS — dependency-light, expression-aware, built on core/functions/expression",
   "author": "Daniel Simon Jr.",
   "license": "MIT",
@@ -12,6 +12,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./render": {
+      "import": "./dist/render-file.js",
+      "types": "./dist/render-file.d.ts"
     }
   },
   "files": [
@@ -19,8 +23,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts src/render-file.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/render-file.ts --format esm --dts --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -31,8 +35,8 @@
   },
   "dependencies": {
     "@danielsimonjr/mathts-core": "^0.6.0",
-    "@danielsimonjr/mathts-functions": "^0.16.0",
-    "@danielsimonjr/mathts-expression": "^0.5.2"
+    "@danielsimonjr/mathts-functions": "^0.16.1",
+    "@danielsimonjr/mathts-expression": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",