reamkit 1.15.0 → 1.15.2

package/dist/esm/core/drawingml/preset-geometry.js

@@ -1,9 +1,14 @@
 import { PathBuilder } from "../vector.js";
 import { arcToBeziers, ellipseSegments, roundRectSegments } from "../arc-to-bezier.js";
 //#region src/core/drawingml/preset-geometry.ts
+/**
+* The four closed segments of the `w`×`h` bounding rectangle, in the local y-up
+* frame (origin bottom-left). The fallback geometry for unknown presets.
+*/
 function rectSegments(w, h) {
 	return new PathBuilder().moveTo(0, 0).lineTo(w, 0).lineTo(w, h).lineTo(0, h).close().build().segments;
 }
+/** The `w`×`h` bounding rectangle as a {@link VectorPath}. */
 function rectPath(w, h) {
 	return { segments: rectSegments(w, h) };
 }
@@ -14,6 +19,19 @@ function polygon(points) {
 }
 var clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
 var frac = (adjust, key, def) => (adjust.get(key) ?? def) / 1e5;
+/**
+* Map a preset shape name (§20.1.10.55) to its vector path(s) in the local y-up
+* frame, sized `w`×`h` points and shaped by the `adjust` guides. Returns `null`
+* for an unknown preset so the caller falls back to the bounding rectangle —
+* graceful degradation that keeps even unimplemented presets visible (with the
+* right fill/line) and never throws.
+*
+* @param preset The preset geometry name (e.g. `'roundRect'`, `'rightArrow'`).
+* @param w      Box width in points.
+* @param h      Box height in points.
+* @param adjust Raw `a:gd` adjust guides by name (thousandths of a percent).
+* @returns The path(s), or `null` for an unrecognised preset.
+*/
 function presetPaths(preset, w, h, adjust) {
 	switch (preset) {
 		case "rect": return [rectPath(w, h)];
@@ -77,6 +95,18 @@ function presetPaths(preset, w, h, adjust) {
 		default: return null;
 	}
 }
+/**
+* Convert a custom geometry (§20.1.9) to a vector path. Path-space coordinates
+* (y-down, origin top-left) are scaled to the shape box and flipped to the local
+* y-up frame; quadratics are elevated to cubics; `arcTo` is decomposed via the
+* shared arc helper. Angles are 1/60000° clockwise in y-down, which becomes
+* negative (CCW) once y is flipped.
+*
+* @param geom The parsed custom geometry (path size + draw commands).
+* @param wPt  Box width in points.
+* @param hPt  Box height in points.
+* @returns A single-element array holding the built path.
+*/
 function customPaths(geom, wPt, hPt) {
 	const sx = geom.pathWidth > 0 ? wPt / geom.pathWidth : 1;
 	const sy = geom.pathHeight > 0 ? hPt / geom.pathHeight : 1;

package/dist/esm/core/drawingml/shape-render.d.ts

@@ -1,10 +1,64 @@
 import { ShapeGeometry, ShapeLine } from '../document-model/index.js';
 import { ShapeGradient, StrokeStyle, VectorPath } from '../vector.js';
+/** EMU per point: 1 inch = 914400 EMU = 72 pt, so 1 pt = 12700 EMU. */
 export declare const EMU_PER_PT = 12700;
+/** Word's default left/right text-box inset (§20.1.2.1) — 0.1", in points. */
 export declare const DEFAULT_INSET_LR_PT: number;
+/** Word's default top/bottom text-box inset (§20.1.2.1) — 0.05", in points. */
 export declare const DEFAULT_INSET_TB_PT: number;
+/**
+ * Build the vector path(s) for a shape's geometry, sized `widthPt`×`heightPt`.
+ * Dispatches preset geometries to {@link presetPaths} (falling back to the
+ * bounding rectangle for unknown presets) and custom geometries to
+ * {@link customPaths}.
+ *
+ * @param geometry The shape geometry (preset or custom).
+ * @param widthPt  Box width in points.
+ * @param heightPt Box height in points.
+ * @returns The path(s) in the local y-up frame.
+ */
 export declare function buildShapePaths(geometry: ShapeGeometry, widthPt: number, heightPt: number): Array<VectorPath>;
+/**
+ * A gradient's solid approximation: the per-channel average of its stop colours
+ * (EP16). Writers without gradient support (the plain PDF emitter) paint this.
+ *
+ * @param gradient The gradient fill.
+ * @returns The averaged colour as uppercase RRGGBB (`'000000'` if no valid stops).
+ */
 export declare function gradientToSolid(gradient: ShapeGradient): string;
+/**
+ * An SVG `<linearGradient>` / `<radialGradient>` definition for a gradient fill
+ * (EP16), shared by the SVG and HTML writers. The linear vector is expressed in
+ * `objectBoundingBox` space; the angle is negated because the shape's own path
+ * transform flips y (local y-up → page y-down).
+ *
+ * @param id The gradient element id (referenced by `fill="url(#id)"`).
+ * @param g  The gradient fill.
+ * @returns The `<linearGradient>` or `<radialGradient>` markup.
+ */
 export declare function gradientSvgDef(id: string, g: ShapeGradient): string;
+/**
+ * Build a {@link StrokeStyle} from a shape's `a:ln` line, resolving the default
+ * width (0.75pt), dash pattern and line cap. Returns `undefined` for no line or
+ * an explicit no-fill stroke.
+ *
+ * @param line The parsed line, or `undefined`.
+ * @returns The stroke style, or `undefined` when nothing should be stroked.
+ */
 export declare function buildStroke(line: ShapeLine | undefined): StrokeStyle | undefined;
+/**
+ * Build the 2×3 affine placement matrix `[a, b, c, d, e, f]` that positions a
+ * shape's local y-up box at `(pageX, pageY)`, applying rotation and h/v flips
+ * about the box centre. DrawingML `rot` is clockwise in y-down space ⇒ a
+ * negative angle in PDF y-up.
+ *
+ * @param pageX       Box left, in page points.
+ * @param pageY       Box bottom, in page points.
+ * @param widthPt     Box width in points.
+ * @param heightPt    Box height in points.
+ * @param rotation60k Rotation in 1/60000°, clockwise.
+ * @param flipH       Mirror horizontally.
+ * @param flipV       Mirror vertically.
+ * @returns The affine matrix as `[a, b, c, d, e, f]`.
+ */
 export declare function buildShapeTransform(pageX: number, pageY: number, widthPt: number, heightPt: number, rotation60k: number, flipH: boolean, flipV: boolean): [number, number, number, number, number, number];

package/dist/esm/core/drawingml/shape-render.js

@@ -1,14 +1,35 @@
 import { customPaths, presetPaths, rectPath } from "./preset-geometry.js";
 //#region src/core/drawingml/shape-render.ts
+/** EMU per point: 1 inch = 914400 EMU = 72 pt, so 1 pt = 12700 EMU. */
 var EMU_PER_PT = 12700;
 var DEFAULT_LINE_WIDTH_EMU = 9525;
+/** Word's default left/right text-box inset (§20.1.2.1) — 0.1", in points. */
 var DEFAULT_INSET_LR_PT = 91440 / EMU_PER_PT;
+/** Word's default top/bottom text-box inset (§20.1.2.1) — 0.05", in points. */
 var DEFAULT_INSET_TB_PT = 45720 / EMU_PER_PT;
+/**
+* Build the vector path(s) for a shape's geometry, sized `widthPt`×`heightPt`.
+* Dispatches preset geometries to {@link presetPaths} (falling back to the
+* bounding rectangle for unknown presets) and custom geometries to
+* {@link customPaths}.
+*
+* @param geometry The shape geometry (preset or custom).
+* @param widthPt  Box width in points.
+* @param heightPt Box height in points.
+* @returns The path(s) in the local y-up frame.
+*/
 function buildShapePaths(geometry, widthPt, heightPt) {
 	if (geometry.kind === "preset") return presetPaths(geometry.preset ?? "rect", widthPt, heightPt, geometry.adjust ?? /* @__PURE__ */ new Map()) ?? [rectPath(widthPt, heightPt)];
 	if (geometry.custom) return customPaths(geometry.custom, widthPt, heightPt);
 	return [rectPath(widthPt, heightPt)];
 }
+/**
+* A gradient's solid approximation: the per-channel average of its stop colours
+* (EP16). Writers without gradient support (the plain PDF emitter) paint this.
+*
+* @param gradient The gradient fill.
+* @returns The averaged colour as uppercase RRGGBB (`'000000'` if no valid stops).
+*/
 function gradientToSolid(gradient) {
 	let r = 0;
 	let g = 0;
@@ -26,6 +47,16 @@ function gradientToSolid(gradient) {
 	const hx = (x) => Math.round(x / n).toString(16).padStart(2, "0");
 	return (hx(r) + hx(g) + hx(b)).toUpperCase();
 }
+/**
+* An SVG `<linearGradient>` / `<radialGradient>` definition for a gradient fill
+* (EP16), shared by the SVG and HTML writers. The linear vector is expressed in
+* `objectBoundingBox` space; the angle is negated because the shape's own path
+* transform flips y (local y-up → page y-down).
+*
+* @param id The gradient element id (referenced by `fill="url(#id)"`).
+* @param g  The gradient fill.
+* @returns The `<linearGradient>` or `<radialGradient>` markup.
+*/
 function gradientSvgDef(id, g) {
 	const n = (x) => String(Math.round(x * 1e4) / 1e4);
 	const stops = g.stops.map((s) => `<stop offset="${n(s.offset)}" stop-color="#${s.colorHex}"/>`).join("");
@@ -35,6 +66,14 @@ function gradientSvgDef(id, g) {
 	const dy = Math.sin(rad) / 2;
 	return `<linearGradient id="${id}" x1="${n(.5 - dx)}" y1="${n(.5 - dy)}" x2="${n(.5 + dx)}" y2="${n(.5 + dy)}">${stops}</linearGradient>`;
 }
+/**
+* Build a {@link StrokeStyle} from a shape's `a:ln` line, resolving the default
+* width (0.75pt), dash pattern and line cap. Returns `undefined` for no line or
+* an explicit no-fill stroke.
+*
+* @param line The parsed line, or `undefined`.
+* @returns The stroke style, or `undefined` when nothing should be stroked.
+*/
 function buildStroke(line) {
 	if (!line || line.fill === "none") return void 0;
 	const widthPt = line.width ?? DEFAULT_LINE_WIDTH_EMU / 12700;
@@ -70,6 +109,21 @@ function dashPattern(dash, w) {
 		case "sysDot": return [u, u];
 	}
 }
+/**
+* Build the 2×3 affine placement matrix `[a, b, c, d, e, f]` that positions a
+* shape's local y-up box at `(pageX, pageY)`, applying rotation and h/v flips
+* about the box centre. DrawingML `rot` is clockwise in y-down space ⇒ a
+* negative angle in PDF y-up.
+*
+* @param pageX       Box left, in page points.
+* @param pageY       Box bottom, in page points.
+* @param widthPt     Box width in points.
+* @param heightPt    Box height in points.
+* @param rotation60k Rotation in 1/60000°, clockwise.
+* @param flipH       Mirror horizontally.
+* @param flipV       Mirror vertically.
+* @returns The affine matrix as `[a, b, c, d, e, f]`.
+*/
 function buildShapeTransform(pageX, pageY, widthPt, heightPt, rotation60k, flipH, flipV) {
 	const theta = -rotation60k / 6e4 * (Math.PI / 180);
 	const sx = flipH ? -1 : 1;

package/dist/esm/core/drawingml/sparkline-geometry.d.ts

@@ -1,8 +1,23 @@
 import { StrokeStyle, VectorPath } from '../vector.js';
+/** The sparkline type: a trend `line`, a `column` bar chart, or `winLoss` bars. */
 export type SparklineKind = 'line' | 'column' | 'winLoss';
+/** One drawable layer of a sparkline: paths sharing a fill and/or stroke. */
 export interface SparklinePrim {
     readonly paths: ReadonlyArray<VectorPath>;
     readonly fillColorHex?: string;
     readonly stroke?: StrokeStyle;
 }
+/**
+ * Build sparkline primitives (E-SHEET SC2) for a single cell in a local y-up
+ * `[0,width]×[0,height]` frame — a bare trend glyph with no axes, legend or
+ * labels. Gaps (`null`) break a line and skip a bar while preserving the slot.
+ * Returns an empty array for a non-positive box or an all-null series.
+ *
+ * @param kind     The sparkline type.
+ * @param values   The data points, in order; `null` marks a gap.
+ * @param width    Frame width in points.
+ * @param height   Frame height in points.
+ * @param colorHex Series colour (RRGGBB); defaults to Excel's sparkline blue.
+ * @returns The drawable layers (win/loss yields separate win and loss layers).
+ */
 export declare function buildSparkline(kind: SparklineKind, values: ReadonlyArray<number | null>, width: number, height: number, colorHex?: string): Array<SparklinePrim>;

package/dist/esm/core/drawingml/sparkline-geometry.js

@@ -2,6 +2,19 @@ import { PathBuilder } from "../vector.js";
 //#region src/core/drawingml/sparkline-geometry.ts
 var DEFAULT_SERIES_HEX = "376092";
 var LOSS_HEX = "D00000";
+/**
+* Build sparkline primitives (E-SHEET SC2) for a single cell in a local y-up
+* `[0,width]×[0,height]` frame — a bare trend glyph with no axes, legend or
+* labels. Gaps (`null`) break a line and skip a bar while preserving the slot.
+* Returns an empty array for a non-positive box or an all-null series.
+*
+* @param kind     The sparkline type.
+* @param values   The data points, in order; `null` marks a gap.
+* @param width    Frame width in points.
+* @param height   Frame height in points.
+* @param colorHex Series colour (RRGGBB); defaults to Excel's sparkline blue.
+* @returns The drawable layers (win/loss yields separate win and loss layers).
+*/
 function buildSparkline(kind, values, width, height, colorHex) {
 	if (width <= 0 || height <= 0 || values.every((v) => v === null)) return [];
 	const color = colorHex ?? DEFAULT_SERIES_HEX;

package/dist/esm/core/drawingml/theme-parser.d.ts

@@ -1 +1,12 @@
+/**
+ * Parse a DrawingML theme part (ECMA-376 §20.1.6.2, `a:clrScheme`) into a
+ * `name → hex` colour map. Reads the twelve scheme slots — `dk1`/`lt1`/`dk2`/
+ * `lt2`, `accent1`–`accent6`, `hlink`/`folHlink` — taking each slot's
+ * `a:srgbClr@val` or, for a system colour, its resolved `a:sysClr@lastClr`.
+ * Unknown slots and slots with no resolvable colour are skipped.
+ *
+ * @param themeXml The raw `word/theme/theme1.xml` (or sibling) bytes, UTF-8.
+ * @returns A map keyed by slot name (`'accent1'`, …) to uppercase RRGGBB hex;
+ *          empty when no `a:clrScheme` is present.
+ */
 export declare function parseTheme(themeXml: Uint8Array): Map<string, string>;

package/dist/esm/core/drawingml/theme-parser.js

@@ -24,6 +24,17 @@ var SCHEME_SLOTS = new Set([
 	"hlink",
 	"folHlink"
 ]);
+/**
+* Parse a DrawingML theme part (ECMA-376 §20.1.6.2, `a:clrScheme`) into a
+* `name → hex` colour map. Reads the twelve scheme slots — `dk1`/`lt1`/`dk2`/
+* `lt2`, `accent1`–`accent6`, `hlink`/`folHlink` — taking each slot's
+* `a:srgbClr@val` or, for a system colour, its resolved `a:sysClr@lastClr`.
+* Unknown slots and slots with no resolvable colour are skipped.
+*
+* @param themeXml The raw `word/theme/theme1.xml` (or sibling) bytes, UTF-8.
+* @returns A map keyed by slot name (`'accent1'`, …) to uppercase RRGGBB hex;
+*          empty when no `a:clrScheme` is present.
+*/
 function parseTheme(themeXml) {
 	const out = /* @__PURE__ */ new Map();
 	const clrScheme = poFindByPath(parser.parse(decoder.decode(themeXml)), [

package/dist/esm/core/font/arabic-joining.d.ts

@@ -1,4 +1,25 @@
+/**
+ * A character's Arabic joining class (ArabicShaping.txt): Right-, Left-,
+ * Dual-joining, join-Causing, Non-joining, or Transparent (combining marks).
+ */
 export type JoiningType = 'R' | 'L' | 'D' | 'C' | 'U' | 'T';
+/** The contextual cursive form a letter takes: isolated, initial, medial or final. */
 export type ArabicForm = 'isol' | 'init' | 'medi' | 'fina';
+/**
+ * Classify a code point's Arabic {@link JoiningType}. Covers the standard Arabic
+ * block plus tatweel and the ZWJ/ZWNJ controls; everything else is non-joining.
+ *
+ * @param cp The Unicode code point.
+ * @returns Its joining type.
+ */
 export declare function arabicJoiningType(cp: number): JoiningType;
+/**
+ * Assign a cursive {@link ArabicForm} to each code point in a run, from the
+ * joining types of the surrounding letters (transparent marks are skipped).
+ * Non-joining characters get `'isol'` — a harmless default, since their glyph is
+ * never in the positional maps.
+ *
+ * @param cps The run's code points, in logical order.
+ * @returns The per-code-point form, parallel to `cps`.
+ */
 export declare function assignArabicForms(cps: ReadonlyArray<number>): Array<ArabicForm>;

package/dist/esm/core/font/arabic-joining.js

@@ -56,6 +56,13 @@ var RIGHT_JOINING = new Set([
 function isTransparentMark(cp) {
 	return cp >= 1552 && cp <= 1562 || cp >= 1611 && cp <= 1631 || cp === 1648 || cp >= 1750 && cp <= 1756 || cp >= 1759 && cp <= 1764 || cp === 1767 || cp === 1768 || cp >= 1770 && cp <= 1773;
 }
+/**
+* Classify a code point's Arabic {@link JoiningType}. Covers the standard Arabic
+* block plus tatweel and the ZWJ/ZWNJ controls; everything else is non-joining.
+*
+* @param cp The Unicode code point.
+* @returns Its joining type.
+*/
 function arabicJoiningType(cp) {
 	if (cp === 1600) return "C";
 	if (cp === 8205) return "C";
@@ -67,6 +74,15 @@ function arabicJoiningType(cp) {
 }
 var canJoinRight = (t) => t === "R" || t === "D" || t === "C";
 var canJoinLeft = (t) => t === "L" || t === "D" || t === "C";
+/**
+* Assign a cursive {@link ArabicForm} to each code point in a run, from the
+* joining types of the surrounding letters (transparent marks are skipped).
+* Non-joining characters get `'isol'` — a harmless default, since their glyph is
+* never in the positional maps.
+*
+* @param cps The run's code points, in logical order.
+* @returns The per-code-point form, parallel to `cps`.
+*/
 function assignArabicForms(cps) {
 	const types = cps.map(arabicJoiningType);
 	const forms = new Array(cps.length).fill("isol");

package/dist/esm/core/font/binary-reader.d.ts

@@ -1,13 +1,30 @@
+/**
+ * A cursor over a byte buffer that reads big-endian integers — the byte order
+ * TrueType / OpenType (ISO/IEC 14496-22) files use for every multi-byte value.
+ * Each read advances {@link BigEndianReader.offset}.
+ */
 export declare class BigEndianReader {
     readonly data: Uint8Array;
     offset: number;
+    /**
+     * @param data   The buffer to read from.
+     * @param offset The starting byte offset (default 0).
+     */
     constructor(data: Uint8Array, offset?: number);
+    /** Move the cursor to an absolute byte offset. */
     seek(offset: number): void;
+    /** Advance the cursor by `bytes` without reading. */
     skip(bytes: number): void;
+    /** Read an unsigned 8-bit integer; advances 1 byte. */
     u8(): number;
+    /** Read an unsigned 16-bit big-endian integer; advances 2 bytes. */
     u16(): number;
+    /** Read a signed 16-bit big-endian integer; advances 2 bytes. */
     i16(): number;
+    /** Read an unsigned 32-bit big-endian integer; advances 4 bytes. */
     u32(): number;
+    /** Read a signed 32-bit big-endian integer; advances 4 bytes. */
     i32(): number;
+    /** Read a 4-byte ASCII tag (e.g. a TrueType table tag); advances 4 bytes. */
     tag(): string;
 }

package/dist/esm/core/font/binary-reader.js

@@ -1,38 +1,55 @@
 //#region src/core/font/binary-reader.ts
+/**
+* A cursor over a byte buffer that reads big-endian integers — the byte order
+* TrueType / OpenType (ISO/IEC 14496-22) files use for every multi-byte value.
+* Each read advances {@link BigEndianReader.offset}.
+*/
 var BigEndianReader = class {
+	/**
+	* @param data   The buffer to read from.
+	* @param offset The starting byte offset (default 0).
+	*/
 	constructor(data, offset = 0) {
 		this.data = data;
 		this.offset = offset;
 	}
+	/** Move the cursor to an absolute byte offset. */
 	seek(offset) {
 		this.offset = offset;
 	}
+	/** Advance the cursor by `bytes` without reading. */
 	skip(bytes) {
 		this.offset += bytes;
 	}
+	/** Read an unsigned 8-bit integer; advances 1 byte. */
 	u8() {
 		return this.data[this.offset++];
 	}
+	/** Read an unsigned 16-bit big-endian integer; advances 2 bytes. */
 	u16() {
 		const d = this.data;
 		const p = this.offset;
 		this.offset += 2;
 		return d[p] << 8 | d[p + 1];
 	}
+	/** Read a signed 16-bit big-endian integer; advances 2 bytes. */
 	i16() {
 		const v = this.u16();
 		return v >= 32768 ? v - 65536 : v;
 	}
+	/** Read an unsigned 32-bit big-endian integer; advances 4 bytes. */
 	u32() {
 		const d = this.data;
 		const p = this.offset;
 		this.offset += 4;
 		return d[p] * 16777216 + (d[p + 1] << 16 | d[p + 2] << 8 | d[p + 3]);
 	}
+	/** Read a signed 32-bit big-endian integer; advances 4 bytes. */
 	i32() {
 		const v = this.u32();
 		return v >= 2147483648 ? v - 4294967296 : v;
 	}
+	/** Read a 4-byte ASCII tag (e.g. a TrueType table tag); advances 4 bytes. */
 	tag() {
 		const d = this.data;
 		const p = this.offset;

package/dist/esm/core/font/font-registry.d.ts

@@ -1,20 +1,57 @@
 import { ParsedTtf } from './ttf-parser.js';
+/** A font style slot: regular, bold, italic or bold-italic. */
 export type FontVariant = 'regular' | 'bold' | 'italic' | 'boldItalic';
+/**
+ * The single owner of face fallback (oop-design §8, A4): the candidate cascade a
+ * missing variant degrades through (`boldItalic → bold → italic → regular`),
+ * shared by the registry and every font provider.
+ *
+ * @param has    Predicate — does a given variant exist?
+ * @param bold   Whether bold was requested.
+ * @param italic Whether italic was requested.
+ * @returns The best available variant, or `undefined` when even `regular` is missing.
+ */
 export declare function pickVariant(has: (variant: FontVariant) => boolean, bold: boolean, italic: boolean): FontVariant | undefined;
+/** Raw TTF/OTF bytes per style variant; only `regular` is required. */
 export interface FontBytesByVariant {
+    /** The regular (upright, normal-weight) face — required. */
     readonly regular: Uint8Array;
+    /** The bold face, if available. */
     readonly bold?: Uint8Array;
+    /** The italic face, if available. */
     readonly italic?: Uint8Array;
+    /** The bold-italic face, if available. */
     readonly boldItalic?: Uint8Array;
 }
+/**
+ * A registry of parsed font variants. The renderer resolves a `(bold, italic)`
+ * request to the closest available face via {@link pickVariant}, degrading
+ * through `bold → italic → regular` when an exact match is missing.
+ */
 export declare class FontRegistry {
     private readonly fonts;
     private constructor();
+    /**
+     * Parse a set of font bytes into a registry.
+     *
+     * @param input The bytes per variant (`regular` required).
+     * @returns A registry holding the parsed faces.
+     */
     static fromBytes(input: FontBytesByVariant): FontRegistry;
+    /**
+     * Resolve a style request to the closest available face.
+     *
+     * @param bold   Whether bold was requested.
+     * @param italic Whether italic was requested.
+     * @returns The chosen variant and its parsed font.
+     * @throws Error when the registry has no usable (regular) font.
+     */
     resolveByStyle(bold: boolean, italic: boolean): {
         variant: FontVariant;
         parsed: ParsedTtf;
     };
+    /** Iterate the `[variant, parsed font]` pairs the registry holds. */
     entries(): IterableIterator<[FontVariant, ParsedTtf]>;
+    /** Whether a given variant is present. */
     hasVariant(v: FontVariant): boolean;
 }

package/dist/esm/core/font/font-registry.js

@@ -1,5 +1,15 @@
 import { parseTtf } from "./ttf-parser.js";
 //#region src/core/font/font-registry.ts
+/**
+* The single owner of face fallback (oop-design §8, A4): the candidate cascade a
+* missing variant degrades through (`boldItalic → bold → italic → regular`),
+* shared by the registry and every font provider.
+*
+* @param has    Predicate — does a given variant exist?
+* @param bold   Whether bold was requested.
+* @param italic Whether italic was requested.
+* @returns The best available variant, or `undefined` when even `regular` is missing.
+*/
 function pickVariant(has, bold, italic) {
 	return (bold && italic ? [
 		"boldItalic",
@@ -8,10 +18,21 @@ function pickVariant(has, bold, italic) {
 		"regular"
 	] : bold ? ["bold", "regular"] : italic ? ["italic", "regular"] : ["regular"]).find(has);
 }
+/**
+* A registry of parsed font variants. The renderer resolves a `(bold, italic)`
+* request to the closest available face via {@link pickVariant}, degrading
+* through `bold → italic → regular` when an exact match is missing.
+*/
 var FontRegistry = class FontRegistry {
 	constructor(fonts) {
 		this.fonts = fonts;
 	}
+	/**
+	* Parse a set of font bytes into a registry.
+	*
+	* @param input The bytes per variant (`regular` required).
+	* @returns A registry holding the parsed faces.
+	*/
 	static fromBytes(input) {
 		const map = /* @__PURE__ */ new Map();
 		map.set("regular", parseTtf(input.regular));
@@ -20,6 +41,14 @@ var FontRegistry = class FontRegistry {
 		if (input.boldItalic) map.set("boldItalic", parseTtf(input.boldItalic));
 		return new FontRegistry(map);
 	}
+	/**
+	* Resolve a style request to the closest available face.
+	*
+	* @param bold   Whether bold was requested.
+	* @param italic Whether italic was requested.
+	* @returns The chosen variant and its parsed font.
+	* @throws Error when the registry has no usable (regular) font.
+	*/
 	resolveByStyle(bold, italic) {
 		const variant = pickVariant((v) => this.fonts.has(v), bold, italic);
 		const parsed = variant ? this.fonts.get(variant) : void 0;
@@ -29,9 +58,11 @@ var FontRegistry = class FontRegistry {
 			parsed
 		};
 	}
+	/** Iterate the `[variant, parsed font]` pairs the registry holds. */
 	entries() {
 		return this.fonts.entries();
 	}
+	/** Whether a given variant is present. */
 	hasVariant(v) {
 		return this.fonts.has(v);
 	}

package/dist/esm/core/font/measure.d.ts

@@ -1,7 +1,27 @@
 import { ParsedTtf } from './ttf-parser.js';
+/**
+ * Text measurement and glyph encoding derived purely from a parsed font (no PDF
+ * involved). Layout measures with these, and the PDF emitter reuses the same
+ * functions, so emit encodes exactly what layout measured. CIDs are GIDs
+ * (Identity ordering), so the hex encoding is writer-agnostic glyph addressing.
+ */
 export interface FontMeasure {
+    /** Glyph advance width in 1000-unit PDF text space, for a glyph id. */
     readonly pdfWidthForGid: (gid: number) => number;
+    /** Shaped width of `text` at `fontSize`, in points. */
     readonly textWidthPt: (text: string, fontSize: number) => number;
+    /** Encode `text` as a hex string of 4-digit glyph ids (Identity-H addressing). */
     readonly encodeTextAsCidHex: (text: string) => string;
 }
+/**
+ * Build a {@link FontMeasure} over a parsed font.
+ *
+ * @param parsed The parsed TTF/OTF.
+ * @param kern   Whether to apply pair kerning to measured advances (E-PARITY
+ *               FP4). The default keeps it; the `'word'` layout profile turns it
+ *               off (Word leaves font kerning off by default, and Ream's `Tj`
+ *               output is un-kerned anyway). Glyph identity is kern-independent,
+ *               so only the widths change.
+ * @returns The measurement / encoding closures.
+ */
 export declare function createFontMeasure(parsed: ParsedTtf, kern?: boolean): FontMeasure;

package/dist/esm/core/font/measure.js

@@ -1,6 +1,17 @@
 import { shapeText } from "./opentype-layout.js";
 //#region src/core/font/measure.ts
 var EMPTY_KERNING = /* @__PURE__ */ new Map();
+/**
+* Build a {@link FontMeasure} over a parsed font.
+*
+* @param parsed The parsed TTF/OTF.
+* @param kern   Whether to apply pair kerning to measured advances (E-PARITY
+*               FP4). The default keeps it; the `'word'` layout profile turns it
+*               off (Word leaves font kerning off by default, and Ream's `Tj`
+*               output is un-kerned anyway). Glyph identity is kern-independent,
+*               so only the widths change.
+* @returns The measurement / encoding closures.
+*/
 function createFontMeasure(parsed, kern = true) {
 	const scale = 1e3 / parsed.unitsPerEm;
 	const kerning = kern ? parsed.kerning : EMPTY_KERNING;