reamkit 1.15.0 → 1.15.2

package/dist/esm/pdf-reader/tagged.js

@@ -1,11 +1,24 @@
 import { pt } from "../core/ir/units.js";
 import { ResourceStore } from "../core/ir/resources.js";
-import { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns } from "./flow-build.js";
+import { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns, sectionFromPdfPages } from "./flow-build.js";
 import { collectPageImages } from "./images.js";
 import { extractPageText } from "./text.js";
 import { readStructTree } from "./struct-tree.js";
 //#region src/pdf-reader/tagged.ts
 var ASSUMED_CONTENT_WIDTH_PT = 468;
+/**
+* Reconstruct a {@link Reconstruction} from a tagged PDF's logical structure
+* (E-PDF EP3 — the honest inverse of the tagged PDF Ream writes). Walks the
+* structure tree ({@link readStructTree}), pulls each element's text from the
+* per-page MCID → text map the content interpreter produced (EP2), and rebuilds
+* headings (`H1`–`H6` → outline level), paragraphs, tables (`Table` → `TR` →
+* `TH`/`TD`), list items (each `LI` → label + body) and figures (EP6 — each
+* `/Figure`'s MCID resolves to a lifted image carrying its `/Alt`). Images no
+* `/Figure` claims are appended in page + top-down order so nothing is lost.
+*
+* @returns The reconstructed document and image losses, or `undefined` when the
+*          PDF carries no structure tree or yields no body content.
+*/
 function reconstructTaggedPdf(file) {
 	const root = readStructTree(file);
 	if (!root) return void 0;
@@ -126,7 +139,7 @@ function reconstructTaggedPdf(file) {
 	for (const { img } of orphans) body.push(imageBlock(img, resources));
 	if (body.length === 0) return void 0;
 	return {
-		doc: buildFlowDoc(body, resources),
+		doc: buildFlowDoc(body, resources, sectionFromPdfPages(pages)),
 		losses: imageLosses
 	};
 }

package/dist/esm/pdf-reader/text.d.ts

@@ -1,3 +1,14 @@
 import { TextRun } from './content.js';
 import { PdfFile, PdfPage } from './document.js';
+/**
+ * Extract a page's text as positioned {@link TextRun}s (E-PDF EP2/EP8/EP13).
+ * Interprets the page content stream and, recursively, the Form XObjects it
+ * paints (EP13 — their text would otherwise be missed), then tags any run whose
+ * origin falls inside a `/Link` annotation's `/Rect` with that link's URI (EP8)
+ * so hyperlinks survive.
+ *
+ * @param file The owning {@link PdfFile}.
+ * @param page The page to extract.
+ * @returns The page's runs, each carrying an `href` when it sits under a link.
+ */
 export declare function extractPageText(file: PdfFile, page: PdfPage): Array<TextRun>;

package/dist/esm/pdf-reader/text.js

@@ -3,6 +3,17 @@ import { IDENTITY, interpretContent, multiply } from "./content.js";
 import { buildContentFont } from "./font.js";
 //#region src/pdf-reader/text.ts
 var MAX_FORM_DEPTH = 8;
+/**
+* Extract a page's text as positioned {@link TextRun}s (E-PDF EP2/EP8/EP13).
+* Interprets the page content stream and, recursively, the Form XObjects it
+* paints (EP13 — their text would otherwise be missed), then tags any run whose
+* origin falls inside a `/Link` annotation's `/Rect` with that link's URI (EP8)
+* so hyperlinks survive.
+*
+* @param file The owning {@link PdfFile}.
+* @param page The page to extract.
+* @returns The page's runs, each carrying an `href` when it sits under a link.
+*/
 function extractPageText(file, page) {
 	const runs = [];
 	collectRuns(file, page.resources, file.pageContent(page), IDENTITY, 0, /* @__PURE__ */ new Set(), runs);

package/dist/esm/pdf-reader/vector.d.ts

@@ -1,11 +1,21 @@
 import { PathSeg } from './content.js';
 import { ShapeGradient } from '../core/vector.js';
 import { PdfFile, PdfPage } from './document.js';
+/**
+ * One painted vector path lifted off a page (E-PDF EP10/EP11/EP16c): the path
+ * segments, whichever of solid fill / gradient fill / stroke survived the
+ * de-cluttering filter, and the path's page-space bounding box plus enclosing
+ * marked-content id.
+ */
 export interface PdfVector {
     readonly segs: ReadonlyArray<PathSeg>;
+    /** Present iff a qualifying solid fill survived (EP10). */
     readonly fillHex?: string;
+    /** Present iff a shading-pattern fill survived (EP16c). */
     readonly gradient?: ShapeGradient;
+    /** Present iff a qualifying stroke survived (EP11). */
     readonly strokeHex?: string;
+    /** Stroke width in page-space points (EP11). */
     readonly lineWidth?: number;
     readonly minX: number;
     readonly minY: number;
@@ -13,4 +23,13 @@ export interface PdfVector {
     readonly maxY: number;
     readonly mcid?: number;
 }
+/**
+ * Lift the painted vector paths off a page (E-PDF EP10/EP11/EP16c). Runs the
+ * content interpreter for its fill (EP10), stroke (EP11) and shading-pattern
+ * (EP16c) placements and keeps only the ones that read as real graphics:
+ * hairline/degenerate fills, invisible white paint, short stroke specks and the
+ * near-full-page background are all dropped, so a reconstructed document gains
+ * genuine coloured shapes, lines and gradients without the dot / page-background
+ * clutter. Clips and the bare `sh` operator are not captured (a documented loss).
+ */
 export declare function collectPageVectors(file: PdfFile, page: PdfPage): Array<PdfVector>;

package/dist/esm/pdf-reader/vector.js

@@ -6,6 +6,15 @@ var MIN_SIDE = 2;
 var MIN_AREA = 16;
 var MIN_STROKE_LEN = 6;
 var MAX_VECTORS = 2e3;
+/**
+* Lift the painted vector paths off a page (E-PDF EP10/EP11/EP16c). Runs the
+* content interpreter for its fill (EP10), stroke (EP11) and shading-pattern
+* (EP16c) placements and keeps only the ones that read as real graphics:
+* hairline/degenerate fills, invisible white paint, short stroke specks and the
+* near-full-page background are all dropped, so a reconstructed document gains
+* genuine coloured shapes, lines and gradients without the dot / page-background
+* clutter. Clips and the bare `sh` operator are not captured (a documented loss).
+*/
 function collectPageVectors(file, page) {
 	const [px0, py0, px1, py1] = page.mediaBox;
 	const pageArea = Math.max(1, Math.abs((px1 - px0) * (py1 - py0)));

package/dist/esm/pptx/placeholder-cascade.d.ts

@@ -2,8 +2,29 @@ import { RunProperties } from '../core/document-model/index.js';
 import { ColorResolver } from '../core/drawingml/colors.js';
 import { PoNode } from '../core/po-helpers.js';
 import { PlaceholderRef, ShapeBoxEmu } from './sp-helpers.js';
+/**
+ * The placeholder cascade (PX2): the resolver a slide parser consults whenever a
+ * slide placeholder shape (`p:sp` with a `p:ph`) lacks its own geometry or run
+ * formatting, supplying the inherited values from the slide's layout, then its
+ * master.
+ */
 export interface PlaceholderCascade {
+    /** The inherited EMU box for a slide placeholder without its own `a:xfrm`. */
     readonly geometryFor: (ph: PlaceholderRef) => ShapeBoxEmu | undefined;
+    /**
+     * The master's default run formatting for a placeholder's paragraph at the
+     * given 0-based outline level (empty when no master text styles apply).
+     */
     readonly defaultsFor: (ph: PlaceholderRef, level: number) => RunProperties;
 }
+/**
+ * Build a {@link PlaceholderCascade} from a slide's already-parsed layout and
+ * master trees: it resolves a placeholder's inherited geometry (the layout's
+ * matching `a:xfrm`, else the master's) and per-level default run formatting (the
+ * master's `p:txStyles`).
+ *
+ * @param layoutTree The parsed `p:sldLayout` part.
+ * @param masterTree The parsed `p:sldMaster` part, when present.
+ * @param colors     The deck's colour resolver, for scheme colours in the text styles.
+ */
 export declare function buildPlaceholderCascade(layoutTree: ReadonlyArray<PoNode>, masterTree: ReadonlyArray<PoNode> | undefined, colors: ColorResolver): PlaceholderCascade;

package/dist/esm/pptx/placeholder-cascade.js

@@ -6,6 +6,16 @@ function categoryOf(type) {
 	if (type === void 0 || type === "body" || type === "subTitle" || type === "obj") return "body";
 	return "other";
 }
+/**
+* Build a {@link PlaceholderCascade} from a slide's already-parsed layout and
+* master trees: it resolves a placeholder's inherited geometry (the layout's
+* matching `a:xfrm`, else the master's) and per-level default run formatting (the
+* master's `p:txStyles`).
+*
+* @param layoutTree The parsed `p:sldLayout` part.
+* @param masterTree The parsed `p:sldMaster` part, when present.
+* @param colors     The deck's colour resolver, for scheme colours in the text styles.
+*/
 function buildPlaceholderCascade(layoutTree, masterTree, colors) {
 	const layoutPhs = collectPlaceholders(layoutTree, "p:sldLayout");
 	const masterPhs = masterTree ? collectPlaceholders(masterTree, "p:sldMaster") : [];

package/dist/esm/pptx/ppt/ppt-reader.d.ts

@@ -1,4 +1,20 @@
 import { DocumentReader, ReadResult } from '../../core/ir/adapters.js';
 import { FlowDoc } from '../../core/ir/flow.js';
+/**
+ * Read a legacy `.ppt` (PowerPoint 97–2003 OLE2/CFB) into the same
+ * {@link FlowDoc} the OOXML pptx reader produces: one page per slide at the deck
+ * size, with each slide's text (run + paragraph formatting), embedded images,
+ * per-shape placement and decorative autoshapes. Always reports a single
+ * {@link Loss} — degraded (the format is read best-effort; re-save as `.pptx` for
+ * full fidelity), or dropped when the file is encrypted/obfuscated.
+ *
+ * @param bytes The raw `.ppt` (CFB) bytes.
+ * @returns The {@link FlowDoc} plus the one-element loss report.
+ */
 export declare function readPpt(bytes: Uint8Array): ReadResult<FlowDoc>;
+/**
+ * The {@link DocumentReader} for legacy `.ppt`: sniffs an OLE2/CFB container with
+ * a `PowerPoint Document` stream (which also keeps an `.xls`/`.doc` or an
+ * encrypted OOXML from mis-routing here) and reads it via {@link readPpt}.
+ */
 export declare const pptReader: DocumentReader<FlowDoc>;

package/dist/esm/pptx/ppt/ppt-reader.js

@@ -29,6 +29,17 @@ var PPT_ENCRYPTED_LOSS = {
 	feature: FEATURES.text,
 	detail: "legacy .ppt is encrypted/obfuscated — its text cannot be read"
 };
+/**
+* Read a legacy `.ppt` (PowerPoint 97–2003 OLE2/CFB) into the same
+* {@link FlowDoc} the OOXML pptx reader produces: one page per slide at the deck
+* size, with each slide's text (run + paragraph formatting), embedded images,
+* per-shape placement and decorative autoshapes. Always reports a single
+* {@link Loss} — degraded (the format is read best-effort; re-save as `.pptx` for
+* full fidelity), or dropped when the file is encrypted/obfuscated.
+*
+* @param bytes The raw `.ppt` (CFB) bytes.
+* @returns The {@link FlowDoc} plus the one-element loss report.
+*/
 function readPpt(bytes) {
 	const content = extractPptContent(bytes);
 	const width = pt(content.slideWidthPt ?? DEFAULT_SLIDE_W);
@@ -326,6 +337,11 @@ function anchorParagraph(breakBefore) {
 		}
 	};
 }
+/**
+* The {@link DocumentReader} for legacy `.ppt`: sniffs an OLE2/CFB container with
+* a `PowerPoint Document` stream (which also keeps an `.xls`/`.doc` or an
+* encrypted OOXML from mis-routing here) and reads it via {@link readPpt}.
+*/
 var pptReader = {
 	id: "ppt",
 	produces: "flow",

package/dist/esm/pptx/ppt/ppt-text.d.ts

@@ -1,25 +1,45 @@
+/** A run of uniformly-formatted text within a paragraph (PPT-2). */
 export interface PptRun {
     readonly text: string;
     readonly bold?: boolean;
     readonly italic?: boolean;
     readonly underline?: boolean;
+    /** The font size in points, when set on the run. */
     readonly sizePt?: number;
+    /** The run colour as 6-hex RGB (no `#`), when an explicit sRGB colour is set. */
     readonly colorHex?: string;
 }
+/**
+ * One slide paragraph: its runs plus the raw PPT alignment enum (0 left, 1
+ * center, 2 right, 3 justify, 4 distribute) and indent level (0–4), mapped by the
+ * reader.
+ */
 export interface PptParagraph {
     readonly runs: ReadonlyArray<PptRun>;
+    /** The raw PowerPoint TextAlignmentEnum (mapped to a document-model alignment by the reader). */
     readonly align?: number;
+    /** The 0-based outline/indent level. */
     readonly level?: number;
 }
+/**
+ * An embedded picture referenced by a slide shape — the raw image bytes pulled
+ * from the Pictures stream (PPT-3).
+ */
 export interface PptImage {
     readonly bytes: Uint8Array;
 }
+/** A shape's rectangle on the slide, in points (from the OfficeArtClientAnchor). */
 export interface PptRect {
     readonly x: number;
     readonly y: number;
     readonly w: number;
     readonly h: number;
 }
+/**
+ * One command of a freeform path (PPT-7), in geometry-bounds space
+ * (`0..pathWidth`, `0..pathHeight`, y down) — the same path-space the DrawingML
+ * custom geometry uses.
+ */
 export type PptPathCmd = {
     readonly kind: 'move';
     readonly x: number;
@@ -39,31 +59,66 @@ export type PptPathCmd = {
 } | {
     readonly kind: 'close';
 };
+/**
+ * A shape's exact custom geometry (PPT-7): the freeform path from the OPT's
+ * `pVertices` + `pSegmentInfo` arrays, in its geometry-bounds coordinate space.
+ */
 export interface PptCustomGeometry {
     readonly pathWidth: number;
     readonly pathHeight: number;
     readonly commands: ReadonlyArray<PptPathCmd>;
 }
+/**
+ * A decorative autoshape (PPT-5): its preset type plus any literal fill / line
+ * colour. Carried only by an anchored shape that has no text and no picture. A
+ * freeform additionally carries its exact custom geometry (PPT-7).
+ */
 export interface PptAutoShape {
+    /** The MSOSPT shape type (the FSP `recInstance`). */
     readonly shapeType: number;
+    /** The resolved fill colour as 6-hex RGB, when present. */
     readonly fillColorHex?: string;
+    /** The resolved line colour as 6-hex RGB, when present. */
     readonly lineColorHex?: string;
     readonly geometry?: PptCustomGeometry;
 }
+/**
+ * One slide shape (PPT-4..5): its text, picture and/or autoshape geometry, plus
+ * its slide rectangle when the shape carries an explicit anchor (else it is laid
+ * out in reading order).
+ */
 export interface PptShape {
     readonly rectPt?: PptRect;
     readonly paragraphs?: ReadonlyArray<PptParagraph>;
     readonly image?: PptImage;
     readonly autoShape?: PptAutoShape;
 }
+/** One slide: its shapes in document order. */
 export interface PptSlide {
     readonly shapes: ReadonlyArray<PptShape>;
 }
+/** The extracted content of a `.ppt`: its slides, deck page size and encryption flag. */
 export interface PptContent {
     readonly slides: ReadonlyArray<PptSlide>;
+    /** The deck page size in points, when the DocumentAtom gives a sane slide size. */
     readonly slideWidthPt?: number;
     readonly slideHeightPt?: number;
+    /** Whether the document streams are encrypted/obfuscated (so no text can be read). */
     readonly encrypted: boolean;
 }
+/**
+ * Walk a `.ppt` (CFB) into its {@link PptContent}: reads the `Current User`
+ * stream for the latest edit (and the encryption token), walks the edit chain to
+ * a persist directory, resolves the DocumentContainer and its slide list, and
+ * reads each slide's shapes/text/pictures. Degrades gracefully — when the
+ * persist/document structure can't be resolved it falls back to scanning the
+ * stream for slide containers directly, and structural doubt yields missing
+ * content, never wrong content. An encrypted file returns no slides with
+ * `encrypted: true`.
+ *
+ * @param bytes The raw `.ppt` (CFB) bytes.
+ * @returns The slides, deck size and encryption flag (empty when not a readable `.ppt`).
+ */
 export declare function extractPptContent(bytes: Uint8Array): PptContent;
+/** The concatenated plain text of a paragraph's runs. */
 export declare function paragraphText(p: PptParagraph): string;

package/dist/esm/pptx/ppt/ppt-text.js

@@ -66,6 +66,19 @@ function* records(d) {
 		off += consumed;
 	}
 }
+/**
+* Walk a `.ppt` (CFB) into its {@link PptContent}: reads the `Current User`
+* stream for the latest edit (and the encryption token), walks the edit chain to
+* a persist directory, resolves the DocumentContainer and its slide list, and
+* reads each slide's shapes/text/pictures. Degrades gracefully — when the
+* persist/document structure can't be resolved it falls back to scanning the
+* stream for slide containers directly, and structural doubt yields missing
+* content, never wrong content. An encrypted file returns no slides with
+* `encrypted: true`.
+*
+* @param bytes The raw `.ppt` (CFB) bytes.
+* @returns The slides, deck size and encryption flag (empty when not a readable `.ppt`).
+*/
 function extractPptContent(bytes) {
 	const empty = {
 		slides: [],
@@ -549,6 +562,7 @@ function matchesMagic(d, off, magic) {
 	for (let i = 0; i < magic.length; i++) if (d[off + i] !== magic[i]) return false;
 	return true;
 }
+/** The concatenated plain text of a paragraph's runs. */
 function paragraphText(p) {
 	return p.runs.map((r) => r.text).join("");
 }

package/dist/esm/pptx/pptx-reader.d.ts

@@ -1,6 +1,27 @@
 import { DocumentReader, ReadResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
 import { PoNode } from '../core/po-helpers.js';
+/**
+ * Read a PresentationML (`.pptx`) package into a {@link FlowDoc}: one page per
+ * slide at the deck size (`p:sldSz`), each slide's shapes placed as absolutely
+ * positioned floating elements. Hidden slides (`p:sld@show="0"`) are omitted (and
+ * recorded as a {@link Loss}, mirroring PowerPoint/LibreOffice export). Resolves
+ * each slide's layout → master → theme chain into the placeholder cascade, colour
+ * resolver and inherited background, plus its images and charts.
+ *
+ * @param bytes The raw `.pptx` (OPC ZIP) bytes.
+ * @returns The {@link FlowDoc} plus the accumulated loss report.
+ */
 export declare function readPptx(bytes: Uint8Array): ReadResult<FlowDoc>;
+/**
+ * Parse an OOXML part's bytes into preserve-order {@link PoNode} roots with the
+ * module's shared, presentation-tuned {@link XMLParser} (attributes kept, values
+ * not coerced, whitespace preserved). Shared with the slide-style resolvers.
+ */
 export declare function parseXml(data: Uint8Array): Array<PoNode>;
+/**
+ * The {@link DocumentReader} for PresentationML (`.pptx`): sniffs the OPC ZIP for
+ * `ppt/presentation.xml` (a cheap substring probe, no unzip) and reads it via
+ * {@link readPptx}.
+ */
 export declare const pptxReader: DocumentReader<FlowDoc>;

package/dist/esm/pptx/pptx-reader.js

@@ -26,6 +26,21 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	trimValues: false
 });
+function isSlideHidden(data) {
+	const root = decoder.decode(data.subarray(0, 4096)).match(/<p:sld\b[^>]*>/);
+	return root ? /\bshow\s*=\s*["']0["']/.test(root[0]) : false;
+}
+/**
+* Read a PresentationML (`.pptx`) package into a {@link FlowDoc}: one page per
+* slide at the deck size (`p:sldSz`), each slide's shapes placed as absolutely
+* positioned floating elements. Hidden slides (`p:sld@show="0"`) are omitted (and
+* recorded as a {@link Loss}, mirroring PowerPoint/LibreOffice export). Resolves
+* each slide's layout → master → theme chain into the placeholder cascade, colour
+* resolver and inherited background, plus its images and charts.
+*
+* @param bytes The raw `.pptx` (OPC ZIP) bytes.
+* @returns The {@link FlowDoc} plus the accumulated loss report.
+*/
 function readPptx(bytes) {
 	const losses = [];
 	const pkg = OpcPackage.open(bytes);
@@ -45,12 +60,23 @@ function readPptx(bytes) {
 		const slideRelById = new Map(pkg.getPartRelationships(presPath).filter((r) => r.type.endsWith("/slide")).map((r) => [r.id, r]));
 		const lst = kids.find((c) => poIs(c, "p:sldIdLst"));
 		const ids = lst ? poChildren(lst).filter((c) => poIs(c, "p:sldId")) : [];
+		let hidden = 0;
 		for (const sldId of ids) {
 			const rid = poAttr(sldId, "r:id");
 			const rel = rid !== void 0 ? slideRelById.get(rid) : void 0;
 			const part = rel ? pkg.resolveRelatedPart(presPath, rel) : void 0;
-			if (part) slideParts.push(part);
+			if (!part) continue;
+			if (isSlideHidden(part.data)) {
+				hidden++;
+				continue;
+			}
+			slideParts.push(part);
 		}
+		if (hidden > 0) losses.push({
+			severity: "dropped",
+			feature: FEATURES.text,
+			detail: `${hidden} hidden slide(s) omitted (p:sld@show="0")`
+		});
 	}
 	if (slideParts.length === 0) losses.push({
 		severity: "dropped",
@@ -118,6 +144,11 @@ function readPptx(bytes) {
 		losses
 	};
 }
+/**
+* Parse an OOXML part's bytes into preserve-order {@link PoNode} roots with the
+* module's shared, presentation-tuned {@link XMLParser} (attributes kept, values
+* not coerced, whitespace preserved). Shared with the slide-style resolvers.
+*/
 function parseXml(data) {
 	return parser.parse(decoder.decode(data));
 }
@@ -223,6 +254,11 @@ function deckColorResolver(pkg, masterPath) {
 	for (const [slot, hex] of parseTheme(theme.data)) palette.set(slot, hex);
 	return makeColorResolver(palette);
 }
+/**
+* The {@link DocumentReader} for PresentationML (`.pptx`): sniffs the OPC ZIP for
+* `ppt/presentation.xml` (a cheap substring probe, no unzip) and reads it via
+* {@link readPptx}.
+*/
 var pptxReader = {
 	id: "pptx",
 	produces: "flow",

package/dist/esm/pptx/slide-parser.d.ts

@@ -4,23 +4,125 @@ import { Loss, Pt, ResourceId } from '../core/ir/index.js';
 import { PoNode } from '../core/po-helpers.js';
 import { PlaceholderCascade } from './placeholder-cascade.js';
 import { PlaceholderRef, ShapeBoxEmu } from './sp-helpers.js';
+/**
+ * Per-slide parsing context: the placeholder cascade (PX2), an image resolver
+ * that turns a slide-scoped relationship id (`a:blip @r:embed`) into a
+ * {@link ResourceId} (PX3a), and a chart resolver that parses a referenced chart
+ * part (`c:chart @r:id`) and returns its document-unique key (PX4a). All optional
+ * — a bare slide needs none.
+ */
 export interface SlideContext {
     readonly cascade?: PlaceholderCascade;
+    /** A slide-scoped blip relationship id (`a:blip @r:embed`) → a stored resource (PX3a). */
     readonly resolveImage?: (relId: string) => ResourceId | undefined;
+    /** A chart relationship id (`c:chart @r:id`) → its document-unique key (PX4a). */
     readonly resolveChart?: (relId: string) => string | undefined;
+    /**
+     * The deck's colour resolver (master theme palette, PX5); defaults to the
+     * Office palette when absent.
+     */
     readonly colors?: ColorResolver;
+    /** A run hyperlink (`a:hlinkClick @r:id`) → its external URL (PX6). */
     readonly resolveHyperlink?: (relId: string) => string | undefined;
+    /**
+     * A SmartArt data relationship (`dgm:relIds @r:dm`) → the diagram's pre-rendered
+     * drawing override (its `dsp:spTree`), or `undefined` when the file ships no
+     * override (E-SMARTART SA0).
+     */
     readonly resolveDiagram?: (relId: string) => PoNode | undefined;
+    /**
+     * Sink for graceful-degradation notices (E-SMARTART SA3): a SmartArt that
+     * declares a diagram but ships no drawing override records a dropped-feature
+     * {@link Loss} here rather than vanishing without a trace.
+     */
     readonly onLoss?: (loss: Loss) => void;
 }
 type LinkResolver = ((relId: string) => string | undefined) | undefined;
 type GroupTransform = (box: ShapeBoxEmu) => ShapeBoxEmu;
+/**
+ * Walk a shape container (`p:spTree` or a `p:grpSp`), turning each `p:sp` into a
+ * floating text/graphic shape, each `p:pic` into a floating image, each
+ * `p:graphicFrame` into a chart/table, and recursing into nested `p:grpSp` groups
+ * (composing their transforms).
+ *
+ * @param container The shape container node.
+ * @param ctx       The per-slide parsing context.
+ * @param transform Maps child-space boxes to the slide (identity at the top level).
+ * @returns The container's shapes as positioned {@link BodyElement}s.
+ */
 export declare function parseSlideShapes(container: PoNode, ctx?: SlideContext, transform?: GroupTransform): Array<BodyElement>;
+/**
+ * The diagram's child shapes live in the spTree's own coordinate space
+ * (`dsp:grpSpPr/a:xfrm` `chOff`/`chExt`); map that onto a target box (the frame on
+ * a slide, or the inline/anchored box in docx). Usually the child space equals
+ * the box, so the scale is 1. Shared by pptx and docx (E-SMARTART).
+ *
+ * @param spTree The diagram drawing's `dsp:spTree`.
+ * @param frame  The target box the diagram is placed into.
+ * @returns A transform mapping diagram-space boxes onto `frame`.
+ */
 export declare function diagramTransform(spTree: PoNode, frame: ShapeBoxEmu): GroupTransform;
+/**
+ * A {@link Loss} for a SmartArt diagram that declares its data part but ships no
+ * pre-rendered drawing override (older files, or a generator that omitted the
+ * fallback). Ream renders the override rather than executing Office's layout
+ * engine, so without it the diagram can't be drawn — this records the gap as a
+ * dropped feature instead of letting it vanish. Shared by pptx and docx
+ * (E-SMARTART SA3).
+ *
+ * @param where Optional location tag for the loss report (e.g. `slide 3`).
+ */
 export declare function noDiagramOverrideLoss(where?: string): Loss;
+/**
+ * Render a SmartArt drawing override (a `dsp:spTree`) into floating shapes. The
+ * `dsp:` wrapper holds an ordinary `a:` `spPr`/`txBody`, so the shared DrawingML
+ * readers apply unchanged. Shared by pptx and docx (E-SMARTART); diagrams carry
+ * no placeholder cascade.
+ *
+ * @param spTree      The diagram drawing's `dsp:spTree`.
+ * @param transform   Maps each shape's diagram-space box to the target space.
+ * @param makeFloat   Anchors a box — page-relative for a slide, column/paragraph-
+ *                    relative for an inline docx diagram.
+ * @param colors      The colour resolver for the shapes' fills/strokes/text.
+ * @param resolveLink A run hyperlink resolver, or `undefined`.
+ * @returns The diagram's visible shapes as positioned {@link ShapeBlock}s.
+ */
 export declare function parseDiagramDrawing(spTree: PoNode, transform: GroupTransform, makeFloat: (box: ShapeBoxEmu) => FloatAnchor, colors: ColorResolver, resolveLink: LinkResolver): Array<ShapeBlock>;
+/**
+ * `p:bg` → the background fill, or `undefined` when none/unsupported. `p:bgPr`
+ * carries the fill directly (`a:solidFill`/`a:gradFill` — the same children
+ * `parseFill` reads; a picture background is not yet supported); `p:bgRef` (a
+ * theme fill-style index) is approximated by its colour child as a solid fill.
+ * Used for the slide's own background and the inherited layout/master one (PX5b).
+ */
 export declare function parseBackgroundFill(bg: PoNode, colors: ColorResolver): ShapeFill | undefined;
+/**
+ * A full-slide backdrop element for a background fill: a rectangle covering the
+ * page, anchored behind the content (PX5b).
+ *
+ * @param fill     The resolved background fill.
+ * @param widthPt  The page width in points.
+ * @param heightPt The page height in points.
+ */
 export declare function backdropElement(fill: ShapeFill, widthPt: Pt, heightPt: Pt): BodyElement;
+/**
+ * `p:spPr` geometry: `a:prstGeom` (preset) or `a:custGeom` (custom path), default
+ * rect. Exported for sheet shapes (E-SHEET W2), whose `xdr:spPr` carries the same
+ * `a:` children.
+ */
 export declare function parseGeometry(spPr: PoNode | undefined): ShapeGeometry;
+/**
+ * `p:txBody` → {@link ShapeTextBody}. `a:bodyPr` carries the insets and the
+ * vertical anchor (PX6: anchor `t`/`ctr`/`b`). Exported for sheet shapes
+ * (E-SHEET W2) — like SmartArt, they pass no placeholder cascade, so runs use
+ * their direct `a:rPr` formatting.
+ *
+ * @param txBody      The `p:txBody` node.
+ * @param ph          The owning placeholder ref, when this is a placeholder shape.
+ * @param cascade     The placeholder cascade supplying inherited run defaults.
+ * @param colors      The colour resolver for run colours.
+ * @param resolveLink A run hyperlink resolver, or `undefined`.
+ * @returns The text body, or `undefined` when it holds no paragraphs.
+ */
 export declare function parseTxBody(txBody: PoNode, ph: PlaceholderRef | undefined, cascade: PlaceholderCascade | undefined, colors: ColorResolver, resolveLink: LinkResolver): ShapeTextBody | undefined;
 export {};