@muhammara/native-core 7.0.0-rc.1 → 7.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/%40muhammara%2Fnative-core.svg)](https://www.npmjs.com/package/@muhammara/native)
 [![License](https://img.shields.io/npm/l/%40muhammara%2Fnative-core.svg)](https://github.com/julianhille/MuhammaraJS/blob/develop/LICENSE)
-[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://muhammarajs.readthedocs.io/)
+[![Documentation status](https://readthedocs.org/projects/muhammarajs/badge/?version=latest)](https://muhammarajs.readthedocs.io/)
 
 **This is an internal package. Do not install it directly.**
 

package/lib/Recipe.js

@@ -1,7 +1,7 @@
 const muhammara = require("./muhammara");
 const path = require("path");
 const fs = require("fs");
-const streams = require("memory-streams");
+const PDFWStreamForBuffer = require("./PDFWStreamForBuffer");
 var { standardInfoKeys } = require("./recipe-info");
 var { AnnotSubtype, PageLayout, Source } = require("./recipe-constants");
 
@@ -53,7 +53,7 @@ class Recipe {
     );
 
     if (this.isBufferSrc) {
-      this.outStream = new streams.WritableStream();
+      this.outStream = new PDFWStreamForBuffer();
       this.output = output;
     } else {
       this.output = output || src;
@@ -109,7 +109,7 @@ class Recipe {
         );
       } else {
         this.writer = muhammara.createWriter(
-          new muhammara.PDFStreamForResponse(this.outStream),
+          this.outStream,
           Object.assign({}, this.encryptOptions, {
             version: this._getVersion(this.options.version),
             log: this.logFile,
@@ -122,7 +122,7 @@ class Recipe {
         if (this.isBufferSrc) {
           this.writer = muhammara.createWriterToModify(
             new muhammara.PDFRStreamForBuffer(this.src),
-            new muhammara.PDFStreamForResponse(this.outStream),
+            this.outStream,
             Object.assign({}, this.encryptOptions, {
               log: this.logFile,
             }),
@@ -319,7 +319,7 @@ class Recipe {
     if (this.ended) {
       if (!callback) return;
       if (!this.isBufferSrc) return callback();
-      return callback(this.output || this.outStream.toBuffer());
+      return callback(this.output || this.outStream.buffer || Buffer.alloc(0));
     }
     var deletingPages = Boolean(this.deletedPages?.size);
     var deletionState = deletingPages
@@ -350,11 +350,13 @@ class Recipe {
       ) {
         if (this.isBufferSrc) {
           const oldStream = this.outStream;
-          this.outStream = new streams.WritableStream();
+          this.outStream = new PDFWStreamForBuffer();
 
           this.writer = muhammara.createWriterToModify(
-            new muhammara.PDFRStreamForBuffer(oldStream.toBuffer()),
-            new muhammara.PDFStreamForResponse(this.outStream),
+            new muhammara.PDFRStreamForBuffer(
+              oldStream.buffer || Buffer.alloc(0),
+            ),
+            this.outStream,
             Object.assign({}, this.encryptOptions, {
               log: this.logFile,
             }),
@@ -401,7 +403,7 @@ class Recipe {
       }
 
       if (this.isBufferSrc && this.output) {
-        fs.writeFileSync(this.output, this.outStream.toBuffer());
+        fs.writeFileSync(this.output, this.outStream.buffer || Buffer.alloc(0));
       }
 
       this.ended = true;
@@ -436,7 +438,7 @@ class Recipe {
         if (this.output) {
           return callback(this.output);
         } else {
-          return callback(this.outStream.toBuffer());
+          return callback(this.outStream.buffer || Buffer.alloc(0));
         }
       } else {
         return callback();

package/lib/recipe/image.js

@@ -1,3 +1,4 @@
+const fs = require("fs");
 const muhammara = require("../muhammara");
 const { HorizontalAlign, VerticalAlign } = require("../recipe-constants");
 
@@ -11,26 +12,60 @@ const { HorizontalAlign, VerticalAlign } = require("../recipe-constants");
  * @param {number|"center"} y - The coordinate y of the top-left corner
  * @param {Object} [options] - The options
  * @returns {Recipe} The recipe instance.
- * @param {number} [options.width] - The new width
+ * @param {number} [options.page=1] - The one-based page of a PDF source, or the
+ *   image of a multi-image TIFF, as in `overlay()`.
+ * @param {number} [options.width] - The new width. The frame's line width is
+ *   `options.lineWidth`.
  * @param {number} [options.height] - The new height
  * @param {number} [options.scale] - Scale the image from the original width and height.
  * @param {boolean} [options.keepAspectRatio=true] - Keep the aspect ratio.
- * @param {number} [options.opacity] - The opacity.
+ * @param {number} [options.opacity] - The opacity of the image and its frame.
  * @param {string} [options.align] - A `Recipe.HorizontalAlign` value, optionally
  *   followed by a space and a `Recipe.VerticalAlign` value, for example
  *   "center center". Horizontal center moves the image left by half its width
  *   and right moves it right by half; vertical center moves it up by half its
  *   height and bottom moves it down by half from its top-left placement.
+ * @param {number} [options.rotation] - Rotate the image, in degrees.
+ * @param {number[]} [options.rotationOrigin] - [x, y] of the rotation origin;
+ *   the bottom-left corner of the drawn image when omitted.
+ * @param {number} [options.skewX] - Skew angle off the x axis, in degrees.
+ * @param {number} [options.skewY] - Skew angle off the y axis, in degrees.
+ * @param {string|number[]} [options.fill] - Paint the image box beneath the
+ *   image in this color.
+ * @param {string|number[]} [options.stroke] - Outline the image box above the
+ *   image in this color.
+ * @param {string|number[]} [options.color] - Outline color when `stroke` is
+ *   not given.
+ * @param {Recipe.Colorspace} [options.colorspace] - The frame colorspace.
+ * @param {string} [options.colorName] - The Separation ink name of a
+ *   `"separation"` frame color.
+ * @param {number} [options.lineWidth] - The outline width. The outline lies
+ *   inside the image box, as a `rectangle()` stroke does.
+ * @param {number[]} [options.dash] - The outline dash pattern.
+ * @param {number} [options.dashPhase] - The outline dash phase.
+ * @param {Recipe.LineCap} [options.lineCap] - The outline dash cap.
+ * @param {Recipe.LineJoin} [options.lineJoin] - The outline corner join.
+ * @param {number} [options.miterLimit] - The outline miter limit.
+ * @param {boolean|number} [options.debug] - Outline the image box in green and
+ *   mark the placement point in red.
  * @param {string} [options.link] - Make the image open this URL.
  * @throws {TypeError} If no page is active.
- * @throws {Error} If the image cannot be read.
+ * @throws {RangeError} If `page` is not an integer from 1 to 4294967296,
+ *   a size is not a finite number, or `miterLimit` is not a number of at
+ *   least 1.
+ * @throws {TypeError} If `rotation` is not a finite number.
+ * @throws {Error} If the image, or the PDF page `page` selects, cannot be read.
  */
 exports.image = function image(imgSrc, x, y, options = {}) {
-  const { width, height, offsetX, offsetY } = this._getImgOffset(
+  // null options act like omitted options.
+  if (options === null) options = {};
+  const index = imageIndex(options);
+  const { width, height, offsetX, offsetY, page } = this._getImgOffset(
     imgSrc,
     options,
   );
   const imgOptions = {
+    index,
     transformation: {
       fit: muhammara.ImageFit.ALWAYS,
       // proportional: true,
@@ -42,7 +77,13 @@ exports.image = function image(imgSrc, x, y, options = {}) {
 
   const _options = this._getPathOptions(options, nx, ny);
   const gsId = _options.fillGsId;
-  const xObjectKeyName = `${imgSrc}__${gsId}`;
+  const xObjectKeyName = `${imgSrc}__${index}__${gsId}`;
+
+  // `width` is the image width; only `lineWidth` sizes the frame outline.
+  const frame = { ...options, width: undefined };
+  if (options.fill) {
+    drawFrame(this, nx, ny, width, height, { ...frame, stroke: undefined });
+  }
 
   // See if this image has been seen already, so as to not duplicate it.
   let xObject = this.xObjects.find((element) => {
@@ -65,61 +106,339 @@ exports.image = function image(imgSrc, x, y, options = {}) {
     xObject.set("height", height);
 
     this.xObjects.push(xObject);
-    ctx.gs(xObject.getGsName(gsId)).drawImage(0, 0, imgSrc, imgOptions);
+    ctx.gs(xObject.getGsName(gsId));
+    if (page) {
+      const placed = placedPage(page, width, height);
+      ctx.cm(...placed.matrix).drawImage(placed.x, placed.y, imgSrc, {
+        index,
+        transformation: { ...imgOptions.transformation, ...placed.size },
+      });
+    } else {
+      ctx.drawImage(0, 0, imgSrc, imgOptions);
+    }
   });
 
+  if (options.stroke || options.color) {
+    drawFrame(this, nx, ny, width, height, { ...frame, fill: undefined });
+  }
+
+  if (options.debug) {
+    drawFrame(this, nx, ny, width, height, {
+      stroke: DEBUG_OUTLINE,
+      lineWidth: 1,
+      rotation: options.rotation,
+      rotationOrigin: options.rotationOrigin,
+      skewX: options.skewX,
+      skewY: options.skewY,
+    });
+    this.circle(x, y, 2, { fill: DEBUG_ANCHOR });
+  }
+
   if (options.link) {
-    this.link(options.link, x + offsetX, y - offsetY - height, width, height);
+    const [linkX, linkY] = this._centrify(x, y);
+    this.link(
+      options.link,
+      linkX + offsetX,
+      linkY - offsetY - height,
+      width,
+      height,
+    );
   }
 
   return this;
 };
 
+/**
+ * Read the one-based `page` option as the zero-based index of the PDF page or
+ * TIFF image that PDFWriter takes.
+ * @private
+ * @param {Object} options - The image() options.
+ * @returns {number} The zero-based index; 0 when `page` is omitted.
+ * @throws {RangeError} If `page` is not an integer from 1 to 4294967296.
+ */
+function imageIndex(options) {
+  const page = options.page ?? 1;
+  if (!Number.isInteger(page) || page < 1 || page > 0x100000000) {
+    throw new RangeError("image page must be an integer from 1 to 4294967296");
+  }
+  return page - 1;
+}
+
+/**
+ * Read a size option of `image()` as a number. A numeric string counts as its
+ * number, as in Wasm; a missing or other falsy value means not given.
+ * A negative size mirrors the image.
+ * @private
+ * @param {Object} options - The image() options.
+ * @param {string} key - `width`, `height`, or `scale`.
+ * @returns {number|undefined} The size, or undefined when not given.
+ * @throws {RangeError} If the value is not a finite number.
+ */
+function imageSize(options, key) {
+  if (!options[key]) return undefined;
+  const size = Number(options[key]);
+  if (!Number.isFinite(size)) {
+    throw new RangeError(`image ${key} must be a finite number`);
+  }
+  return size;
+}
+
+/**
+ * Read the media box and rotation of a page of a PDF image source, caching
+ * them per file version on the Recipe. Returns null for a source that is not
+ * a readable PDF file, which is measured and drawn as an image.
+ * @private
+ * @param {Recipe} recipe - The recipe instance.
+ * @param {string} imgSrc - The image path.
+ * @param {number} index - The zero-based page.
+ * @returns {?{mediaBox: number[], rotate: number}} The page geometry.
+ * @throws {Error} If the PDF has no page at `index`: PDFWriter would read a
+ *   page that does not exist.
+ */
+function pdfPage(recipe, imgSrc, index) {
+  let key;
+  try {
+    const stat = fs.statSync(imgSrc);
+    key = `${imgSrc}\0${stat.mtimeMs}\0${stat.size}`;
+  } catch {
+    // A missing file measures 0 by 0 and is rejected as an unknown image.
+    return null;
+  }
+  recipe._pdfSources = recipe._pdfSources || new Map();
+  let source = recipe._pdfSources.get(key);
+  if (!source) {
+    source = {
+      pdf: recipe.writer.getImageType(imgSrc) === muhammara.PDFImageType.PDF,
+      pages: new Map(),
+    };
+    recipe._pdfSources.set(key, source);
+  }
+  if (!source.pdf) return null;
+  if (!source.pages.has(index)) {
+    source.pages.set(index, readPdfPage(imgSrc, index));
+  }
+  const page = source.pages.get(index);
+  if (!page) throw new Error(`Unknown image: ${imgSrc}`);
+  return page;
+}
+
+/**
+ * Read the media box and rotation of one page of a PDF file.
+ * @private
+ * @param {string} imgSrc - The PDF path.
+ * @param {number} index - The zero-based page.
+ * @returns {?{mediaBox: number[], rotate: number}} The page geometry, or null
+ *   when the PDF cannot be read or has no such page.
+ */
+function readPdfPage(imgSrc, index) {
+  let reader;
+  try {
+    reader = muhammara.createReader(imgSrc);
+  } catch {
+    return null;
+  }
+  try {
+    if (index >= reader.getPagesCount()) return null;
+    const page = reader.parsePage(index);
+    return { mediaBox: page.getMediaBox(), rotate: page.getRotate() };
+  } finally {
+    reader.end();
+  }
+}
+
+/**
+ * The size of a PDF page as it is displayed: its media box, turned by its
+ * `/Rotate`.
+ * @private
+ * @param {{mediaBox: number[], rotate: number}} page - The page geometry.
+ * @returns {{width: number, height: number}} The displayed size.
+ */
+function displayedPageSize(page) {
+  const [left, bottom, right, top] = page.mediaBox;
+  return quarterTurns(page.rotate) % 2
+    ? { width: top - bottom, height: right - left }
+    : { width: right - left, height: top - bottom };
+}
+
+/**
+ * How to draw a PDF page into a displayed box: PDFWriter fits the unturned
+ * media box and ignores its origin, so the page is turned by its `/Rotate`
+ * and drawn at its origin scaled away.
+ * @private
+ * @param {{mediaBox: number[], rotate: number}} page - The page geometry.
+ * @param {number} width - The displayed width.
+ * @param {number} height - The displayed height.
+ * @returns {{matrix: number[], x: number, y: number, size: {width: number, height: number}}}
+ *   The turning matrix, the drawing position, and the fitted unturned size.
+ */
+function placedPage(page, width, height) {
+  const [left, bottom, right, top] = page.mediaBox;
+  const turns = quarterTurns(page.rotate);
+  const w = turns % 2 ? height : width;
+  const h = turns % 2 ? width : height;
+  const matrix = [
+    [1, 0, 0, 1, 0, 0],
+    [0, -1, 1, 0, 0, w],
+    [-1, 0, 0, -1, w, h],
+    [0, 1, -1, 0, h, 0],
+  ][turns];
+  return {
+    matrix,
+    x: (-left * w) / (right - left),
+    y: (-bottom * h) / (top - bottom),
+    size: { width: w, height: h },
+  };
+}
+
+/**
+ * The clockwise quarter turns of a page `/Rotate` value.
+ * @private
+ * @param {number} rotate - The `/Rotate` value, a multiple of 90.
+ * @returns {number} 0 to 3; 0 for a value that is not a multiple of 90.
+ */
+function quarterTurns(rotate) {
+  const turns = (((Number(rotate) || 0) % 360) + 360) % 360;
+  return turns % 90 ? 0 : turns / 90;
+}
+
+// The diagnostic colors the shape `debug` options draw with.
+const DEBUG_OUTLINE = "#00ff00";
+const DEBUG_ANCHOR = "#ff0000";
+
+/**
+ * Paint the box of a placed image, with the image's rotation and skew: a fill
+ * when `options.fill` is given, otherwise an outline inset by half its line
+ * width, as `rectangle()` strokes are.
+ * @private
+ * @param {Recipe} recipe - The recipe instance.
+ * @param {number} nx - The PDF x of the image's bottom-left corner.
+ * @param {number} ny - The PDF y of the image's bottom-left corner.
+ * @param {number} width - The drawn image width.
+ * @param {number} height - The drawn image height.
+ * @param {Object} options - The image() frame options, `width` excluded.
+ * @returns {void}
+ */
+function drawFrame(recipe, nx, ny, width, height, options) {
+  const pathOptions = recipe._getPathOptions(options, nx, ny);
+  // A negative size mirrors the image into the other side of its corner.
+  const left = Math.min(0, width);
+  const bottom = Math.min(0, height);
+  const boxWidth = Math.abs(width);
+  const boxHeight = Math.abs(height);
+  if (options.fill) {
+    const colorModel = pathOptions.fillModel;
+    pathOptions.type = muhammara.DrawingPathType.FILL;
+    pathOptions.color = colorModel.color;
+    pathOptions.colorspace = colorModel.colorspace;
+    recipe._drawObject(
+      recipe,
+      nx,
+      ny,
+      width,
+      height,
+      pathOptions,
+      (ctx, xObject) => {
+        ctx.gs(xObject.getGsName(pathOptions.fillGsId));
+        xObject.fill(colorModel);
+        ctx.drawRectangle(
+          left,
+          bottom,
+          boxWidth,
+          boxHeight,
+          recipe._devicePathOptions(pathOptions),
+        );
+      },
+    );
+    return;
+  }
+  const colorModel =
+    pathOptions.stroke !== undefined
+      ? pathOptions.strokeModel
+      : pathOptions.colorModel;
+  pathOptions.type = muhammara.DrawingPathType.STROKE;
+  pathOptions.color = colorModel.color;
+  pathOptions.colorspace = colorModel.colorspace;
+  recipe._drawObject(
+    recipe,
+    nx,
+    ny,
+    width,
+    height,
+    pathOptions,
+    (ctx, xObject) => {
+      // The form clips at the image box, so the outline lies inside it.
+      const margin = pathOptions.width;
+      ctx.gs(xObject.getGsName(pathOptions.strokeGsId));
+      xObject.stroke(colorModel);
+      ctx
+        .J(pathOptions.lineCap)
+        .j(pathOptions.lineJoin)
+        .M(pathOptions.miterLimit)
+        .d(pathOptions.dash, pathOptions.dashPhase)
+        .drawRectangle(
+          left + Math.min(margin / 2, boxWidth / 2),
+          bottom + Math.min(margin / 2, boxHeight / 2),
+          Math.max(0, boxWidth - margin),
+          Math.max(0, boxHeight - margin),
+          recipe._devicePathOptions(pathOptions),
+        );
+    },
+  );
+}
+
 /**
  * Compute the drawn size of an image and the offset its alignment applies.
- * Sets `options.keepAspectRatio` to true when it is not given.
+ * A missing `options.keepAspectRatio` keeps the aspect ratio.
  * @private
  * @param {string} [imgSrc=''] - The image path.
- * @param {Object} [options] - The image() options.
- * @returns {{width: number, height: number, offsetX: number, offsetY: number}}
- *   The drawn size and the PDF offset from the placement point.
- * @throws {Error} If the image cannot be read.
+ * @param {Object} [options] - The image() options; `page` selects the page or
+ *   image that is measured.
+ * @returns {{width: number, height: number, offsetX: number, offsetY: number, page: ?Object}}
+ *   The drawn size, the PDF offset from the placement point, and the page
+ *   geometry of a PDF source.
+ * @throws {Error} If the image, or the PDF page `page` selects, cannot be read.
  */
 exports._getImgOffset = function _getImgOffset(imgSrc = "", options = {}) {
-  // set default to true
-  options.keepAspectRatio =
-    options.keepAspectRatio == void 0 ? true : options.keepAspectRatio;
-  const dimensions = this.writer.getImageDimensions(imgSrc);
+  // A missing keepAspectRatio keeps it; the caller's options stay untouched.
+  const keepAspectRatio = options.keepAspectRatio ?? true;
+  const index = imageIndex(options);
+  const page = pdfPage(this, imgSrc, index);
+  const dimensions = page
+    ? displayedPageSize(page)
+    : this.writer.getImageDimensions(imgSrc, index);
   // An unreadable image measures 0 by 0. Drawing it would leave an image
   // object that is never written, so endPDF() could not finish the PDF.
   if (!(dimensions.width > 0 && dimensions.height > 0)) {
     throw new Error(`Unknown image: ${imgSrc}`);
   }
   const ratio = dimensions.width / dimensions.height;
+  const scale = imageSize(options, "scale");
+  const wantedWidth = imageSize(options, "width");
+  const wantedHeight = imageSize(options, "height");
 
   let width = dimensions.width;
   let height = dimensions.height;
-  if (options.scale) {
-    width = width * options.scale;
-    height = height * options.scale;
-  } else if (options.width && !options.height) {
-    width = options.width;
-    height = options.width / ratio;
-  } else if (!options.width && options.height) {
-    width = options.height * ratio;
-    height = options.height;
-  } else if (options.width && options.height) {
-    if (!options.keepAspectRatio) {
-      width = options.width;
-      height = options.height;
+  if (scale) {
+    width = width * scale;
+    height = height * scale;
+  } else if (wantedWidth && !wantedHeight) {
+    width = wantedWidth;
+    height = wantedWidth / ratio;
+  } else if (!wantedWidth && wantedHeight) {
+    width = wantedHeight * ratio;
+    height = wantedHeight;
+  } else if (wantedWidth && wantedHeight) {
+    if (!keepAspectRatio) {
+      width = wantedWidth;
+      height = wantedHeight;
     } else {
       // fit to the smaller
-      if (options.width / ratio <= options.height) {
-        width = options.width;
-        height = options.width / ratio;
+      if (wantedWidth / ratio <= wantedHeight) {
+        width = wantedWidth;
+        height = wantedWidth / ratio;
       } else {
-        width = options.height * ratio;
-        height = options.height;
+        width = wantedHeight * ratio;
+        height = wantedHeight;
       }
     }
   }
@@ -145,11 +464,13 @@ exports._getImgOffset = function _getImgOffset(imgSrc = "", options = {}) {
           offsetY = (-1 * height) / 2;
           break;
         case VerticalAlign.BOTTOM:
-          offsetY = height / 2;
+          // Down by half the height from the top-left placement, as
+          // documented; 6.x moved the image up by 1.5 times its height.
+          offsetY = -1.5 * height;
           break;
         default:
       }
     }
   }
-  return { width, height, offsetX, offsetY };
+  return { width, height, offsetX, offsetY, page };
 };

package/lib/recipe/text.js

@@ -321,7 +321,7 @@ exports._makeTextBox = function _makeTextBox(options) {
  * @param {string} [options.subject] - Subject of annotation.
  * @param {string} [options.link] - Make the text open this URL.
  * @returns {Recipe} The recipe instance. Without an active page nothing is drawn.
- * @throws {TypeError} If `options.charSpace` is not a finite number; nothing is drawn.
+ * @throws {TypeError} If `options.charSpace` or `options.rotation` is not a finite number; nothing is drawn.
  * @throws {Error} If an overflow callback names an undefined layout, or a font cannot be loaded.
  */
 exports.text = function text(text = "", x, y, options = {}) {

package/lib/recipe/vector.helper.js

@@ -1,6 +1,7 @@
 const { xObjectForm } = require("./xObjectForm");
 const { resolveFontSize } = require("./utils");
 const { Colorspace, LineCap, LineJoin } = require("../recipe-constants");
+const { miterLimitOption, rotationOption } = require("../recipe-options");
 
 /**
  * Resolve drawing and text options into path options: font, size, colors
@@ -11,7 +12,9 @@ const { Colorspace, LineCap, LineJoin } = require("../recipe-constants");
  * @param {number} originX - The PDF x of the default rotation origin.
  * @param {number} originY - The PDF y of the default rotation origin.
  * @returns {Object} The resolved path options.
- * @throws {RangeError} If a given font size is not greater than zero.
+ * @throws {RangeError} If a given font size is not greater than zero, or
+ *   `miterLimit` is not a number of at least 1.
+ * @throws {TypeError} If `rotation` is not a finite number.
  * @throws {Error} If the font cannot be loaded.
  */
 exports._getPathOptions = function _getPathOptions(
@@ -20,6 +23,9 @@ exports._getPathOptions = function _getPathOptions(
   originY,
 ) {
   this.current = this.current || {};
+  // Validate before anything is resolved or drawn.
+  const rotation = rotationOption(options.rotation);
+  const miterLimit = miterLimitOption(options.miterLimit);
   const colorspace = options.colorspace || this.options.colorspace;
   const colorName = options.colorName;
 
@@ -94,18 +100,16 @@ exports._getPathOptions = function _getPathOptions(
 
   // A fill or stroke replaces the default color. Resolving that default under
   // colorName would write an unused Separation color space for the ink.
-  const paintsColor =
-    options.color || options.colour || (!options.fill && !options.stroke);
+  const paintsColor = options.color || (!options.fill && !options.stroke);
   pathOptions.colorModel = this._transformColor(
-    options.color || options.colour,
+    options.color,
     paintsColor ? colorOpts : { ...colorOpts, colorName: undefined },
   );
   pathOptions.color = pathOptions.colorModel.color;
   pathOptions.colorspace = pathOptions.colorModel.colorspace;
 
   // rotation
-  if (options.rotation !== void 0) {
-    const rotation = parseFloat(options.rotation);
+  if (rotation !== undefined) {
     pathOptions.rotation = rotation;
     pathOptions.rotationOrigin = options.rotationOrigin || null;
   }
@@ -135,11 +139,7 @@ exports._getPathOptions = function _getPathOptions(
     pathOptions.lineCap = this._lineCap(options.lineCap);
   }
 
-  if (options.miterLimit !== void 0) {
-    if (!isNaN(options.miterLimit)) {
-      pathOptions.miterLimit = options.miterLimit;
-    }
-  }
+  if (miterLimit !== undefined) pathOptions.miterLimit = miterLimit;
 
   return pathOptions;
 };

package/lib/recipe/vector.js

@@ -14,6 +14,7 @@
 
 const { linkPdf } = require("./annotation");
 const muhammara = require("../muhammara");
+const { miterLimitOption } = require("../recipe-options");
 
 /**
  * Draw a circle
@@ -668,15 +669,19 @@ exports.pie = function pie(x, y, radius, startAngle, endAngle, options = {}) {
  * @param {number} [options.lineWidth] - Alias for width.
  * @param {number} [options.cap] - The PDF line cap style, a `LineCapStyle` value.
  * @param {number} [options.join] - The PDF line join style: 0 miter, 1 round, 2 bevel.
- * @param {number} [options.miterLimit] - The miter limit.
+ * @param {number} [options.miterLimit] - The miter limit, at least 1.
  * @param {number[]} [options.dash] - The dash pattern.
  * @param {number} [options.dashPhase] - The dash pattern phase.
  * @returns {Recipe} The recipe instance.
  * @throws {TypeError} If no page is active.
+ * @throws {RangeError} If `miterLimit` is not a number of at least 1.
  */
 exports.lineStyle = function lineStyle(options = {}) {
   // null options act like omitted options.
   if (options === null) options = {};
+  // Validate before anything is written.
+  const miterLimit = miterLimitOption(options.miterLimit);
+  if (miterLimit !== undefined) options = { ...options, miterLimit };
   this.current = this.current || {};
   this.current.lineStyle = this.current.lineStyle || {};
 

package/lib/recipe-options.js

@@ -0,0 +1,47 @@
+// Validation of Recipe drawing options shared by shapes, text, and images.
+
+/**
+ * Read a `rotation` option in degrees. A numeric string counts as its number.
+ * @param {*} value - The option value.
+ * @returns {number|undefined} The rotation, or undefined when omitted or null.
+ * @throws {TypeError} If the value is not a finite number: it used to write
+ *   NaN transformation matrices.
+ */
+function rotationOption(value) {
+  if (value === undefined || value === null) return undefined;
+  const rotation = optionNumber(value);
+  if (!Number.isFinite(rotation)) {
+    throw new TypeError("rotation must be a finite number");
+  }
+  return rotation;
+}
+
+/**
+ * Read a `miterLimit` option. A numeric string counts as its number.
+ * @param {*} value - The option value.
+ * @returns {number|undefined} The miter limit, or undefined when omitted or
+ *   null.
+ * @throws {RangeError} If the value is not a number of at least 1, which PDF
+ *   requires.
+ */
+function miterLimitOption(value) {
+  if (value === undefined || value === null) return undefined;
+  const miterLimit = optionNumber(value);
+  if (!(miterLimit >= 1) || !Number.isFinite(miterLimit)) {
+    throw new RangeError("miterLimit must be a number of at least 1");
+  }
+  return miterLimit;
+}
+
+/**
+ * The number of a numeric option: a number, or a string holding one.
+ * @param {*} value - The option value.
+ * @returns {number} The number; NaN for any other value.
+ */
+function optionNumber(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && value.trim() !== "") return Number(value);
+  return NaN;
+}
+
+module.exports = { miterLimitOption, rotationOption };

package/muhammara.d.ts

@@ -3332,20 +3332,30 @@ declare namespace muhammara {
       userProtectionFlag?: number;
     }
 
-    interface ImageOptions {
+    /**
+     * Options of `image()`. `fill`, `stroke`, or `color` frame the drawn image
+     * box: the fill beneath the image, the outline above it and inside the
+     * box, as a `rectangle()` stroke. The line options style that outline.
+     */
+    interface ImageOptions extends PathOptions, TransformOptions {
       /** Make the rendered image open this URL. */
       link?: string;
+      /** The drawn image width. `lineWidth` sets the frame outline width. */
       width?: number;
       height?: number;
+      /** Scale the source size; wins over `width` and `height`. */
       scale?: number;
       keepAspectRatio?: boolean;
+      /** The opacity of the image and its frame. */
       opacity?: number;
       /** `Recipe.HorizontalAlign`, optionally followed by a space and `Recipe.VerticalAlign`. */
       align?: ImageAlign;
-      rotation?: number;
-      rotationOrigin?: [number, number];
-      skewX?: number;
-      skewY?: number;
+      /** The one-based page of a PDF source, or image of a multi-image TIFF, as in `overlay()`; defaults to 1. */
+      page?: number;
+      /** Paint the image box beneath the image. */
+      fill?: Color;
+      /** Outline the image box in green and mark the placement point in red. */
+      debug?: boolean | number;
     }
 
     interface InfoOptions {
@@ -4151,19 +4161,36 @@ declare namespace muhammara {
      * @param y - The coordinate y of the top-left corner
      * @param options - The options
      * @returns The recipe instance.
-     * @param options.width - The new width
+     * @param options.page - The one-based page of a PDF source, or image of a
+     *   multi-image TIFF, as in `overlay()`; defaults to 1.
+     * @param options.width - The new width. The frame outline width is
+     *   `options.lineWidth`.
      * @param options.height - The new height
      * @param options.scale - Scale the image from the original width and height.
      * @param options.keepAspectRatio - Keep the aspect ratio; defaults to true.
-     * @param options.opacity - The opacity.
+     * @param options.opacity - The opacity of the image and its frame.
      * @param options.align - A `Recipe.HorizontalAlign` value, optionally
      *   followed by a space and a `Recipe.VerticalAlign` value, for example
      *   "center center". Horizontal center moves the image left by half its width
      *   and right moves it right by half; vertical center moves it up by half its
      *   height and bottom moves it down by half from its top-left placement.
+     * @param options.rotation - Rotate the image, in degrees.
+     * @param options.rotationOrigin - [x, y] of the rotation origin; the
+     *   bottom-left corner of the drawn image when omitted.
+     * @param options.fill - Paint the image box beneath the image.
+     * @param options.stroke - Outline the image box above the image.
+     * @param options.color - Outline color when `stroke` is not given.
+     * @param options.lineWidth - The outline width; the outline lies inside
+     *   the image box, as a `rectangle()` stroke does.
+     * @param options.debug - Outline the image box in green and mark the
+     *   placement point in red.
      * @param options.link - Make the image open this URL.
      * @throws {TypeError} If no page is active.
-     * @throws {Error} If the image cannot be read.
+     * @throws {RangeError} If `page` is not an integer from 1 to 4294967296,
+     *   a size is not a finite number, or `miterLimit` is not a number of at
+     *   least 1.
+     * @throws {TypeError} If `rotation` is not a finite number.
+     * @throws {Error} If the image, or the PDF page `page` selects, cannot be read.
      */
     image(
       imgSrc: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhammara/native-core",
-  "version": "7.0.0-rc.1",
+  "version": "7.0.0",
   "description": "Shared JavaScript API for MuhammaraJS native packages",
   "homepage": "https://muhammarajs.readthedocs.io/",
   "license": "Apache-2.0",
@@ -31,8 +31,7 @@
   ],
   "dependencies": {
     "@xmldom/xmldom": "^0.9.10",
-    "linebreak": "^1.1.0",
-    "memory-streams": "^0.1.3"
+    "linebreak": "^1.1.0"
   },
   "publishConfig": {
     "access": "public",