@danielsimonjr/sciengjs 0.4.0 → 0.5.0

package/README.md

@@ -10,7 +10,7 @@ sciengjs turns diagram source into images on your own machine. It sends no sourc
 
 ## What this release does
 
-Release 0.4.0 holds four input types: **Graphviz DOT**, **Mermaid** (every diagram type), **LaTeX math** (to SVG, PNG and PDF) and **HTML** (to PNG and PDF). The browser stage draws the Mermaid types other than class, state and sequence, and every PDF.
+Release 0.5.0 holds five input types: **Graphviz DOT**, **Mermaid** (every diagram type), **LaTeX math** (to SVG, PNG and PDF), **Plotly plots** (to SVG, PNG and HTML) and **HTML** (to PNG and PDF). The browser stage draws the Mermaid types other than class, state and sequence, and every PDF.
 
 | Input | Output | Engine |
 |---|---|---|
@@ -170,6 +170,107 @@ const svg = await render({ type: "math", source: "\\frac{a}{b}", format: "svg" }
 const png = await render({ type: "math", source: "\\ce{H2O + CO2 -> H2CO3}", format: "png", options: { scale: 2 } });
 ```
 
+## Plots
+
+The `plot` input draws a chart from JSON. The source is a JSON text with the keys `data` and `layout`. The output formats are `svg`, `png` and `html`. The `svg` and `png` outputs make no network request.
+
+```js
+import { render } from "@danielsimonjr/sciengjs";
+
+const source = JSON.stringify({
+  data: [{ type: "scatter", mode: "lines+markers", x: [0, 1, 2], y: [0, 1, 4], name: "y = x^2" }],
+  layout: { title: { text: "Square" } },
+});
+const { bytes } = await render({ type: "plot", source, format: "svg" }, {});
+```
+
+The engine reads a subset of the Plotly figure format. The subset holds `scatter` traces, page and grid layout keys, `line` and `rect` shapes, and linear or log axes. A key outside the subset rejects with `E_INPUT` and the key path. Set `lenient` to `true` to skip such a key and get a warning. The `html` output is a page that draws the figure with Plotly 4.2.0, the pinned build. The page loads that build from a CDN, with a subresource integrity hash. The package does not ship Plotly. The full subset is in the [design](docs/superpowers/specs/2026-11-01-scieng-engine-design.md), section PLOT.
+
+The reader applies these rules:
+
+- A figure has the top-level keys `data` and `layout` only.
+- The first axis of each letter is `xaxis` or `yaxis`. The other axes are `xaxis2`, `xaxis3` and up, with no leading zero. Plotly also accepts `xaxis1` for the first axis. This reader rejects `xaxis1`, so that each axis has one name.
+- An axis key must name an axis of a subplot in `layout.grid`.
+- `tickformat` is `.Nf` only, with N from 0 to 20. N sets the fixed decimals of the tick labels.
+- `dtick`, `width` and `height` must be above zero.
+- One axis has 1000 ticks at most. A `dtick` that gives more ticks rejects with `E_INPUT` and the key path, for example `layout.xaxis.dtick`.
+
+A tick label that needs more than 20 decimals uses exponent form, for example `1e-300`. A log axis that spans too many decades for minor ticks shows major ticks only.
+
+### Control helpers
+
+The `./plot` subpath has six helpers. Each helper takes a transfer function `{ num, den }` with the coefficients of the numerator and the denominator, highest power first. Each helper returns `{ figure, numbers }`. The `figure` is a plot figure. Pass it to `render` as JSON text to draw it. The `numbers` hold the key values that the analysis derives from the same model.
+
+Frequencies are in rad/s. Margins and phases are in degrees. Overshoot is in percent.
+
+`bode` returns the crossover frequencies and the margins:
+
+```js
+import { bode } from "@danielsimonjr/sciengjs/plot";
+
+const { figure, numbers } = bode({ num: [10], den: [1, 1, 0] });
+// numbers.gainCrossover is about 3.08, numbers.phaseMargin is about 17.96
+```
+
+`step` returns the final value, the rise time, the settling time, the overshoot and the peak time:
+
+```js
+import { step } from "@danielsimonjr/sciengjs/plot";
+
+const { figure, numbers } = step({ num: [1], den: [1, 0.6, 1] });
+// numbers.overshoot is about 37.2, numbers.riseTime is about 1.32
+```
+
+The step helper measures the peak and the overshoot in the direction of the final value, so a negative DC gain gives a correct overshoot. A response with no peak before the end of the time grid has a `peakTime` of `null` and an `overshoot` of 0. A system with a pole on or right of the imaginary axis has no final value: each number is `null`. The rise and settling times are interpolated between samples.
+
+The helpers reject with `E_INPUT` when the roots of the model do not converge, or when a computed value is not finite. A pole or a zero at 0 is exact and does not set the frequency range.
+
+`impulse` returns the peak value and its time:
+
+```js
+import { impulse } from "@danielsimonjr/sciengjs/plot";
+
+const { figure, numbers } = impulse({ num: [1], den: [1, 1] });
+// numbers.peak is 1, numbers.peakTime is 0
+```
+
+`nyquist` returns the least distance from the curve to the point -1:
+
+```js
+import { nyquist } from "@danielsimonjr/sciengjs/plot";
+
+const { figure, numbers } = nyquist({ num: [10], den: [1, 1, 0] });
+// numbers.minDistanceToMinusOne is about 0.299
+```
+
+`poleZero` returns the poles and the zeros:
+
+```js
+import { poleZero } from "@danielsimonjr/sciengjs/plot";
+
+const { figure, numbers } = poleZero({ num: [1, 3], den: [1, 2, 5] });
+// the poles are -1 + 2j and -1 - 2j, the zero is -3
+```
+
+`rootLocus` returns the breakaway points and the gain at each point:
+
+```js
+import { rootLocus } from "@danielsimonjr/sciengjs/plot";
+
+const { figure, numbers } = rootLocus({ num: [1], den: [1, 3, 2] });
+// numbers.breakawayPoints[0] is { re: -1.5, k: 0.25 }
+```
+
+To draw a helper figure, pass it to `render`:
+
+```js
+import { render } from "@danielsimonjr/sciengjs";
+import { bode } from "@danielsimonjr/sciengjs/plot";
+
+const { figure } = bode({ num: [10], den: [1, 1, 0] });
+const { bytes } = await render({ type: "plot", source: JSON.stringify(figure), format: "html" }, {});
+```
+
 ## Roadmap
 
 The [build plan](docs/superpowers/plans/2026-11-01-scieng-engine-build.md) gives the order of the increments. Each increment adds one input type, its tests and one release. The [design](docs/superpowers/specs/2026-11-01-scieng-engine-design.md) gives the API, the stages, the security controls and the licence of each engine.
@@ -180,7 +281,7 @@ The [build plan](docs/superpowers/plans/2026-11-01-scieng-engine-build.md) gives
 | Mermaid | graph, mermaid, browser | class, state and sequence: released in 0.2.0; other types: released in 0.3.0 |
 | LaTeX math | math (MathJax) | svg, png and pdf are built; pdf needs the browser stage |
 | TikZ, circuitikz, LaTeX | tex (an own WASM build of `tex.web`) | trial builds pass |
-| Plots | plot | planned |
+| Plots | plot | svg, png and html are built, not yet released; pdf is not planned |
 | SysML v2 | sysml | planned |
 | STEP, IGES, BREP | mesh (OpenCascade WASM) | trial build passes |
 | HTML to PNG, PDF and Markdown | html, browser | PNG and PDF: released in 0.3.0; Markdown: planned |

package/THIRD_PARTY_NOTICES.md

@@ -21,6 +21,7 @@ Version: each row gives the version that the engine pins.
 | raster | `@resvg/resvg-wasm` 2.6.2 | MPL-2.0 | a dependency |
 | raster | Liberation Serif Regular 2.1.5 (font, in `assets/fonts/`) | SIL Open Font License 1.1 | bundled |
 | html | `parse5` | MIT | not yet a dependency |
+| plot (html output) | `plotly.js-dist-min` 4.2.0 (the pinned Plotly build, loaded by the html page from a CDN with a subresource integrity hash) | MIT | a devDependency. The package does not ship the build. The html page loads it from the CDN |
 | browser | Chromium or Google Chrome | Installed by the user. The engine does not ship it | not a package dependency |
 
 ## Notices
@@ -56,6 +57,10 @@ The Eclipse Public License 2.0 applies to Graphviz. The MIT licence applies to t
 
 The Apache License 2.0 applies to the MathJax packages. The BlueOak Model License 1.0.0 applies to the glob packages. The MIT licence applies to the other packages. Each package keeps its own licence text in its installed folder. The `dist/` folder holds the compiled code of this package only. It holds no code of the packages in the table: npm installs them as dependencies.
 
+### Plotly (MIT)
+
+The MIT licence applies to `plotly.js-dist-min` 4.2.0. The package is a devDependency. The engine does not bundle the build into the package and does not copy it into the assets folder. The html output of the `plot` stage is a page that loads the pinned build from the CDN URL in the engine, with a subresource integrity hash. The page makes that request when a reader opens it. The licence text is in the installed package at `node_modules/plotly.js-dist-min/LICENSE`.
+
 ### Mermaid (MIT)
 
 The MIT licence applies to `mermaid` 11.17.2. The build writes the file mermaid.min.js into the assets folder. That file is generated at build time and is not committed. The licence text is in `assets/licenses/MIT-mermaid.txt`.

package/dist/browser/page.d.ts

@@ -1,5 +1,12 @@
 /** Writes a value as a JavaScript literal that cannot end a script element or break a line. */
 export declare function scriptJson(text: string): string;
+/** Writes a JSON value as a JavaScript object literal that cannot end a script element. */
+export declare function scriptData(value: unknown): string;
+/**
+ * A page that loads the pinned Plotly build with its Subresource Integrity value and draws one figure.
+ * The figure object comes from the engine after the reader accepts it. The page title is the title argument.
+ */
+export declare function plotlyPageHtml(figure: unknown, cdnUrl: string, sri: string, title?: string): string;
 /** A page that shows one SVG document. The SVG text comes from the engine, not from the caller. */
 export declare function svgPageHtml(svg: string): string;
 /**

package/dist/browser/page.js

@@ -1,7 +1,33 @@
 const PAGE_STYLE = "html,body{margin:0;background:#fff}";
 /** Writes a value as a JavaScript literal that cannot end a script element or break a line. */
 export function scriptJson(text) {
-    return JSON.stringify(text).replace(/[<>&\u2028\u2029]/g, (ch) => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"));
+    return escapeScriptText(JSON.stringify(text));
+}
+/** Writes a JSON value as a JavaScript object literal that cannot end a script element. */
+export function scriptData(value) {
+    return escapeScriptText(JSON.stringify(value));
+}
+/** Escapes the characters that could end a script element or break a line in JavaScript source. */
+function escapeScriptText(text) {
+    return text.replace(/[<>&\u2028\u2029]/g, (ch) => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/** Escapes text for an HTML element body. */
+function escapeHtmlText(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+ * A page that loads the pinned Plotly build with its Subresource Integrity value and draws one figure.
+ * The figure object comes from the engine after the reader accepts it. The page title is the title argument.
+ */
+export function plotlyPageHtml(figure, cdnUrl, sri, title = "plot") {
+    return ('<!DOCTYPE html><html><head><meta charset="utf-8">' +
+        '<meta name="viewport" content="width=device-width, initial-scale=1">' +
+        `<title>${escapeHtmlText(title)}</title><style>${PAGE_STYLE}</style></head><body>` +
+        '<div id="sciengjs-diagram"></div>' +
+        `<script src="${cdnUrl}" integrity="${sri}" crossorigin="anonymous"></script>` +
+        `<script>(function () { const fig = ${scriptData(figure)}; ` +
+        'Plotly.newPlot(document.getElementById("sciengjs-diagram"), fig.data, fig.layout, { responsive: false }); })();</script>' +
+        "</body></html>");
 }
 /** A page that shows one SVG document. The SVG text comes from the engine, not from the caller. */
 export function svgPageHtml(svg) {

package/dist/browser/page.js.map

@@ -1 +1 @@
-{"version":3,"file":"page.js","sourceRoot":"","sources":["../../src/browser/page.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,qCAAqC,CAAC;AAEzD,+FAA+F;AAC/F,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CACjC,oBAAoB,EACpB,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,2DAA2D,UAAU,mDAAmD,GAAG,sBAAsB,CAAC;AAC3J,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,MAAc;IAC5D,MAAM,MAAM,GACV,yJAAyJ;QACzJ,6EAA6E;QAC7E,2DAA2D,UAAU,CAAC,MAAM,CAAC,KAAK;QAClF,kFAAkF;QAClF,sHAAsH;QACtH,2FAA2F;QAC3F,6CAA6C;QAC7C,kHAAkH;QAClH,0CAA0C;QAC1C,oEAAoE;QACpE,gDAAgD;QAChD,sGAAsG,CAAC;IACzG,OAAO,CACL,2DAA2D,UAAU,uBAAuB;QAC5F,mCAAmC;QACnC,gBAAgB,MAAM,aAAa;QACnC,0BAA0B,MAAM,+BAA+B,CAChE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../src/browser/page.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,qCAAqC,CAAC;AAEzD,+FAA+F;AAC/F,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,mGAAmG;AACnG,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC5G,CAAC;AAED,6CAA6C;AAC7C,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe,EAAE,MAAc,EAAE,GAAW,EAAE,KAAK,GAAG,MAAM;IACzF,OAAO,CACL,mDAAmD;QACnD,sEAAsE;QACtE,UAAU,cAAc,CAAC,KAAK,CAAC,kBAAkB,UAAU,uBAAuB;QAClF,mCAAmC;QACnC,gBAAgB,MAAM,gBAAgB,GAAG,qCAAqC;QAC9E,sCAAsC,UAAU,CAAC,MAAM,CAAC,IAAI;QAC5D,0HAA0H;QAC1H,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,2DAA2D,UAAU,mDAAmD,GAAG,sBAAsB,CAAC;AAC3J,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,MAAc;IAC5D,MAAM,MAAM,GACV,yJAAyJ;QACzJ,6EAA6E;QAC7E,2DAA2D,UAAU,CAAC,MAAM,CAAC,KAAK;QAClF,kFAAkF;QAClF,sHAAsH;QACtH,2FAA2F;QAC3F,6CAA6C;QAC7C,kHAAkH;QAClH,0CAA0C;QAC1C,oEAAoE;QACpE,gDAAgD;QAChD,sGAAsG,CAAC;IACzG,OAAO,CACL,2DAA2D,UAAU,uBAAuB;QAC5F,mCAAmC;QACnC,gBAAgB,MAAM,aAAa;QACnC,0BAA0B,MAAM,+BAA+B,CAChE,CAAC;AACJ,CAAC"}

package/dist/browser/pinned.d.ts

@@ -14,3 +14,11 @@ export interface PinnedAsset {
 }
 /** The pinned builds of the engine. Each entry names the URL of the CDN and the local file. */
 export declare const PINNED_ASSETS: readonly PinnedAsset[];
+/** The pinned Plotly version. It equals the exact devDependency plotly.js-dist-min of the repository. */
+export declare const PLOTLY_VERSION = "4.2.0";
+/** The SHA-256 of the pinned Plotly build, in hex. */
+export declare const PLOTLY_SHA256 = "fde93964a7511bfa54c5745c49b5d0e41715cbde0cc5ebeae3f9a02de0396cae";
+/** The Subresource Integrity value of the pinned Plotly build. The browser refuses other bytes. */
+export declare const PLOTLY_SRI = "sha256-/ek5ZKdRG/pUxXRcSbXQ5BcVy94Mxevq4/mgLeA5bK4=";
+/** The address that a plot page names for the pinned Plotly build. */
+export declare const PLOTLY_CDN_URL = "https://cdn.jsdelivr.net/npm/plotly.js-dist-min@4.2.0/plotly.min.js";

package/dist/browser/pinned.js

@@ -10,4 +10,12 @@ export const MERMAID_CDN_URL = `https://cdn.jsdelivr.net/npm/mermaid@${MERMAID_V
 export const PINNED_ASSETS = [
     { url: MERMAID_CDN_URL, file: MERMAID_FILE, mime: "application/javascript" },
 ];
+/** The pinned Plotly version. It equals the exact devDependency plotly.js-dist-min of the repository. */
+export const PLOTLY_VERSION = "4.2.0";
+/** The SHA-256 of the pinned Plotly build, in hex. */
+export const PLOTLY_SHA256 = "fde93964a7511bfa54c5745c49b5d0e41715cbde0cc5ebeae3f9a02de0396cae";
+/** The Subresource Integrity value of the pinned Plotly build. The browser refuses other bytes. */
+export const PLOTLY_SRI = "sha256-/ek5ZKdRG/pUxXRcSbXQ5BcVy94Mxevq4/mgLeA5bK4=";
+/** The address that a plot page names for the pinned Plotly build. */
+export const PLOTLY_CDN_URL = `https://cdn.jsdelivr.net/npm/plotly.js-dist-min@${PLOTLY_VERSION}/plotly.min.js`;
 //# sourceMappingURL=pinned.js.map

package/dist/browser/pinned.js.map

@@ -1 +1 @@
-{"version":3,"file":"pinned.js","sourceRoot":"","sources":["../../src/browser/pinned.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AACzC,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAG,kEAAkE,CAAC;AACjG,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAC7C,gHAAgH;AAChH,MAAM,CAAC,MAAM,eAAe,GAAG,wCAAwC,eAAe,sBAAsB,CAAC;AAS7G,+FAA+F;AAC/F,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,wBAAwB,EAAE;CAC7E,CAAC"}
+{"version":3,"file":"pinned.js","sourceRoot":"","sources":["../../src/browser/pinned.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AACzC,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAG,kEAAkE,CAAC;AACjG,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAC7C,gHAAgH;AAChH,MAAM,CAAC,MAAM,eAAe,GAAG,wCAAwC,eAAe,sBAAsB,CAAC;AAS7G,+FAA+F;AAC/F,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,wBAAwB,EAAE;CAC7E,CAAC;AAEF,yGAAyG;AACzG,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AACtC,sDAAsD;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,kEAAkE,CAAC;AAChG,mGAAmG;AACnG,MAAM,CAAC,MAAM,UAAU,GAAG,qDAAqD,CAAC;AAChF,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,mDAAmD,cAAc,gBAAgB,CAAC"}

package/dist/plot/backend-html.d.ts

@@ -0,0 +1,3 @@
+import type { BackendOutput, WorkerJob } from "../worker/protocol.ts";
+/** Renders plot to html: one standalone page that loads the pinned Plotly build and draws the figure. The page title is the figure title, or "plot". */
+export declare function render(request: WorkerJob["request"]): Promise<BackendOutput>;

package/dist/plot/backend-html.js

@@ -0,0 +1,13 @@
+import { plotlyPageHtml } from "../browser/page.js";
+import { PLOTLY_CDN_URL, PLOTLY_SRI } from "../browser/pinned.js";
+import { readPlotOptions } from "./backend-svg.js";
+import { readPlotFigure } from "./reader.js";
+/** Renders plot to html: one standalone page that loads the pinned Plotly build and draws the figure. The page title is the figure title, or "plot". */
+export async function render(request) {
+    const { lenient } = readPlotOptions(request.options, ["lenient"]);
+    const { figure, warnings } = readPlotFigure(String(request.source), { lenient });
+    const title = figure.layout.title?.text;
+    const html = plotlyPageHtml(figure, PLOTLY_CDN_URL, PLOTLY_SRI, typeof title === "string" && title !== "" ? title : "plot");
+    return { bytes: new TextEncoder().encode(html), warnings };
+}
+//# sourceMappingURL=backend-html.js.map

package/dist/plot/backend-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-html.js","sourceRoot":"","sources":["../../src/plot/backend-html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,wJAAwJ;AACxJ,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAA6B;IACxD,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAClE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACjF,MAAM,KAAK,GAAI,MAAM,CAAC,MAAM,CAAC,KAAwC,EAAE,IAAI,CAAC;IAC5E,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5H,OAAO,EAAE,KAAK,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC7D,CAAC"}

package/dist/plot/backend-png.d.ts

@@ -0,0 +1,3 @@
+import type { BackendOutput, WorkerJob } from "../worker/protocol.ts";
+/** Renders plot to png: the SVG of the figure, then the PNG of that SVG at the option scale. */
+export declare function render(request: WorkerJob["request"]): Promise<BackendOutput>;

package/dist/plot/backend-png.js

@@ -0,0 +1,12 @@
+import { readScale, svgDocumentToPng } from "../graph/backend-png.js";
+import { plotToSvg } from "./plotter.js";
+import { readPlotOptions } from "./backend-svg.js";
+/** Renders plot to png: the SVG of the figure, then the PNG of that SVG at the option scale. */
+export async function render(request) {
+    const { lenient } = readPlotOptions(request.options, ["lenient", "scale"]);
+    const scale = readScale(request.options);
+    const result = plotToSvg(String(request.source), { lenient });
+    const png = await svgDocumentToPng(result.svg, request, scale);
+    return { bytes: png.bytes, warnings: [...result.warnings, ...(png.warnings ?? [])] };
+}
+//# sourceMappingURL=backend-png.js.map

package/dist/plot/backend-png.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-png.js","sourceRoot":"","sources":["../../src/plot/backend-png.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,gGAAgG;AAChG,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAA6B;IACxD,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/D,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;AACvF,CAAC"}

package/dist/plot/backend-svg.d.ts

@@ -0,0 +1,7 @@
+import type { BackendOutput, WorkerJob } from "../worker/protocol.ts";
+/** Reads the plot options. The only key is lenient, a boolean. Any other key rejects with E_INPUT. */
+export declare function readPlotOptions(options: Record<string, unknown>, allowed: readonly string[]): {
+    lenient: boolean;
+};
+/** Renders plot to svg. The options are lenient only. */
+export declare function render(request: WorkerJob["request"]): Promise<BackendOutput>;

package/dist/plot/backend-svg.js

@@ -0,0 +1,21 @@
+import { RenderError } from "../errors.js";
+import { plotToSvg } from "./plotter.js";
+/** Reads the plot options. The only key is lenient, a boolean. Any other key rejects with E_INPUT. */
+export function readPlotOptions(options, allowed) {
+    for (const key of Object.keys(options)) {
+        if (!allowed.includes(key))
+            throw new RenderError("E_INPUT", "plot takes no option " + key);
+    }
+    const lenient = options.lenient;
+    if (lenient !== undefined && typeof lenient !== "boolean") {
+        throw new RenderError("E_INPUT", "option lenient must be true or false");
+    }
+    return { lenient: lenient === true };
+}
+/** Renders plot to svg. The options are lenient only. */
+export async function render(request) {
+    const { lenient } = readPlotOptions(request.options, ["lenient"]);
+    const result = plotToSvg(String(request.source), { lenient });
+    return { bytes: new TextEncoder().encode(result.svg), warnings: result.warnings };
+}
+//# sourceMappingURL=backend-svg.js.map

package/dist/plot/backend-svg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-svg.js","sourceRoot":"","sources":["../../src/plot/backend-svg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,OAAgC,EAAE,OAA0B;IAC1F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,uBAAuB,GAAG,GAAG,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1D,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,sCAAsC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAA6B;IACxD,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,OAAO,EAAE,KAAK,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;AACpF,CAAC"}

package/dist/plot/control.d.ts

@@ -0,0 +1,93 @@
+/** A transfer function G(s) = num(s) / den(s). Coefficients are in descending powers of s. */
+export interface TransferFunction {
+    num: number[];
+    den: number[];
+}
+/** A complex number. */
+export interface Complex {
+    re: number;
+    im: number;
+}
+/** The Plotly subset that the plotter reads. */
+export interface ControlFigure {
+    data: Array<Record<string, unknown>>;
+    layout: Record<string, unknown>;
+}
+/** A figure plus the numbers that the analysis derived from the same model. */
+export interface ControlResult<N> {
+    figure: ControlFigure;
+    numbers: N;
+}
+/** Options for the frequency helpers: the grid from wMin to wMax, in rad/s, with points samples. */
+export interface FrequencyOptions {
+    wMin?: number;
+    wMax?: number;
+    points?: number;
+}
+/** Options for the time helpers: the end time tEnd and the number of points. */
+export interface TimeOptions {
+    tEnd?: number;
+    points?: number;
+}
+/** Options for rootLocus: the largest gain kMax and the number of points. */
+export interface RootLocusOptions {
+    kMax?: number;
+    points?: number;
+}
+/** Key values of a Bode plot: crossover frequencies in rad/s, margins in degrees. A null value means none was found. */
+export interface BodeNumbers {
+    gainCrossover: number | null;
+    phaseCrossover: number | null;
+    gainMargin: number | null;
+    phaseMargin: number | null;
+}
+/**
+ * Key values of a step response: final value, rise and settling times, overshoot in percent, and peak time.
+ * The peak and the overshoot are measured in the direction of the final value. A system with a pole on or
+ * right of the imaginary axis has no final value, so every number is null. A response with no peak before
+ * the end of the time grid has a null peak time and an overshoot of 0.
+ */
+export interface StepNumbers {
+    finalValue: number | null;
+    riseTime: number | null;
+    settlingTime: number | null;
+    overshoot: number | null;
+    peakTime: number | null;
+}
+/** Key values of an impulse response: the peak value and the time of the peak. */
+export interface ImpulseNumbers {
+    peak: number;
+    peakTime: number;
+}
+/** The poles and the zeros of a transfer function, as complex numbers. */
+export interface PoleZeroNumbers {
+    poles: Complex[];
+    zeros: Complex[];
+}
+/** The least distance from the Nyquist curve to the point -1. */
+export interface NyquistNumbers {
+    minDistanceToMinusOne: number;
+}
+/** The breakaway points of the root locus, each with its gain k. */
+export interface RootLocusNumbers {
+    breakawayPoints: Array<{
+        re: number;
+        k: number;
+    }>;
+}
+/** Validates a transfer function. Rejects with E_INPUT: empty, non-finite, leading-zero den, or improper. */
+export declare function checkTransferFunction(input: unknown): TransferFunction;
+/** The roots of a polynomial with descending coefficients. Each trailing zero coefficient gives an exact root at 0; Durand-Kerner finds the others. No convergence rejects with E_INPUT. */
+export declare function polynomialRoots(coeffs: number[]): Complex[];
+/** Bode plot. Crossovers and margins are null where no crossing exists. */
+export declare function bode(input: unknown, options?: FrequencyOptions): ControlResult<BodeNumbers>;
+/** Step response by exact zero-order-hold simulation. finalValue is the DC gain, null for a system that is not stable. */
+export declare function step(input: unknown, options?: TimeOptions): ControlResult<StepNumbers>;
+/** Impulse response of the strictly proper part, C e^(At) B for t > 0. A direct feedthrough term is not plotted. */
+export declare function impulse(input: unknown, options?: TimeOptions): ControlResult<ImpulseNumbers>;
+/** Pole-zero map: poles as crosses, zeros as circles. */
+export declare function poleZero(input: unknown): ControlResult<PoleZeroNumbers>;
+/** Nyquist plot of G(j omega) for negative and positive frequencies, with the critical point -1. */
+export declare function nyquist(input: unknown, options?: FrequencyOptions): ControlResult<NyquistNumbers>;
+/** Root locus of den + K num = 0 for K from 0 to kMax, with breakaway points on the real axis. */
+export declare function rootLocus(input: unknown, options?: RootLocusOptions): ControlResult<RootLocusNumbers>;