reamkit 1.15.0 → 1.15.2

package/dist/esm/core/font/opentype-layout.d.ts

@@ -1,21 +1,70 @@
+/** GSUB ligature substitutions: a comma-joined input GID sequence → output GID. */
 export type LigatureMap = ReadonlyMap<string, number>;
+/** GPOS pair kerning: `"gid1,gid2"` → advance adjustment in font units. */
 export type KerningMap = ReadonlyMap<string, number>;
+/**
+ * GSUB single-substitution maps (gid → positional gid) for the Arabic cursive
+ * features init / medi / fina. Empty for fonts without Arabic shaping.
+ */
 export interface ArabicJoiningForms {
+    /** Initial-form substitutions. */
     readonly init: ReadonlyMap<number, number>;
+    /** Medial-form substitutions. */
     readonly medi: ReadonlyMap<number, number>;
+    /** Final-form substitutions. */
     readonly fina: ReadonlyMap<number, number>;
 }
+/** An {@link ArabicJoiningForms} with no substitutions (a non-Arabic font). */
 export declare const EMPTY_JOINING_FORMS: ArabicJoiningForms;
 interface TableInfo {
     readonly offset: number;
     readonly length: number;
 }
+/**
+ * Parse a GSUB table and return only the `liga`/`clig` ligature substitutions.
+ *
+ * @param raw   The whole font bytes.
+ * @param table The GSUB table location, or `undefined` when the font has none.
+ * @returns The ligature map (empty when absent or on any parse error).
+ */
 export declare function parseGsubLigatures(raw: Uint8Array, table: TableInfo | undefined): LigatureMap;
+/**
+ * Parse a GPOS table and return only the `kern` pair-positioning lookup.
+ *
+ * @param raw   The whole font bytes.
+ * @param table The GPOS table location, or `undefined` when the font has none.
+ * @returns The kerning map keyed on `"gid1,gid2"` (empty when absent or on error).
+ */
 export declare function parseGposKerning(raw: Uint8Array, table: TableInfo | undefined): KerningMap;
+/**
+ * Parse GSUB single substitutions (Lookup Type 1) for the Arabic positional
+ * features. Each of init/medi/fina yields a gid → gid map the shaper applies per
+ * cursive form.
+ *
+ * @param raw   The whole font bytes.
+ * @param table The GSUB table location, or `undefined` when the font has none.
+ * @returns The per-form joining maps (empty when absent or on error).
+ */
 export declare function parseGsubArabicForms(raw: Uint8Array, table: TableInfo | undefined): ArabicJoiningForms;
+/** The result of {@link shapeText}: output glyph ids and their advances. */
 export interface ShapedRun {
+    /** Output glyph ids, after ligature, kerning and Arabic-joining substitution. */
     readonly gids: Array<number>;
+    /** Font-unit advance per output gid (parallel to `gids`). */
     readonly advances: Array<number>;
 }
+/**
+ * Shape a string into glyphs: map characters to GIDs, apply Arabic cursive
+ * joining, then ligature substitution and pair kerning, returning the output
+ * glyph ids with their font-unit advances.
+ *
+ * @param text              The text to shape.
+ * @param glyphForCodepoint Codepoint → glyph id (from the font's cmap).
+ * @param advanceWidths     Per-glyph advance widths (font units).
+ * @param ligatures         GSUB ligature map.
+ * @param kerning           GPOS pair-kerning map.
+ * @param joiningForms      Arabic init/medi/fina maps (default: none).
+ * @returns The shaped run (gids + advances).
+ */
 export declare function shapeText(text: string, glyphForCodepoint: (cp: number) => number, advanceWidths: ReadonlyArray<number>, ligatures: LigatureMap, kerning: KerningMap, joiningForms?: ArabicJoiningForms): ShapedRun;
 export {};

package/dist/esm/core/font/opentype-layout.js

@@ -1,11 +1,19 @@
 import { BigEndianReader } from "./binary-reader.js";
 import { assignArabicForms } from "./arabic-joining.js";
 //#region src/core/font/opentype-layout.ts
+/** An {@link ArabicJoiningForms} with no substitutions (a non-Arabic font). */
 var EMPTY_JOINING_FORMS = {
 	init: /* @__PURE__ */ new Map(),
 	medi: /* @__PURE__ */ new Map(),
 	fina: /* @__PURE__ */ new Map()
 };
+/**
+* Parse a GSUB table and return only the `liga`/`clig` ligature substitutions.
+*
+* @param raw   The whole font bytes.
+* @param table The GSUB table location, or `undefined` when the font has none.
+* @returns The ligature map (empty when absent or on any parse error).
+*/
 function parseGsubLigatures(raw, table) {
 	if (!table) return /* @__PURE__ */ new Map();
 	try {
@@ -19,6 +27,13 @@ function parseGsubLigatures(raw, table) {
 		return /* @__PURE__ */ new Map();
 	}
 }
+/**
+* Parse a GPOS table and return only the `kern` pair-positioning lookup.
+*
+* @param raw   The whole font bytes.
+* @param table The GPOS table location, or `undefined` when the font has none.
+* @returns The kerning map keyed on `"gid1,gid2"` (empty when absent or on error).
+*/
 function parseGposKerning(raw, table) {
 	if (!table) return /* @__PURE__ */ new Map();
 	try {
@@ -32,6 +47,15 @@ function parseGposKerning(raw, table) {
 		return /* @__PURE__ */ new Map();
 	}
 }
+/**
+* Parse GSUB single substitutions (Lookup Type 1) for the Arabic positional
+* features. Each of init/medi/fina yields a gid → gid map the shaper applies per
+* cursive form.
+*
+* @param raw   The whole font bytes.
+* @param table The GSUB table location, or `undefined` when the font has none.
+* @returns The per-form joining maps (empty when absent or on error).
+*/
 function parseGsubArabicForms(raw, table) {
 	if (!table) return EMPTY_JOINING_FORMS;
 	try {
@@ -286,6 +310,19 @@ function matchingGlyphs(coverage, classMap, cls) {
 	for (const [gid, c] of classMap) if (c === cls) out.push(gid);
 	return out;
 }
+/**
+* Shape a string into glyphs: map characters to GIDs, apply Arabic cursive
+* joining, then ligature substitution and pair kerning, returning the output
+* glyph ids with their font-unit advances.
+*
+* @param text              The text to shape.
+* @param glyphForCodepoint Codepoint → glyph id (from the font's cmap).
+* @param advanceWidths     Per-glyph advance widths (font units).
+* @param ligatures         GSUB ligature map.
+* @param kerning           GPOS pair-kerning map.
+* @param joiningForms      Arabic init/medi/fina maps (default: none).
+* @returns The shaped run (gids + advances).
+*/
 function shapeText(text, glyphForCodepoint, advanceWidths, ligatures, kerning, joiningForms = EMPTY_JOINING_FORMS) {
 	const cps = [];
 	for (const ch of text) cps.push(ch.codePointAt(0));

package/dist/esm/core/font/ttf-parser.d.ts

@@ -1,8 +1,17 @@
 import { ArabicJoiningForms, KerningMap, LigatureMap } from './opentype-layout.js';
+/** A table's location within the sfnt: byte offset and length. */
 export interface TtfTableInfo {
+    /** Byte offset of the table from the start of the file. */
     readonly offset: number;
+    /** Table length in bytes. */
     readonly length: number;
 }
+/**
+ * A parsed TrueType / OpenType font (ISO/IEC 14496-22): metrics, the
+ * cmap-derived codepoint→glyph mapping, OpenType layout maps (ligatures,
+ * kerning, Arabic joining) and the raw bytes for embedding. Glyph outlines
+ * (glyf/CFF) are not decoded — the whole font is embedded in the PDF /FontFile2.
+ */
 export interface ParsedTtf {
     readonly raw: Uint8Array;
     readonly sfntVersion: number;
@@ -12,9 +21,19 @@ export interface ParsedTtf {
     readonly fontBBox: readonly [number, number, number, number];
     readonly ascender: number;
     readonly descender: number;
+    /**
+     * hhea line gap (font units); with ascender/descender it forms the hhea
+     * vertical triple that drives the `'libreoffice'` line-height profile (E-PARITY).
+     */
     readonly lineGap: number;
     readonly capHeight: number;
     readonly xHeight: number;
+    /**
+     * E-PARITY line-height metrics: OS/2 win/typo verticals (font units) selected
+     * by layout profile. `'word'` uses winAscent/winDescent (the GDI cell box);
+     * `'libreoffice'` uses the hhea triple above, or typo* when `useTypoMetrics` is
+     * set. All fall back to hhea when the font has no OS/2 table.
+     */
     readonly vmetrics: {
         readonly typoAscent: number;
         readonly typoDescent: number;
@@ -31,8 +50,21 @@ export interface ParsedTtf {
     readonly glyphOffsets: ReadonlyArray<number>;
     readonly advanceWidths: ReadonlyArray<number>;
     readonly glyphForCodepoint: (cp: number) => number;
+    /** OpenType ligature substitutions: input GID sequence `"gid1,gid2[,gid3…]"` → output GID. */
     readonly ligatures: LigatureMap;
+    /** OpenType pair kerning: `"gid1,gid2"` → advance adjustment in font units. */
     readonly kerning: KerningMap;
+    /**
+     * Arabic cursive-joining substitutions (init/medi/fina). Empty for non-Arabic
+     * fonts, so the shaper leaves output unchanged.
+     */
     readonly joiningForms: ArabicJoiningForms;
 }
+/**
+ * Parse TrueType / OpenType font bytes into a {@link ParsedTtf}.
+ *
+ * @param raw The font bytes (sfnt: TrueType `0x00010000` or OpenType-CFF `OTTO`).
+ * @returns The parsed metrics, mappings and layout tables.
+ * @throws Error when the bytes are not a TrueType or OpenType font.
+ */
 export declare function parseTtf(raw: Uint8Array): ParsedTtf;

package/dist/esm/core/font/ttf-parser.js

@@ -3,6 +3,13 @@ import { parseGposKerning, parseGsubArabicForms, parseGsubLigatures } from "./op
 //#region src/core/font/ttf-parser.ts
 var SFNT_TRUETYPE = 65536;
 var SFNT_OPENTYPE_CFF = 1330926671;
+/**
+* Parse TrueType / OpenType font bytes into a {@link ParsedTtf}.
+*
+* @param raw The font bytes (sfnt: TrueType `0x00010000` or OpenType-CFF `OTTO`).
+* @returns The parsed metrics, mappings and layout tables.
+* @throws Error when the bytes are not a TrueType or OpenType font.
+*/
 function parseTtf(raw) {
 	const r = new BigEndianReader(raw);
 	const sfntVersion = r.u32();

package/dist/esm/core/font/ttf-subset.d.ts

@@ -1,3 +1,24 @@
 import { ParsedTtf } from './ttf-parser.js';
+/**
+ * Subset a TrueType font to the glyphs in `usedGids` (plus their composite
+ * components and GID 0). All tables are kept intact so the CIDFontType2
+ * `/CIDToGIDMap /Identity` contract holds; only `glyf`/`loca` are rebuilt, with
+ * unused glyphs zero-length.
+ *
+ * @param parsed   The parsed source font (must have `glyf` + `loca`).
+ * @param usedGids The glyph ids actually used.
+ * @returns The subset font bytes.
+ * @throws Error when the font has no `glyf`/`loca` (e.g. a CFF/OTF font).
+ */
 export declare function subsetTtf(parsed: ParsedTtf, usedGids: Iterable<number>): Uint8Array;
+/**
+ * The glyph ids actually present in a subset for `usedGids`: the seeds, their
+ * composite components (transitively) and GID 0. With Identity CID↔GID this is
+ * exactly the CID set of the embedded subset, used to build the PDF/A `/CIDSet`
+ * (ISO 19005-1 §6.3.5). Mirrors {@link subsetTtf}'s own closure.
+ *
+ * @param parsed   The parsed font.
+ * @param usedGids The seed glyph ids.
+ * @returns The closed set of glyph ids.
+ */
 export declare function glyphClosure(parsed: ParsedTtf, usedGids: Iterable<number>): Set<number>;

package/dist/esm/core/font/ttf-subset.js

@@ -7,6 +7,17 @@ var COMPOSITE_WE_HAVE_A_SCALE = 8;
 var COMPOSITE_MORE_COMPONENTS = 32;
 var COMPOSITE_WE_HAVE_AN_X_AND_Y_SCALE = 64;
 var COMPOSITE_WE_HAVE_A_TWO_BY_TWO = 128;
+/**
+* Subset a TrueType font to the glyphs in `usedGids` (plus their composite
+* components and GID 0). All tables are kept intact so the CIDFontType2
+* `/CIDToGIDMap /Identity` contract holds; only `glyf`/`loca` are rebuilt, with
+* unused glyphs zero-length.
+*
+* @param parsed   The parsed source font (must have `glyf` + `loca`).
+* @param usedGids The glyph ids actually used.
+* @returns The subset font bytes.
+* @throws Error when the font has no `glyf`/`loca` (e.g. a CFF/OTF font).
+*/
 function subsetTtf(parsed, usedGids) {
 	const glyf = parsed.tables.get("glyf");
 	const loca = parsed.tables.get("loca");
@@ -14,6 +25,16 @@ function subsetTtf(parsed, usedGids) {
 	const { newGlyf, newLoca } = rewriteGlyfLoca(parsed, glyf, computeGlyphClosure(parsed, glyf, usedGids));
 	return assembleSubsetTtf(parsed, newGlyf, newLoca);
 }
+/**
+* The glyph ids actually present in a subset for `usedGids`: the seeds, their
+* composite components (transitively) and GID 0. With Identity CID↔GID this is
+* exactly the CID set of the embedded subset, used to build the PDF/A `/CIDSet`
+* (ISO 19005-1 §6.3.5). Mirrors {@link subsetTtf}'s own closure.
+*
+* @param parsed   The parsed font.
+* @param usedGids The seed glyph ids.
+* @returns The closed set of glyph ids.
+*/
 function glyphClosure(parsed, usedGids) {
 	const glyf = parsed.tables.get("glyf");
 	if (!glyf) return new Set([0, ...usedGids]);

package/dist/esm/core/fonts/provider.d.ts

@@ -1,11 +1,15 @@
 import { FetchLike } from './remote-fonts.js';
 import { FontBytesByVariant, FontRegistry } from '../font/index.js';
+/** A font resolution request: the wanted family and style. */
 export interface FontRequest {
     /** Family name as the document references it (e.g. "Times New Roman"). */
     readonly family?: string;
+    /** Whether a bold face is wanted. */
     readonly bold: boolean;
+    /** Whether an italic face is wanted. */
     readonly italic: boolean;
 }
+/** A provider's answer: resolved bytes, or `none` to fall through to the next provider. */
 export type FontAnswer = {
     readonly kind: 'bytes';
     readonly bytes: Uint8Array;
@@ -16,10 +20,13 @@ export type FontAnswer = {
 } | {
     readonly kind: 'none';
 };
+/** The shared `none` answer — a provider that cannot satisfy a request. */
 export declare const NO_FONT: FontAnswer;
+/** One stage in the font-resolution chain (ir-design §8). */
 export interface FontProvider {
-    /** 'embedded' | 'caller' | 'local' | 'remote' | custom ids. */
+    /** Provider id: `'embedded'` | `'caller'` | `'local'` | `'remote'` | a custom id. */
     readonly id: string;
+    /** Resolve a request to bytes, or {@link NO_FONT} to defer to the next provider. */
     resolve: (req: FontRequest) => Promise<FontAnswer>;
 }
 /** First byte-level answer wins; 'none' falls through to the next provider. */

package/dist/esm/core/fonts/provider.js

@@ -1,6 +1,7 @@
 import { fetchFontSet, resolveFamilyKey } from "./remote-fonts.js";
 import { pickVariant } from "../font/font-registry.js";
 //#region src/core/fonts/provider.ts
+/** The shared `none` answer — a provider that cannot satisfy a request. */
 var NO_FONT = { kind: "none" };
 /** First byte-level answer wins; 'none' falls through to the next provider. */
 function chainProviders(providers) {

package/dist/esm/core/fonts/remote-fonts.d.ts

@@ -1,13 +1,35 @@
 import { FontBytesByVariant } from '../font/index.js';
+/** A curated open substitute family (the Croscore + Carlito/Caladea set, like LibreOffice). */
 export type FamilyKey = 'arimo' | 'tinos' | 'cousine' | 'carlito' | 'caladea';
+/**
+ * Map a document-referenced font family to a curated open substitute: an exact
+ * metric twin when one is known (e.g. Calibri → Carlito), otherwise a
+ * serif/mono/sans style fallback.
+ *
+ * @param name The referenced family name (case-insensitive); empty ⇒ Arimo.
+ * @returns The chosen {@link FamilyKey}.
+ */
 export declare function resolveFamilyKey(name: string | undefined): FamilyKey;
+/** A minimal `fetch`-like function (injectable for tests / offline use). */
 export type FetchLike = (url: string) => Promise<{
     ok: boolean;
     arrayBuffer: () => Promise<ArrayBuffer>;
 }>;
+/** Options for {@link fetchFontSet}. */
 export interface FetchFontSetOptions {
+    /** Document font family name to substitute, or a curated {@link FamilyKey} directly. */
     readonly family?: string | FamilyKey;
+    /** Injectable fetch (defaults to the global `fetch`); lets tests run offline. */
     readonly fetch?: FetchLike;
 }
+/**
+ * Download a full variant set (regular required; bold/italic/bold-italic
+ * best-effort) for the open family that best matches the requested name.
+ *
+ * @param options The family to substitute and an optional fetch override.
+ * @returns The downloaded font bytes per variant.
+ * @throws Error when the required regular face cannot be downloaded.
+ */
 export declare function fetchFontSet(options?: FetchFontSetOptions): Promise<FontBytesByVariant>;
+/** Test / diagnostic helper: clear the in-memory font-download cache. */
 export declare function clearFontCache(): void;

package/dist/esm/core/fonts/remote-fonts.js

@@ -59,6 +59,14 @@ var MONO = new Set([
 	"dejavu sans mono",
 	"monospace"
 ]);
+/**
+* Map a document-referenced font family to a curated open substitute: an exact
+* metric twin when one is known (e.g. Calibri → Carlito), otherwise a
+* serif/mono/sans style fallback.
+*
+* @param name The referenced family name (case-insensitive); empty ⇒ Arimo.
+* @returns The chosen {@link FamilyKey}.
+*/
 function resolveFamilyKey(name) {
 	if (!name) return "arimo";
 	const n = name.trim().toLowerCase();
@@ -95,6 +103,14 @@ async function fetchTtf(url, fetchImpl, required) {
 	}
 	return result;
 }
+/**
+* Download a full variant set (regular required; bold/italic/bold-italic
+* best-effort) for the open family that best matches the requested name.
+*
+* @param options The family to substitute and an optional fetch override.
+* @returns The downloaded font bytes per variant.
+* @throws Error when the required regular face cannot be downloaded.
+*/
 async function fetchFontSet(options = {}) {
 	const fetchImpl = options.fetch ?? ((url) => fetch(url));
 	const family = FAMILIES[options.family && options.family in FAMILIES ? options.family : resolveFamilyKey(options.family)];

package/dist/esm/core/hyphenation/index.d.ts

@@ -1,10 +1,35 @@
 import { Hyphenator } from './liang.js';
 export type { Hyphenator, HyphenatorOptions } from './liang.js';
 export { createHyphenator, splitPatternBundle } from './liang.js';
+/** A language for which bundled hyphenation patterns exist. */
 export type SupportedLanguage = 'en-us' | 'ru';
+/**
+ * Lazily build (and cache) a language's {@link Hyphenator}. The patterns module
+ * is dynamically imported the first time a language is requested, so callers
+ * that never hyphenate pay no cold-start cost.
+ *
+ * @param language The language to load.
+ * @returns The cached hyphenator.
+ */
 export declare function getHyphenator(language: SupportedLanguage): Promise<Hyphenator>;
+/**
+ * Synchronous variant of {@link getHyphenator}: build a {@link Hyphenator} from
+ * already-loaded pattern strings (useful when patterns are bundled or fetched
+ * out-of-band).
+ *
+ * @param language The language (selects the left/right minimums).
+ * @param bundle   The pattern and optional exception strings.
+ * @returns The hyphenator.
+ */
 export declare function createLanguageHyphenator(language: SupportedLanguage, bundle: {
     patterns: string;
     exceptions?: string;
 }): Hyphenator;
+/**
+ * Alias of {@link getHyphenator} — load a hyphenator for `language` using the
+ * patterns bundled with this package.
+ *
+ * @param language The language to load.
+ * @returns The hyphenator.
+ */
 export declare function loadHyphenator(language: SupportedLanguage): Promise<Hyphenator>;

package/dist/esm/core/hyphenation/index.js

@@ -13,6 +13,14 @@ var REGISTRY = {
 	}
 };
 var cache = /* @__PURE__ */ new Map();
+/**
+* Lazily build (and cache) a language's {@link Hyphenator}. The patterns module
+* is dynamically imported the first time a language is requested, so callers
+* that never hyphenate pay no cold-start cost.
+*
+* @param language The language to load.
+* @returns The cached hyphenator.
+*/
 async function getHyphenator(language) {
 	const cached = cache.get(language);
 	if (cached) return cached;
@@ -26,6 +34,15 @@ async function getHyphenator(language) {
 	cache.set(language, h);
 	return h;
 }
+/**
+* Synchronous variant of {@link getHyphenator}: build a {@link Hyphenator} from
+* already-loaded pattern strings (useful when patterns are bundled or fetched
+* out-of-band).
+*
+* @param language The language (selects the left/right minimums).
+* @param bundle   The pattern and optional exception strings.
+* @returns The hyphenator.
+*/
 function createLanguageHyphenator(language, bundle) {
 	const desc = REGISTRY[language];
 	return createHyphenator(splitPatternBundle(bundle.patterns), {

package/dist/esm/core/hyphenation/liang.d.ts

@@ -1,10 +1,37 @@
+/** A configured hyphenator for one language. */
 export interface Hyphenator {
+    /**
+     * Return the 0-indexed break positions inside `word`. A position `p` means the
+     * word can be split between `word[p-1]` and `word[p]`; e.g. "computer" with
+     * breaks `[3,5]` → "com·pu·ter".
+     */
     hyphenate: (word: string) => Array<number>;
 }
+/** Options for {@link createHyphenator}. */
 export interface HyphenatorOptions {
+    /** Minimum characters before the first break (TeX default: 2). */
     readonly leftMin?: number;
+    /** Minimum characters after the last break (TeX default: 3 for English, often 2 elsewhere). */
     readonly rightMin?: number;
+    /**
+     * Explicit exceptions that override pattern output. Each is a word with
+     * hyphens marking the allowed breaks, e.g. `"as-so-ciate"`.
+     */
     readonly exceptions?: ReadonlyArray<string>;
 }
+/**
+ * Build a Liang pattern-based {@link Hyphenator} from a pattern list.
+ *
+ * @param patterns The TeX-style hyphenation patterns (e.g. `"hy3ph"`).
+ * @param options  Left/right minimums and explicit exceptions.
+ * @returns The hyphenator.
+ */
 export declare function createHyphenator(patterns: ReadonlyArray<string>, options?: HyphenatorOptions): Hyphenator;
+/**
+ * Split a TeX-style pattern bundle (a whitespace-separated string) into the
+ * pattern array {@link createHyphenator} expects.
+ *
+ * @param bundle The whitespace-separated patterns.
+ * @returns The pattern array (empty entries removed).
+ */
 export declare function splitPatternBundle(bundle: string): Array<string>;

package/dist/esm/core/hyphenation/liang.js

@@ -34,6 +34,13 @@ function insertPattern(root, pattern) {
 	}
 	node.weights = [...weights];
 }
+/**
+* Build a Liang pattern-based {@link Hyphenator} from a pattern list.
+*
+* @param patterns The TeX-style hyphenation patterns (e.g. `"hy3ph"`).
+* @param options  Left/right minimums and explicit exceptions.
+* @returns The hyphenator.
+*/
 function createHyphenator(patterns, options = {}) {
 	const root = makeNode();
 	for (const p of patterns) insertPattern(root, p);
@@ -72,6 +79,13 @@ function createHyphenator(patterns, options = {}) {
 		return breaks;
 	} };
 }
+/**
+* Split a TeX-style pattern bundle (a whitespace-separated string) into the
+* pattern array {@link createHyphenator} expects.
+*
+* @param bundle The whitespace-separated patterns.
+* @returns The pattern array (empty entries removed).
+*/
 function splitPatternBundle(bundle) {
 	return bundle.split(/\s+/).filter((s) => s.length > 0);
 }

package/dist/esm/core/images.d.ts

@@ -1,17 +1,49 @@
+/** The raster formats this module recognizes and can prepare for embedding. */
 export type ImageFormat = 'jpeg' | 'png' | 'jpeg2000';
+/**
+ * Sniff the raster format from a file's leading magic bytes (JPEG SOI, the PNG
+ * signature, or a JP2 box / raw JPEG 2000 codestream). Returns the
+ * {@link ImageFormat}, or `null` when none matches.
+ */
 export declare function detectImageFormat(bytes: Uint8Array): ImageFormat | null;
+/** Options controlling how {@link prepareImage} emits an image. */
 export interface EmbedImageOptions {
+    /**
+     * PDF/A-1 forbids transparency (soft masks). When true, PNG alpha is
+     * composited onto an opaque white background and no `/SMask` is emitted.
+     */
     readonly flattenAlpha?: boolean;
 }
+/**
+ * The ready-to-emit result of decoding and validating one image, from the
+ * prepare/add split (oop-design §3.1): {@link prepareImage} is the pure expert —
+ * decode, validate (throws on unsupported/corrupt input) and produce the
+ * stream bytes; `addImage` only creates the PDF objects. Layout probes with
+ * `prepareImage` (no throwaway document), the emit phase replays the prepared
+ * result, and other writers (SVG) reuse the mime/dimensions.
+ */
 export interface PreparedImage {
     readonly format: ImageFormat;
     readonly mimeType: 'image/jp2' | 'image/jpeg' | 'image/png';
     readonly widthPx: number;
     readonly heightPx: number;
+    /**
+     * ColorSpace/BitsPerComponent are absent for JPEG 2000 (carried inside the
+     * JPX codestream).
+     */
     readonly colorSpace?: 'DeviceGray' | 'DeviceRGB';
     readonly bitsPerComponent?: number;
+    /** The PDF stream filter the `data` bytes are encoded with. */
     readonly filter: 'DCTDecode' | 'FlateDecode' | 'JPXDecode';
     readonly data: Uint8Array;
+    /** PNG alpha channel, already FlateDecode-compressed (DeviceGray, 8 bpc). */
     readonly smaskData?: Uint8Array;
 }
+/**
+ * Decode and validate one image into a {@link PreparedImage} ready to embed.
+ * JPEG and JPEG 2000 pass through verbatim (readers decode them); PNG is
+ * inflated, de-filtered and re-compressed, splitting any alpha into a soft mask.
+ *
+ * @throws Error when the format is unrecognized, unsupported, or corrupt.
+ */
 export declare function prepareImage(bytes: Uint8Array, options?: EmbedImageOptions): PreparedImage;

package/dist/esm/core/images.js

@@ -1,5 +1,10 @@
 import { unzlibSync, zlibSync } from "fflate";
 //#region src/core/images.ts
+/**
+* Sniff the raster format from a file's leading magic bytes (JPEG SOI, the PNG
+* signature, or a JP2 box / raw JPEG 2000 codestream). Returns the
+* {@link ImageFormat}, or `null` when none matches.
+*/
 function detectImageFormat(bytes) {
 	if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "jpeg";
 	if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) return "png";
@@ -7,6 +12,13 @@ function detectImageFormat(bytes) {
 	if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 79 && bytes[2] === 255 && bytes[3] === 81) return "jpeg2000";
 	return null;
 }
+/**
+* Decode and validate one image into a {@link PreparedImage} ready to embed.
+* JPEG and JPEG 2000 pass through verbatim (readers decode them); PNG is
+* inflated, de-filtered and re-compressed, splitting any alpha into a soft mask.
+*
+* @throws Error when the format is unrecognized, unsupported, or corrupt.
+*/
 function prepareImage(bytes, options = {}) {
 	const format = detectImageFormat(bytes);
 	if (format === "jpeg") return prepareJpeg(bytes);

package/dist/esm/core/ir/adapters.d.ts

@@ -1,14 +1,25 @@
 import { Feature } from './features.js';
 import { FlowDoc } from './flow.js';
 import { LossReport } from './loss.js';
+/** Reader-call options. Open-ended; per-reader limits live in the readers. */
 export interface ReadOptions {
     /** Reserved for reader-specific knobs (limits live in the readers). */
     readonly [key: string]: unknown;
 }
+/** The result of {@link DocumentReader.read}: the parsed tree plus any losses. */
 export interface ReadResult<TDoc> {
+    /** The parsed document tree. */
     readonly doc: TDoc;
+    /** Losses recorded while reading. */
     readonly losses: LossReport;
 }
+/**
+ * A synchronous reader for one source format (ir-design §7). All async I/O —
+ * font fetching, resource loading — lives in the conversion facade, not here.
+ *
+ * @experimental The adapter contracts may change until they stabilize against
+ * three or more adapters.
+ */
 export interface DocumentReader<TDoc = FlowDoc> {
     /** Format id: 'docx', 'xlsx', 'pdf', … */
     readonly id: string;
@@ -20,18 +31,30 @@ export interface DocumentReader<TDoc = FlowDoc> {
     sniff: (bytes: Uint8Array) => boolean;
     read: (bytes: Uint8Array, opts?: ReadOptions) => ReadResult<TDoc>;
 }
+/** Writer-call options. Open-ended; per-writer knobs live in the writers. */
 export interface WriteOptions {
     readonly [key: string]: unknown;
 }
+/** The result of {@link DocumentWriter.write}: the encoded bytes plus any losses. */
 export interface WriteResult {
+    /** The encoded output bytes. */
     readonly bytes: Uint8Array;
+    /** Losses recorded while writing. */
     readonly losses: LossReport;
 }
+/**
+ * A synchronous writer for one output format (ir-design §7).
+ *
+ * @experimental The adapter contracts may change until they stabilize against
+ * three or more adapters.
+ */
 export interface DocumentWriter<TDoc> {
     /** Output format id: 'pdf', 'svg', 'html', 'docx', 'xlsx', … */
     readonly id: string;
     /** Which tree this writer consumes ('sheet' for the native grid writer). */
     readonly consumes: 'flow' | 'page' | 'sheet';
+    /** Feature vocabulary this writer understands. */
     readonly supports: ReadonlySet<Feature>;
+    /** Encode `doc` to the output bytes, collecting any losses. */
     write: (doc: TDoc, opts?: WriteOptions) => WriteResult;
 }