reamkit 1.15.1 → 1.15.3

package/dist/esm/layout/styled-layout.d.ts

@@ -8,29 +8,100 @@ import { SignaturePlaceholder } from '../pdf/signature.js';
 import { PdfEncryptOptions } from '../pdf/encryption.js';
 import { ResourceStore } from '../core/ir/index.js';
 import { StructTreeBuilder } from '../pdf/struct-tree.js';
+/**
+ * PDF/A conformance string: part 1 (ISO 19005-1, PDF 1.4) / 2 (ISO 19005-2) / 3
+ * (ISO 19005-3, both PDF 1.7); conformance level a (tagged) / b (visual) /
+ * u (Unicode — only 2/3).
+ */
 export type PdfALevel = 'PDF/A-1b' | 'PDF/A-1a' | 'PDF/A-2b' | 'PDF/A-2u' | 'PDF/A-2a' | 'PDF/A-3b' | 'PDF/A-3u' | 'PDF/A-3a';
+/** A {@link PdfALevel} decomposed into the part, level, and the apparatus they imply. */
 export interface PdfAProfile {
     readonly part: 1 | 2 | 3;
     readonly level: 'a' | 'b' | 'u';
+    /** Whether the level mandates a tagged PDF (level `a`). */
     readonly tagged: boolean;
+    /** PDF version the part pins: part 1 → 1.4, else 1.7. */
     readonly version: '1.4' | '1.7';
 }
+/**
+ * E-PARITY: renderer-compatibility profile for the line-height model.
+ *   `'ream'` (default) — Ream's flat 1.2× leading; byte-identical to before.
+ *   `'word'` — leading from the font's OS/2 usWin metrics (the GDI cell box).
+ *   `'libreoffice'` — leading from hhea (or OS/2 typo when USE_TYPO_METRICS is set).
+ *
+ * Opt-in: a profile emulates that renderer's vertical rhythm for closer visual
+ * parity. It never changes default (`'ream'`) output.
+ */
 export type LayoutProfile = 'ream' | 'word' | 'libreoffice';
+/**
+ * The full option set the layout engine and PDF emitter consume: the resolved
+ * font registry, the style/numbering tables, the section model and page
+ * geometry, the after-body apparatus (footnotes, endnotes, comments), and every
+ * PDF-output toggle (PDF/A, tagged, PDF/UA, encryption, attachments,
+ * signatures). Only `registry` and `styles` are required; everything else falls
+ * back to a sensible default.
+ */
 export interface StyledRenderOptions {
+    /** The resolved font set every run draws with (the guaranteed fallback registry). */
     readonly registry: FontRegistry;
+    /** Renderer-compatibility profile for the line-height model (default `'ream'`). */
     readonly layoutProfile?: LayoutProfile;
+    /**
+     * Per-run font resolution: when supplied, each text run picks the registry of
+     * its declared family (sans→arimo / serif→tinos / mono→cousine via the run's
+     * `w:ascii`) instead of always using `registry`. Absent ⇒ single-family (every
+     * run uses `registry`), byte-identical to before. `registry` remains the
+     * guaranteed fallback for math/chart/default glyphs and any missing family.
+     */
     readonly registriesByFamily?: ReadonlyMap<FamilyKey, FontRegistry>;
+    /**
+     * The document's OWN embedded fonts (`word/fonts/*.odttf`, de-obfuscated),
+     * keyed by normalized font name. A run whose `w:ascii` matches one renders with
+     * the real font — glyph-exact, no substitution. Highest priority.
+     */
     readonly embeddedFonts?: ReadonlyMap<string, FontRegistry>;
+    /** §18.8 / ECMA-376 style table the cascade resolves against. */
     readonly styles: StyleSheet;
+    /** §17.9 numbering definitions; applied to list paragraphs before layout. */
     readonly numbering?: Numbering;
+    /**
+     * Single-section legacy entry-point. If `sections` is set it takes precedence
+     * and `section` is ignored.
+     */
     readonly section?: SectionProperties;
+    /**
+     * ECMA-376 §17.6 — ordered list of sections. Each section's `endIndex` is the
+     * exclusive bound into the body array (section N covers
+     * `body[sections[N-1].endIndex..sections[N].endIndex)`).
+     */
     readonly sections?: ReadonlyArray<Section>;
+    /** Header/footer body content keyed by relationship id. */
     readonly headersFooters?: ReadonlyMap<string, ReadonlyArray<BodyElement>>;
+    /**
+     * §17.11 notes content by id. Footnotes render in a reserved band at the
+     * bottom of the referencing page; endnotes flow after the body.
+     */
     readonly footnotes?: ReadonlyMap<string, ReadonlyArray<BodyElement>>;
     readonly endnotes?: ReadonlyMap<string, ReadonlyArray<BodyElement>>;
+    /**
+     * §17.13.4 review comments by id; rendered as superscript markers in text and
+     * a list after the body (after endnotes), each with its author/date.
+     */
     readonly comments?: ReadonlyMap<string, Comment>;
+    /**
+     * CM2b — also emit each comment as a native PDF `/Text` (sticky-note)
+     * annotation at its marker. Opt-in and interactive-only: suppressed under
+     * PDF/A and tagged output (where it would need annotation/appearance
+     * conformance), since the clickable marker + Comments section already carry
+     * the content there.
+     */
     readonly commentAnnotations?: boolean;
+    /** Content-addressed binary store; image nodes reference it by {@link ResourceId}. */
     readonly resources?: ResourceStore;
+    /**
+     * Parsed charts keyed by relationship id (`ChartBlock.chartRelId`). Supplied by
+     * the converter, which resolves the chart parts from the package.
+     */
     readonly charts?: ReadonlyMap<string, Chart>;
     readonly pageWidth?: number;
     readonly pageHeight?: number;
@@ -38,39 +109,130 @@ export interface StyledRenderOptions {
     readonly marginRight?: number;
     readonly marginTop?: number;
     readonly marginBottom?: number;
+    /**
+     * Optional Liang hyphenator. When set, each word token is split at allowed
+     * hyphenation positions and offered to Knuth-Plass as potential break points
+     * (with a small disincentive). Improves justified paragraph rags.
+     */
     readonly hyphenator?: Hyphenator;
+    /**
+     * Optional `/Info` dictionary metadata (ISO 32000-1 §14.3.3). Unset fields are
+     * omitted; if any field is set a PDF `/Info` entry is emitted.
+     */
     readonly info?: DocumentInfo;
+    /**
+     * When set, emit a PDF/A-conformant file: an OutputIntent with an embedded
+     * sRGB ICC profile, document XMP `/Metadata` (the pdfaid identifier), `/ID`,
+     * and subset-tagged fonts with a `/CIDSet`. The profile picks the rest:
+     *   part 1 → PDF 1.4 + flattened image alpha (no transparency);
+     *   part 2/3 → PDF 1.7 + preserved transparency (image `/SMask` + page group);
+     *   part 3 → may carry embedded associated files (see `attachments`);
+     *   level a → tagged (logical structure); b → visual; u → b + Unicode mapping.
+     */
     readonly pdfA?: PdfALevel;
+    /**
+     * Emit a tagged PDF (ISO 32000-1 §14.8): a `/StructTreeRoot` describing reading
+     * order, marked content (BDC/EMC + MCID) on body text, and `/Artifact` marking
+     * of page decoration. Implied by `pdfA: 'PDF/A-1a'`. Independent of PDF/A
+     * otherwise (a plain tagged PDF is useful on its own).
+     */
     readonly tagged?: boolean;
+    /**
+     * PDF/UA-1 (ISO 14289-1): implies tagged; the XMP carries `pdfuaid:part=1` and
+     * the document always gets a title (AT announces it). Combines freely with
+     * `pdfA` level-a profiles.
+     */
     readonly pdfUA?: boolean;
+    /**
+     * Document natural language (BCP 47, e.g. `"en-US"`, `"ru-RU"`) for the
+     * tagged-PDF catalog `/Lang` (§14.9.2). Defaults to `"en-US"`. The docx
+     * converter fills this from the document's default `w:lang`.
+     */
     readonly language?: string;
+    /**
+     * §7.6 PDF encryption (AES-256, R6). Only honoured on the ASYNC conversion
+     * path (WebCrypto); mutually exclusive with `pdfA` (ISO 19005 forbids
+     * `/Encrypt`) and with signatures (v1).
+     */
     readonly encrypt?: PdfEncryptOptions;
+    /**
+     * Files to embed as associated files (catalog `/AF` + `/Names`
+     * `/EmbeddedFiles`). Only emitted for plain PDF and PDF/A-3 (PDF/A-1/2 forbid
+     * arbitrary embedded files); ignored for PDF/A-1/2. The docx/xlsx converters
+     * can embed the source document automatically via `embedSource`.
+     */
     readonly attachments?: ReadonlyArray<AttachedFile>;
+    /**
+     * Emit an (invisible) signature field + signature dictionary with placeholder
+     * `/ByteRange` and `/Contents` (ISO 32000 §12.8). The result is an UNSIGNED
+     * PDF; pass it to `signPdf()` to fill the placeholder with a real PKCS#7
+     * signature.
+     */
     readonly signaturePlaceholder?: SignaturePlaceholder;
 }
 export type { DocumentInfo } from '../core/document-model/index.js';
+/** A4 page width in points (the page-geometry fallback). */
 export declare const A4_WIDTH = 595;
+/** A4 page height in points (the page-geometry fallback). */
 export declare const A4_HEIGHT = 842;
+/**
+ * §17.13.6.2 — a bookmark's GoTo destination: the page (0-based) and the y-up
+ * top of the anchoring paragraph's first line.
+ */
 export interface BookmarkPosition {
     readonly pageIdx: number;
     readonly yTopPt: number;
 }
+/** A comment's `/Text` annotation payload: the author and the flattened body (CM2b). */
 export interface CommentNote {
     readonly author?: string;
     readonly contents: string;
 }
+/**
+ * PDF-only companion the same layout pass produces (oop-design A13): the
+ * logical-structure tree, per-section geometry (the emit fallback page), and the
+ * parsed PDF/A profile. Consumed only by `emitStyledPdf`; the SVG writer never
+ * sees it.
+ */
 export interface PdfLayoutAux {
     readonly structBuilder: StructTreeBuilder | undefined;
     readonly sectionCtxs: ReadonlyArray<SectionRenderCtx>;
     readonly pdfaProfile: PdfAProfile | undefined;
     readonly tagged: boolean;
     readonly bookmarks: ReadonlyMap<string, BookmarkPosition>;
+    /**
+     * CM2b — comment marker anchor (`comment-${n}`) → the note the emitter attaches
+     * as a `/Text` annotation. Present only when `commentAnnotations` was requested.
+     */
     readonly commentNotes?: ReadonlyMap<string, CommentNote>;
 }
+/**
+ * What {@link layoutStyledDocument} actually returns: the PageDoc with the PDF
+ * companion riding on `pdf`. Assignable to the narrow `LaidOutDocument`, so
+ * PageDoc-only consumers (`writeSvg`) take it as-is.
+ */
 export interface LaidOutPdfDocument extends LaidOutDocument {
     readonly pdf: PdfLayoutAux;
 }
+/**
+ * Layout phase (the FlowDoc→PageDoc transform of ir-design §7): body →
+ * positioned pages (PageItems), font/image resources, logical structure. Drives
+ * the whole pass — numbering and note numbering, per-section geometry, per-block
+ * layout, the footnote/endnote/comment tails, then pagination — and returns the
+ * {@link LaidOutPdfDocument} (the PageDoc plus its PDF companion).
+ *
+ * @param body    The document body the section model partitions.
+ * @param options The resolved fonts, styles, section model, and PDF-output toggles.
+ * @returns The positioned pages plus the PDF-only {@link PdfLayoutAux} companion.
+ */
 export declare function layoutStyledDocument(body: ReadonlyArray<BodyElement>, options: StyledRenderOptions): LaidOutPdfDocument;
+/**
+ * The resolved page box + header/footer offsets, in points. Priority for page
+ * geometry:
+ *   1. explicit value in {@link StyledRenderOptions} (test/library caller override)
+ *   2. value from section properties (`sectPr/pgSz/pgMar` from the docx)
+ *   3. A4 + 1-inch margins fallback
+ */
 export interface PageDimensions {
     readonly pageWidth: number;
     readonly pageHeight: number;
@@ -81,6 +243,13 @@ export interface PageDimensions {
     readonly headerOffsetPt: number;
     readonly footerOffsetPt: number;
 }
+/**
+ * Per-section render context: the section's exclusive body `endIndex`, its
+ * resolved {@link PageDimensions} (flattened), the derived content box, the
+ * column geometry, the pre-laid header/footer bands, and the title-page /
+ * even-and-odd header toggles. Built once per section and threaded through both
+ * layout and pagination.
+ */
 export interface SectionRenderCtx {
     readonly endIndex: number;
     readonly properties: SectionProperties;
@@ -91,6 +260,12 @@ export interface SectionRenderCtx {
     readonly marginBottom: number;
     readonly contentWidth: number;
     readonly pageContentHeight: number;
+    /**
+     * §17.6.4 multi-column sections: per-column x-offset (from `marginLeft`) and
+     * width. Absent for single-column sections. Body blocks are laid out at the
+     * FIRST column's width (explicit unequal widths degrade to flowing without
+     * re-wrap); headers/footers and footnotes keep the full content width.
+     */
     readonly columns?: ReadonlyArray<{
         readonly xOffsetPt: number;
         readonly widthPt: number;

package/dist/esm/layout/styled-layout.js

@@ -8,6 +8,8 @@ import { segmentLevels } from "../core/bidi/segments.js";
 import { analyzeString, hasBidiCharacters } from "../core/bidi/index.js";
 import { FORCED_BREAK, breakLines } from "../core/line-breaker/knuth-plass.js";
 import { greedyBreakLines } from "../core/line-breaker/greedy.js";
+import { cjkBreakBetween, splitCjkSegment } from "../core/line-breaker/cjk.js";
+import "../core/line-breaker/index.js";
 import { applyNumbering, applyNumberingToHeadersFooters } from "../core/numbering/apply.js";
 import { DEFAULT_RESOLVED_PARAGRAPH, DEFAULT_RESOLVED_RUN } from "../core/style-cascade/types.js";
 import { resolveParagraphProperties, resolveRunProperties } from "../core/style-cascade/resolver.js";
@@ -242,6 +244,17 @@ function commentTailBlocks(comment, n, opts) {
 		}
 	}, ...comment.content];
 }
+/**
+* Layout phase (the FlowDoc→PageDoc transform of ir-design §7): body →
+* positioned pages (PageItems), font/image resources, logical structure. Drives
+* the whole pass — numbering and note numbering, per-section geometry, per-block
+* layout, the footnote/endnote/comment tails, then pagination — and returns the
+* {@link LaidOutPdfDocument} (the PageDoc plus its PDF companion).
+*
+* @param body    The document body the section model partitions.
+* @param options The resolved fonts, styles, section model, and PDF-output toggles.
+* @returns The positioned pages plus the PDF-only {@link PdfLayoutAux} companion.
+*/
 function layoutStyledDocument(body, options) {
 	const sectionList = resolveSectionList(body, options);
 	const noteAssigned = assignNoteNumbers(applyNumbering(body, options.numbering), options.comments ? new Set(options.comments.keys()) : void 0);
@@ -1323,15 +1336,20 @@ function tokenizeText(text) {
 		text: m[1],
 		isSpace: true
 	});
-	else if (m[2] !== void 0) out.push({
-		text: m[2],
+	else if (m[2] !== void 0) for (const piece of splitCjkSegment(m[2])) out.push({
+		text: piece,
 		isSpace: false
 	});
 	return out;
 }
 var HYPHENATION_PENALTY = 50;
+function lastCodePoint(s) {
+	const chars = [...s];
+	return chars.length > 0 ? chars[chars.length - 1].codePointAt(0) : 0;
+}
 function paragraphItemStream(tokens, hyphenator) {
 	const entries = [];
+	let prevBoxEndCp = null;
 	for (const tok of tokens) {
 		if (tok.isSpace || tok.kind === "image" || tok.kind === "math") {
 			entries.push({
@@ -1346,8 +1364,20 @@ function paragraphItemStream(tokens, hyphenator) {
 				},
 				token: tok
 			});
+			prevBoxEndCp = null;
 			continue;
 		}
+		const startCp = tok.text.codePointAt(0) ?? 0;
+		if (prevBoxEndCp !== null && cjkBreakBetween(prevBoxEndCp, startCp)) entries.push({
+			item: {
+				type: "penalty",
+				width: 0,
+				penalty: 0,
+				flagged: false
+			},
+			token: null
+		});
+		prevBoxEndCp = lastCodePoint(tok.text);
 		const positions = hyphenator ? hyphenator.hyphenate(tok.text) : [];
 		if (positions.length === 0) {
 			entries.push({
@@ -1837,7 +1867,23 @@ function listItemParagraphNode(builder, stack, list, wantLbl) {
 		...lblId !== void 0 ? { lblId } : {}
 	};
 }
+/**
+* A9 (oop-design §4.3): the page-assembly state machine, extracted verbatim from
+* `paginateSections`. One instance assembles all pages of a document: fields are
+* the former local state, methods the former closures — the block loop drives it.
+* Push order into `current`/`pages` IS the byte order of the emitted PDF, so the
+* bodies move unchanged.
+*/
 var PageAssembler = class {
+	/**
+	* @param sectionCtxs      The per-section render contexts, in order; assembly
+	*                         starts on the first section's first page.
+	* @param builder          The tagged-PDF structure builder, or `undefined` for
+	*                         untagged output.
+	* @param notes            The footnote plan (lazy per-section layout), or
+	*                         `undefined` when there are none.
+	* @param bookmarkPositions Out-param: bookmark name → its GoTo destination.
+	*/
 	constructor(sectionCtxs, builder, notes, bookmarkPositions) {
 		this.sectionCtxs = sectionCtxs;
 		this.builder = builder;
@@ -1845,6 +1891,7 @@ var PageAssembler = class {
 		this.bookmarkPositions = bookmarkPositions;
 		this.ctx = sectionCtxs[0];
 		this.cursorY = this.ctx.pageHeight - this.ctx.marginTop;
+		this.colStartY = this.cursorY;
 	}
 	pages = [];
 	ctx;
@@ -1854,21 +1901,56 @@ var PageAssembler = class {
 	current = [];
 	pendingPageBreak = false;
 	cursorY;
+	/**
+	* §17.6.4 multi-column flow: content fills column after column before the page
+	* flushes. `colStartLen` marks where the current column's items begin in
+	* `current` — the single-column "page has content" guard generalizes to "this
+	* column has content" (identical when there is one column).
+	*/
 	colIdx = 0;
 	colStartLen = 0;
+	/** The cursor's y at the top of the current column — see {@link colHasContent}. */
+	colStartY;
+	/** The current column's left edge (`marginLeft` plus the column x-offset). */
 	colLeft = () => this.ctx.marginLeft + (this.ctx.columns?.[this.colIdx]?.xOffsetPt ?? 0);
+	/** The current column's width (the section content width when single-column). */
 	colWidth = () => this.ctx.columns?.[this.colIdx]?.widthPt ?? this.ctx.contentWidth;
-	colHasContent = () => this.current.length > this.colStartLen;
+	/**
+	* Whether the current column is already in use.
+	*
+	* This gates every overflow break, so that a block too tall for an empty page
+	* is placed rather than looping forever. It used to ask whether the column had
+	* received any drawable ITEM, which is not the same question: a run of empty
+	* table rows consumes vertical space and draws nothing, so the guard stayed
+	* false, no break ever fired, and the rows marched off the bottom of the page.
+	* A spreadsheet is full of such rows — the sheet in tdf171828.xlsx has 162 of
+	* them — and they were silently costing whole pages of pagination.
+	*
+	* Consumed space counts as use, whether or not any ink went with it.
+	*/
+	colHasContent = () => this.current.length > this.colStartLen || this.cursorY < this.colStartY;
+	/** Overflow step: next column on this page, or a fresh page after the last. */
 	advanceColumn = () => {
 		if (this.ctx.columns && this.colIdx + 1 < this.ctx.columns.length) {
 			this.colIdx++;
 			this.colStartLen = this.current.length;
 			this.cursorY = this.ctx.pageHeight - this.ctx.marginTop;
+			this.colStartY = this.cursorY;
 		} else this.flushPage();
 	};
+	/**
+	* §20.4.2.3 out-of-flow drawings (wrap `'none'`): they render at their anchored
+	* position without moving the cursor. `behindDoc` sinks below the body text,
+	* everything else above it; both flush with the page.
+	*/
 	floatsBehind = [];
 	floatsFront = [];
+	/**
+	* Side-wrapping floats (wrapSquare/tight/through): rectangles the body text
+	* must flow around. Page-scoped, like the float graphics.
+	*/
 	exclusions = [];
+	/** The float's left edge on the page, resolved from its horizontal anchor. */
 	floatX = (f, widthPt) => {
 		const h = f.posH;
 		if (!h) return this.colLeft();
@@ -1878,6 +1960,10 @@ var PageAssembler = class {
 		if (h.align === "right") return base + span - widthPt;
 		return base + (h.offsetPt ?? 0);
 	};
+	/**
+	* The drawing's TOP in the y-up cursor frame. Paragraph/line-relative offsets
+	* hang off the anchoring paragraph's current position.
+	*/
 	floatTopYUp = (f) => {
 		const v = f.posV;
 		if (!v) return this.cursorY;
@@ -1885,11 +1971,26 @@ var PageAssembler = class {
 		if (v.relativeFrom === "margin") return this.ctx.pageHeight - this.ctx.marginTop - (v.offsetPt ?? 0);
 		return this.cursorY - (v.offsetPt ?? 0);
 	};
+	/**
+	* Tagged PDF: the stack of open list levels (for L/LI/LBody nesting). Cleared
+	* whenever a non-list-item block interrupts the run of list paragraphs.
+	*/
 	listStack = [];
+	/**
+	* §17.11 footnotes: `pageNotes` reserved for the CURRENT page (greedy — a line
+	* carrying a reference pulls its note's height out of the page bottom, so the
+	* line and its note land together). `placedNotes` is global: a note renders
+	* once, on its first reference's page.
+	*/
 	pageNotes = [];
 	noteReserve = 0;
 	placedNotes = /* @__PURE__ */ new Set();
+	/** The page's usable bottom: the margin plus whatever the notes band has claimed so far. */
 	bottomLimit = () => this.ctx.marginBottom + this.noteReserve;
+	/**
+	* The first exclusion a line spanning `[yTop-h, yTop]` collides with in the
+	* current column (x-overlap with the column required).
+	*/
 	exclusionAt = (yTop, h) => {
 		const cl = this.colLeft();
 		const cr = cl + this.colWidth();
@@ -1899,6 +2000,10 @@ var PageAssembler = class {
 			return e;
 		}
 	};
+	/**
+	* Per-line geometry beside an exclusion: the narrowed width and the x shift.
+	* Text goes on the WIDER side of the float (one side per line, v1).
+	*/
 	lineGeometryAt = (yTop, h) => {
 		const full = this.colWidth();
 		const e = this.exclusionAt(yTop, h);
@@ -1921,6 +2026,12 @@ var PageAssembler = class {
 			xOffset: 0
 		};
 	};
+	/**
+	* Estimated per-line widths for a paragraph starting at `startY`: narrowed
+	* while lines (estimated at the first line's height) overlap an exclusion, then
+	* one full width Knuth-Plass reuses for the tail. `undefined` when nothing
+	* overlaps — the caller keeps the original block.
+	*/
 	lineWidthsFor = (block, startY) => {
 		if (this.exclusions.length === 0 || block.lines.length === 0) return void 0;
 		const h0 = computeLineHeight(block.lines[0], block.resolved);
@@ -1938,6 +2049,10 @@ var PageAssembler = class {
 		}
 		return narrowed ? widths : void 0;
 	};
+	/**
+	* New (unplaced) footnotes referenced by a line's tokens, with their layout at
+	* the current section's width.
+	*/
 	lineFootnotes = (line) => {
 		if (!this.notes) return [];
 		const out = [];
@@ -1957,6 +2072,10 @@ var PageAssembler = class {
 		}
 		return out;
 	};
+	/**
+	* The notes band for the flushing page: separator rule + each note's blocks
+	* stacked inside the reserved area. Tagged: each note is a Note→P element.
+	*/
 	renderNotesBand = () => {
 		if (this.pageNotes.length === 0) return [];
 		const out = [];
@@ -1981,9 +2100,21 @@ var PageAssembler = class {
 		}
 		return out;
 	};
+	/**
+	* Dynamic PAGE/NUMPAGES bands re-render after pagination (both numbers are
+	* known only then); each use records where its commands must be spliced.
+	*/
 	dynBands = [];
+	/**
+	* Finish the in-progress page: pick the header/footer band, queue any dynamic
+	* band, push the assembled commands as a page, then reset all per-page state
+	* (cursor, floats, exclusions, notes, columns) for the next one.
+	*
+	* @param force Emit a page even when no body content was placed (used to
+	*              guarantee one page for a header/footer-only document).
+	*/
 	flushPage = (force = false) => {
-		if (this.current.length === 0 && !force) return;
+		if (this.current.length === 0 && this.cursorY >= this.colStartY && !force) return;
 		const band = bandForPage(this.pageInSection, this.globalPageIdx, this.ctx.titlePg, this.ctx.evenAndOddHeaders);
 		const header = pickBand(this.ctx.headerSet, band);
 		const footer = pickBand(this.ctx.footerSet, band);
@@ -2022,6 +2153,7 @@ var PageAssembler = class {
 		this.pageInSection++;
 		this.globalPageIdx++;
 		this.cursorY = this.ctx.pageHeight - this.ctx.marginTop;
+		this.colStartY = this.cursorY;
 	};
 };
 function paginateSections(blocks, sectionCtxs, builder, defaultLang = "en-US", notes, bookmarkPositions, reflowParagraph) {

package/dist/esm/pdf/builtin-fonts.d.ts

@@ -1,2 +1,7 @@
+/** One of the 14 Standard Type 1 font names (ISO 32000-1 §9.6.2.2). */
 export type BuiltinFontName = 'Helvetica' | 'Helvetica-Bold' | 'Helvetica-Oblique' | 'Helvetica-BoldOblique' | 'Times-Roman' | 'Times-Bold' | 'Times-Italic' | 'Times-BoldItalic' | 'Courier' | 'Courier-Bold' | 'Courier-Oblique' | 'Courier-BoldOblique' | 'Symbol' | 'ZapfDingbats';
+/**
+ * The 14 Standard Type 1 fonts, guaranteed available in every conforming PDF
+ * reader and never embedded.
+ */
 export declare const BUILTIN_FONTS: ReadonlyArray<BuiltinFontName>;

package/dist/esm/pdf/cid-font.d.ts

@@ -1,15 +1,37 @@
 import { ParsedTtf } from '../core/font/index.js';
 import { PdfRef } from './objects.js';
 import { PdfDocument } from './writer.js';
+/** Options for {@link embedTtfFont}. */
 export interface EmbedTtfOptions {
+    /** The glyph ids actually used; given, the font is subset to just these (plus their closure). */
     readonly usedGids?: Iterable<number>;
+    /**
+     * Emit a `/CIDSet` in the font descriptor (required by PDF/A-1; omitted
+     * otherwise, since PDF/A-2/3 only constrain it when present).
+     */
     readonly cidSet?: boolean;
 }
+/** The result of {@link embedTtfFont}: the Type 0 font reference plus measurement/encoding helpers. */
 export interface EmbeddedFont {
+    /** Indirect reference to the `/Type0` font dictionary, for page resource `/Font` entries. */
     readonly fontRef: PdfRef;
+    /** The parsed source font. */
     readonly parsed: ParsedTtf;
+    /** Glyph advance width in PDF text-space units (1000/em) for a given glyph id. */
     readonly pdfWidthForGid: (gid: number) => number;
+    /** Measured width of `text` at `fontSize`, in points. */
     readonly textWidthPt: (text: string, fontSize: number) => number;
+    /** Encode `text` as the hex CID string used inside a `Tj`/`TJ` show operator (Identity-H). */
     readonly encodeTextAsCidHex: (text: string) => string;
 }
+/**
+ * Embed a TrueType font as a composite (Type 0) font with a CIDFontType2
+ * descendant (ISO 32000-1 §9.7), optionally subsetting it to the used glyphs.
+ * Adds the `/FontFile2`, `/FontDescriptor`, `/CIDFontType2` and `/Type0` objects
+ * (plus a `/ToUnicode` CMap and an optional `/CIDSet`) to `doc`.
+ *
+ * @param parsed  The parsed TrueType font.
+ * @param options Subset glyph set and/or PDF/A-1 `/CIDSet` emission.
+ * @returns The font reference and measurement/encoding helpers ({@link EmbeddedFont}).
+ */
 export declare function embedTtfFont(doc: PdfDocument, parsed: ParsedTtf, options?: EmbedTtfOptions): EmbeddedFont;

package/dist/esm/pdf/cid-font.js

@@ -3,6 +3,16 @@ import { createFontMeasure } from "../core/font/measure.js";
 import { dict, name, ref, stream } from "./objects.js";
 //#region src/pdf/cid-font.ts
 var encoder = new TextEncoder();
+/**
+* Embed a TrueType font as a composite (Type 0) font with a CIDFontType2
+* descendant (ISO 32000-1 §9.7), optionally subsetting it to the used glyphs.
+* Adds the `/FontFile2`, `/FontDescriptor`, `/CIDFontType2` and `/Type0` objects
+* (plus a `/ToUnicode` CMap and an optional `/CIDSet`) to `doc`.
+*
+* @param parsed  The parsed TrueType font.
+* @param options Subset glyph set and/or PDF/A-1 `/CIDSet` emission.
+* @returns The font reference and measurement/encoding helpers ({@link EmbeddedFont}).
+*/
 function embedTtfFont(doc, parsed, options = {}) {
 	const scale = 1e3 / parsed.unitsPerEm;
 	const toPdfUnits = (v) => Math.round(v * scale);

package/dist/esm/pdf/embedded-file.d.ts

@@ -1,11 +1,27 @@
 import { PdfRef } from './objects.js';
 import { PdfDocument } from './writer.js';
+/** How an embedded file relates to the document (`/AFRelationship`, ISO 32000-2 §14.13). */
 export type AFRelationship = 'Source' | 'Data' | 'Alternative' | 'Supplement' | 'Unspecified';
+/** One file to embed as a PDF/A-3 associated file (see {@link embedAssociatedFile}). */
 export interface AttachedFile {
+    /** File name as shown to the user, e.g. `"source.docx"`. ASCII recommended. */
     readonly name: string;
     readonly bytes: Uint8Array;
+    /**
+     * MIME type for the `/EmbeddedFile` `/Subtype`, e.g.
+     * `"application/vnd.openxmlformats-officedocument.wordprocessingml.document"`.
+     */
     readonly mimeType: string;
     readonly relationship?: AFRelationship;
     readonly description?: string;
 }
+/**
+ * Embed `file` as an `/EmbeddedFile` stream wrapped in a `/Filespec` (ISO 32000-1
+ * §7.11, ISO 19005-3 §6.8). The MIME type becomes a `Name` (the serializer
+ * hex-escapes the `/`), which readers decode back.
+ *
+ * @param file The file bytes plus its name, MIME type and relationship.
+ * @returns A reference to the `/Filespec`, to place in the catalog `/AF` array
+ *   and the `/Names` `/EmbeddedFiles` name tree.
+ */
 export declare function embedAssociatedFile(doc: PdfDocument, file: AttachedFile): PdfRef;

package/dist/esm/pdf/embedded-file.js

@@ -1,5 +1,14 @@
 import { dict, name, ref, stream, unicodeString } from "./objects.js";
 //#region src/pdf/embedded-file.ts
+/**
+* Embed `file` as an `/EmbeddedFile` stream wrapped in a `/Filespec` (ISO 32000-1
+* §7.11, ISO 19005-3 §6.8). The MIME type becomes a `Name` (the serializer
+* hex-escapes the `/`), which readers decode back.
+*
+* @param file The file bytes plus its name, MIME type and relationship.
+* @returns A reference to the `/Filespec`, to place in the catalog `/AF` array
+*   and the `/Names` `/EmbeddedFiles` name tree.
+*/
 function embedAssociatedFile(doc, file) {
 	const efRef = doc.add(stream({
 		Type: name("EmbeddedFile"),