reamkit 1.15.0 → 1.15.2

package/dist/esm/layout/page-doc.d.ts

@@ -3,35 +3,74 @@ import { FontMeasure, ParsedTtf } from '../core/font/index.js';
 import { ResolvedParagraphProperties, ResolvedRunProperties } from '../core/style-cascade/index.js';
 import { PathSegment, VectorShape } from '../core/vector.js';
 import { PreparedImage } from '../core/images.js';
+/** A font bound into a {@link LaidOutDocument}: the parsed face plus what layout/emit need from it. */
 export interface FontResource {
     readonly resourceName: string;
     readonly parsed: ParsedTtf;
+    /**
+     * Pure measurement/encoding (no `PdfDocument`): layout measures with this and
+     * emit encodes with it; the PDF font objects are created in the emit phase.
+     */
     readonly measure: FontMeasure;
+    /** Glyphs collected by the usage walk — the emit phase subsets to these. */
     readonly gids: ReadonlySet<number>;
 }
+/** A run of text on a {@link Line}: the string plus its resolved font, size, width and link/tagging state. */
 export interface TextToken {
     readonly kind: 'text';
     readonly text: string;
     readonly isSpace: boolean;
+    /**
+     * External hyperlink target inherited from the source run (rels-resolved).
+     * Writers MUST sanitize the scheme (`core/links`) before emitting anything
+     * clickable.
+     */
     readonly href?: string;
+    /**
+     * §17.11.14 — the token renders a footnote reference number; pagination
+     * reserves the note's block at the bottom of the page it lands on.
+     */
     readonly footnoteRef?: string;
+    /**
+     * §17.16.22 — internal link target: a bookmark name in this document (not a
+     * URL; resolves to a GoTo destination, never through the scheme list).
+     */
     readonly anchor?: string;
+    /**
+     * List-item marker glyphs (`"1."`, `"•"`) — tagged PDF brackets them in a Lbl
+     * element separate from the item body.
+     */
     readonly listMarker?: true;
+    /**
+     * The token falls inside a comment range (`commentRangeRefs`): the emitter
+     * fills a soft highlight behind it (E-COMMENTS CM2c).
+     */
     readonly highlight?: true;
     readonly resolvedRun: ResolvedRunProperties;
     readonly font: FontResource;
     readonly fontSizePt: number;
     readonly widthPt: number;
+    /**
+     * UAX #9 embedding level of this token's characters (0 for pure-LTR docs).
+     * Even = LTR, odd = RTL. Used for visual reordering at emit time.
+     */
     readonly bidiLevel: number;
 }
+/** An inline image on a {@link Line}: its sized box plus the resource name binding to the page XObject. */
 export interface ImageToken {
     readonly kind: 'image';
     readonly imageResourceName: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Constants kept to satisfy {@link Token} consumers — they never read these for images. */
     readonly isSpace: false;
     readonly bidiLevel: number;
 }
+/**
+ * A math draw item with its font already resolved (`math-layout` emits a
+ * variant; the tokenizer maps it to a {@link FontResource} so the emit phase
+ * needs no fonts).
+ */
 export type ResolvedMathItem = {
     readonly kind: 'glyph';
     readonly x: number;
@@ -51,6 +90,10 @@ export type ResolvedMathItem = {
     readonly strokeWidthPt?: number;
     readonly fill?: boolean;
 };
+/**
+ * An inline OfficeMath object — an atomic box straddling the baseline (its own
+ * ascent/descent extend the line height).
+ */
 export interface MathToken {
     readonly kind: 'math';
     readonly items: ReadonlyArray<ResolvedMathItem>;
@@ -60,7 +103,9 @@ export interface MathToken {
     readonly isSpace: false;
     readonly bidiLevel: number;
 }
+/** A positioned atom on a {@link Line}: a text run, an inline image, or an inline math box. */
 export type Token = TextToken | ImageToken | MathToken;
+/** A laid-out line of a paragraph: its broken tokens plus the geometry pagination needs. */
 export interface Line {
     readonly tokens: ReadonlyArray<Token>;
     readonly contentWidthPt: number;
@@ -69,25 +114,61 @@ export interface Line {
     readonly firstLine: boolean;
     readonly resolved: ResolvedParagraphProperties;
     isLastInParagraph: boolean;
+    /**
+     * Max ascent/descent contributed by math tokens (0 when none) — they straddle
+     * the baseline, so the line height/descent must grow to fit them.
+     */
     readonly mathAscentPt?: number;
     readonly mathDescentPt?: number;
+    /**
+     * E-PARITY: metric-derived single-line height and descent (Pt), the max over
+     * the line's text-token fonts under a non-default `layoutProfile`. Absent under
+     * `'ream'`, where leading stays the flat 1.2×/0.2 model (byte-identical).
+     */
     readonly metricHeightPt?: number;
     readonly metricDescentPt?: number;
 }
+/** An image bound into a {@link LaidOutDocument}: its resource name plus the decoded/validated bytes. */
 export interface ImageResource {
     readonly resourceName: string;
+    /**
+     * Decoded/validated at layout time (the probe); the emit phase replays it
+     * without touching the source bytes again.
+     */
     readonly prepared: PreparedImage;
 }
+/**
+ * The fields every {@link PageItem} shares (ir-design §6, frozen at stage 6.4):
+ * the positioned, layout-output vocabulary a page is made of. Page-frame
+ * geometry is branded `Pt` (PostScript points) with a TOP-LEFT origin, y growing
+ * downward (like CSS/SVG); the PDF emitter converts into PDF's native y-up frame
+ * at emission. Offsets measured from a text baseline (math/inline-image boxes
+ * inside a {@link Line}) and styling magnitudes (font/stroke sizes) stay plain
+ * numbers — they are not page-frame coordinates.
+ */
 export interface PageItemBase {
+    /**
+     * Tagged PDF (§14.8): the logical structure node this item's content belongs
+     * to. Set only on body content in tagged mode; undefined text in the line pass
+     * is treated as an artifact. Ignored when not tagging.
+     */
     readonly structId?: number;
+    /**
+     * Tagged PDF: explicitly mark this item as a pagination artifact (running
+     * header/footer, §14.8.2.2.2). Distinguishes header/footer text from
+     * not-yet-tagged body content so it is typed `/Artifact /Pagination`, never a P.
+     */
     readonly artifact?: 'pagination';
 }
+/** A laid-out line of text (tokens carry their fonts/sizes/positions). */
 export interface TextLineItem extends PageItemBase {
     readonly type: 'line';
     readonly line: Line;
     readonly originX: Pt;
+    /** Distance from the page TOP down to the text baseline. */
     readonly baselineY: Pt;
 }
+/** One edge of a table-cell frame; `(x, y)` is the cell box's top-left corner. */
 export interface BorderItem extends PageItemBase {
     readonly type: 'border';
     readonly side: 'top' | 'right' | 'bottom' | 'left';
@@ -98,6 +179,7 @@ export interface BorderItem extends PageItemBase {
     readonly borderSizePt: number;
     readonly borderColorHex: string;
 }
+/** A filled rectangle (cell shading); `(x, y)` is its top-left corner. */
 export interface FillItem extends PageItemBase {
     readonly type: 'fill';
     readonly x: Pt;
@@ -106,6 +188,10 @@ export interface FillItem extends PageItemBase {
     readonly height: Pt;
     readonly fillColorHex: string;
 }
+/**
+ * A placed raster image (resource name binds to the page XObject dict); `(x, y)`
+ * is its top-left corner.
+ */
 export interface ImageItem extends PageItemBase {
     readonly type: 'image';
     readonly x: Pt;
@@ -114,10 +200,15 @@ export interface ImageItem extends PageItemBase {
     readonly height: Pt;
     readonly imageResourceName: string;
 }
+/**
+ * DrawingML vector geometry. `shape.transform` maps the shape's local y-up frame
+ * into the top-left page frame (see `flipTransform`).
+ */
 export interface ShapeItem extends PageItemBase {
     readonly type: 'shape';
     readonly shape: VectorShape;
 }
+/** A positioned item on a laid-out page: a text line, border, fill, image, or vector shape. */
 export type PageItem = TextLineItem | BorderItem | FillItem | ImageItem | ShapeItem;
 export interface PagePaintPlan {
     readonly fills: ReadonlyArray<FillItem>;

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;
@@ -1854,11 +1900,21 @@ 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 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;
+	/** Whether the current column has received any items yet. */
 	colHasContent = () => this.current.length > this.colStartLen;
+	/** 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++;
@@ -1866,9 +1922,19 @@ var PageAssembler = class {
 			this.cursorY = this.ctx.pageHeight - this.ctx.marginTop;
 		} 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 +1944,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 +1955,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 +1984,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 +2010,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 +2033,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 +2056,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,7 +2084,19 @@ 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;
 		const band = bandForPage(this.pageInSection, this.globalPageIdx, this.ctx.titlePg, this.ctx.evenAndOddHeaders);