@pacem/pacem-foundation 1.0.0-bessel → 1.0.0-binet

package/typings/index.d.ts

@@ -1,10 +1,16 @@
+/** Represents an angle defined by a vertex and two points laying on its sides. */
 export declare interface Angle {
     vertex: Point;
     start: Point;
     end: Point;
 }
 
+/** Angle-related utilities. */
 export declare class Angle {
+    /**
+     * Type-guards a value as a valid {@link Angle} object.
+     * @param obj Value to check.
+     */
     static isAngle(obj: any): obj is Angle;
     /**
      * Returns the angle span in radians.
@@ -22,18 +28,69 @@ export declare class Angle {
     static angleBetween(vertex: Point, start: Point, end: Point): number;
 }
 
+/** Array manipulation utilities. */
 export declare class Arrays {
+    /**
+     * Generates an array of `items` evenly-spaced numbers from 1 to `items`.
+     * @param items Number of items to generate (also used as the upper bound).
+     * @returns Array of evenly-spaced numbers.
+     */
     static range(items: number): number[];
+    /**
+     * Generates an array of evenly-spaced numbers between `min` and `max`.
+     * @param min Range lower bound.
+     * @param max Range upper bound.
+     * @param items Number of items to generate (defaults to 2).
+     * @returns Array of evenly-spaced numbers.
+     */
     static range(min: number, max: number, items?: number): number[];
+    /**
+     * 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: any[], size: number): any[][];
 }
 
+/** Conversion utilities between `Blob`, base64/data URLs and plain text. */
 export declare 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: Blob): Promise<string>;
     private static _b64ToUint8Array;
+    /**
+     * 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: string, options?: BlobPropertyBag): Blob;
+    /**
+     * 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: string): Blob;
+    /**
+     * 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 blobToText(blob: Blob, encoding?: string): Promise<string>;
+    /**
+     * Encodes text into a `Blob`.
+     * @param content Text content to encode.
+     * @param type MIME type of the resulting blob (defaults to `text/plain`).
+     * @param charset Text encoding to use (defaults to `utf-8`).
+     * @param bom Whether to prepend a byte-order mark (defaults to `false`, except for `utf-16` which defaults to `true`).
+     * @param lossyChar Replacement character code used for characters that cannot be represented in single-byte encodings (`ascii`/`iso-8859-1`); pass `0` to throw instead.
+     * @returns The resulting `Blob`.
+     */
     static textToBlob(content: string): Blob;
     static textToBlob(content: string, type: string): Blob;
     static textToBlob(content: string, type: string, charset: BlobTextEncoding): Blob;
@@ -41,8 +98,10 @@ export declare class Blobs {
     static textToBlob(content: string, type: string, charset: BlobTextEncoding, bom: boolean, lossyChar: number): Blob;
 }
 
+/** Text encodings supported by {@link Blobs.textToBlob}. */
 declare type BlobTextEncoding = 'utf-8' | 'utf-16' | 'utf-16be' | 'utf-16le' | 'iso-8859-1' | 'ascii';
 
+/** Represents a color in the CIE 1931 XYZ color space. */
 export declare interface CieXYZ {
     readonly x: number;
     readonly y: number;
@@ -50,19 +109,47 @@ export declare interface CieXYZ {
     a?: number;
 }
 
+/** Color parsing, conversion (RGB/HSL/CIE XYZ) and manipulation utilities. */
 export declare class Colors {
+    /** Minimum WCAG contrast ratio recommended for large-scale text/graphical objects. */
     static WCAG_MINIMUM_CONTRAST: number;
+    /** Minimum WCAG (AA) contrast ratio recommended for normal-sized text. */
     static WCAG_NORMAL_TEXT_CONTRAST: number;
+    /** Minimum WCAG (AAA) contrast ratio recommended for enhanced accessibility. */
     static WCAG_SAFE_CONTRAST: number;
     private static _clampRGB;
     private static _normalize;
+    /**
+     * 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: string): Rgba;
+    /**
+     * Converts an {@link Rgba} color into its {@link Hsla} equivalent.
+     * @param rgb Color to convert.
+     * @returns The converted color.
+     */
     static hsl(rgb: Rgba): Hsla;
+    /** Converts an {@link Rgba} color into the CIE 1931 XYZ color space. */
     static cieXYZ(rgb: Rgba): CieXYZ;
+    /** Converts an {@link Hsla} color into the CIE 1931 XYZ color space. */
     static cieXYZ(hsl: Hsla): CieXYZ;
+    /** Converts an {@link Hsla} color into its {@link Rgba} equivalent. */
     static rgb(hsl: Hsla): Rgba;
+    /** Converts a {@link CieXYZ} color into its {@link Rgba} equivalent. */
     static rgb(cieXYZ: CieXYZ): Rgba;
+    /**
+     * Stringifies an {@link Hsla} color into its CSS `hsla()` representation.
+     * @param hsl Color to stringify.
+     * @param precision Number of decimal digits used to round the channels (defaults to 1).
+     */
     static stringify(hsl: Hsla, precision?: number): string;
+    /**
+     * Stringifies an {@link Rgba} color into its CSS representation.
+     * @param rgb Color to stringify.
+     * @param hex Whether to render as a `#RRGGBB` hex string when fully opaque (defaults to `true`); when `false`, always renders as `rgb()`/`rgba()`.
+     */
     static stringify(rgb: Rgba, hex?: boolean): string;
     /**
      * Contrast ratio betwen two colors (useful for accessibility assessments). Output range: 1 (no-contrast) to 21 (maximum contrast)
@@ -72,14 +159,42 @@ export declare class Colors {
      * Returns the relative luminance as of WCAG specs.
      */
     static luminance(clr: Rgba | Hsla): number;
+    /**
+     * Returns a lightened copy of the given color.
+     * @param clr Color to lighten (`Rgba` or `Hsla`).
+     * @param amount Amount to add to the lightness channel, in the [0,1] range (defaults to 0.1).
+     */
     static lighten(rgb: Rgba, amount?: number): Rgba;
     static lighten(rgb: Hsla, amount?: number): Hsla;
+    /**
+     * Returns a darkened copy of the given color (shorthand for {@link Colors.lighten} with a negated amount).
+     * @param clr Color to darken (`Rgba` or `Hsla`).
+     * @param amount Amount to subtract from the lightness channel, in the [0,1] range (defaults to 0.1).
+     */
     static darken(rgb: Rgba, amount?: number): Rgba;
     static darken(rgb: Hsla, amount?: number): Hsla;
+    /**
+     * Returns a more saturated copy of the given color.
+     * @param clr Color to saturate (`Rgba` or `Hsla`).
+     * @param amount Amount to add to the saturation channel, in the [0,1] range (defaults to 0.1).
+     */
     static saturate(rgb: Rgba, amount?: number): Rgba;
     static saturate(rgb: Hsla, amount?: number): Hsla;
+    /**
+     * Returns a less saturated copy of the given color (shorthand for {@link Colors.saturate} with a negated amount).
+     * @param clr Color to desaturate (`Rgba` or `Hsla`).
+     * @param amount Amount to subtract from the saturation channel, in the [0,1] range (defaults to 0.1).
+     */
     static desaturate(rgb: Rgba, amount?: number): Rgba;
     static desaturate(rgb: Hsla, amount?: number): Hsla;
+    /**
+     * Blends two colors together (weighted average, computed in the CIE XYZ color space).
+     * @param clr1 First color.
+     * @param clr2 Second color.
+     * @param weight1 Weight of the first color (defaults to 0.5).
+     * @param weight2 Weight of the second color (defaults to `weight1`).
+     * @returns A new color of the same kind as the inputs (`Rgba`, `Hsla` or `CieXYZ`).
+     */
     static interpolate(rgb1: Rgba, rgb2: Rgba, weight1?: number, weight2?: number): Rgba;
     static interpolate(hsl1: Hsla, hsl2: Hsla, weight1?: number, weight2?: number): Hsla;
     static interpolate(cieXYZ1: CieXYZ, cieXYZ2: CieXYZ, weight1?: number, weight2?: number): CieXYZ;
@@ -106,9 +221,26 @@ declare namespace Compile_2 {
     }
 }
 
+/** Date parsing and arithmetic utilities. */
 export declare 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: string | Date | number): Date;
+    /**
+     * Gets whether the given year is a leap year.
+     * @param year Year to check.
+     */
     static isLeapYear(year: number): boolean;
+    /**
+     * 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: number, month: number): number;
     /**
      * Gets whether a date is an `Invalid Date` or not.
@@ -120,30 +252,73 @@ export declare class Dates {
      * @param datetime
      */
     static dateOnly(datetime: Date): Date;
+    /**
+     * 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: Date, value: number): Date;
+    /**
+     * 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: Date, value: number): Date;
+    /**
+     * 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: Date, end: Date): number;
 }
 
+/** Deep-merging utility for plain objects. */
 export declare class DeepMerger {
     private 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<S extends PlainObject, T extends PlainObject>(source: S, target?: T): T & S;
 }
 
+/**
+ * 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`.
+ */
 export declare function detect(userAgent?: string): {
     name: string;
     version: any;
 };
 
+/** Granularity used by {@link Strings.diff}: per-character, per-word, or per-line. */
 export declare type DiffMode = 'char' | 'word' | 'line';
 
+/** A single chunk of a diff result, as produced by {@link Strings.diff}. */
 export declare type DiffToken = {
     type: DiffTokenType;
     value: string;
 };
 
+/** Kind of a {@link DiffToken}: `'='` unchanged, `'-'` removed (present only in the first input), `'+'` added (present only in the second input). */
 export declare type DiffTokenType = '=' | '-' | '+';
 
+/**
+ * A custom grammar rule that extends the built-in Markdown grammar.
+ * Plain {@link Compile.Rule} values are treated as `inline` rules. Otherwise, `type` selects
+ * where the rule is plugged in: `'block'` (top-level block grammar), `'inline'` (inline/span
+ * grammar, recursively applied inside block content) or `'code'` (fenced-code-block grammar,
+ * scoped to a specific `lang`).
+ */
 declare type ExtraRule = (Compile_2.Rule | {
     rule: Compile_2.Rule;
     type: 'block' | 'inline';
@@ -156,22 +331,37 @@ declare type ExtraRule = (Compile_2.Rule | {
 /** Grants undo/redo functionalities for given state. */
 export declare class HistoryService<TState = any> {
     #private;
+    /**
+     * @param state Initial state.
+     * @param maxlength Maximum number of stored states (undo queue + redo stack); unbounded when omitted.
+     */
     constructor(state: TState, maxlength?: number);
     /**
      * Gets the current state.
      */
     get current(): TState;
+    /** Gets whether there is a previous state to revert to. @readonly */
     get canUndo(): boolean;
+    /** Gets whether there is a subsequent state to reapply. @readonly */
     get canRedo(): boolean;
     /** Sets the maximum number of stored states, queue + stack.
      */
     set maxlength(v: number);
+    /** Reverts to the previous state, if any (see {@link canUndo}), moving the current state onto the redo stack. */
     undo(): void;
+    /** Reapplies the next state, if any (see {@link canRedo}), moving the current state onto the undo queue. */
     redo(): void;
+    /**
+     * 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: TState): void;
+    /** Clears both the undo queue and the redo stack, leaving the current state untouched. */
     reset(): void;
 }
 
+/** Represents a color in the HSL color space; `h` is in degrees [0,360], `s`, `l` and `a` are normalized to the [0,1] range. */
 export declare interface Hsla {
     readonly h: number;
     readonly s: number;
@@ -179,29 +369,71 @@ export declare interface Hsla {
     a?: number;
 }
 
+/** Image loading and resizing utilities, based on `OffscreenCanvas`. */
 export declare 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 loadImage(url: string): Promise<Blob>;
+    /**
+     * Resizes an image to the given target size, drawing it onto an offscreen canvas.
+     * @param img Source image, either as a `Blob` or a URL to fetch it from.
+     * @param width Target width, in pixels.
+     * @param height Target height, in pixels.
+     * @param options Resize/encoding options (fit mode, alignment, quality, output type, background).
+     * @returns A promise resolving with the resized image as a `Blob`.
+     */
     static resizeImage(img: Blob, width: number, height: number, options?: ImagingResizeOptions): Promise<Blob>;
     static resizeImage(img: string, width: number, height: number, options?: ImagingResizeOptions): Promise<Blob>;
 }
 
+/** Options controlling how {@link Imaging.resizeImage} fits and encodes the resized image. */
 export declare type ImagingResizeOptions = {
+    /** How the source image is fitted into the target size: `'contain'` (letterboxed), `'cover'` (cropped) or `'stretch'` (default, non-uniform scale). */
     mode?: 'contain' | 'cover' | 'stretch';
+    /** Horizontal alignment used when the scaled image doesn't exactly fill the target size (`'contain'`/`'cover'` modes). */
     align?: 'left' | 'center' | 'right';
+    /** Vertical alignment used when the scaled image doesn't exactly fill the target size (`'contain'`/`'cover'` modes). */
     valign?: 'top' | 'middle' | 'bottom';
+    /** Output encoding quality, in the [0,1] range (only relevant for lossy formats, e.g. `image/jpeg`). */
     quality?: number;
+    /** Output MIME type (defaults to `image/jpeg`). */
     type?: string;
+    /** Background fill color, applied before drawing the resized image (useful with `'contain'` mode to avoid transparent letterboxing). */
     background?: string;
 };
 
+/** Unique key/id generation utilities. */
 export declare class Keys {
     #private;
+    /**
+     * Generates a process-wide monotonically increasing numeric id, seeded from the current timestamp.
+     * @returns A new unique numeric id.
+     */
     static uniqueId(): number;
+    /**
+     * Generates a process-wide unique id, base-62 encoded.
+     * @returns A new unique string code.
+     */
     static uniqueCode(): string;
+    /**
+     * 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: number): string;
 }
 
+/** Turns raw input into a stream of {@link Token}s given a grammar (list of {@link Rule}s). */
 declare interface Lexer {
+    /**
+     * Tokenizes the whole input string against a grammar.
+     * @param input String to tokenize.
+     * @param grammar Ordered list of rules; the first rule that matches at each position wins.
+     * @returns The resulting list of tokens.
+     */
     tokenize(input: string, grammar: Rule[]): Token[];
 }
 
@@ -222,19 +454,63 @@ export declare interface Matrix2D {
     readonly f: number;
 }
 
+/** 2D affine matrix ([a b; c d] linear part, [e f] translation) manipulation utilities. */
 export declare class Matrix2D {
+    /**
+     * Returns whether the given matrix is the identity matrix.
+     * @param m Matrix to check.
+     */
     static isIdentity(m: Matrix2D): boolean;
+    /** Gets a fresh identity matrix. @readonly */
     static get identity(): Matrix2D;
+    /**
+     * Returns a shallow copy of the given matrix.
+     * @param m Matrix to copy.
+     */
     static copy(m: Matrix2D): Matrix2D;
+    /**
+     * Returns a copy of `m` scaled by the given factor(s).
+     * @param m Matrix to scale.
+     * @param sx Horizontal scale factor (used for both axes if `sy` is omitted).
+     * @param sy Vertical scale factor (defaults to `sx`).
+     */
     static scale(m: Matrix2D, s: number): Matrix2D;
     static scale(m: Matrix2D, sx: number, sy: number): Matrix2D;
+    /**
+     * Returns a copy of `m` translated by the given vector.
+     * @param m Matrix to translate.
+     * @param t Translation vector.
+     */
     static translate(m: Matrix2D, t: Point): Matrix2D;
+    /**
+     * 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: Matrix2D, rad: number): Matrix2D;
+    /** Scales a matrix by a scalar factor, component-wise. */
     static multiply(m: Matrix2D, f: number): Matrix2D;
+    /** Transforms a point by a matrix. */
     static multiply(p: Point, m: Matrix2D): Point;
+    /** Composes two matrices (`m1` applied first, then `m2`). */
     static multiply(m1: Matrix2D, m2: Matrix2D): Matrix2D;
+    /**
+     * Computes the determinant of the matrix's linear part.
+     * @param m Matrix to compute the determinant of.
+     */
     static det(m: Matrix2D): number;
+    /**
+     * 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: Matrix2D): Matrix2D;
+    /**
+     * 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: Matrix2D, transformOrigin?: Point): {
         scaleX: number;
         scaleY: number;
@@ -258,44 +534,124 @@ export declare class Matrix2D {
     static areClose(m1: Matrix2D, m2: Matrix2D, precision?: number): boolean;
 }
 
+/** Null/empty value-checking utilities. */
 export declare class NullChecker {
+    /**
+     * Returns whether the given value is `null` or `undefined`.
+     * @param o Value to check.
+     */
     static isNull(o: any): o is null | undefined;
+    /**
+     * 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: any): boolean;
+    /**
+     * Returns whether the given value is `null`, `undefined`, or "empty" (see {@link NullChecker.isEmpty}).
+     * @param o Value to check.
+     */
     static isNullOrEmpty(o: any): boolean;
 }
 
+/** Numeric utilities. */
 export declare 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: number, step?: number): number;
+    /**
+     * Computes the logarithm of `x` in an arbitrary `base`.
+     * @param x Value to compute the logarithm of.
+     * @param base Logarithm base.
+     */
     static log(x: number, base: number): number;
+    /**
+     * 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: number | string, from: number, to: number): string;
 }
 
+/**
+ * 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.
+ */
 export declare function parseAsNumericalArray(input: string): number[];
 
+/** Generic tokenize-then-render text parser: lexes input against a grammar, then renders the resulting token tree. */
 declare class Parser {
     private _lexer;
+    /**
+     * @param _lexer Lexer implementation to use (defaults to a built-in greedy, rule-ordered lexer).
+     */
     constructor(_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: string, grammar: Rule[], renderer: Renderer): string;
 }
 
+/** Markdown parser: tokenizes Markdown source and renders it to HTML (or another format via a custom {@link Compile.Renderer}). */
 declare class Parser_2 extends Compile_2.Parser {
+    /**
+     * 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: string, extraGrammar?: ExtraRule[], extraItemRenderer?: (token: Compile_2.Token, allTokens: Compile_2.Token[]) => string): string;
+    /**
+     * 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: string, extraGrammar?: ExtraRule[]): any[];
+    /** Parses Markdown `input` and renders it to HTML using the built-in grammar. */
     parse(input: string): string;
+    /** Parses Markdown `input` using the built-in grammar and renders it with a custom `renderer`. */
     parse(input: string, renderer: Compile_2.Renderer): string;
+    /** Parses Markdown `input` using a custom `grammar` and renders it to HTML. */
     parse(input: string, grammar: Compile_2.Rule[]): string;
+    /** Parses Markdown `input` using a custom `grammar` and a custom `renderer`. */
     parse(input: string, grammar: Compile_2.Rule[], renderer: Compile_2.Renderer): string;
 }
 
 declare type PlainObject = Record<string, unknown>;
 
+/** Represents a 2D point/vector. */
 export declare interface Point {
     x: number;
     y: number;
 }
 
+/** Point-related utilities. */
 export declare 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: string): Point;
+    /**
+     * Type-guards a value as a valid {@link Point} object.
+     * @param obj Value to check.
+     */
     static isPoint(obj: any): obj is Point;
     /**
      * Computes the distance between two points.
@@ -323,11 +679,23 @@ export declare class Point {
     static multiply(p: Point, f: number): Point;
 }
 
+/** Represents a 2D axis-aligned rectangle (position + size). */
 export declare interface Rect extends Point, Size {
 }
 
+/** Rectangle-related utilities (parsing, transform computation, intersection, bounding box). */
 export declare 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: string): Rect;
+    /**
+     * Type-guards a value as a valid {@link Rect} object.
+     * @param obj Value to check.
+     */
     static isRect(obj: any): obj is Rect;
     private static _stretch;
     private static _contain;
@@ -360,10 +728,12 @@ export declare class Rect {
     static expand(rect: Rect, ...points: Point[]): Rect;
 }
 
+/** Turns a token tree, as produced by a {@link Lexer}, into an output string (e.g. HTML, JSON, ...). */
 declare interface Renderer {
     render: (tree: Token[]) => string;
 }
 
+/** Represents a color in the RGB color space; `r`, `g`, `b` and `a` channels are normalized to the [0,1] range. */
 export declare interface Rgba {
     readonly r: number;
     readonly g: number;
@@ -371,53 +741,134 @@ export declare interface Rgba {
     a?: number;
 }
 
+/** A single grammar rule: attempts to recognize a token (or sequence of tokens) at the start of the input string. */
 declare interface Rule {
+    /**
+     * Attempts to match this rule against the beginning of `input`.
+     * @param input String to match against.
+     * @param lexer Lexer instance, provided to allow recursive tokenization (e.g. for nested/inline content).
+     * @returns The matched tokens, or a falsy value when the rule does not match.
+     */
     exec: (input: string, lexer?: Lexer) => Token[];
 }
 
+/** Represents a 2D size (width/height). */
 export declare interface Size {
     width: number;
     height: number;
 }
 
+/** Size-related utilities. */
 export declare 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: string): Size;
+    /**
+     * Type-guards a value as a valid {@link Size} object.
+     * @param obj Value to check.
+     */
     static isSize(obj: any): obj is Size;
 }
 
+/** String manipulation utilities. */
 export declare class Strings {
     /** @deprecated Use String.prototype.padStart() instead. */
     static leftPad(v: any, targetLength: number, padChar: string): string;
+    /**
+     * 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: string, ...args: any[]): string;
+    /**
+     * 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: string, b: string, mode?: DiffMode): DiffToken[];
+    /**
+     * 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 hash(input: string, algo?: HashAlgorithmIdentifier): Promise<string>;
 }
 
+/** A lexical token produced by tokenizing input against a grammar. */
 declare interface Token {
+    /** Position (character offset) within the original input where this token starts, if known. */
     readonly index?: number;
+    /** Discriminates the kind of token (grammar/renderer-specific). */
     readonly type: string;
+    /** Raw matched substring, including any markup/syntax characters. */
     readonly raw: string;
+    /** Text content of the token, with markup/syntax characters stripped where applicable. */
     readonly text: string;
+    /** Nested tokens, when this token's content was recursively tokenized. */
     readonly tokens?: Token[];
 }
 
 declare global {
     interface Number {
+        /**
+         * Checks whether this number is close enough to `other`, within a given decimal precision.
+         * @param other Number to compare against.
+         * @param precision Number of decimal digits of tolerance (defaults to 14).
+         * @returns Whether the two numbers are close to each other.
+         */
         isCloseTo(other: number, precision?: number): boolean;
+        /**
+         * Rounds this number to a given number of decimal digits.
+         * @param precision Number of decimal digits to keep (defaults to 14).
+         * @returns The rounded value.
+         */
         roundoff(precision?: number): number;
+        /**
+         * Clamps this number between a minimum and a maximum value.
+         * @param min Lower bound (ignored if `null`/`NaN`).
+         * @param max Upper bound (ignored if `null`/`NaN`).
+         * @returns The clamped value.
+         */
         clamp(min: number, max: number): any;
+        /** Converts this number into its base-62 string representation (digits + uppercase + lowercase letters). */
         toBase62(): string;
+        /** Converts this number into its base-36 string representation. */
         toBase36(): string;
     }
 }
 
 declare global {
     interface Array<T> {
+        /**
+         * Moves an item within the array, shifting the other items accordingly.
+         * @param from Index of the item to move.
+         * @param to Destination index.
+         */
         moveWithin(from: number, to: number): void;
         /** Checks content equality between arrays. */
         equalsContent(other: T[]): boolean;
+        /**
+         * Mutates this array in-place so its content matches `other`, only touching indexes whose value actually changed (and trimming/growing length as needed).
+         * @param other Array whose content is to be cloned into this one.
+         */
         cloneFrom(other: T[]): void;
+        /**
+         * Returns the union (set union, duplicates removed) of this array and `other`.
+         * @param other Array to union with.
+         * @returns A new array with the distinct items of both arrays.
+         */
         union(other: T[]): T[];
+        /** Returns a new array with duplicate items removed, preserving the first occurrence's order. */
         distinct(): T[];
     }
 }