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

package/lib/recipe/text.js

@@ -1,10 +1,17 @@
 const LineBreaker = require("linebreak");
 const { Word, Line, Column } = require("./text.helper");
-const { htmlToTextObjects } = require("./htmlToTextObjects");
+const { htmlToTextObjects, HtmlTag } = require("./htmlToTextObjects");
 const { Color, xObjectForm } = require("./xObjectForm");
 const { linkPdf } = require("./annotation");
 const muhammara = require("../muhammara");
 const { UsedFont } = require("../muhammara");
+const {
+  TextWrap,
+  TextAlign,
+  VerticalAlign,
+  HorizontalAlign,
+  Colorspace,
+} = require("../recipe-constants");
 
 //  Table indicating how to specify coloration of elements
 //  -------------------------------------------------------------------
@@ -40,6 +47,15 @@ const { UsedFont } = require("../muhammara");
 //     return target
 // }
 
+/**
+ * Merge text options: arrays and non-object values from `source` replace those
+ * in `target`, and nested objects are merged. `source` objects are updated in
+ * place; the result is a new object.
+ * @private
+ * @param {Object} target - The base options.
+ * @param {Object} source - The overriding options.
+ * @returns {Object} The merged options.
+ */
 exports._merge = function merge(target, source) {
   // Iterate through `source` properties and if an `Object` set property to merge of `target` and `source` properties
   for (const key of Object.keys(source)) {
@@ -63,6 +79,32 @@ exports._merge = function merge(target, source) {
   return Object.assign({}, target, source);
 };
 
+/**
+ * Reject a character spacing that cannot become a `Tc` operand.
+ * @private
+ * @param {Object} [options] - The text options of one text() call.
+ * @returns {void}
+ * @throws {TypeError} If `options.charSpace` is given and is not a finite number.
+ */
+function _validateCharSpace(options) {
+  const charSpace = options?.charSpace ?? 0;
+  if (!Number.isFinite(charSpace)) {
+    throw new TypeError("charSpace must be a finite number");
+  }
+}
+
+/**
+ * Resolve the text position and options for text(): a call without
+ * coordinates continues the flow or starts at the margins, a call with them
+ * starts a new text box; previous options are merged in.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {number|"center"|Object} [x] - The x coordinate, or the options.
+ * @param {number|"center"} [y] - The y coordinate.
+ * @param {Object} [options] - The text options.
+ * @returns {Object} The merged text options.
+ * @throws {TypeError} If no page is active.
+ */
 function _initOptions(self, x = {}, y, options = {}) {
   // This allows user to skip providing x/y coordinates
   if (typeof x === "object") {
@@ -138,10 +180,25 @@ function _initOptions(self, x = {}, y, options = {}) {
   return mergedOpts;
 }
 
+/**
+ * Whether a value is missing or an empty plain object.
+ * @private
+ * @param {*} obj - The value.
+ * @returns {boolean} True for a falsy value or an empty plain object.
+ */
 function isEmpty(obj) {
   return !obj || (Object.keys(obj).length === 0 && obj.constructor === Object);
 }
 
+/**
+ * Wrap plain text as a one-element list of text layout objects, the same
+ * shape htmlToTextObjects() returns.
+ * @private
+ * @param {string} text - The text.
+ * @param {number} size - The font size.
+ * @param {Object} options - The text options: font, bold and italic.
+ * @returns {Object[]} The text layout objects.
+ */
 exports._makeTextObject = function _makeTextObject(text, size, options) {
   return [
     {
@@ -162,6 +219,14 @@ exports._makeTextObject = function _makeTextObject(text, size, options) {
   ];
 };
 
+/**
+ * Build the text box from the textBox options; without them the text is
+ * simple, page-wide text.
+ * @private
+ * @param {Object} options - The text options.
+ * @returns {Object} The text box: width, height, lineHeight, padding,
+ *   minHeight, style, textAlign, clipping and wrap settings.
+ */
 exports._makeTextBox = function _makeTextBox(options) {
   return isEmpty(options.textBox)
     ? {
@@ -171,7 +236,7 @@ exports._makeTextBox = function _makeTextBox(options) {
         lineHeight: 0,
         padding: 0,
         minHeight: 0,
-        wrap: "auto",
+        wrap: TextWrap.AUTO,
       }
     : {
         width: options.textBox.width || 100,
@@ -184,7 +249,9 @@ exports._makeTextBox = function _makeTextBox(options) {
         clipIfExceedsBox: options.textBox.clipIfExceedsBox,
         onClip: options.textBox.onClip,
         wrap:
-          options.textBox.wrap !== undefined ? options.textBox.wrap : "auto",
+          options.textBox.wrap !== undefined
+            ? options.textBox.wrap
+            : TextWrap.AUTO,
       };
 };
 
@@ -195,8 +262,8 @@ exports._makeTextBox = function _makeTextBox(options) {
  * @todo support break words
  * @memberof Recipe#
  * @param {string} [text=''] - The text content
- * @param {number} x - The coordinate x
- * @param {number} y - The coordinate y
+ * @param {number|"center"|Object} [x] - The coordinate x, or the options to continue at the current position
+ * @param {number|"center"} [y] - The coordinate y
  * @param {Object} [options] - The options
  * @param {string|number[]} [options.color] - Text color (HexColor, PercentColor or DecimalColor)
  * @param {number} [options.opacity=1] - opacity
@@ -206,8 +273,8 @@ exports._makeTextBox = function _makeTextBox(options) {
  * @param {number} [options.size=14] - The font size
  * @param {number} [options.charSpace=0] - space to be added between characters, units in points.
  * @param {string} [options.align='left top'] - This is the alignment of the text in relationship to its position
- * coordinates, specified as 'horizontal vertical', where horizontal is either 'left', 'center' or 'right
- * and vertical is either 'top', 'center' or bottom.
+ * coordinates, specified as 'horizontal vertical': a `Recipe.HorizontalAlign` value, optionally followed by a
+ * space and a `Recipe.VerticalAlign` value.
  * @param {Object|Boolean} [options.highlight] - Text markup annotation.
  * @param {Object|Boolean} [options.underline] - Text markup annotation.
  * @param {Object|Boolean} [options.strikeOut] - Text markup annotation.
@@ -230,11 +297,11 @@ exports._makeTextBox = function _makeTextBox(options) {
  * @param {number} [options.textBox.minHeight=0] - Text Box minimum height
  * @param {number|number[]} [options.textBox.padding=0] - Text Box padding, [top, right, bottom, left]
  * @param {number} [options.textBox.lineHeight=0] - Text Box line height
- * @param {string|Boolean} [options.textBox.wrap='auto'] - Text wrapping mechanism, may be true, false,
- * 'auto', 'clip', 'trim', 'ellipsis'. All the option values that are not equivalent to 'auto' dictate
+ * @param {Recipe.TextWrap|Boolean} [options.textBox.wrap='auto'] - Text wrapping mechanism, may be true, false,
+ * or a `Recipe.TextWrap` value: 'auto', 'clip', 'trim', 'ellipsis'. All the option values that are not equivalent to 'auto' dictate
  *  how the text which does not fit on a line is to be truncated. True is equivalent to 'auto'. False is equivalent to 'ellipsis'.
  * @param {string} [options.textBox.textAlign='left top'] - Alignment inside text box, specified as 'horizontal vertical',
- * where horizontal is one of: 'left', 'center', 'right', 'justify' and vertical is one of: 'top', 'center', 'bottom'.
+ * where horizontal is a `Recipe.TextAlign` value and vertical a `Recipe.VerticalAlign` value.
  * @param {boolean} [options.textBox.clipIfExceedsBox=false] - Render only complete lines that fit within the text box height.
  * @param {function} [options.textBox.onClip] - Called as onClip(recipe, result) when clipping leaves text unrendered.
  * Do not call endPage() or endPDF() in this callback because the text operation is still active.
@@ -248,16 +315,31 @@ exports._makeTextBox = function _makeTextBox(options) {
  * @param {string} [options.title] - Title of annotation
  * @param {boolean} [options.open=false] - Open the annotation. Annotation will be closed by default. Specific to text annotations; subtype='Text'
  * @param {boolean} [options.richText] - Rich text in annotation
- * @param {'invisible'|'hidden'|'print'|'nozoom'|'norotate'|'noview'|'readonly'|'locked'|'togglenoview'} [options.flag] - The annotation flag.
- * @param {'Comment'|'Key'|'Note'|'Help'|'NewParagraph'|'Paragraph'|'Insert'} [options.icon='Note'] - The icon of annotation. Specific to text annotations.
+ * @param {Recipe.AnnotFlag} [options.flag] - The annotation flag, a `Recipe.AnnotFlag` value.
+ * @param {Recipe.AnnotIcon} [options.icon='Note'] - The icon of annotation, a `Recipe.AnnotIcon` value. Specific to text annotations.
  * @param {string} [options.date] - Date of text to show up on annotation
  * @param {string} [options.subject] - Subject of annotation.
- * @returns {Recipe} The recipe instance.
+ * @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 {Error} If an overflow callback names an undefined layout, or a font cannot be loaded.
  */
 exports.text = function text(text = "", x, y, options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
   if (!this.pageContext) {
     return this;
   }
+  // Validate before _initOptions moves the text position or resets the flow.
+  const rawOptions = (typeof x === "object" ? x : options) || {};
+  _validateCharSpace(rawOptions);
+  // Reject invalid markup annotations before any text is drawn.
+  for (let key in rawOptions) {
+    if (this._getTextMarkupAnnotationSubtype(key) && rawOptions[key]) {
+      const markup = typeof rawOptions[key] === "object" ? rawOptions[key] : {};
+      this._validateAnnot({ ...markup, flag: rawOptions.flag });
+    }
+  }
   options = _initOptions(this, x, y, options);
   const linkX = this.x;
   const linkY = this.y;
@@ -361,16 +443,15 @@ exports.text = function text(text = "", x, y, options = {}) {
         ? toWriteTextObjects[0].writeOptions.alignVertical
         : undefined
     ) {
-      case "center":
+      case VerticalAlign.CENTER:
         textYpos -=
           (textBox.height - textBox.textHeight) / 2 - textBox.paddingTop;
         break;
-      case "bottom":
+      case VerticalAlign.BOTTOM:
         textYpos -= textBox.height - textBox.textHeight - textBox.paddingBottom;
         break;
     }
 
-    let context = this.pageContext;
     let currentY = textYpos - textBox.paddingTop;
     let boxTop = currentY;
     let currentLineID;
@@ -379,7 +460,6 @@ exports.text = function text(text = "", x, y, options = {}) {
     let columnIndex = 1;
 
     toWriteTextObjects.some((toWriteTextObject, index) => {
-      const isHTML = toWriteTextObject.writeOptions.html;
       const { text, lineHeight, lineWidth, lineID, spaceWidth } =
         toWriteTextObject;
 
@@ -390,10 +470,10 @@ exports.text = function text(text = "", x, y, options = {}) {
         let spaceWidth = content.text.endsWith(" ") ? content.spaceWidth : 0;
         let offsetX;
         switch (content.writeOptions.alignHorizontal) {
-          case "center":
+          case TextAlign.CENTER:
             offsetX = (textBox.width - currentLineWidth) / 2;
             break;
-          case "right":
+          case TextAlign.RIGHT:
             offsetX =
               textBox.width -
               textBox.paddingRight -
@@ -413,9 +493,22 @@ exports.text = function text(text = "", x, y, options = {}) {
         if (options.underline) {
           const underlineY = y - options.textHeight * 0.1;
           const width = options.lineWidth;
+          ctx.q();
+          if (options.colorModel.xObject) {
+            this._setSeparationColor(
+              options.colorModel.xObject,
+              options.colorModel,
+              true,
+            );
+          }
           ctx
-            .q()
-            .drawPath(x, underlineY, x + width, underlineY, options)
+            .drawPath(
+              x,
+              underlineY,
+              x + width,
+              underlineY,
+              this._devicePathOptions(options),
+            )
             .Q();
         }
       };
@@ -425,9 +518,22 @@ exports.text = function text(text = "", x, y, options = {}) {
         if (options.strikeOut) {
           const strikeOutY = y + options.textHeight * 0.2;
           const width = options.lineWidth;
+          ctx.q();
+          if (options.colorModel.xObject) {
+            this._setSeparationColor(
+              options.colorModel.xObject,
+              options.colorModel,
+              true,
+            );
+          }
           ctx
-            .q()
-            .drawPath(x, strikeOutY, x + width, strikeOutY, options)
+            .drawPath(
+              x,
+              strikeOutY,
+              x + width,
+              strikeOutY,
+              this._devicePathOptions(options),
+            )
             .Q();
         }
       };
@@ -475,7 +581,7 @@ exports.text = function text(text = "", x, y, options = {}) {
         }
       };
 
-      const writeText = (context, x, y, wto) => {
+      const writeText = (x, y, wto) => {
         const options = wto.writeOptions;
         const { lineWidth, lineHeight, text, baseline } = wto;
         let next_x = 0;
@@ -484,6 +590,9 @@ exports.text = function text(text = "", x, y, options = {}) {
           // nothing to write, so simply escape.
           return next_x;
         }
+        // The opacity and rotation path below resets x to the text box edge;
+        // text-markup annotations need the line's own start.
+        const lineX = x;
 
         if (options.underline || options.strikeOut) {
           options.lineWidth = lineWidth;
@@ -498,12 +607,12 @@ exports.text = function text(text = "", x, y, options = {}) {
           // The hiliting rectangle cannot use the text box line
           // width when justification is activated because the
           // spaces between words is calculated dynamically.
-          if (options.alignHorizontal === "justify") {
+          if (options.alignHorizontal === TextAlign.JUSTIFY) {
             bxWidth = justify(nx, x, wto, textBox) - x;
 
             // Except for 'right' alignment cases, have to consider
             // text on line ending with spaces to tweak box width.
-          } else if (options.alignHorizontal !== "right") {
+          } else if (options.alignHorizontal !== TextAlign.RIGHT) {
             if (text.endsWith(" ")) {
               bxWidth += wto.spaceWidth;
             }
@@ -519,14 +628,18 @@ exports.text = function text(text = "", x, y, options = {}) {
         }
 
         // Note that the last line of a text box ignores justification.
-        const _justify = options.alignHorizontal === "justify" && !wto.lastLine;
+        const _justify =
+          options.alignHorizontal === TextAlign.JUSTIFY && !wto.lastLine;
 
         // write directly to page when not dealing with opacity, rotation and special colorspace.
         if (
           options.opacity === 1 &&
-          options.colorspace !== "separation" &&
+          options.colorspace !== Colorspace.SEPARATION &&
           (options.rotation === 0 || options.rotation === undefined)
         ) {
+          // Read the context here: a hilite rectangle or an earlier line may
+          // have paused an edited page, which resumes into a new context.
+          const context = this.pageContext;
           context.q();
 
           if (_justify) {
@@ -542,7 +655,7 @@ exports.text = function text(text = "", x, y, options = {}) {
               },
             );
           } else {
-            if (textBox.wrap !== "auto") {
+            if (textBox.wrap !== TextWrap.AUTO) {
               // This applies a clipping region around the text
               context
                 .m(nx, y + lineHeight)
@@ -607,20 +720,39 @@ exports.text = function text(text = "", x, y, options = {}) {
 
         const { textHeight } = options;
 
+        var markupLeft = lineX;
+        var markupBottom = y - textHeight * 0.2;
+        var markupWidth = _justify ? next_x - lineX : currentLineWidth;
+        var markupHeight = textHeight * 1.4;
+        if (textBox.wrap === TextWrap.CLIP) {
+          // Clipped runs retain the first overflowing word, so measure the
+          // drawn text instead of using the preceding fitting line's width.
+          var markupRight = Math.min(
+            lineX + new Word(text, options).dimensions.xMax,
+            nx + textBox.width,
+          );
+          var markupTop = Math.min(markupBottom + markupHeight, y + lineHeight);
+          markupLeft = Math.max(markupLeft, nx);
+          markupBottom = Math.max(markupBottom, y);
+          markupWidth = markupRight - markupLeft;
+          markupHeight = markupTop - markupBottom;
+          if (markupWidth <= 0 || markupHeight <= 0) return next_x;
+        }
+
         for (let key in targetAnnotations) {
           const subtype = this._getTextMarkupAnnotationSubtype(key);
-          if (subtype) {
+          if (subtype && targetAnnotations[key]) {
+            // Copy so the caller's markup options are not modified.
             const markupOption =
               typeof targetAnnotations[key] != "object"
                 ? {}
-                : targetAnnotations[key];
+                : { ...targetAnnotations[key] };
             const { title, open, richText, flag, icon, date, subject } =
               targetAnnotations;
             Object.assign(markupOption, {
-              height: textHeight * 1.4,
-              width: currentLineWidth,
+              height: markupHeight,
+              width: markupWidth,
               text: markupOption.text || "",
-              _textHeight: textHeight,
               // add options to annotation
               title: title || "",
               open: Boolean(open),
@@ -630,7 +762,11 @@ exports.text = function text(text = "", x, y, options = {}) {
               date: date || "",
               subject: subject || "",
             });
-            const { ox, oy } = this._reverseCoordinate(x, y - textHeight * 0.2);
+            // annot() takes the rectangle's top-left corner.
+            const { ox, oy } = this._reverseCoordinate(
+              markupLeft,
+              markupBottom + markupHeight,
+            );
 
             this.annot(ox, oy, subtype, markupOption);
           }
@@ -639,22 +775,37 @@ exports.text = function text(text = "", x, y, options = {}) {
         return next_x;
       };
 
+      /** Queues a text link limited to the run's visible clipping region. */
+      var queueTextLink = function (content, x, y, nextX) {
+        if (!content.writeOptions.link) return;
+        var left = x;
+        var width = nextX ? nextX - x : content.lineWidth;
+        if (textBox.wrap === TextWrap.CLIP) {
+          var right = Math.min(
+            x + new Word(content.text, content.writeOptions).dimensions.xMax,
+            nx + textBox.width,
+          );
+          left = Math.max(left, nx);
+          width = right - left;
+          if (width <= 0) return;
+        }
+        linkAnnotations.push({
+          url: content.writeOptions.link,
+          left,
+          bottom: y,
+          width,
+          height: content.lineHeight,
+        });
+      };
+
       if (!isContinued) {
         // flush out current line before processing next one
         let next_x = 0;
         toWriteContents.forEach((content) => {
           const x = next_x || getStartX(content.startX, content);
           const y = currentY;
-          next_x = writeText(context, x, y, content);
-          if (content.writeOptions.link) {
-            linkAnnotations.push({
-              url: content.writeOptions.link,
-              left: x,
-              bottom: y,
-              width: next_x ? next_x - x : content.lineWidth,
-              height: content.lineHeight,
-            });
-          }
+          next_x = writeText(x, y, content);
+          queueTextLink(content, x, y, next_x);
         });
         // The line offset from the last line in the
         // group determines Y positioning for next line.
@@ -683,6 +834,7 @@ exports.text = function text(text = "", x, y, options = {}) {
         }
 
         if (overflow && this._overflowNotifier) {
+          flushTextLinks(this, linkAnnotations);
           let orders = this._overflowNotifier(this);
           if (orders === true) {
             return true; // stop processing remaining text.
@@ -710,7 +862,6 @@ exports.text = function text(text = "", x, y, options = {}) {
             updateTextBox(this._columns[columnIndex - 1]);
             updateVertical = false;
           }
-          context = this.pageContext; // in case user changed page
         }
 
         if (updateVertical) {
@@ -723,18 +874,16 @@ exports.text = function text(text = "", x, y, options = {}) {
 
       const startX = nx + currentLineWidth;
 
-      // This text will only ever have this strange tag when the
-      // HTML option is being used and an explicit linebreak encountered.
-      if (text != "[@@DONOT_RENDER_THIS@@]") {
-        toWriteTextObject.startX = toWriteTextObject.startX || startX;
-        toWriteContents.push(toWriteTextObject);
-      }
+      toWriteTextObject.startX = toWriteTextObject.startX || startX;
+      toWriteContents.push(toWriteTextObject);
 
       // To handle text that has been split in middle of word,
-      // need to decide if current text ends with a space.
+      // need to decide if current text ends with a space. HTML segments carry
+      // their own separating space, so adding one unconditionally in HTML mode
+      // measured every line a space wider than it is drawn and pushed aligned
+      // lines left.
       currentLineWidth +=
-        lineWidth +
-        (isHTML || toWriteTextObject.text.endsWith(" ") ? spaceWidth : 0);
+        lineWidth + (toWriteTextObject.text.endsWith(" ") ? spaceWidth : 0);
 
       // Processing last text object?
       if (index === toWriteTextObjects.length - 1) {
@@ -752,16 +901,8 @@ exports.text = function text(text = "", x, y, options = {}) {
           const content = toWriteContents[ii];
           const x = next_x || getStartX(content.startX, content);
           const y = currentY;
-          next_x = writeText(context, x, y, content);
-          if (content.writeOptions.link) {
-            linkAnnotations.push({
-              url: content.writeOptions.link,
-              left: x,
-              bottom: y,
-              width: next_x ? next_x - x : content.lineWidth,
-              height: content.lineHeight,
-            });
-          }
+          next_x = writeText(x, y, content);
+          queueTextLink(content, x, y, next_x);
         }
 
         // Flush any left over text objects.
@@ -772,31 +913,56 @@ exports.text = function text(text = "", x, y, options = {}) {
     });
 
     if (clipResult && typeof textBox.onClip === "function") {
-      // The active text operation owns the page context until it returns.
+      // The callback may finish the page or start drawing on another one.
+      flushTextLinks(this, linkAnnotations);
       textBox.onClip(this, clipResult);
     }
   }
 
-  linkAnnotations.forEach((annotation) => {
+  flushTextLinks(this, linkAnnotations);
+  return this;
+};
+
+/**
+ * Write pending text links before a callback can change the active page.
+ * @private
+ * @param {Recipe} recipe - The recipe instance.
+ * @param {Object[]} annotations - Pending {url, left, bottom, width, height}
+ *   links; emptied.
+ * @returns {void}
+ */
+function flushTextLinks(recipe, annotations) {
+  for (var annotation of annotations.splice(0)) {
     linkPdf(
-      this,
+      recipe,
       annotation.url,
       annotation.left,
       annotation.bottom,
       annotation.width,
       annotation.height,
     );
-  });
-  return this;
-};
+  }
+}
 
+/**
+ * Lay out text objects in a text box: resolve padding and wrap, walk HTML
+ * children (list bullets, numbering and indentation), split them into lines
+ * and turn line breaks into line state.
+ * @private
+ * @param {Object[]} textObjects - The text layout objects.
+ * @param {Object} textBox - The text box; wrap and padding are normalized in place.
+ * @param {Object} pathOptions - The resolved text options.
+ * @returns {{toWriteTextObjects: Object[], textHeight: number}} The laid-out
+ *   runs and the total text height.
+ * @throws {Error} If a font cannot be loaded.
+ */
 exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
   let totalHeight = 0;
   // allow user to treat wrap as boolean
   if (textBox.wrap === true) {
-    textBox.wrap = "auto";
+    textBox.wrap = TextWrap.AUTO;
   } else if (textBox.wrap === false) {
-    textBox.wrap = "ellipsis";
+    textBox.wrap = TextWrap.ELLIPSIS;
   }
 
   // Allows user to enter a single number which will be used for all text box sides,
@@ -831,19 +997,52 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
 
   let firstLineHeight;
   let toWriteTextObjects = [];
-  /** Reports whether a layout node contains content other than the break sentinel. */
+  /** Reports whether a layout node contains text, not only line breaks. */
   const hasRenderableContent = (textObject) =>
     (textObject.value !== undefined &&
       textObject.value !== null &&
-      textObject.value !== "" &&
-      textObject.value !== "[@@DONOT_RENDER_THIS@@]") ||
+      textObject.value !== "") ||
     textObject.childs?.some(hasRenderableContent);
 
+  /** Adds laid-out objects, recording the first line height. */
+  const addLaidOutObjects = (newToWriteObjects, paragraphHeight) => {
+    toWriteTextObjects = [...toWriteTextObjects, ...newToWriteObjects];
+
+    if (!firstLineHeight) {
+      this._lineHeight = firstLineHeight = toWriteTextObjects[0].lineHeight;
+      if (!this._firstLineHeight) {
+        this._firstLineHeight = this._lineHeight; // used in textbox coordinate computation
+      }
+    }
+    totalHeight += paragraphHeight;
+  };
+
   const writeValue = (textObject) => {
     textObject.lineID = textObject.lineID || Date.now() * Math.random();
-    textObject.lineID = textObject.needsLineBreaker
-      ? Date.now() * Math.random()
-      : textObject.lineID;
+    textObject.lineID =
+      textObject.needsLineBreaker || textObject.lineBreak
+        ? Date.now() * Math.random()
+        : textObject.lineID;
+    if (textObject.lineBreak) {
+      // A line break lays out as one empty line sized like its text; the
+      // normalization below turns it into line state, never into text.
+      const { toWriteTextObjects: newToWriteObjects, paragraphHeight } =
+        makeTextObjects(
+          this,
+          Object.assign({}, textObject, { value: "" }),
+          pathOptions,
+          textBox,
+        );
+      const lineBreak = newToWriteObjects[newToWriteObjects.length - 1];
+      lineBreak.lineBreak = true;
+      // Flowed text marks the last word of the previous line, so an empty
+      // break line still carries one empty word.
+      if (!lineBreak.wordsInLine.length) {
+        lineBreak.wordsInLine.push(new Word("", pathOptions));
+      }
+      addLaidOutObjects(newToWriteObjects, paragraphHeight);
+      return;
+    }
     // Want to allow empty string to pass through. Undefined and null elements, stay out!
     if (textObject.value !== undefined && textObject.value !== null) {
       textObject.styles.color = textObject.styles.color
@@ -851,16 +1050,7 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
         : pathOptions.color;
       const { toWriteTextObjects: newToWriteObjects, paragraphHeight } =
         makeTextObjects(this, textObject, pathOptions, textBox);
-
-      toWriteTextObjects = [...toWriteTextObjects, ...newToWriteObjects];
-
-      if (!firstLineHeight) {
-        this._lineHeight = firstLineHeight = toWriteTextObjects[0].lineHeight;
-        if (!this._firstLineHeight) {
-          this._firstLineHeight = this._lineHeight; // used in textbox coordinate computation
-        }
-      }
-      totalHeight += paragraphHeight;
+      addLaidOutObjects(newToWriteObjects, paragraphHeight);
     }
     if (textObject.tag && textObject.childs.length) {
       // console.log(textObject);
@@ -874,34 +1064,36 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
       textObject.currentIndex = 0;
       let prependValue = textObject.prependValue;
 
+      const tag = (textObject.tag || "").toLowerCase();
       textObject.childs.forEach((child) => {
-        if (textObject.tag == "ul") {
+        const childTag = (child.tag || "").toLowerCase();
+        if (tag === HtmlTag.UL) {
           child.prependValue = "* ";
           child.layer = textObject.layer + 1;
           // child.indent = 4 * child.layer;
         }
-        if (textObject.tag == "ol") {
-          if (child.tag != "ol") {
+        if (tag === HtmlTag.OL) {
+          if (childTag !== HtmlTag.OL) {
             textObject.currentIndex++;
             child.prependValue = `${textObject.currentIndex.toString()}. `;
           }
           child.layer = textObject.layer + 1;
           // child.indent = 4 * child.layer;
         }
-        if (textObject.tag == "li") {
-          if (child.tag == "ol" || child.tag == "ul") {
+        if (tag === HtmlTag.LI) {
+          if (childTag === HtmlTag.OL || childTag === HtmlTag.UL) {
             child.layer = textObject.layer - 1;
           }
         }
         if (
           prependValue &&
-          !["ol", "ul"].includes(child.tag) &&
+          ![HtmlTag.OL, HtmlTag.UL].includes(childTag) &&
           hasRenderableContent(child)
         ) {
           child.prependValue = prependValue;
           prependValue = null;
           textObject.indent =
-            textObject.tag == "li"
+            tag === HtmlTag.LI
               ? 2 * textObject.layer
               : textObject.indent || 2 * textObject.layer;
         }
@@ -931,14 +1123,18 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
       });
     }
   };
+  // Top-level nodes share a line, as children of a block element do, so
+  // inline runs outside any element are not split onto separate lines.
+  const topLevelLineID = Date.now() * Math.random();
   textObjects.forEach((textObject) => {
+    textObject.lineID = textObject.lineID || topLevelLineID;
     writeValue(textObject);
   });
 
   const normalizedTextObjects = [];
   let pendingBreaks = [];
   const replacementLineIDs = new Map();
-  /** Converts pending break sentinels into line state without rendering their text. */
+  /** Converts pending line breaks into line state: blank lines and line IDs. */
   const appendPendingBreaks = (nextTextObject) => {
     const previous = normalizedTextObjects[normalizedTextObjects.length - 1];
     if (previous) previous.lineComplete = true;
@@ -963,12 +1159,13 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
     pendingBreaks = [];
   };
   toWriteTextObjects.forEach((textObject, index, objects) => {
-    const sentinel = textObject.text.trim() == "[@@DONOT_RENDER_THIS@@]";
-    const beforeSentinel =
+    // Whitespace that only precedes a line break would start a blank line.
+    const beforeLineBreak =
+      !textObject.lineBreak &&
       textObject.text.trim() == "" &&
-      objects[index + 1]?.text.trim() == "[@@DONOT_RENDER_THIS@@]";
-    if (beforeSentinel) return;
-    if (sentinel) {
+      objects[index + 1]?.lineBreak;
+    if (beforeLineBreak) return;
+    if (textObject.lineBreak) {
       pendingBreaks.push(textObject);
       return;
     }
@@ -986,6 +1183,13 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
   };
 };
 
+/**
+ * The height of laid-out text: the sum of the line heights, counting each
+ * line once.
+ * @private
+ * @param {Object[]} textObjs - The laid-out runs.
+ * @returns {number} The text height.
+ */
 function getTextBoxHeight(textObjs) {
   let previousLineID;
   let height = 0;
@@ -1009,6 +1213,15 @@ function getTextBoxHeight(textObjs) {
   return height;
 }
 
+/**
+ * Keep the complete lines that fit a height.
+ * @private
+ * @param {Object[]} textObjs - The laid-out runs.
+ * @param {number} availableHeight - The height available for text.
+ * @returns {{textObjects: Object[], linesWritten: number, clipped: boolean,
+ *   remainder: string}} The fitting runs, their line count, whether lines were
+ *   dropped, and the dropped text with its line breaks.
+ */
 function clipTextToBox(textObjs, availableHeight) {
   const lines = [];
   let line = [];
@@ -1053,6 +1266,15 @@ function clipTextToBox(textObjs, availableHeight) {
   };
 }
 
+/**
+ * The PDF position of a text box, after its alignment offset.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {Object} textBox - The laid-out text box.
+ * @param {Object} pathOptions - The resolved text options.
+ * @returns {number[]} The [x, y] PDF position.
+ * @throws {TypeError} If no page is active.
+ */
 function getTextBoxPosition(self, textBox, pathOptions) {
   const { offsetX, offsetY } = self._getTextBoxOffset(textBox, pathOptions);
   const { nx, ny } = self._calibrateCoordinate(
@@ -1064,6 +1286,16 @@ function getTextBoxPosition(self, textBox, pathOptions) {
   return [nx, ny];
 }
 
+/**
+ * Draw the text box border and background from its style.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {number} nx - The PDF x of the box.
+ * @param {number} ny - The PDF y of the first line.
+ * @param {Object} textBox - The laid-out text box with its style.
+ * @param {Object} pathOptions - The resolved text options, for rotation.
+ * @returns {void}
+ */
 function drawTextBox(self, nx, ny, textBox, pathOptions) {
   const textBoxWidth = textBox.width; //+ textBox.paddingLeft + textBox.paddingRight;
   let borderRadius = textBox.style ? textBox.style.borderRadius : 0;
@@ -1093,6 +1325,7 @@ function drawTextBox(self, nx, ny, textBox, pathOptions) {
  * @param {Object[]} wto is a write object
  * @param {Object} textBox holds text box properties
  * @param {Function} [position] used to place given word at a postion on the line
+ * @returns {number} The x where the next run on the line starts.
  */
 function justify(left, x, wto, textBox, position) {
   // For some reason, textWidth is smaller than lineWidth. My suspicions lie in the fact
@@ -1149,6 +1382,15 @@ function justify(left, x, wto, textBox, position) {
   return word.value.endsWith(" ") ? x : x - spaceBetweenWords;
 }
 
+/**
+ * The word between the previous break and the next one.
+ * @private
+ * @param {string} text - The text being broken.
+ * @param {Object} brk - The line break opportunity: position and required.
+ * @param {number} previousPosition - The position of the previous break.
+ * @param {Object} pathOptions - The resolved text options.
+ * @returns {Word} The word; trimmed at a required break.
+ */
 function nextWord(text, brk, previousPosition, pathOptions) {
   let nextWord = text.slice(previousPosition, brk.position);
 
@@ -1160,10 +1402,21 @@ function nextWord(text, brk, previousPosition, pathOptions) {
   return new Word(nextWord, pathOptions);
 }
 
+/**
+ * Handle the first word that does not fit a line when wrapping is off: CLIP
+ * keeps it for the clipping region, ELLIPSIS shortens it with "…", and TRIM
+ * drops it.
+ * @private
+ * @param {Object} textBox - The text box with its wrap mode.
+ * @param {Line} line - The full line; updated in place.
+ * @param {Word} word - The word that did not fit.
+ * @param {Object} pathOptions - The resolved text options.
+ * @returns {void}
+ */
 function elideNonFittingText(textBox, line, word, pathOptions) {
-  if (textBox.wrap === "clip") {
+  if (textBox.wrap === TextWrap.CLIP) {
     line.addWord(word);
-  } else if (textBox.wrap === "ellipsis") {
+  } else if (textBox.wrap === TextWrap.ELLIPSIS) {
     // This is more complicated than the other no-wrap options.
     // It makes an initial attempt to take the word that was
     // too big and make it shrink in size until it and the
@@ -1194,6 +1447,17 @@ function elideNonFittingText(textBox, line, word, pathOptions) {
   }
 }
 
+/**
+ * Turn a finished line into a laid-out run and record the line.
+ * @private
+ * @param {Line[]} lines - The finished lines; the line is appended.
+ * @param {Line} line - The line.
+ * @param {number} lineID - The ID tying the first HTML line to its group.
+ * @param {Object} textBox - The laid-out text box.
+ * @param {Object} [options] - html, lastLine, lineComplete, wordCount,
+ *   totalTextWidth and writeOptions.
+ * @returns {Object} The run: text, line metrics and justification data.
+ */
 function makeTextObject(lines, line, lineID, textBox, options = {}) {
   const lineHeight = line.height;
   const spaceSz =
@@ -1230,6 +1494,15 @@ function makeTextObject(lines, line, lineID, textBox, options = {}) {
   };
 }
 
+/**
+ * Carry justification totals across runs that share a line.
+ * @private
+ * @param {Line} line - The line being finished.
+ * @param {Object[]} textObjects - The runs laid out so far; updated in place.
+ * @param {number} wordCount - The words counted so far on the line.
+ * @param {number} totalTextWidth - The text width counted so far on the line.
+ * @returns {number[]} The updated [wordCount, totalTextWidth].
+ */
 function bindTextToLine(line, textObjects, wordCount, totalTextWidth) {
   // Apply justification information to previous text objects.
   if (wordCount > 0) {
@@ -1267,6 +1540,18 @@ function bindTextToLine(line, textObjects, wordCount, totalTextWidth) {
   return [wordCount, totalTextWidth];
 }
 
+/**
+ * Break one text layout object into lines that fit the text box, continuing
+ * any unfinished flowed lines.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {Object} [textObject] - The text layout object.
+ * @param {Object} pathOptions - The resolved text options.
+ * @param {Object} [textBox] - The text box; line and baseline heights are set in place.
+ * @returns {{toWriteTextObjects: Object[], paragraphHeight: number}} The runs,
+ *   including the carried-over flowed ones, and the paragraph height.
+ * @throws {Error} If the font cannot be loaded.
+ */
 function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
   const toWriteTextObjects = [...self._previousTextObjects];
   let text =
@@ -1297,7 +1582,8 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
     opacity: parseFloat(textObject.styles.opacity || pathOptions.opacity || 1),
     underline: textObject.underline || pathOptions.underline,
     strikeOut: textObject.strikeOut || pathOptions.strikeOut,
-    size: textObject.size,
+    // Text outside any HTML element has no inherited size of its own.
+    size: size,
     alignHorizontal: alignHorizontal,
     alignVertical: alignVertical,
     font: self._getFont(textObject),
@@ -1339,7 +1625,7 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
     const previousLine = toWriteTextObjects[end];
     let lineComplete, fini;
 
-    if (text === "" && !self._flow) {
+    if (text === "" && !self._flow && !textObject.lineBreak) {
       // turning off flow with empty text so
       previousLine.lastLine = true; // need to make previous line, the last.
     }
@@ -1396,7 +1682,7 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
         }
       } else {
         // remove any trailing space on previous word so right justification works appropriately
-        if (previousWord && textBox.wrap === "auto") {
+        if (previousWord && textBox.wrap === TextWrap.AUTO) {
           newLine.replaceLastWord(previousWord.value.trim());
         }
 
@@ -1425,7 +1711,7 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
       }
 
       // now deal with text line wrap (what happens to text that doesn't fit in line)
-      if (textBox.wrap !== "auto") {
+      if (textBox.wrap !== TextWrap.AUTO) {
         flushLine = true;
         elideNonFittingText(textBox, newLine, word, pathOptions);
 
@@ -1499,7 +1785,7 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
     }
   }
 
-  let isLastLine = alignHorizontal === "justify" && !self._flow;
+  let isLastLine = alignHorizontal === TextAlign.JUSTIFY && !self._flow;
 
   if (!flushLine) {
     [wordCount, totalTextWidth] = bindTextToLine(
@@ -1535,6 +1821,14 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
   };
 }
 
+/**
+ * Mark the last run as ending its line: trim it, mark its last word and
+ * optionally move the next line down.
+ * @private
+ * @param {Object[]} toWriteTextObjects - The runs; the last one is updated.
+ * @param {number|null} [lines=null] - The line offset for the next line.
+ * @returns {void}
+ */
 function markLineComplete(toWriteTextObjects, lines = null) {
   // Get last element in text objects and mark it.
   const textObj = toWriteTextObjects[toWriteTextObjects.length - 1];
@@ -1560,8 +1854,9 @@ function markLineComplete(toWriteTextObjects, lines = null) {
 exports.movedown = function movedown(lines = 1, returnCoords = false) {
   if (!this._flow || this._previousTextObjects.length === 0) {
     this._previousTextObjects = [];
-    this.y += this._lineHeight * lines;
-    this.x = this.box.x;
+    // Before any text is written there is no cursor or line height yet.
+    this.y = (this.y || 0) + (this._lineHeight || 14) * lines;
+    this.x = this.box ? this.box.x : this.x || 0;
   } else {
     // This handles continuous text positioning
     markLineComplete(this._previousTextObjects, lines);
@@ -1572,6 +1867,15 @@ exports.movedown = function movedown(lines = 1, returnCoords = false) {
   return returnCoords ? [this.x, this.y] : this;
 };
 
+/**
+ * Move a column layout so its first column starts at a point, keeping the
+ * column spacing.
+ * @private
+ * @param {Column[]} columns - The layout columns; updated in place.
+ * @param {number} x - The new x of the first column.
+ * @param {number} y - The new y of the first column.
+ * @returns {void}
+ */
 function adjustcolumnPosition(columns, x, y) {
   const ydiff = y - columns[0].y;
   for (const column of columns) {
@@ -1586,16 +1890,17 @@ function adjustcolumnPosition(columns, x, y) {
  * @function
  * @memberof Recipe#
  * @param {number|string} id - The identifier to be associated with the layout. (See 'text' layout option)
- * @param {number} x - The coordinate x used to position text columns on page. When zero, left margin used.
- * @param {number} y - The coordinate y used to position text columns on page. When zero, top margin used.
- * @param {number} width - The width of a text column. When zero, space between left and right margin used.
- * @param {number} height - The height of a text column. When zero, space between top and bottom margin used.
+ * @param {number} [x] - The coordinate x used to position text columns on page. When zero or omitted, left margin used.
+ * @param {number} [y] - The coordinate y used to position text columns on page. When zero or omitted, top margin used.
+ * @param {number} [width] - The width of a text column. When zero or omitted, space between left and right margin used.
+ * @param {number} [height] - The height of a text column. When zero or omitted, space between top and bottom margin used.
  * @param {object} [options] - The options.
  * @param {number} [options.columns] - Represents the number of columns in which to divide the given width.
  * @param {number} [options.gap=18] - Defines the separation between layout columns, units in points.
  * @param {boolean} [options.reset] - True indicates that the a new layout should be produced for the given
  * layout id, so any previous layout associated with the given id will be lost.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If width or height is omitted while no page is active.
  */
 exports.layout = function layout(id, x, y, width, height, options = {}) {
   this._layouts = this._layouts || {};