@danielsimonjr/mathts-workbook 0.4.1 → 0.4.3

package/dist/cli.d.ts

@@ -7,18 +7,94 @@
  * `main()` at the bottom wires them to the real streams, and only runs when
  * this file is the process entry point.
  */
+/**
+ * Result of one CLI command handler. `main()` writes `stdout` and `stderr` to the
+ * process streams and exits with `exitCode`. A handler returns this value and does
+ * not write to the console itself.
+ */
 export interface CommandResult {
     stdout: string;
     stderr: string;
     exitCode: number;
 }
+/**
+ * Run a workbook file (`mtsw run`) and report each cell result.
+ *
+ * The command first checks the optional `--expect-hash` SHA-256, then parses the file.
+ * With `--timeout <ms>`, the run occurs in a worker thread that is terminated when the
+ * budget expires. `--timeout` refuses `-c` and `-v`. Without `--timeout`, the run uses
+ * `runReport()`, so one failed cell does not stop the other cells. `--write` stores the
+ * results back into the file with an atomic write.
+ *
+ * @param args - Command arguments after `run`.
+ * @returns Exit code 0 if every reported cell succeeds or passes. Exit code 1 for a
+ * usage, read, hash, parse, unknown-cell, timeout or write error, or for any failed cell.
+ */
 export declare function runCommand(args: string[]): Promise<CommandResult>;
+/**
+ * Parse a workbook file and list its problems (`mtsw validate`). The command does not
+ * run the cells.
+ *
+ * @param args - Command arguments after `validate`.
+ * @returns Exit code 0 if the file has no problems. Exit code 1 for a usage or read
+ * error, or if the file has one or more problems.
+ */
 export declare function validateCommand(args: string[]): CommandResult;
+/**
+ * Print the structure of a workbook file (`mtsw describe`): cells, types and the
+ * dependency graph. With `--json`, the data is the `DescribeDoc` from `describeData()`.
+ * The command does not run the cells.
+ *
+ * @param args - Command arguments after `describe`.
+ * @returns Exit code 0 if the file parses with no problems, else exit code 1.
+ */
 export declare function describeCommand(args: string[]): CommandResult;
+/**
+ * Print the CLI version, the schema version, the supported and deferred cell types,
+ * and the command list (`mtsw capabilities`).
+ *
+ * @param args - Command arguments. Only `--json` has an effect.
+ * @returns Always exit code 0.
+ */
 export declare function capabilitiesCommand(args: string[]): CommandResult;
+/**
+ * List the names and descriptions of the templates that `mtsw new` accepts.
+ *
+ * @param args - Command arguments. Only `--json` has an effect.
+ * @returns Always exit code 0.
+ */
 export declare function templatesCommand(args: string[]): CommandResult;
+/**
+ * List the function names and constant names that expression cells can use
+ * (`mtsw functions`).
+ *
+ * @param args - Command arguments. Only `--json` has an effect.
+ * @returns Always exit code 0.
+ */
 export declare function functionsCommand(args: string[]): CommandResult;
+/**
+ * Read or change the workbook metadata (`mtsw meta get|set`).
+ *
+ * `set` accepts `--title`, `--author`, `--description` and `--tags` (a comma-separated
+ * list). `set` writes the file with an atomic write.
+ *
+ * @param args - Command arguments after `meta`. The first argument is `get` or `set`.
+ * @returns Exit code 0 on success. Exit code 1 for a usage, read, parse or write
+ * error, or for `set` with no field to change.
+ */
 export declare function metaCommand(args: string[]): CommandResult;
+/**
+ * Export a workbook as HTML, TeX, JSON, PDF or ipynb (`mtsw export`).
+ *
+ * The command runs the workbook first, unless `--no-run` is given. If the run fails as a
+ * whole (a result with the id `(workbook)`, for example a dependency cycle), the export
+ * stops with exit code 1. The `json` format needs a run. The `pdf` format needs `-o`.
+ * Without `-o`, the rendered text goes to stdout.
+ *
+ * @param args - Command arguments after `export`.
+ * @returns Exit code 0 on success. Exit code 1 for an unknown format, a usage, read,
+ * parse or write error, a whole-run failure, or a PDF render error.
+ */
 export declare function exportCommand(args: string[]): Promise<CommandResult>;
 /**
  * Run the JSON-RPC-over-stdio server loop until `shutdown`, stdin EOF, or a
@@ -26,11 +102,69 @@ export declare function exportCommand(args: string[]): Promise<CommandResult>;
  * for a run are flushed before that run's response (not mid-run in v1).
  */
 export declare function runServer(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+/**
+ * Start the JSON-RPC server on stdin and stdout (`mtsw serve`). The returned promise
+ * resolves after `runServer()` stops.
+ *
+ * @returns Always exit code 0, with empty `stdout` and `stderr`.
+ */
 export declare function serveCommand(): Promise<CommandResult>;
+/**
+ * Print the dependency graph of a workbook file (`mtsw graph`). The default output is
+ * one line for each cell. `-f mermaid` and `-f dot` select the other formats.
+ *
+ * `graph` has no JSON output. With `--json`, the command returns a JSON error envelope
+ * that tells the user to use `describe --json`.
+ *
+ * @param args - Command arguments after `graph`.
+ * @returns Exit code 0 on success. Exit code 1 for `--json`, or for a usage, read or
+ * parse error.
+ */
 export declare function graphCommand(args: string[]): CommandResult;
+/**
+ * Remove the stored outputs from a workbook file (`mtsw strip`). The command prints the
+ * result. With `-w` or `--write`, the command writes the result back into the file with
+ * an atomic write.
+ *
+ * @param args - Command arguments after `strip`.
+ * @returns Exit code 0 on success. Exit code 1 for a usage, read, parse or write error.
+ */
 export declare function stripCommand(args: string[]): CommandResult;
+/**
+ * Create a new workbook file from a template (`mtsw new`).
+ *
+ * A bare name must match `[A-Za-z0-9._-]+` and must not be `.`, `..` or a reserved
+ * Windows device name. This check stops a bare name from selecting a different
+ * directory. `-o <path>` gives an explicit path, and the name check does not apply to
+ * it. Without `--force`, the command does not overwrite an existing file. With
+ * `--force`, the command still refuses to overwrite a symbolic link.
+ *
+ * @param args - Command arguments after `new`.
+ * @returns Exit code 0 when the file is created. Exit code 1 for an unknown template,
+ * a missing or invalid name, an existing file or symbolic link, or a write error.
+ */
 export declare function newCommand(args: string[]): CommandResult;
+/**
+ * Convert JSON or YAML input into a workbook (`mtsw import`). The input comes from a
+ * file, or from stdin if the file argument is absent or `-`. With `-o`, the command
+ * writes the result with an atomic write. Otherwise it prints the result.
+ *
+ * @param args - Command arguments after `import`.
+ * @returns Exit code 0 on success. Exit code 1 if no input is available, or for a
+ * read, import or write error.
+ */
 export declare function importCommand(args: string[]): CommandResult;
+/**
+ * Add, edit, remove, move or rename one cell in a workbook file (`mtsw cell`).
+ *
+ * Each verb calls the related function in `edit.ts`. If that function throws, the
+ * command writes nothing and returns exit code 1. `--dry-run` prints the result and
+ * does not write. The command writes the file only if the content changed.
+ *
+ * @param args - Command arguments after `cell`. The first argument is the verb.
+ * @returns Exit code 0 on success, which includes "no change". Exit code 1 for a
+ * usage, read, parse, edit or write error.
+ */
 export declare function cellCommand(args: string[]): CommandResult;
 /**
  * Route argv to a command handler. Pure — returns a CommandResult.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAuCH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAwOD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAqHvE;AAqDD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAoC7D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA+C7D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAYjE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAa9D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAU9D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA2DzD;AAuFD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CA8H1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,GAAE,MAAM,CAAC,cAA8B,EAC5C,MAAM,GAAE,MAAM,CAAC,cAA+B,GAC7C,OAAO,CAAC,IAAI,CAAC,CAuEf;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAG3D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAsC1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA0B1D;AAuDD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAqFxD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAiD3D;AAyED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA4HzD;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAuDrE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAsCH;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAwOD;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAqHvE;AAqDD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAoC7D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA+C7D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAYjE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAa9D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAU9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA2DzD;AAoFD;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CA8H1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,GAAE,MAAM,CAAC,cAA8B,EAC5C,MAAM,GAAE,MAAM,CAAC,cAA+B,GAC7C,OAAO,CAAC,IAAI,CAAC,CAuEf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAG3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAsC1D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA0B1D;AAuDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAqFxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAiD3D;AAyED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA4HzD;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAuDrE"}

package/dist/cli.js

@@ -15,7 +15,7 @@ import {
   runWorkbookWithTimeout,
   setMetadata,
   writeFileAtomic
-} from "./chunk-JM3ZAYJC.js";
+} from "./chunk-AFI7I47D.js";
 import {
   buildDependencyGraph,
   createExecutor,
@@ -162,6 +162,9 @@ function texEscape(s) {
     }
   });
 }
+function verbatimBody(body, env) {
+  return body.split(`\\end{${env}}`).join(`\\end {${env}}`);
+}
 function escapeInlineNonLink(text) {
   let s = texEscape(text);
   s = s.replace(/`([^`]+)`/g, (_m, code) => `\\texttt{${code}}`);
@@ -199,9 +202,11 @@ function markdownToTex(src) {
         i++;
       }
       i++;
-      out.push(`\\begin{lstlisting}
-${buf.join("\n")}
-\\end{lstlisting}`);
+      out.push(
+        `\\begin{lstlisting}
+${verbatimBody(buf.join("\n"), "lstlisting")}
+\\end{lstlisting}`
+      );
       continue;
     }
     if (line2.trim() === "") {
@@ -252,6 +257,48 @@ ${items.join("\n")}
   return out.join("\n\n");
 }
 
+// src/svg.ts
+import { line, scatter, bar } from "@danielsimonjr/mathts-plot";
+function coerce(v) {
+  if (typeof v === "number") return v;
+  if (typeof v === "bigint") return Number(v);
+  const u = v;
+  if (u && typeof u.toNumeric === "function") {
+    try {
+      return Number(u.toNumeric());
+    } catch {
+      return NaN;
+    }
+  }
+  return Number(v);
+}
+function toNums(raw) {
+  let arr = raw;
+  const m = raw;
+  if (m && typeof m.toArray === "function") {
+    try {
+      arr = m.toArray();
+    } catch {
+      arr = raw;
+    }
+  }
+  return Array.isArray(arr) ? arr.flat(Infinity).map(coerce) : [];
+}
+function renderChart(spec, xRaw, yRaw, format = "svg") {
+  const xs = toNums(xRaw);
+  const ys = toNums(yRaw);
+  const opts = format === "tikz" ? {
+    title: spec.title,
+    xLabel: spec.xLabel,
+    yLabel: spec.yLabel,
+    format: "tikz",
+    tikz: { standalone: false }
+  } : { title: spec.title, xLabel: spec.xLabel, yLabel: spec.yLabel };
+  if (spec.type === "scatter") return scatter(xs, ys, opts);
+  if (spec.type === "bar") return bar(xs, ys, opts);
+  return line(xs, ys, opts);
+}
+
 // src/html.ts
 function esc2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -310,7 +357,7 @@ function renderCell(cell, parse3) {
     }
     case "chart": {
       const note = cell.note ? `<p class="note">\u26A0 ${esc2(cell.note)}</p>` : "";
-      return `<figure class="cell cell-chart">${cap}${cell.chartSvg ?? '<p class="note">no chart</p>'}${note}</figure>`;
+      return `<figure class="cell cell-chart">${cap}${cell.chart ? renderChart(cell.chart.spec, cell.chart.x, cell.chart.y, "svg") : '<p class="note">no chart</p>'}${note}</figure>`;
     }
     default:
       return `<figure class="cell"><pre><code>${esc2(cell.content)}</code></pre></figure>`;
@@ -407,7 +454,7 @@ function renderCellTex(cell, parse3) {
       const cap = cell.id ? `\\textit{${texEscape(cell.id)}}\\\\
 ` : "";
       const src = `\\begin{lstlisting}
-${cell.content}
+${verbatimBody(cell.content, "lstlisting")}
 \\end{lstlisting}`;
       let res = "";
       if (cell.error !== void 0)
@@ -418,7 +465,7 @@ ${cell.content}
         res = `
 
 \\begin{verbatim}
-${cell.output}
+${verbatimBody(cell.output, "verbatim")}
 \\end{verbatim}`;
       return `${cap}${src}${res}`;
     }
@@ -435,11 +482,11 @@ ${cell.output}
       const cap = cell.id ? `\\textit{${texEscape(cell.id)}}\\\\
 ` : "";
       return `${cap}\\begin{verbatim}
-${val}
+${verbatimBody(val, "verbatim")}
 \\end{verbatim}`;
     }
     case "chart": {
-      const chart = cell.chartTikz ?? "% no chart";
+      const chart = cell.chart ? renderChart(cell.chart.spec, cell.chart.x, cell.chart.y, "tikz") : "% no chart";
       const note = cell.note ? `
 
 \\textit{${texEscape(cell.note)}}` : "";
@@ -449,7 +496,7 @@ ${chart}
     }
     default:
       return `\\begin{verbatim}
-${cell.content}
+${verbatimBody(cell.content, "verbatim")}
 \\end{verbatim}`;
   }
 }
@@ -493,10 +540,11 @@ function renderCodeCell(cell, counter) {
       traceback: [cell.error]
     });
   } else if (cell.type === "chart") {
-    if (cell.chartSvg !== void 0) {
+    if (cell.chart !== void 0) {
+      const svg = renderChart(cell.chart.spec, cell.chart.x, cell.chart.y, "svg");
       outputs.push({
         output_type: "display_data",
-        data: { "image/svg+xml": toSourceLines(cell.chartSvg), "text/plain": ["<chart>"] },
+        data: { "image/svg+xml": toSourceLines(svg), "text/plain": ["<chart>"] },
         metadata: {}
       });
     }
@@ -551,48 +599,6 @@ function toIpynb(doc) {
   return JSON.stringify(notebook, null, 2);
 }
 
-// src/svg.ts
-import { line, scatter, bar } from "@danielsimonjr/mathts-plot";
-function coerce(v) {
-  if (typeof v === "number") return v;
-  if (typeof v === "bigint") return Number(v);
-  const u = v;
-  if (u && typeof u.toNumeric === "function") {
-    try {
-      return Number(u.toNumeric());
-    } catch {
-      return NaN;
-    }
-  }
-  return Number(v);
-}
-function toNums(raw) {
-  let arr = raw;
-  const m = raw;
-  if (m && typeof m.toArray === "function") {
-    try {
-      arr = m.toArray();
-    } catch {
-      arr = raw;
-    }
-  }
-  return Array.isArray(arr) ? arr.flat(Infinity).map(coerce) : [];
-}
-function renderChart(spec, xRaw, yRaw, format = "svg") {
-  const xs = toNums(xRaw);
-  const ys = toNums(yRaw);
-  const opts = format === "tikz" ? {
-    title: spec.title,
-    xLabel: spec.xLabel,
-    yLabel: spec.yLabel,
-    format: "tikz",
-    tikz: { standalone: false }
-  } : { title: spec.title, xLabel: spec.xLabel, yLabel: spec.yLabel };
-  if (spec.type === "scatter") return scatter(xs, ys, opts);
-  if (spec.type === "bar") return bar(xs, ys, opts);
-  return line(xs, ys, opts);
-}
-
 // src/cli.ts
 var parse2 = mathFunctions.parse;
 var HELP = `
@@ -1087,7 +1093,7 @@ function metaCommand(args) {
     return { stdout: jsonEnvelope("meta", true, next.metadata, []), stderr: "", exitCode: 0 };
   return { stdout: "", stderr: `Updated metadata in ${file}`, exitCode: 0 };
 }
-function buildRenderDoc(workbook, byId, format = "svg") {
+function buildRenderDoc(workbook, byId) {
   const lookup = (ref) => {
     if (typeof ref !== "string") return ref;
     return byId?.get(ref)?.output ?? workbook.cells.find((c) => c.id === ref)?.output;
@@ -1099,14 +1105,16 @@ function buildRenderDoc(workbook, byId, format = "svg") {
       rc.type = "chart";
       try {
         const spec = parseYamlSafe(c.content);
-        const rendered = renderChart(
-          { type: spec?.type, title: spec?.title, xLabel: spec?.x?.label, yLabel: spec?.y?.label },
-          lookup(spec?.x?.data),
-          lookup(spec?.y?.data),
-          format
-        );
-        if (format === "tikz") rc.chartTikz = rendered;
-        else rc.chartSvg = rendered;
+        rc.chart = {
+          spec: {
+            type: spec?.type,
+            title: spec?.title,
+            xLabel: spec?.x?.label,
+            yLabel: spec?.y?.label
+          },
+          x: lookup(spec?.x?.data),
+          y: lookup(spec?.y?.data)
+        };
         const unresolved = [];
         for (const ref of [spec?.x?.data, spec?.y?.data]) {
           if (typeof ref !== "string") continue;
@@ -1121,9 +1129,7 @@ function buildRenderDoc(workbook, byId, format = "svg") {
           rc.note = `chart data did not resolve: ${unresolved.join(", ")}${byId ? "" : " (try without --no-run)"}`;
         }
       } catch (error2) {
-        const placeholder = renderChart({}, [], [], format);
-        if (format === "tikz") rc.chartTikz = placeholder;
-        else rc.chartSvg = placeholder;
+        rc.chart = { spec: {}, x: [], y: [] };
         rc.note = `invalid chart spec: ${errMessage(error2)}`;
       }
       return rc;
@@ -1223,14 +1229,14 @@ async function exportCommand(args) {
     const outPath2 = flagValue(args, "-o") ?? flagValue(args, "--output");
     if (!outPath2) return fail(["--format pdf requires an output path: -o <file.pdf>"]);
     try {
-      await toPDF(buildRenderDoc(workbook, byId, "tikz"), outPath2, { parse: parse2 });
+      await toPDF(buildRenderDoc(workbook, byId), outPath2, { parse: parse2 });
     } catch (error) {
       return fail([`PDF export failed: ${errMessage(error)}`]);
     }
     return json ? { stdout: jsonEnvelope("export", true, { path: outPath2 }, []), stderr: "", exitCode: 0 } : { stdout: "", stderr: `Exported ${file} -> ${outPath2}`, exitCode: 0 };
   }
   const fragment = args.includes("--fragment");
-  const rendered = format === "tex" ? toTeX(buildRenderDoc(workbook, byId, "tikz"), { parse: parse2, fragment }) : format === "ipynb" ? toIpynb(buildRenderDoc(workbook, byId)) : toHTML(buildRenderDoc(workbook, byId), { parse: parse2 });
+  const rendered = format === "tex" ? toTeX(buildRenderDoc(workbook, byId), { parse: parse2, fragment }) : format === "ipynb" ? toIpynb(buildRenderDoc(workbook, byId)) : toHTML(buildRenderDoc(workbook, byId), { parse: parse2 });
   const bytes = Buffer.byteLength(rendered, "utf-8");
   const outPath = flagValue(args, "-o") ?? flagValue(args, "--output");
   if (outPath) {

package/dist/doc.d.ts

@@ -3,6 +3,11 @@
  * command and the serve JSON-RPC router (kept out of cli.ts to avoid a cycle).
  */
 import type { Workbook } from './types';
+/**
+ * Structured description of a workbook: metadata, runtime settings, cells, and the
+ * dependency graph with its cycles. `describeData()` builds it. The `describe` command
+ * and the JSON-RPC router return it.
+ */
 export interface DescribeDoc {
     version: string;
     metadata: Workbook['metadata'];

package/dist/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../src/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC;QAChB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC;CAC3E;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAsBlE"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../src/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC;QAChB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC;CAC3E;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAwBlE"}

package/dist/edit.d.ts

@@ -8,31 +8,100 @@
  * file on a throw.
  */
 import type { Workbook, CellType } from './types';
+/**
+ * Insertion point for a cell. The functions use the first field that is set, in this
+ * order: `at` (an index), `before` (a cell id), `after` (a cell id). With no field set,
+ * the cell goes at the end.
+ */
 export interface CellPosition {
     before?: string;
     after?: string;
     at?: number;
 }
+/**
+ * Result of `removeCell()`: the new workbook and the cells that were detached from the
+ * removed cell.
+ */
 export interface RemoveResult {
     workbook: Workbook;
     /** Cells whose `depends_on` was edited to detach the removed cell (force). */
     changedCells: string[];
 }
+/**
+ * Add a cell and return a new workbook. The input workbook does not change.
+ *
+ * @param wb - The workbook to start from.
+ * @param spec - The id, type, content and dependencies of the new cell.
+ * @param position - Where to put the cell. The default is the end.
+ * @returns A new workbook that contains the cell.
+ * @throws Error if the id is not an identifier or is a duplicate, if the type is not
+ * supported, if a dependency is unknown or is the cell itself, if the position is not
+ * valid, or if the change creates a new dependency cycle.
+ */
 export declare function addCell(wb: Workbook, spec: {
     id: string;
     type: CellType;
     content?: string;
     dependsOn?: string[];
 }, position?: CellPosition): Workbook;
+/**
+ * Change the content, type or dependencies of a cell and return a new workbook. The
+ * input workbook does not change. A changed cell loses its stored output and error.
+ *
+ * @param wb - The workbook to start from.
+ * @param id - The id of the cell to change.
+ * @param changes - The fields to change. An absent field keeps its value.
+ * @returns A new workbook that contains the changed cell.
+ * @throws Error if the cell does not exist, if the type is not supported, if a
+ * dependency is unknown or is the cell itself, or if the change creates a new
+ * dependency cycle.
+ */
 export declare function editCell(wb: Workbook, id: string, changes: {
     content?: string;
     type?: CellType;
     dependsOn?: string[];
 }): Workbook;
+/**
+ * Remove a cell and return a new workbook. The input workbook does not change.
+ *
+ * If other cells depend on the removed cell, the function throws, unless `force` is
+ * set. With `force`, the function removes the dependency from each dependent cell. It
+ * also clears the stored output and error of each such cell.
+ *
+ * @param wb - The workbook to start from.
+ * @param id - The id of the cell to remove.
+ * @param options - Set `force` to detach the dependent cells.
+ * @returns The new workbook and the ids of the detached cells.
+ * @throws Error if the cell does not exist, or if it has dependents and `force` is not set.
+ */
 export declare function removeCell(wb: Workbook, id: string, options?: {
     force?: boolean;
 }): RemoveResult;
+/**
+ * Move a cell to a new position and return a new workbook. The input workbook does not
+ * change. A move relative to the cell itself returns an unchanged copy.
+ *
+ * @param wb - The workbook to start from.
+ * @param id - The id of the cell to move.
+ * @param position - The new position.
+ * @returns A new workbook with the cell at the new position.
+ * @throws Error if the cell does not exist or if the position is not valid.
+ */
 export declare function moveCell(wb: Workbook, id: string, position: CellPosition): Workbook;
+/**
+ * Rename a cell and return a new workbook. The input workbook does not change.
+ *
+ * Each dependent cell gets the new id in its `dependsOn` list. The function also
+ * replaces each whole-word match of the old id in the content of those dependent
+ * cells. This replacement can also change the old id inside a string literal. Stored
+ * outputs do not change.
+ *
+ * @param wb - The workbook to start from.
+ * @param oldId - The current id.
+ * @param newId - The new id.
+ * @returns A new workbook with the renamed cell.
+ * @throws Error if the cell does not exist, or if `newId` is not an identifier or is a duplicate.
+ */
 export declare function renameCell(wb: Workbook, oldId: string, newId: string): Workbook;
 /** Update workbook-level metadata fields (only the provided ones). */
 export declare function setMetadata(wb: Workbook, changes: {

package/dist/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../src/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAQ,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAkFD,wBAAgB,OAAO,CACrB,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAC5E,QAAQ,CAAC,EAAE,YAAY,GACtB,QAAQ,CAiBV;AAED,wBAAgB,QAAQ,CACtB,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACnE,QAAQ,CAyBV;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAoBhG;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,CASnF;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CA6B/E;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAClF,QAAQ,CAOV"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../src/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAQ,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAoFD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAC5E,QAAQ,CAAC,EAAE,YAAY,GACtB,QAAQ,CAiBV;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACnE,QAAQ,CAyBV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAsBhG;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,CASnF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CA6B/E;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAClF,QAAQ,CAOV"}

package/dist/formatter.d.ts

@@ -5,5 +5,17 @@
  * MUST NOT throw — circular references, BigInt, and unserializable values all
  * fall back to safe markers rather than crashing the run.
  */
+/**
+ * Convert a cell result to text for the terminal.
+ *
+ * `null` and `undefined` give `(no result)`. A non-array object with a custom
+ * `toString` method uses that method, if the method returns text other than
+ * `[object Object]`. Other objects use JSON: a BigInt becomes `<digits>n`, and a
+ * circular reference becomes `[Circular]`. The function catches the errors of
+ * `toString` and of JSON conversion, and then uses a fallback text.
+ *
+ * @param value - The value to convert.
+ * @returns The text form of the value.
+ */
 export declare function formatResult(value: unknown): string;
 //# sourceMappingURL=formatter.d.ts.map

package/dist/formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkDH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA8BnD"}
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkDH;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA8BnD"}

package/dist/html.d.ts

@@ -9,6 +9,22 @@
  * outputs are pre-formatted strings supplied by the caller. All user content is
  * HTML-escaped before embedding.
  */
+import { type ChartSpec } from './svg.js';
+/**
+ * The chart of a `chart` cell: the chart settings and the raw x and y data.
+ */
+export interface RenderChart {
+    spec: ChartSpec;
+    x: unknown;
+    y: unknown;
+}
+/**
+ * One cell of a `RenderDoc`.
+ *
+ * SECURITY: a cell does not carry chart markup. `toHTML()`, `toTeX()` and `toIpynb()`
+ * make the chart markup from `chart` with `renderChart()`. The plot package escapes
+ * the title and the axis labels.
+ */
 export interface RenderCell {
     type: string;
     content: string;
@@ -18,13 +34,16 @@ export interface RenderCell {
     error?: string;
     /** For `test` cells: whether the assertion passed. */
     passed?: boolean;
-    /** For `chart` cells: pre-rendered inline SVG. */
-    chartSvg?: string;
-    /** For `chart` cells in a TeX export: pre-rendered embeddable TikZ. */
-    chartTikz?: string;
+    /** For `chart` cells: the chart settings and data. If omitted, the export shows "no chart". */
+    chart?: RenderChart;
     /** Optional diagnostic note (e.g. a chart whose data didn't resolve). */
     note?: string;
 }
+/**
+ * Document structure that `toHTML()`, `toTeX()` and `toPDF()` render. It does not use
+ * the `Workbook` type. `toHTML()` escapes `title`, `author`, `description` and `tags`.
+ * `toTeX()` escapes `title` and `author`.
+ */
 export interface RenderDoc {
     title?: string;
     author?: string;
@@ -32,6 +51,9 @@ export interface RenderDoc {
     tags?: string[];
     cells: RenderCell[];
 }
+/**
+ * Options for `toHTML()`.
+ */
 export interface ToHtmlOptions {
     /** Parser for equation expressions (e.g. the functions package `parse`). */
     parse?: (expr: string) => unknown;

package/dist/html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAyED,sFAAsF;AACtF,wBAAgB,KAAK,IAAI,MAAM,CA8B9B;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA6B1E"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;CACZ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAyED,sFAAsF;AACtF,wBAAgB,KAAK,IAAI,MAAM,CA8B9B;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA6B1E"}

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   renameCell,
   runWorkbookWithTimeout,
   setMetadata
-} from "./chunk-JM3ZAYJC.js";
+} from "./chunk-AFI7I47D.js";
 import {
   WorkbookExecutor,
   buildDependencyGraph,

package/dist/ipynb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ipynb.d.ts","sourceRoot":"","sources":["../src/ipynb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAoHvD,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAqB9C"}
+{"version":3,"file":"ipynb.d.ts","sourceRoot":"","sources":["../src/ipynb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAsHvD,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAqB9C"}