reamkit 1.15.1 → 1.15.3

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

@@ -4,7 +4,7 @@ import { FEATURES } from "../core/ir/features.js";
 import { EMPTY_STYLE_SHEET, resolveBodyStyles } from "../core/style-cascade/resolver.js";
 import "../core/style-cascade/index.js";
 import { poAttr, poChildren, poFindDescendant, poIntAttr, poIs } from "../core/po-helpers.js";
-import { bytesInclude } from "../core/bytes.js";
+import { bytesIncludePartName } from "../core/bytes.js";
 import { DEFAULT_THEME_PALETTE, defaultColorResolver, makeColorResolver } from "../core/drawingml/colors.js";
 import { parseChart, withChartColorStyle } from "../core/drawingml/chart-parser.js";
 import { parseTheme } from "../core/drawingml/theme-parser.js";
@@ -30,6 +30,17 @@ 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);
@@ -133,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));
 }
@@ -238,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",
@@ -248,7 +269,7 @@ var pptxReader = {
 		FEATURES.charts,
 		FEATURES.tables
 	]),
-	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesInclude(bytes, "ppt/presentation.xml"),
+	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesIncludePartName(bytes, "ppt/presentation.xml"),
 	read: (bytes) => readPptx(bytes)
 };
 //#endregion

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 {};

package/dist/esm/pptx/slide-parser.js

@@ -21,6 +21,17 @@ var RECT_GEOMETRY = {
 	adjust: /* @__PURE__ */ new Map()
 };
 var IDENTITY_TRANSFORM = (box) => box;
+/**
+* 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.
+*/
 function parseSlideShapes(container, ctx = {}, transform = IDENTITY_TRANSFORM) {
 	const out = [];
 	for (const child of poChildren(container)) if (poIs(child, "p:sp")) {
@@ -148,6 +159,16 @@ function parseGraphicFrame(gf, ctx, transform) {
 	}
 	return [];
 }
+/**
+* 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`.
+*/
 function diagramTransform(spTree, frame) {
 	const grpSpPr = poChildren(spTree).find((c) => poIs(c, "dsp:grpSpPr"));
 	const xfrm = grpSpPr ? poChildren(grpSpPr).find((c) => poIs(c, "a:xfrm")) : void 0;
@@ -166,6 +187,16 @@ function diagramTransform(spTree, frame) {
 		cy: b.cy * sy
 	});
 }
+/**
+* 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`).
+*/
 function noDiagramOverrideLoss(where) {
 	return {
 		severity: "dropped",
@@ -174,6 +205,20 @@ function noDiagramOverrideLoss(where) {
 		...where ? { where } : {}
 	};
 }
+/**
+* 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.
+*/
 function parseDiagramDrawing(spTree, transform, makeFloat, colors, resolveLink) {
 	const out = [];
 	for (const sp of poChildren(spTree)) {
@@ -202,6 +247,13 @@ function parseDiagramDrawing(spTree, transform, makeFloat, colors, resolveLink)
 	}
 	return out;
 }
+/**
+* `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).
+*/
 function parseBackgroundFill(bg, colors) {
 	const bgPr = poChildren(bg).find((c) => poIs(c, "p:bgPr"));
 	if (bgPr) {
@@ -217,6 +269,14 @@ function parseBackgroundFill(bg, colors) {
 		};
 	}
 }
+/**
+* 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.
+*/
 function backdropElement(fill, widthPt, heightPt) {
 	return {
 		kind: "shape",
@@ -241,6 +301,11 @@ function backdropElement(fill, widthPt, heightPt) {
 		}
 	};
 }
+/**
+* `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.
+*/
 function parseGeometry(spPr) {
 	if (!spPr) return RECT_GEOMETRY;
 	const prst = poChildren(spPr).find((c) => poIs(c, "a:prstGeom"));
@@ -286,6 +351,19 @@ function txBodyParagraphs(txBody, ph, cascade, colors, resolveLink) {
 	}
 	return content;
 }
+/**
+* `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.
+*/
 function parseTxBody(txBody, ph, cascade, colors, resolveLink) {
 	const content = txBodyParagraphs(txBody, ph, cascade, colors, resolveLink);
 	if (content.length === 0) return void 0;