@pacem/pacem 1.0.0-bessel → 1.0.0-dirac

package/dist/browser/pacem-foundation.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -41,7 +41,14 @@
 
     //namespace Pacem {
     const JSON_DATE_PATTERN = /^\/Date\([\d]+\)\/$/i;
+    /** Date parsing and arithmetic utilities. */
     class Dates {
+        /**
+         * Parses a value into a `Date`. Accepts ISO/parseable date strings, ASP.NET-style
+         * `/Date(ticks)/` JSON date strings, numeric timestamps, or a `Date` instance (returned as-is).
+         * @param input Value to parse.
+         * @returns The resulting `Date`.
+         */
         static parse(input) {
             let d;
             if (typeof input === 'string') {
@@ -57,9 +64,19 @@
             else
                 return input;
         }
+        /**
+         * Gets whether the given year is a leap year.
+         * @param year Year to check.
+         */
         static isLeapYear(year) {
             return (((year % 4 === 0) && (year % 100 !== 0)) || (year % 400 === 0));
         }
+        /**
+         * Gets the number of days in a given month of a given year.
+         * @param year Year (used to account for leap Februaries).
+         * @param month Zero-based month index (0 = January, ..., 11 = December).
+         * @returns Number of days in the month.
+         */
         static daysInMonth(year, month) {
             return [31, (Dates.isLeapYear(year) ? 29 : 28), 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month];
         }
@@ -77,6 +94,13 @@
         static dateOnly(datetime) {
             return new Date(datetime.getFullYear(), datetime.getMonth(), datetime.getDate());
         }
+        /**
+         * Returns a new date obtained by adding a (possibly negative) number of months to `input`,
+         * clamping the day-of-month to the target month's length (e.g. Jan 31 + 1 month => Feb 28/29).
+         * @param input Starting date.
+         * @param value Number of months to add.
+         * @returns The resulting date.
+         */
         static addMonths(input, value) {
             let n = input.getDate(), i = new Date(input), month = i.getMonth() + value, years = 0;
             while (month < 0) {
@@ -89,9 +113,21 @@
             i.setDate(Math.min(n, Dates.daysInMonth(i.getFullYear(), i.getMonth())));
             return i;
         }
+        /**
+         * Returns a new date obtained by adding a (possibly negative) number of days to `input`.
+         * @param input Starting date.
+         * @param value Number of days to add.
+         * @returns The resulting date.
+         */
         static addDays(input, value) {
             return new Date(input.valueOf() + value * 86400000);
         }
+        /**
+         * Computes the number of days (possibly fractional) between two dates.
+         * @param start Start date.
+         * @param end End date.
+         * @returns Number of days between `start` and `end` (negative if `end` precedes `start`).
+         */
         static daysBetween(start, end) {
             return (end.valueOf() - start.valueOf()) / 86400000;
         }
@@ -100,10 +136,21 @@
 
     /// <reference path="dates.ts" />
     // namespace Pacem {
+    /** Null/empty value-checking utilities. */
     class NullChecker {
+        /**
+         * Returns whether the given value is `null` or `undefined`.
+         * @param o Value to check.
+         */
         static isNull(o) {
             return o === null || o === void 0;
         }
+        /**
+         * Returns whether the given value is "empty": an empty array, an empty string, or a
+         * plain object with no own enumerable keys (dates, regexes and file-system handles are never
+         * considered empty).
+         * @param o Value to check.
+         */
         static isEmpty(o) {
             try {
                 return (Array.isArray(o) && o.length === 0)
@@ -115,6 +162,10 @@
                 return false;
             }
         }
+        /**
+         * Returns whether the given value is `null`, `undefined`, or "empty" (see {@link NullChecker.isEmpty}).
+         * @param o Value to check.
+         */
         static isNullOrEmpty(o) {
             return NullChecker.isNull(o) || NullChecker.isEmpty(o);
         }
@@ -209,9 +260,18 @@
         }
         return output;
     }
+    /** Deep-merging utility for plain objects. */
     class DeepMerger {
         constructor() {
         }
+        /**
+         * Recursively merges `source` into `target`, in place: plain-object properties are merged
+         * recursively (into a fresh object, never adopted by reference), arrays are shallow-copied,
+         * and any other value overwrites the target's.
+         * @param source Object whose properties are merged into `target`.
+         * @param target Object to merge into (defaults to, and lazily creates, the global `Pacem` namespace object).
+         * @returns The mutated `target`, typed as the union of both inputs.
+         */
         static merge(source, target) {
             target ??= (globalThis['Pacem'] ??= {});
             return deepMerge(target, source);
@@ -219,6 +279,7 @@
     }
 
     //namespace Pacem {
+    /** Array manipulation utilities. */
     class Arrays {
         static range(min, max, items = 2) {
             let x = min;
@@ -237,6 +298,12 @@
             }
             return output;
         }
+        /**
+         * Splits an array into chunks of a given size.
+         * @param source Array to split.
+         * @param size Maximum size of each chunk (must be a positive integer).
+         * @returns Array of chunks; an empty array if `source` is null or empty.
+         */
         static chunkify(source, size) {
             if (NullChecker.isNullOrEmpty(source)) {
                 return [];
@@ -254,7 +321,13 @@
     //}
 
     //namespace Pacem {
+    /** Conversion utilities between `Blob`, base64/data URLs and plain text. */
     class Blobs {
+        /**
+         * Reads a `Blob` and resolves it as a base64-encoded data URL.
+         * @param blob Blob to read.
+         * @returns A promise resolving with the data URL string.
+         */
         static blobToDataURL(blob) {
             return new Promise((resolve, _) => {
                 const a = new FileReader();
@@ -270,10 +343,21 @@
             }
             return u8arr;
         }
+        /**
+         * Converts a base64-encoded string into a `Blob`.
+         * @param bstr Base64-encoded string (without the `data:...;base64,` prefix).
+         * @param options Blob options (e.g. MIME `type`).
+         * @returns The resulting `Blob`.
+         */
         static base64ToBlob(bstr, options) {
             const u8arr = Blobs._b64ToUint8Array(atob(bstr));
             return new Blob([u8arr], options);
         }
+        /**
+         * Converts a data URL (`data:<mime>;base64,<data>`) into a `Blob`, inferring the MIME type when present.
+         * @param dataurl Data URL to convert.
+         * @returns The resulting `Blob`.
+         */
         static dataURLToBlob(dataurl) {
             const coma = dataurl.indexOf(',');
             if (coma === -1) {
@@ -285,6 +369,12 @@
                 return Blobs.base64ToBlob(bstr, { type: mime });
             }
         }
+        /**
+         * Reads a `Blob` and decodes it as text.
+         * @param blob Blob to read.
+         * @param encoding Text encoding to use for decoding (defaults to the platform's default, typically UTF-8).
+         * @returns A promise resolving with the decoded text.
+         */
         static async blobToText(blob, encoding) {
             const buffer = await blob.arrayBuffer();
             const decoder = new TextDecoder(encoding, { fatal: false });
@@ -371,6 +461,11 @@
         return match ? match[2] : null;
     };
     // https://stackoverflow.com/77095874
+    /**
+     * Detects the browser name and version from a user-agent string.
+     * @param userAgent User-agent string to parse (defaults to `navigator.userAgent`).
+     * @returns An object with the detected browser `name` (e.g. `Chrome`, `Firefox`, `Safari`, `Edge`, `IE`, `unknown`, ...) and its `version`.
+     */
     function detect(userAgent = navigator.userAgent) {
         let browser = 'unknown';
         let version = null;
@@ -569,9 +664,13 @@
         return v.toString(16).padStart(2, '0');
         //return Pacem.Strings.leftPad(v.toString(16), 2, '0');
     }
+    /** Color parsing, conversion (RGB/HSL/CIE XYZ) and manipulation utilities. */
     class Colors {
+        /** Minimum WCAG contrast ratio recommended for large-scale text/graphical objects. */
         static { this.WCAG_MINIMUM_CONTRAST = 3.0; }
+        /** Minimum WCAG (AA) contrast ratio recommended for normal-sized text. */
         static { this.WCAG_NORMAL_TEXT_CONTRAST = 4.5; }
+        /** Minimum WCAG (AAA) contrast ratio recommended for enhanced accessibility. */
         static { this.WCAG_SAFE_CONTRAST = 7.0; }
         static _clampRGB(rgb) {
             const clmp = (n) => Math.min(1.0, Math.max(0, n));
@@ -583,6 +682,11 @@
         static _normalize(rgb) {
             return [rgb[0] / 255.0, rgb[1] / 255.0, rgb[2] / 255.0, rgb[3]];
         }
+        /**
+         * Parses a CSS color string (`rgb()`, `rgba()`, `#rrggbb`, `#rgb`, `hsl()` or `hsla()`) into an {@link Rgba} value.
+         * @param clr CSS color string.
+         * @returns The parsed color, or `undefined` if the string does not match any supported format.
+         */
         static parse(clr) {
             clr = (clr || '').toLowerCase();
             /* rgb(255,255,255) */
@@ -619,6 +723,11 @@
                 return this.rgb(hsla);
             }
         }
+        /**
+         * Converts an {@link Rgba} color into its {@link Hsla} equivalent.
+         * @param rgb Color to convert.
+         * @returns The converted color.
+         */
         static hsl(rgb) {
             const l = luminance(rgb), s = saturation(rgb, l), h = hueCircle(rgb);
             return { h, s, l, a: rgb.a };
@@ -767,6 +876,11 @@
 
     // 1.7763568394002505e-15 -20.4551920341394 40 40
     const FLOAT_PATTERN = /[-+]?([\d]+(\.[\d]+(e-[\d]+)?)?|[\d]*(\.[\d]+(e-[\d]+)?))/g;
+    /**
+     * Extracts all the floating point numbers found in a string (e.g. `"10px 20px"` => `[10, 20]`).
+     * @param input String to parse.
+     * @returns Array of the numbers found, in order of appearance.
+     */
     function parseAsNumericalArray(input) {
         const arr = [];
         let reg = input.match(FLOAT_PATTERN);
@@ -775,7 +889,12 @@
         }
         return arr;
     }
+    /** Angle-related utilities. */
     class Angle {
+        /**
+         * Type-guards a value as a valid {@link Angle} object.
+         * @param obj Value to check.
+         */
         static isAngle(obj) {
             return typeof obj === 'object'
                 && 'vertex' in obj && Point.isPoint(obj['vertex'])
@@ -809,7 +928,14 @@
             return -Math.atan2(cross, dot);
         }
     }
+    /** Size-related utilities. */
     class Size {
+        /**
+         * Parses a string containing exactly two numbers into a {@link Size}.
+         * @param sz String to parse (e.g. `"100 50"`).
+         * @returns The parsed size.
+         * @throws If `sz` does not contain exactly two numbers.
+         */
         static parse(sz) {
             let arr = parseAsNumericalArray(sz);
             if (arr && arr.length === 2) {
@@ -817,13 +943,24 @@
             }
             throw new Error(`Cannot parse "${sz}" as a valid Size.`);
         }
+        /**
+         * Type-guards a value as a valid {@link Size} object.
+         * @param obj Value to check.
+         */
         static isSize(obj) {
             return typeof obj === 'object'
                 && 'width' in obj && typeof obj['width'] === 'number'
                 && 'height' in obj && typeof obj['height'] === 'number';
         }
     }
+    /** Point-related utilities. */
     class Point {
+        /**
+         * Parses a string containing exactly two numbers into a {@link Point}.
+         * @param pt String to parse (e.g. `"10 20"`).
+         * @returns The parsed point.
+         * @throws If `pt` does not contain exactly two numbers.
+         */
         static parse(pt) {
             let arr = parseAsNumericalArray(pt);
             if (arr && arr.length === 2) {
@@ -831,6 +968,10 @@
             }
             throw new Error(`Cannot parse "${pt}" as a valid Point.`);
         }
+        /**
+         * Type-guards a value as a valid {@link Point} object.
+         * @param obj Value to check.
+         */
         static isPoint(obj) {
             return typeof obj === 'object'
                 && 'x' in obj && typeof obj['x'] === 'number'
@@ -877,22 +1018,42 @@
     //}
 
     /// <reference path="geom.ts" />
+    /** 2D affine matrix ([a b; c d] linear part, [e f] translation) manipulation utilities. */
     class Matrix2D {
+        /**
+         * Returns whether the given matrix is the identity matrix.
+         * @param m Matrix to check.
+         */
         static isIdentity(m) {
             return m.a === 1 && m.d === 1 && m.b === 0 && m.f === 0 && m.c === 0 && m.e === 0;
         }
+        /** Gets a fresh identity matrix. @readonly */
         static get identity() {
             return { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
         }
+        /**
+         * Returns a shallow copy of the given matrix.
+         * @param m Matrix to copy.
+         */
         static copy(m) {
             return { a: m.a, b: m.b, c: m.c, d: m.d, e: m.e, f: m.f };
         }
         static scale(m, sx, sy = sx) {
             return { a: m.a * sx, b: m.b, c: m.c, d: m.d * sy, e: m.e, f: m.f };
         }
+        /**
+         * Returns a copy of `m` translated by the given vector.
+         * @param m Matrix to translate.
+         * @param t Translation vector.
+         */
         static translate(m, t) {
             return { a: m.a, b: m.b, c: m.c, d: m.d, e: m.e + t.x, f: m.f + t.y };
         }
+        /**
+         * Returns a copy of `m` rotated (about the origin) by the given angle.
+         * @param m Matrix to rotate.
+         * @param rad Rotation angle, in radians.
+         */
         static rotate(m, rad) {
             const cos = Math.cos(rad), sin = Math.sin(rad);
             return Matrix2D.multiply(m, { a: cos, b: sin, c: -sin, d: cos, e: 0, f: 0 });
@@ -920,9 +1081,18 @@
                 f: m1.e * m2.b + m1.f * m2.d + m2.f
             };
         }
+        /**
+         * Computes the determinant of the matrix's linear part.
+         * @param m Matrix to compute the determinant of.
+         */
         static det(m) {
             return m.a * m.d - m.c * m.b;
         }
+        /**
+         * Computes the inverse of the given matrix.
+         * @param m Matrix to invert.
+         * @returns The inverse matrix, or `null` if `m` is singular (determinant is zero).
+         */
         static invert(m) {
             const det = this.det(m);
             if (det === 0) {
@@ -946,6 +1116,12 @@
                 f: m.e * m.b - m.a * m.f
             }, invdet);
         }
+        /**
+         * Decomposes a matrix into its scale, rotation and translation components.
+         * @param m Matrix to decompose.
+         * @param transformOrigin Origin about which the rotation/scale are considered to be applied (defaults to `{x:0, y:0}`).
+         * @returns The decomposed `scaleX`, `scaleY`, `rotation` (radians) and `translation`.
+         */
         static toComponents(m, transformOrigin = { x: 0, y: 0 }) {
             const scaleX = Math.sqrt(m.a * m.a + m.c * m.c);
             const scaleY = Math.sqrt(m.b * m.b + m.d * m.d);
@@ -1009,7 +1185,14 @@
     }
     // }
 
+    /** Rectangle-related utilities (parsing, transform computation, intersection, bounding box). */
     class Rect {
+        /**
+         * Parses a string containing exactly four numbers into a {@link Rect}.
+         * @param rect String to parse (e.g. `"0 0 100 50"`, in `x y width height` order).
+         * @returns The parsed rect.
+         * @throws If `rect` does not contain exactly four numbers.
+         */
         static parse(rect) {
             let arr = parseAsNumericalArray(rect);
             if (arr && arr.length === 4) {
@@ -1017,6 +1200,10 @@
             }
             throw new Error(`Cannot parse "${rect}" as a valid Rect.`);
         }
+        /**
+         * Type-guards a value as a valid {@link Rect} object.
+         * @param obj Value to check.
+         */
         static isRect(obj) {
             return Point.isPoint(obj) && Size.isSize(obj);
         }
@@ -1139,6 +1326,10 @@
     // namespace Pacem {
     /** Grants undo/redo functionalities for given state. */
     class HistoryService {
+        /**
+         * @param state Initial state.
+         * @param maxlength Maximum number of stored states (undo queue + redo stack); unbounded when omitted.
+         */
         constructor(state, maxlength) {
             this.#current = state;
             this.#maxlength = maxlength;
@@ -1156,9 +1347,11 @@
         get current() {
             return this.#current;
         }
+        /** Gets whether there is a previous state to revert to. @readonly */
         get canUndo() {
             return this.#backwards.length > 0;
         }
+        /** Gets whether there is a subsequent state to reapply. @readonly */
         get canRedo() {
             return this.#forwards.length > 0;
         }
@@ -1167,6 +1360,7 @@
         set maxlength(v) {
             this.#maxlength = v;
         }
+        /** Reverts to the previous state, if any (see {@link canUndo}), moving the current state onto the redo stack. */
         undo() {
             if (this.canUndo) {
                 const back = this.#backwards, fore = this.#forwards, current = this.#current;
@@ -1174,6 +1368,7 @@
                 this.#current = back.pop();
             }
         }
+        /** Reapplies the next state, if any (see {@link canRedo}), moving the current state onto the undo queue. */
         redo() {
             if (this.canRedo) {
                 const back = this.#backwards, fore = this.#forwards, current = this.#current;
@@ -1181,6 +1376,11 @@
                 this.#current = fore.shift();
             }
         }
+        /**
+         * Pushes a new current state, clearing the redo stack and enqueuing the previous current state for undo.
+         * Trims the undo queue to `maxlength`, if set.
+         * @param state New current state.
+         */
         push(state) {
             this.#forwards.splice(0);
             this.#backwards.push(this.#current);
@@ -1190,6 +1390,7 @@
                 queue.splice(0, queue.length - max);
             }
         }
+        /** Clears both the undo queue and the redo stack, leaving the current state untouched. */
         reset() {
             this.#forwards.splice(0);
             this.#backwards.splice(0);
@@ -1205,7 +1406,13 @@
         quality: 1,
         type: 'image/jpeg'
     };
+    /** Image loading and resizing utilities, based on `OffscreenCanvas`. */
     class Imaging {
+        /**
+         * Fetches an image from a URL as a `Blob`.
+         * @param url URL of the image to load.
+         * @returns A promise resolving with the loaded `Blob`, or `null` if the fetch response was not OK.
+         */
         static async loadImage(url) {
             const response = await fetch(url);
             if (!response.ok) {
@@ -1248,16 +1455,30 @@
     // }
 
     // namespace Pacem {
+    /** Unique key/id generation utilities. */
     class Keys {
         static #seed;
+        /**
+         * Generates a process-wide monotonically increasing numeric id, seeded from the current timestamp.
+         * @returns A new unique numeric id.
+         */
         static uniqueId() {
             let seed = Keys.#seed || Date.now();
             return Keys.#seed = ++seed;
         }
+        /**
+         * Generates a process-wide unique id, base-62 encoded.
+         * @returns A new unique string code.
+         */
         static uniqueCode() {
             const newid = Keys.uniqueId();
             return newid.toBase62();
         }
+        /**
+         * Generates a random base-62 string of at least the given length.
+         * @param length Minimum length of the generated string.
+         * @returns A random string.
+         */
         static randomString(length) {
             let retval = '';
             do {
@@ -1269,13 +1490,32 @@
     // }
 
     // namespace Pacem {
+    /** Numeric utilities. */
     class Numbers {
+        /**
+         * Rounds a number to the nearest multiple of `step`.
+         * @param x Value to round.
+         * @param step Rounding step/increment (defaults to 1).
+         * @returns The rounded value.
+         */
         static round(x, step = 1.0) {
             return Math.round(x / step) * step;
         }
+        /**
+         * Computes the logarithm of `x` in an arbitrary `base`.
+         * @param x Value to compute the logarithm of.
+         * @param base Logarithm base.
+         */
         static log(x, base) {
             return Math.log10(x) / Math.log10(base);
         }
+        /**
+         * Converts a number (or numeric string) from one base to another.
+         * @param v Value to convert, expressed in base `from`.
+         * @param from Source base (2-36).
+         * @param to Target base (2-36).
+         * @returns The value re-expressed in base `to`, as a string; `"NaN"` if `v` is not a valid number in base `from`.
+         */
         static rebase(v, from, to) {
             const vStr = v.toString();
             const firstPass = parseInt(vStr, from);
@@ -1428,6 +1668,7 @@
         return diffInternal(aTokens, bTokens, dp, '\n');
     }
     //#endregion
+    /** String manipulation utilities. */
     class Strings {
         /** @deprecated Use String.prototype.padStart() instead. */
         static leftPad(v, targetLength, padChar) {
@@ -1437,6 +1678,14 @@
             //    retval = padChar + retval;
             //return retval;
         }
+        /**
+         * Formats a template string, replacing `{0}`, `{1}`, ... placeholders with the corresponding arguments.
+         * Doubled braces (`{{`/`}}`) escape a placeholder.
+         * @param template Template string containing `{n}` placeholders.
+         * @param args Values to substitute into the placeholders, by index.
+         * @returns The formatted string.
+         * @throws If the template references an argument index that was not supplied.
+         */
         static format(template, ...args) {
             const array = Array.from(args);
             let retval = template;
@@ -1452,6 +1701,13 @@
             }
             return retval;
         }
+        /**
+         * Computes a diff between two strings, using the Longest Common Subsequence algorithm.
+         * @param a First (original) string.
+         * @param b Second (modified) string.
+         * @param mode Diffing granularity: `'char'` (default), `'word'` or `'line'`.
+         * @returns Array of {@link DiffToken}s describing unchanged, removed and added chunks.
+         */
         static diff(a, b, mode = 'char') {
             switch (mode) {
                 case 'line':
@@ -1462,6 +1718,12 @@
                     return diffChars(a, b);
             }
         }
+        /**
+         * Computes the cryptographic hash of a string using the SubtleCrypto API.
+         * @param input String to hash.
+         * @param algo Hash algorithm to use (defaults to `SHA-256`).
+         * @returns A promise resolving with the hash, hex-encoded.
+         */
         static async hash(input, algo = 'SHA-256') {
             const hashBuffer = await crypto.subtle.digest(algo, new TextEncoder().encode(input));
             return Array.from(new Uint8Array(hashBuffer))
@@ -1494,10 +1756,21 @@
             return tokens;
         }
     }
+    /** Generic tokenize-then-render text parser: lexes input against a grammar, then renders the resulting token tree. */
     let Parser$1 = class Parser {
+        /**
+         * @param _lexer Lexer implementation to use (defaults to a built-in greedy, rule-ordered lexer).
+         */
         constructor(_lexer = new LexerClass()) {
             this._lexer = _lexer;
         }
+        /**
+         * Tokenizes `input` against `grammar` and renders the resulting token tree.
+         * @param input String to parse.
+         * @param grammar Ordered list of rules describing the grammar.
+         * @param renderer Renderer used to turn the token tree into the output string.
+         * @returns The rendered output.
+         */
         parse(input, grammar, renderer) {
             const tokens = this._lexer.tokenize(input, grammar);
             return renderer.render(tokens);
@@ -1620,6 +1893,12 @@
         MARKDOWN_RULES[MARKDOWN_RULES["Text"] = 254] = "Text";
         MARKDOWN_RULES[MARKDOWN_RULES["Space"] = 255] = "Space";
     })(MARKDOWN_RULES || (MARKDOWN_RULES = {}));
+    /**
+     * Builds the full Markdown grammar (block + inline rules, comment/reference handling first),
+     * optionally merging in caller-supplied {@link ExtraRule}s.
+     * @param extra Additional block/inline/code rules to plug into the built-in grammar.
+     * @returns Ordered list of {@link Compile.Rule}s ready to be fed to a {@link Compile.Lexer}.
+     */
     function getGrammar(extra = []) {
         const inert = {
             // comment
@@ -1970,6 +2249,7 @@
         return input?.replace(TRIM_INSIDE, '\n').trim();
     }
     // #endregion
+    /** Renders a Markdown token tree, as produced by the grammar returned by {@link getGrammar}, into HTML markup. */
     class HtmlRenderer {
         constructor(_extraItemRender = (token, __) => token?.text || '') {
             this._extraItemRender = _extraItemRender;
@@ -2061,6 +2341,7 @@
             return trim(this._render(tree));
         }
     }
+    /** Renders a Markdown token tree as a JSON array of tokens, mainly useful for debugging/inspection. */
     class TokenRenderer {
         _render(token) {
             return NullChecker.isNullOrEmpty(token) ? '' : JSON.stringify(token);
@@ -2072,7 +2353,15 @@
     function isRenderer(obj) {
         return obj && typeof obj === 'object' && typeof obj.render === 'function';
     }
+    /** Markdown parser: tokenizes Markdown source and renders it to HTML (or another format via a custom {@link Compile.Renderer}). */
     class Parser extends Parser$1 {
+        /**
+         * Parses Markdown `input` and renders it to an HTML string.
+         * @param input Markdown source.
+         * @param extraGrammar Additional grammar rules to extend the built-in Markdown syntax.
+         * @param extraItemRenderer Fallback renderer invoked for token types not natively handled (e.g. tokens produced by `extraGrammar`); defaults to returning the token's `text`.
+         * @returns The rendered HTML string.
+         */
         toHtml(input, extraGrammar, extraItemRenderer) {
             const renderer = new HtmlRenderer(extraItemRenderer);
             if (NullChecker.isNullOrEmpty(extraGrammar)) {
@@ -2080,6 +2369,12 @@
             }
             return this.parse(input, getGrammar(extraGrammar), renderer);
         }
+        /**
+         * Parses Markdown `input` and returns its token tree as a plain (JSON-serializable) array, useful for inspection/debugging.
+         * @param input Markdown source.
+         * @param extraGrammar Additional grammar rules to extend the built-in Markdown syntax.
+         * @returns The parsed token tree.
+         */
         tokenize(input, extraGrammar) {
             const json = this.parse(input, getGrammar(extraGrammar), new TokenRenderer());
             return JSON.parse(json);